Improve subcommand usage, options inheritance and completions command management

- show app name in subcommand usage output
- stop subcommands from inheriting `description` and `defaultCommand` from parent
- prevent `gen-completions` command from being injected into subcommands or itself

Author: sigmaSd

deno.json

@@ -1,13 +1,14 @@
 {
   "name": "@sigma/parse",
-  "version": "0.52.0",
+  "version": "0.53.0",
   "exports": "./mod.ts",
   "license": "MIT",
   "tasks": {
     "test": "deno doc --lint mod.ts && deno test --doc --parallel && bun test --preload ./bun-preload.ts"
   },
   "imports": {
-    "@std/assert": "jsr:@std/assert@^1.0.18"
+    "@std/assert": "jsr:@std/assert@^1.0.18",
+    "@std/fmt": "jsr:@std/fmt@^1.0.9"
   },
   "nodeModulesDir": "auto",
   "exclude": ["./coverage"]

deno.lock

@@ -80,17 +80,21 @@ function printUsageSection(
     const fullCommandPath = commandPath || commandName;
     const hasSubCommands = subCommands && subCommands.size > 0;
 
+    const commandPrefix = appName
+      ? `${colors.cyan(appName)} ${colors.brightCyan(fullCommandPath)}`
+      : colors.brightCyan(fullCommandPath);
+
     if (hasSubCommands) {
       console.log(
-        `  ${colors.cyan(baseCommand)} ${colors.brightCyan(fullCommandPath)}${
-          colors.green(usageArgs)
-        } ${colors.yellow("<command>")} ${colors.dim("[options]")}`,
+        `  ${commandPrefix}${colors.green(usageArgs)} ${
+          colors.yellow("<command>")
+        } ${colors.dim("[options]")}`,
       );
     } else {
       console.log(
-        `  ${colors.cyan(baseCommand)} ${colors.brightCyan(fullCommandPath)}${
-          colors.green(usageArgs)
-        } ${colors.dim("[options]")}`,
+        `  ${commandPrefix}${colors.green(usageArgs)} ${
+          colors.dim("[options]")
+        }`,
       );
     }
   } else if (subCommands && subCommands.size > 0) {

src/help.ts

@@ -153,7 +153,10 @@ function parseInstanceBased(
   );
 
   // 2. Inject gen-completions command if at root
-  if (!commandPath && !subCommands.has("gen-completions")) {
+  if (
+    !commandPath && !subCommands.has("gen-completions") &&
+    instance.constructor.name !== "GenCompletionsCommand"
+  ) {
     subCommands.set("gen-completions", {
       name: "gen-completions",
       commandClass: GenCompletionsCommand,
@@ -376,7 +379,8 @@ function executeSubCommand(
 
   if (
     "parse" in commandConstructor &&
-    typeof commandConstructor.parse === "function"
+    typeof commandConstructor.parse === "function" &&
+    commandConstructor.parse !== Args.parse
   ) {
     return commandConstructor.parse(args);
   }
@@ -387,20 +391,14 @@ function executeSubCommand(
   })[Symbol.metadata];
   const subOptions = subMetadata?.__cliOptions as ParseOptions | undefined;
 
-  const mergedOptions = subOptions
-    ? { ...parentOptions, ...subOptions }
-    : (parentOptions
-      ? { ...parentOptions, defaultCommand: undefined }
-      : undefined);
-
-  if (mergedOptions) {
-    if (sub.description) {
-      mergedOptions.description = sub.description;
-    } else if (!subOptions?.description) {
-      // If neither @subCommand nor @cli provided a description, don't inherit parent's
-      mergedOptions.description = undefined;
-    }
-  }
+  const mergedOptions: ParseOptions = {
+    ...parentOptions,
+    ...subOptions,
+    // Subcommands should not inherit defaultCommand from parent
+    defaultCommand: subOptions?.defaultCommand,
+    // Subcommands should not inherit description from parent
+    description: sub.description || subOptions?.description,
+  };
 
   const parsedValues = parseInstanceBased(
     subInstance,

src/index.ts

@@ -0,0 +1,69 @@
+import {
+  Args,
+  cli,
+  command,
+  isParseError,
+  opt,
+  subCommand,
+} from "@sigma/parse";
+import { assertNotMatch, assertStringIncludes } from "@std/assert";
+import { stripAnsiCode } from "@std/fmt/colors";
+
+@command()
+class ListCommand extends Args {
+  @opt({
+    short: "r",
+    description: "Specify an installation root of scripts.",
+    type: "string",
+  })
+  root?: string;
+}
+
+@cli({
+  name: "nub",
+  description: "A command-line tool.",
+  color: true,
+  exitOnHelp: false,
+})
+class Nub extends Args {
+  @subCommand(ListCommand, { description: "List installed scripts." })
+  list?: ListCommand;
+}
+
+function getHelpOutput(args: string[]): string {
+  try {
+    Nub.parse(args);
+    return "";
+  } catch (e) {
+    if (isParseError(e)) {
+      return e.message;
+    }
+    throw e;
+  }
+}
+
+Deno.test("subcommand help shows colors", () => {
+  const helpOutput = getHelpOutput(["list", "--help"]);
+  assertStringIncludes(helpOutput, "\x1b[");
+});
+
+Deno.test("subcommand help shows correct description", () => {
+  const helpOutput = getHelpOutput(["list", "--help"]);
+  assertStringIncludes(helpOutput, "List installed scripts.");
+});
+
+Deno.test("subcommand help does not show gen-completions", () => {
+  const helpOutput = getHelpOutput(["list", "--help"]);
+  assertNotMatch(helpOutput, /gen-completions/);
+});
+
+Deno.test("root help shows gen-completions", () => {
+  const helpOutput = getHelpOutput(["--help"]);
+  assertStringIncludes(helpOutput, "gen-completions");
+});
+
+Deno.test("subcommand usage shows app name and subcommand name", () => {
+  const helpOutput = getHelpOutput(["list", "--help"]);
+  const plainOutput = stripAnsiCode(helpOutput);
+  assertStringIncludes(plainOutput, "Usage:\n  nub list [options]");
+});