feat(cli-forge,parser): add strict mode to parser and CLI

Copilot · AgentEnder · AgentEnder · commit d9299d70038b · 2025-12-23T19:02:22.000-05:00
Co-authored-by: AgentEnder &lt;6933928+AgentEnder@users.noreply.github.com&gt;

Fix examples and e2e tests for strict mode

Co-authored-by: AgentEnder &lt;6933928+AgentEnder@users.noreply.github.com&gt;

Simplify strict mode condition check

Co-authored-by: AgentEnder &lt;6933928+AgentEnder@users.noreply.github.com&gt;

Add .strict() method to parser and support .strict(false)

Co-authored-by: AgentEnder &lt;6933928+AgentEnder@users.noreply.github.com&gt;

Add explicit .strict(false) to non-strict-mode example

Co-authored-by: AgentEnder &lt;6933928+AgentEnder@users.noreply.github.com&gt;
diff --git a/e2e/run-examples.ts b/e2e/run-examples.ts
@@ -87,6 +87,8 @@ function runExampleCommand(
 ) {
   const command = typeof config === 'string' ? config : config.command;
   const env = typeof config === 'string' ? {} : config.env;
+  const expectedExitCode = typeof config === 'string' ? 0 : config.exitCode ?? 0;
+  
   try {
     process.stdout.write('▶️ ' + label);
     const a = performance.now();
@@ -96,6 +98,16 @@ function runExampleCommand(
       cwd,
     }).toString();
     const b = performance.now();
+    
+    // Check if we expected the command to succeed (exit code 0)
+    if (expectedExitCode !== 0) {
+      // If we expected a non-zero exit code but got success, that's an error
+      process.stdout.write('\r');
+      console.log(`❌ ${label}`.padEnd(process.stdout.columns, ' '));
+      console.log(`Expected exit code ${expectedExitCode} but got 0`);
+      return false;
+    }
+    
     checkAssertions(output, config.assertions);
     // move cursor to the beginning of the line
     process.stdout.write('\r');
@@ -106,7 +118,28 @@ function runExampleCommand(
       )
     );
   } catch (e) {
-    // move cursor to the beginning of the line
+    // Command failed - check if this was expected
+    const actualExitCode = e.status ?? 1;
+    const output = (e.stdout?.toString() || '') + (e.stderr?.toString() || '');
+    
+    if (actualExitCode === expectedExitCode) {
+      // Expected failure - check assertions on the error output
+      try {
+        checkAssertions(output, config.assertions);
+        process.stdout.write('\r');
+        console.log(
+          `✅ ${label} (expected failure)`.padEnd(process.stdout.columns, ' ')
+        );
+        return true;
+      } catch (assertionError) {
+        process.stdout.write('\r');
+        console.log(`❌ ${label}`.padEnd(process.stdout.columns, ' '));
+        console.log(assertionError.toString());
+        return false;
+      }
+    }
+    
+    // Unexpected failure
     process.stdout.write('\r');
     console.log(`❌ ${label}`.padEnd(process.stdout.columns, ' '));
 
diff --git a/examples/non-strict-mode.ts b/examples/non-strict-mode.ts
@@ -0,0 +1,43 @@
+// ---
+// id: non-strict-mode
+// title: Non-Strict Mode (Default)
+// description: |
+//   This example demonstrates the default behavior without strict mode.
+//   Unmatched arguments are collected in the `unmatched` array and don't cause errors.
+// commands:
+//   - command: '{filename} --name World'
+//     assertions:
+//       - contains: 'Hello, World!'
+//       - contains: 'Unmatched: []'
+//   - command: '{filename} --name World --unknown arg extra'
+//     assertions:
+//       - contains: 'Hello, World!'
+//       - contains: "--unknown"
+//       - contains: "arg"
+//       - contains: "extra"
+// ---
+import cliForge from 'cli-forge';
+
+const cli = cliForge('non-strict-mode-example')
+  // Strict mode is disabled by default
+  .strict(false)
+  .option('name', {
+    type: 'string',
+    description: 'The name to greet',
+    default: 'World',
+  })
+  .command('$0', {
+    builder: (args) => args,
+    handler: (args) => {
+      console.log(`Hello, ${args.name}!`);
+      console.log('Unmatched:', args.unmatched);
+    },
+  });
+
+export default cli;
+
+if (require.main === module) {
+  (async () => {
+    await cli.forge();
+  })();
+}
diff --git a/examples/strict-mode.ts b/examples/strict-mode.ts
@@ -0,0 +1,40 @@
+// ---
+// id: strict-mode
+// title: Strict Mode
+// description: |
+//   This example demonstrates how to use strict mode to ensure that all arguments are recognized.
+//   Strict mode throws a validation error when unmatched arguments are encountered.
+// commands:
+//   - command: '{filename} --name World'
+//     assertions:
+//       - contains: 'Hello, World!'
+//   - command: '{filename} --name World --unknown arg'
+//     assertions:
+//       - contains: 'Unknown argument: --unknown'
+//       - contains: 'Unknown argument: arg'
+//     exitCode: 1
+// ---
+import cliForge from 'cli-forge';
+
+const cli = cliForge('strict-mode-example')
+  // Enable strict mode - unmatched arguments will throw validation errors
+  .strict()
+  .option('name', {
+    type: 'string',
+    description: 'The name to greet',
+    default: 'World',
+  })
+  .command('$0', {
+    builder: (args) => args,
+    handler: (args) => {
+      console.log(`Hello, ${args.name}!`);
+    },
+  });
+
+export default cli;
+
+if (require.main === module) {
+  (async () => {
+    await cli.forge();
+  })();
+}
diff --git a/packages/cli-forge/src/lib/internal-cli.spec.ts b/packages/cli-forge/src/lib/internal-cli.spec.ts
@@ -343,4 +343,40 @@ describe('cliForge', () => {
       // - 'bar' handler
     ]);
   });
