feat: add strictFlags option to reject unknown flags with suggestions

Author: privatenumber

package.json

@@ -58,6 +58,7 @@
 		"@types/node": "^24.9.2",
 		"clean-pkg-json": "^1.3.0",
 		"expect-type": "^1.2.2",
+		"fastest-levenshtein": "^1.0.16",
 		"kolorist": "^1.8.0",
 		"lintroll": "^1.24.2",
 		"manten": "^1.5.0",

pnpm-lock.yaml

@@ -1,4 +1,5 @@
 import { typeFlag } from 'type-flag';
+import { closest, distance } from 'fastest-levenshtein';
 import type {
 	CallbackFunction,
 	CliOptions,
@@ -117,6 +118,52 @@ function helpEnabled(help: false | undefined | HelpOptions): help is (HelpOption
 	return help !== false;
 }
 
+const getKnownFlagNames = (flags: Record<string, unknown>): string[] => {
+	const names: string[] = [];
+	for (const [name, config] of Object.entries(flags)) {
+		names.push(name);
+		if (config && typeof config === 'object' && 'alias' in config) {
+			const { alias } = config as { alias?: string | string[] };
+			if (typeof alias === 'string' && alias) {
+				names.push(alias);
+			} else if (Array.isArray(alias)) {
+				names.push(...alias.filter(Boolean));
+			}
+		}
+	}
+	return names;
+};
+
+const findClosestFlag = (
+	unknown: string,
+	knownFlags: string[],
+): string | undefined => {
+	// Don't suggest for very short flags (e.g. -a vs -b)
+	if (unknown.length < 3 || knownFlags.length === 0) {
+		return undefined;
+	}
+	const match = closest(unknown, knownFlags);
+	return distance(unknown, match) <= 2 ? match : undefined;
+};
+
+const handleUnknownFlags = (
+	unknownFlags: Record<string, unknown>,
+	knownFlagNames: string[],
+): void => {
+	const unknownFlagNames = Object.keys(unknownFlags);
+	if (unknownFlagNames.length === 0) {
+		return;
+	}
+
+	for (const flag of unknownFlagNames) {
+		const closestMatch = findClosestFlag(flag, knownFlagNames);
+		const suggestion = closestMatch ? ` (did you mean --${closestMatch}?)` : '';
+		console.error(`Error: Unknown flag --${flag}${suggestion}`);
+	}
+
+	process.exit(1);
+};
+
 function cliBase<
 	CommandName extends string | undefined,
 	Options extends CliOptionsInternal,
@@ -199,6 +246,13 @@ function cliBase<
 		return process.exit(0);
 	}
 
+	// Check for unknown flags if strictFlags is enabled
+	// Inherit from parent if not explicitly set
+	const strictFlags = options.strictFlags ?? options.parent?.strictFlags;
+	if (strictFlags) {
+		handleUnknownFlags(parsed.unknownFlags, getKnownFlagNames(flags));
+	}
+
 	if (options.parameters) {
 		let { parameters } = options;
 		let cliArguments = parsed._ as string[];

src/cli.ts

@@ -44,6 +44,13 @@ export type CommandOptions<Parameters = string[]> = {
 	 * Which argv elements to ignore from parsing
 	 */
 	ignoreArgv?: IgnoreFunction;
+
+	/**
+	 * When enabled, prints an error and exits if unknown flags are passed.
+	 * Suggests the closest matching flag name when possible.
+	 * Inherits from parent CLI if not specified.
+	 */
+	strictFlags?: boolean;
 };
 
 export function command<

src/command.ts

@@ -133,6 +133,12 @@ export type CliOptions<
 	 * Which argv elements to ignore from parsing
 	 */
 	ignoreArgv?: IgnoreFunction;
+
+	/**
+	 * When enabled, prints an error and exits if unknown flags are passed.
+	 * Suggests the closest matching flag name when possible.
+	 */
+	strictFlags?: boolean;
 };
 
 export type CliOptionsInternal<

src/types.ts

@@ -1,6 +1,7 @@
 import { setImmediate } from 'node:timers/promises';
 import { testSuite, expect } from 'manten';
 import { spy } from 'nanospy';
+import { mockEnvFunctions } from '../utils/mock-env-functions';
 import { cli, command } from '#cleye';
 
 export default testSuite(({ describe }) => {
@@ -441,5 +442,83 @@ export default testSuite(({ describe }) => {
 				expect(cliResolved).toBe(false);
 			});
 		});
+
+		describe('strictFlags inheritance', ({ test }) => {
+			test('command inherits strictFlags from parent', () => {
+				const mocked = mockEnvFunctions();
+
+				const buildCommand = command({
+					name: 'build',
+					flags: {
+						watch: Boolean,
+					},
+				});
+
+				cli(
+					{
+						strictFlags: true,
+						commands: [buildCommand],
+					},
+					undefined,
+					['build', '--wathc'],
+				);
+				mocked.restore();
+
+				expect(mocked.consoleError.called).toBe(true);
+				expect(mocked.consoleError.calls[0][0]).toContain('--wathc');
+				expect(mocked.consoleError.calls[0][0]).toContain('--watch');
+				expect(mocked.processExit.calls).toStrictEqual([[1]]);
+			});
+
+			test('command can override strictFlags to false', () => {
+				const mocked = mockEnvFunctions();
+
+				const buildCommand = command({
+					name: 'build',
+					flags: {
+						watch: Boolean,
+					},
+					strictFlags: false,
+				});
+
+				const parsed = cli(
+					{
+						strictFlags: true,
+						commands: [buildCommand],
+					},
+					undefined,
+					['build', '--unknown'],
+				);
+				mocked.restore();
+
+				expect(mocked.consoleError.called).toBe(false);
+				expect(mocked.processExit.called).toBe(false);
+				expect(parsed.unknownFlags.unknown).toEqual([true]);
+			});
+
+			test('command can enable strictFlags independently', () => {
+				const mocked = mockEnvFunctions();
+
+				const buildCommand = command({
+					name: 'build',
+					flags: {
+						watch: Boolean,
+					},
+					strictFlags: true,
+				});
+
+				cli(
+					{
+						commands: [buildCommand],
+					},
+					undefined,
+					['build', '--wathc'],
+				);
+				mocked.restore();
+
+				expect(mocked.consoleError.called).toBe(true);
+				expect(mocked.processExit.calls).toStrictEqual([[1]]);
+			});
+		});
 	});
 });

