refactor(args): validate explicit boolean flag values (review feedback)

Address PR review:
- hoist the recognised true/false token sets to module-level Sets instead
  of allocating an array on every boolean-flag parse
- accept common spellings (true/1/yes/on, false/0/no/off; case- and
  whitespace-insensitive) and throw a clear error for an unrecognised
  explicit value (e.g. `--flag=maybe`, `--flag=`) so a typo cannot
  silently enable a flag, consistent with numeric-flag validation
- expand tests to cover no/off, case/whitespace, true-like values, and the
  rejection path

Author: Osamaali313

src/args.ts

@@ -1,6 +1,10 @@
 import type { GlobalFlags } from './types/flags';
 import type { OptionDef } from './command';
 
+/** Recognised spellings for an explicit boolean flag value, e.g. `--flag=false`. */
+const BOOLEAN_TRUE_VALUES = new Set(['true', '1', 'yes', 'on']);
+const BOOLEAN_FALSE_VALUES = new Set(['false', '0', 'no', 'off']);
+
 function kebabToCamel(str: string): string {
   return str.replace(/-([a-z])/g, (_, c: string) => c.toUpperCase());
 }
@@ -115,11 +119,22 @@ export function parseFlags(argv: string[], options: OptionDef[]): GlobalFlags {
 
       if (schema.booleans.has(camelKey)) {
         // A bare boolean flag (`--flag`) is true. Honour an explicit value
-        // such as `--flag=false` / `--flag=0` instead of silently forcing the
-        // flag to true and discarding what the user typed.
-        (flags as Record<string, unknown>)[camelKey] =
-          value === undefined ||
-          !['false', '0', 'no', 'off'].includes(value.trim().toLowerCase());
+        // (`--flag=false`, `--flag=0`, ...) and reject an unrecognised one so a
+        // typo cannot silently enable the flag, mirroring numeric-flag handling.
+        if (value === undefined) {
+          (flags as Record<string, unknown>)[camelKey] = true;
+        } else {
+          const normalized = value.trim().toLowerCase();
+          if (BOOLEAN_TRUE_VALUES.has(normalized)) {
+            (flags as Record<string, unknown>)[camelKey] = true;
+          } else if (BOOLEAN_FALSE_VALUES.has(normalized)) {
+            (flags as Record<string, unknown>)[camelKey] = false;
+          } else {
+            throw new Error(
+              `Flag --${key} requires a boolean value (e.g. true/false), got "${value}".`,
+            );
+          }
+        }
         i++;
         continue;
       }

test/args.test.ts

@@ -31,10 +31,25 @@ describe('parseFlags', () => {
     expect(parseFlags(['--verbose'], OPTIONS).verbose).toBe(true);
   });
 
-  it('honours an explicit value on a boolean flag instead of forcing true', () => {
+  it('honours explicit false-like values on a boolean flag', () => {
     // Regression: `--flag=false` / `--flag=0` were silently set to true.
-    expect(parseFlags(['--verbose=false'], OPTIONS).verbose).toBe(false);
-    expect(parseFlags(['--verbose=0'], OPTIONS).verbose).toBe(false);
-    expect(parseFlags(['--verbose=true'], OPTIONS).verbose).toBe(true);
+    for (const v of ['false', '0', 'no', 'off', ' OFF ', 'False']) {
+      expect(parseFlags([`--verbose=${v}`], OPTIONS).verbose).toBe(false);
+    }
+  });
+
+  it('honours explicit true-like values on a boolean flag', () => {
+    for (const v of ['true', '1', 'yes', 'on', 'TRUE']) {
+      expect(parseFlags([`--verbose=${v}`], OPTIONS).verbose).toBe(true);
+    }
+  });
+
+  it('rejects an unrecognised explicit boolean value', () => {
+    expect(() => parseFlags(['--verbose=maybe'], OPTIONS)).toThrow(
+      'Flag --verbose requires a boolean value',
+    );
+    expect(() => parseFlags(['--verbose='], OPTIONS)).toThrow(
+      'Flag --verbose requires a boolean value',
+    );
   });
 });