+
+  it('should support strict mode', async () => {
+    const mock = mockConsoleLog();
+    
+    try {
+      await cli('test')
+        .strict()
+        .option('foo', { type: 'string' })
+        .forge(['--foo', 'hello', '--unknown', 'arg']);
+    } catch (e) {
+      // Expected to throw
+    }
+
+    const output = mock.getOutput();
+    expect(output).toContain('Unknown argument: --unknown');
+    expect(output).toContain('Unknown argument: arg');
+    mock.restore();
+  });
+
+  it('should allow disabling strict mode via .strict(false)', async () => {
+    let captured: any;
+    
+    await cli('test')
+      .strict(false)
+      .option('foo', { type: 'string' })
+      .command('$0', {
+        builder: (args) => args,
+        handler: (args) => {
+          captured = args;
+        },
+      })
+      .forge(['--foo', 'hello', '--unknown', 'arg']);
+
+    expect(captured.foo).toBe('hello');
+    expect(captured.unmatched).toEqual(['--unknown', 'arg']);
+  });
 });
diff --git a/packages/cli-forge/src/lib/internal-cli.ts b/packages/cli-forge/src/lib/internal-cli.ts
@@ -360,6 +360,11 @@ export class InternalCLI<
     return this as unknown as CLI<TArgs, THandlerReturn, TChildren, TParent>;
   }
 
