fix(cli): suggest nested subcommands under their parent path

`varlock proxy strat` suggested `varlock start`, which does not exist. The lookup
fails under a parent path, so a bare candidate is not runnable on its own. Use the
`commandPath` the error carries for both the suggestion and the help pointer, so
`varlock proxy strat` now suggests `varlock proxy start` and points at
`varlock proxy --help`.

Also filters gunshi's `(anonymous)` entry-command placeholder out of the candidate
list, so it can never be offered as a suggestion.

Author: theoephraim

packages/varlock/src/cli/helpers/test/validation-errors.test.ts

@@ -17,11 +17,13 @@ const unknownOption = (rawName: string, candidates: Array<string>) => ({
 class CommandNotFoundError extends Error {
   commandName: string;
   candidates: Array<string>;
-  constructor(commandName: string, candidates: Array<string>) {
+  commandPath: Array<string>;
+  constructor(commandName: string, candidates: Array<string>, commandPath: Array<string> = []) {
     super(`Command not found: ${commandName}`);
     this.name = 'CommandNotFoundError';
     this.commandName = commandName;
     this.candidates = candidates;
+    this.commandPath = commandPath;
   }
 }
 
@@ -106,6 +108,24 @@ describe('toCliExitError', () => {
     expect(out).toContain('varlock load');
   });
 
+  it('suggests a nested subcommand under its parent path, so the advice is runnable', () => {
+    // `varlock proxy strat` must not suggest `varlock start`, which does not exist
+    const error = new AggregateError([new CommandNotFoundError('strat', ['start', 'run'], ['proxy'])]);
+    const out = toCliExitError(error, ['proxy', 'strat']).getFormattedOutput();
+
+    expect(out).toContain('Invalid subcommand: strat');
+    expect(out).toContain('varlock proxy start');
+    expect(out).not.toMatch(/Did you mean\s+\S*varlock start/);
+    // and point at the help for the level that actually failed
+    expect(out).toContain('varlock proxy --help');
+  });
+
+  it('never suggests the anonymous entry command', () => {
+    const error = new AggregateError([new CommandNotFoundError('anonymou', ['(anonymous)', 'load'])]);
+    const out = toCliExitError(error, ['anonymou']).getFormattedOutput();
+    expect(out).not.toContain('(anonymous)');
+  });
+
   it('passes through other validation errors (bad enum, wrong type)', () => {
     const error = new AggregateError([new Error("Optional argument '--format' should be chosen from 'enum' [\"json\"] values")]);
     const out = toCliExitError(error, ['load', '--format']).getFormattedOutput();

packages/varlock/src/cli/helpers/validation-errors.ts

@@ -19,8 +19,13 @@ type UnknownOptionError = {
 type CommandNotFoundError = {
   commandName: string;
   candidates: Array<string>;
+  /** parent path the lookup failed under: `['proxy']` for `varlock proxy strat`, `[]` at the top level */
+  commandPath?: Array<string>;
 };
 
+/** gunshi's placeholder name for the unnamed entry command; never something to suggest */
+const ANONYMOUS_COMMAND_NAME = '(anonymous)';
+
 /**
  * Levenshtein distance, kept dependency-free for the "did you mean" suggestion.
  *
@@ -110,6 +115,7 @@ export function toCliExitError(error: AggregateError, args: Array<string>): CliE
   const unknownFlags: Array<string> = [];
   const details: Array<string> = [];
   let notFoundCommand: string | undefined;
+  let notFoundParentPath: Array<string> = [];
 
   for (const err of error.errors) {
     const unknownOption = asUnknownOptionError(err);
@@ -124,8 +130,15 @@ export function toCliExitError(error: AggregateError, args: Array<string>): CliE
     const commandNotFound = asCommandNotFoundError(err);
     if (commandNotFound) {
       notFoundCommand = commandNotFound.commandName;
-      const suggestion = suggestClosest(commandNotFound.commandName, commandNotFound.candidates ?? []);
-      if (suggestion) details.push(`Did you mean ${fmt.command(`varlock ${suggestion}`)}?`);
+      // the lookup happens under a parent path, so a bare candidate is not runnable on its
+      // own: `varlock proxy strat` must suggest `varlock proxy start`, not `varlock start`
+      notFoundParentPath = commandNotFound.commandPath ?? [];
+      const candidates = (commandNotFound.candidates ?? []).filter((c) => c !== ANONYMOUS_COMMAND_NAME);
+      const suggestion = suggestClosest(commandNotFound.commandName, candidates);
+      if (suggestion) {
+        const fullCommand = ['varlock', ...notFoundParentPath, suggestion].join(' ');
+        details.push(`Did you mean ${fmt.command(fullCommand)}?`);
+      }
       continue;
     }
 
@@ -142,9 +155,11 @@ export function toCliExitError(error: AggregateError, args: Array<string>): CliE
   }
 
   if (notFoundCommand !== undefined) {
+    // point at the help for the level that actually failed (`varlock proxy --help`)
+    const notFoundHelp = ['varlock', ...notFoundParentPath, '--help'].join(' ');
     return new CliExitError(`Invalid subcommand: ${notFoundCommand}`, {
       details: details.length ? details : undefined,
-      suggestion: `Run \`${fmt.command('varlock --help', { jsPackageManager: true })}\` for more info.`,
+      suggestion: `Run \`${fmt.command(notFoundHelp, { jsPackageManager: true })}\` for more info.`,
     });
   }