Add supersedes arg support for CLI

Author: roryabraham

scripts/utils/CLI.ts

@@ -21,10 +21,13 @@ type BooleanArg = CLIArg;
  * Any other argument is provided raw in process.argv as a string.
  * It can remain a string, or can be transformed into another type by a custom `parse` function.
  * It can be optional (by providing a default) or required (no default value).
+ * It can also supersede other named arguments when provided.
  */
 type StringArg<T = unknown> = CLIArg & {
     default?: T;
     parse?: (val: string) => T;
+    supersedes?: string[];
+    required?: boolean;
 };
 
 /**
@@ -162,6 +165,8 @@ class CLI<TConfig extends CLIConfig> {
 
             const parsedNamedArgs: Partial<Writable<typeof this.namedArgs>> = {};
             const parsedPositionalArgs: Partial<Writable<typeof this.positionalArgs>> = {};
+            const providedNamedArgs = new Set<string>();
+
             let positionalIndex = 0;
             for (let i = 0; i < rawArgs.length; i++) {
                 const rawArg = rawArgs.at(i);
@@ -177,6 +182,8 @@ class CLI<TConfig extends CLIConfig> {
                         this.flags[rawArgName as keyof typeof this.flags] = true;
                     } else if (config.namedArgs && rawArgName in config.namedArgs) {
                         // Arg is a named arg
+                        providedNamedArgs.add(rawArgName);
+
                         // Grab the value from the split token, otherwise go for the next token
                         let argValueBeforeParse = '';
                         if (rawArgValue) {
@@ -205,16 +212,34 @@ class CLI<TConfig extends CLIConfig> {
                 }
             }
 
+            // Handle supercession logic
+            const supersededArgs = new Set<string>();
+            for (const [name, spec] of Object.entries(config.namedArgs ?? {})) {
+                if (providedNamedArgs.has(name) && spec.supersedes) {
+                    for (const supersededArg of spec.supersedes) {
+                        supersededArgs.add(supersededArg);
+                    }
+                }
+            }
+
             // Validate that all required args are present, assign defaults where values are not parsed
             for (const [name, spec] of Object.entries(config.namedArgs ?? {})) {
                 if (!(name in parsedNamedArgs)) {
-                    if (spec.default !== undefined) {
+                    if (supersededArgs.has(name)) {
+                        // This arg was superseded, so don't require it and don't assign a default
+                        continue;
+                    } else if (spec.default !== undefined) {
                         parsedNamedArgs[name as keyof typeof parsedNamedArgs] = spec.default as ValueOf<typeof parsedNamedArgs>;
+                    } else if (spec.required === false) {
+                        // Explicitly marked as optional, leave undefined
+                        continue;
                     } else {
+                        // Arguments without defaults are required by default (unless explicitly marked as optional)
                         throw new Error(`Missing required named argument --${name}`);
                     }
                 }
             }
+
             for (const spec of config.positionalArgs ?? []) {
                 if (!(spec.name in parsedPositionalArgs)) {
                     if (spec.default !== undefined) {
@@ -263,7 +288,8 @@ class CLI<TConfig extends CLIConfig> {
             console.log('Named Arguments:');
             for (const [name, spec] of Object.entries(namedArgs)) {
                 const defaultLabel = spec.default !== undefined ? ` (default: ${String(spec.default)})` : '';
-                console.log(`  --${name.padEnd(20)} ${spec.description}${defaultLabel}`);
+                const supersededLabel = spec.supersedes && spec.supersedes.length > 0 ? ` (supersedes: ${spec.supersedes.join(', ')})` : '';
+                console.log(`  --${name.padEnd(20)} ${spec.description}${defaultLabel}${supersededLabel}`);
             }
             console.log('');
         }

tests/unit/CLITests.ts

@@ -212,4 +212,114 @@ describe('CLI', () => {
         expect(actualOutput).toBe(expectedOutput);
         expect(mockExit).toHaveBeenCalledWith(0);
     });
+
+    it('handles supercession when superseding arg is provided', () => {
+        process.argv.push('--paths', 'common.save,errors.generic');
+        const cli = new CLI({
+            namedArgs: {
+                compareRef: {
+                    description: 'Compare reference',
+                    default: 'main',
+                },
+                paths: {
+                    description: 'Specific paths to process',
+                    parse: (val) => val.split(','),
+                    supersedes: ['compareRef'],
+                    required: false,
+                },
+            },
+        });
+
+        expect(cli.namedArgs.paths).toEqual(['common.save', 'errors.generic']);
+        expect(cli.namedArgs.compareRef).toBeUndefined();
+    });
+
+    it('uses default value when superseding arg is not provided', () => {
+        const cli = new CLI({
+            namedArgs: {
+                compareRef: {
+                    description: 'Compare reference',
+                    default: 'main',
+                },
+                paths: {
+                    description: 'Specific paths to process',
+                    parse: (val) => val.split(','),
+                    supersedes: ['compareRef'],
+                    required: false,
+                },
+            },
+        });
+
+        expect(cli.namedArgs.paths).toBeUndefined();
+        expect(cli.namedArgs.compareRef).toBe('main');
+    });
+
+    it('shows supercession information in help message', () => {
+        process.argv.push('--help');
+        expect(
+            () =>
+                new CLI({
+                    namedArgs: {
+                        compareRef: {
+                            description: 'Compare reference',
+                            default: 'main',
+                        },
+                        paths: {
+                            description: 'Specific paths to process',
+                            supersedes: ['compareRef'],
+                            required: false,
+                        },
+                    },
+                }),
+        ).toThrow('exit');
+
+        const actualOutput = mockLog.mock.calls.flat().join('\n');
+        expect(actualOutput).toContain('(supersedes: compareRef)');
+        expect(mockExit).toHaveBeenCalledWith(0);
+    });
+
+    it('handles multiple superseded args', () => {
+        process.argv.push('--priority', 'high');
+        const cli = new CLI({
+            namedArgs: {
+                lowPriority: {
+                    description: 'Low priority mode',
+                    default: 'enabled',
+                },
+                mediumPriority: {
+                    description: 'Medium priority mode',
+                    default: 'enabled',
+                },
+                priority: {
+                    description: 'Priority level',
+                    supersedes: ['lowPriority', 'mediumPriority'],
+                    required: false,
+                },
+            },
+        });
+
+        expect(cli.namedArgs.priority).toBe('high');
+        expect(cli.namedArgs.lowPriority).toBeUndefined();
+        expect(cli.namedArgs.mediumPriority).toBeUndefined();
+    });
+
+    it('requires superseded args when superseding arg is not provided', () => {
+        expect(
+            () =>
+                new CLI({
+                    namedArgs: {
+                        compareRef: {
+                            description: 'Compare reference',
+                            // No default value
+                        },
+                        paths: {
+                            description: 'Specific paths to process',
+                            supersedes: ['compareRef'],
+                            required: false,
+                        },
+                    },
+                }),
+        ).toThrow();
+        expect(mockError).toHaveBeenCalledWith('Missing required named argument --compareRef');
+    });
 });