+  strict(enable = true): CLI<TArgs, THandlerReturn, TChildren, TParent> {
+    this.parser.options.strict = enable;
+    return this as unknown as CLI<TArgs, THandlerReturn, TChildren, TParent>;
+  }
+
   usage(usageText: string): CLI<TArgs, THandlerReturn, TChildren, TParent> {
     this.configuration ??= {};
     this.configuration.usage = usageText;
diff --git a/packages/cli-forge/src/lib/public-api.ts b/packages/cli-forge/src/lib/public-api.ts
@@ -676,6 +676,15 @@ export interface CLI<
    */
   demandCommand(): CLI<TArgs, THandlerReturn, TChildren, TParent>;
 
+  /**
+   * Enables or disables strict mode. When strict mode is enabled, the parser throws a validation error
+   * when unmatched arguments are encountered. Unmatched arguments are those that don't match any
+   * configured option or positional argument.
+   * @param enable Whether to enable strict mode. Defaults to true.
+   * @returns Updated CLI instance.
+   */
+  strict(enable?: boolean): CLI<TArgs, THandlerReturn, TChildren, TParent>;
+
   /**
    * Sets the usage text for the CLI. This text will be displayed in place of the default usage text
    * @param usageText Text displayed in place of the default usage text for `--help` and in generated docs.
diff --git a/packages/parser/src/lib/parser.spec.ts b/packages/parser/src/lib/parser.spec.ts
@@ -283,6 +283,57 @@ describe('parser', () => {
     });
   });
 
+  it('should throw error in strict mode when unmatched arguments are present', () => {
+    expect(() =>
+      parser({ strict: true })
+        .option('foo', { type: 'string' })
+        .parse(['--foo', 'hello', 'world'])
+    ).toThrowAggregateErrorContaining('Unknown argument: world');
+  });
+
+  it('should throw error in strict mode for unmatched flags', () => {
+    expect(() =>
+      parser({ strict: true })
+        .option('foo', { type: 'string' })
+        .parse(['--foo', 'hello', '--bar', '42'])
+    ).toThrowAggregateErrorContaining('Unknown argument: --bar', 'Unknown argument: 42');
+  });
+
+  it('should not throw error in strict mode when all arguments are matched', () => {
+    expect(
+      parser({ strict: true })
+        .option('foo', { type: 'string' })
+        .option('bar', { type: 'number' })
+        .parse(['--foo', 'hello', '--bar', '42'])
+    ).toEqual({ foo: 'hello', bar: 42, unmatched: [] });
+  });
+
+  it('should allow strict mode to be disabled (default behavior)', () => {
+    expect(
+      parser({ strict: false })
+        .option('foo', { type: 'string' })
+        .parse(['--foo', 'hello', 'world'])
+    ).toEqual({ foo: 'hello', unmatched: ['world'] });
+  });
+
+  it('should allow enabling strict mode via .strict() method', () => {
+    expect(() =>
+      parser()
+        .option('foo', { type: 'string' })
+        .strict()
+        .parse(['--foo', 'hello', 'world'])
+    ).toThrowAggregateErrorContaining('Unknown argument: world');
+  });
+
+  it('should allow disabling strict mode via .strict(false) method', () => {
+    expect(
+      parser({ strict: true })
+        .option('foo', { type: 'string' })
+        .strict(false)
+        .parse(['--foo', 'hello', 'world'])
+    ).toEqual({ foo: 'hello', unmatched: ['world'] });
+  });
+
   it('should have correct types with coerce', () => {
     const parsed = parser()
       .option('foo', { type: 'string', coerce: (s) => Number(s) })
diff --git a/packages/parser/src/lib/parser.ts b/packages/parser/src/lib/parser.ts
@@ -84,6 +84,12 @@ export type ParserOptions<T extends ParsedArgs = ParsedArgs> = {
     tokens: string[],
     parser: ArgvParser<T>
   ) => boolean;
+
+  /**
+   * When set to true, throws a validation error if any unmatched arguments are encountered.
+   * Unmatched arguments are those that don't match any configured option or positional argument.
+   */
+  strict?: boolean;
 };
 
 export interface ReadonlyArgvParser<TArgs extends ParsedArgs> {
@@ -154,6 +160,7 @@ export class ArgvParser<
     this.options = {
       extraParsers: {},
       unmatchedParser: () => false,
+      strict: false,
       ...options,
     };
     this.parserMap = {
@@ -614,6 +621,17 @@ export class ArgvParser<
       }
     }
 
+    // Validate strict mode - check for unmatched arguments
+    if (this.options.strict && result.unmatched?.length) {
+      for (const unmatchedArg of result.unmatched) {
+        const error = new Error(
+          `Unknown argument: ${unmatchedArg}`
+        );
+        delete error.stack;
+        errors.push(error);
+      }
+    }
+
     if (errors.length) {
       const error = new ValidationFailedError<TArgs>(
         errors.map((error) =>
@@ -728,6 +746,18 @@ export class ArgvParser<
     return this;
   }
 
+  /**
+   * Enables or disables strict mode. When strict mode is enabled, the parser throws a validation error
+   * when unmatched arguments are encountered. Unmatched arguments are those that don't match any
+   * configured option or positional argument.
+   * @param enable Whether to enable strict mode. Defaults to true.
+   * @returns The parser instance for method chaining.
+   */
+  strict(enable = true) {
+    this.options.strict = enable;
+    return this;
+  }
+
   /**
    * Used to combine two parsers into a single parser. Mutates `this`, but returns with updated typings
    * @param parser The parser to augment the current parser with.
diff --git a/tools/scripts/collect-examples.ts b/tools/scripts/collect-examples.ts
@@ -10,6 +10,7 @@ export type CommandConfiguration = {
   command: string;
   env: Record<string, string>;
   assertions?: Array<{ contains?: string }>;
+  exitCode?: number;
 };
 
 export type FrontMatter = {