tests/specs/command.ts

@@ -376,5 +376,161 @@ export default testSuite(({ describe }) => {
 				expect(parsed.unknownFlags.unknown2).toEqual([true]);
 			});
 		});
+
+		describe('strictFlags', ({ test }) => {
+			test('errors on unknown flag', () => {
+				const mocked = mockEnvFunctions();
+				cli(
+					{
+						flags: {
+							verbose: Boolean,
+						},
+						strictFlags: true,
+					},
+					undefined,
+					['--unknown'],
+				);
+				mocked.restore();
+
+				expect(mocked.consoleError.called).toBe(true);
+				expect(mocked.consoleError.calls[0][0]).toContain('Unknown flag');
+				expect(mocked.consoleError.calls[0][0]).toContain('--unknown');
+				expect(mocked.processExit.calls).toStrictEqual([[1]]);
+			});
+
+			test('suggests closest match when within distance 2', () => {
+				const mocked = mockEnvFunctions();
+				cli(
+					{
+						flags: {
+							verbose: Boolean,
+						},
+						strictFlags: true,
+					},
+					undefined,
+					['--verbos'], // Missing 'e'
+				);
+				mocked.restore();
+
+				expect(mocked.consoleError.calls[0][0]).toContain('--verbose');
+				expect(mocked.consoleError.calls[0][0]).toMatch(/did you mean/i);
+			});
+
+			test('no suggestion when flag is too different', () => {
+				const mocked = mockEnvFunctions();
+				cli(
+					{
+						flags: {
+							verbose: Boolean,
+						},
+						strictFlags: true,
+					},
+					undefined,
+					['--xyz'],
+				);
+				mocked.restore();
+
+				expect(mocked.consoleError.calls[0][0]).not.toMatch(/did you mean/i);
+			});
+
+			test('no suggestion for very short unknown flags', () => {
+				const mocked = mockEnvFunctions();
+				cli(
+					{
+						flags: {
+							ab: Boolean,
+							ac: Boolean,
+						},
+						strictFlags: true,
+					},
+					undefined,
+					['--ad'], // Short unknown flag (2 chars) shouldn't get suggestions
+				);
+				mocked.restore();
+
+				expect(mocked.consoleError.called).toBe(true);
+				expect(mocked.consoleError.calls[0][0]).toContain('--ad');
+				expect(mocked.consoleError.calls[0][0]).not.toMatch(/did you mean/i);
+			});
+
+			test('reports multiple unknown flags', () => {
+				const mocked = mockEnvFunctions();
+				cli(
+					{
+						flags: {
+							verbose: Boolean,
+							output: String,
+						},
+						strictFlags: true,
+					},
+					undefined,
+					['--verbos', '--outpu'],
+				);
+				mocked.restore();
+
+				expect(mocked.consoleError.callCount).toBe(2);
+				expect(mocked.consoleError.calls[0][0]).toContain('--verbos');
+				expect(mocked.consoleError.calls[1][0]).toContain('--outpu');
+			});
+
+			test('known flags still work', () => {
+				const mocked = mockEnvFunctions();
+				const parsed = cli(
+					{
+						flags: {
+							verbose: Boolean,
+							output: String,
+						},
+						strictFlags: true,
+					},
+					undefined,
+					['--verbose', '--output', 'file.txt'],
+				);
+				mocked.restore();
+
+				expect(mocked.consoleError.called).toBe(false);
+				expect(mocked.processExit.called).toBe(false);
+				expect(parsed.flags.verbose).toBe(true);
+				expect(parsed.flags.output).toBe('file.txt');
+			});
+
+			test('strictFlags disabled by default', () => {
+				const mocked = mockEnvFunctions();
+				const parsed = cli(
+					{
+						flags: {
+							verbose: Boolean,
+						},
+					},
+					undefined,
+					['--unknown'],
+				);
+				mocked.restore();
+
+				expect(mocked.consoleError.called).toBe(false);
+				expect(mocked.processExit.called).toBe(false);
+				expect(parsed.unknownFlags.unknown).toEqual([true]);
+			});
+
+			test('suggests flag aliases', () => {
+				const mocked = mockEnvFunctions();
+				cli(
+					{
+						flags: {
+							verbose: {
+								type: Boolean,
+								alias: 'v',
+							},
+						},
+						strictFlags: true,
+					},
+					undefined,
+					['--verbos'],
+				);
+				mocked.restore();
+
+				expect(mocked.consoleError.calls[0][0]).toContain('--verbose');
+			});
+		});
 	});
 });