@guanghechen/commander 4.3.0 → 4.4.0

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Change Log
 
+## 4.4.0
+
+### Minor Changes
+
+- enforce per-node help subcommand semantics
+
 ## 4.3.0
 
 ### Minor Changes

package/lib/cjs/index.cjs

@@ -613,18 +613,48 @@ class Command {
             }),
         };
     }
+    #findSubcommandEntry(token) {
+        return this.#subcommandsList.find(e => e.name === token || e.aliases.includes(token));
+    }
+    #createUnknownSubcommandError(subcommand) {
+        const commandPath = this.#getCommandPath();
+        return new CommanderError('UnknownSubcommand', `unknown subcommand "${subcommand}" for command "${commandPath}"`, commandPath);
+    }
     #processHelpSubcommand(argv) {
-        if (!this.#builtin.command.help)
-            return argv;
-        if (argv.length < 1 || argv[0] !== 'help')
-            return argv;
-        if (argv.length === 1 || this.#subcommandsList.length === 0) {
-            return ['--help'];
-        }
-        const subName = argv[1];
-        const entry = this.#subcommandsList.find(e => e.name === subName || e.aliases.includes(subName));
-        if (entry) {
-            return [subName, '--help', ...argv.slice(2)];
+        let current = this;
+        for (let i = 0; i < argv.length; ++i) {
+            const token = argv[i];
+            if (token.startsWith('-')) {
+                return argv;
+            }
+            if (token === 'help') {
+                if (!current.#builtin.command.help) {
+                    if (current.#subcommandsList.length > 0) {
+                        throw current.#createUnknownSubcommandError('help');
+                    }
+                    return argv;
+                }
+                if (current.#subcommandsList.length === 0) {
+                    return argv;
+                }
+                const target = argv[i + 1];
+                if (target === undefined) {
+                    return [...argv.slice(0, i), '--help'];
+                }
+                const targetEntry = current.#findSubcommandEntry(target);
+                if (targetEntry === undefined) {
+                    throw current.#createUnknownSubcommandError(target);
+                }
+                if (argv[i + 2] !== undefined) {
+                    throw new CommanderError('UnexpectedArgument', 'help subcommand accepts at most one subcommand argument', current.#getCommandPath());
+                }
+                return [...argv.slice(0, i), target, '--help'];
+            }
+            const entry = current.#findSubcommandEntry(token);
+            if (entry === undefined) {
+                return argv;
+            }
+            current = entry.command;
         }
         return argv;
     }
@@ -636,7 +666,7 @@ class Command {
             const token = argv[idx];
             if (token.startsWith('-'))
                 break;
-            const entry = current.#subcommandsList.find(e => e.name === token || e.aliases.includes(token));
+            const entry = current.#findSubcommandEntry(token);
             if (!entry)
                 break;
             current = entry.command;

package/lib/esm/index.mjs

@@ -591,18 +591,48 @@ class Command {
             }),
         };
     }
+    #findSubcommandEntry(token) {
+        return this.#subcommandsList.find(e => e.name === token || e.aliases.includes(token));
+    }
+    #createUnknownSubcommandError(subcommand) {
+        const commandPath = this.#getCommandPath();
+        return new CommanderError('UnknownSubcommand', `unknown subcommand "${subcommand}" for command "${commandPath}"`, commandPath);
+    }
     #processHelpSubcommand(argv) {
-        if (!this.#builtin.command.help)
-            return argv;
-        if (argv.length < 1 || argv[0] !== 'help')
-            return argv;
-        if (argv.length === 1 || this.#subcommandsList.length === 0) {
-            return ['--help'];
-        }
-        const subName = argv[1];
-        const entry = this.#subcommandsList.find(e => e.name === subName || e.aliases.includes(subName));
-        if (entry) {
-            return [subName, '--help', ...argv.slice(2)];
+        let current = this;
+        for (let i = 0; i < argv.length; ++i) {
+            const token = argv[i];
+            if (token.startsWith('-')) {
+                return argv;
+            }
+            if (token === 'help') {
+                if (!current.#builtin.command.help) {
+                    if (current.#subcommandsList.length > 0) {
+                        throw current.#createUnknownSubcommandError('help');
+                    }
+                    return argv;
+                }
+                if (current.#subcommandsList.length === 0) {
+                    return argv;
+                }
+                const target = argv[i + 1];
+                if (target === undefined) {
+                    return [...argv.slice(0, i), '--help'];
+                }
+                const targetEntry = current.#findSubcommandEntry(target);
+                if (targetEntry === undefined) {
+                    throw current.#createUnknownSubcommandError(target);
+                }
+                if (argv[i + 2] !== undefined) {
+                    throw new CommanderError('UnexpectedArgument', 'help subcommand accepts at most one subcommand argument', current.#getCommandPath());
+                }
+                return [...argv.slice(0, i), target, '--help'];
+            }
+            const entry = current.#findSubcommandEntry(token);
+            if (entry === undefined) {
+                return argv;
+            }
+            current = entry.command;
         }
         return argv;
     }
@@ -614,7 +644,7 @@ class Command {
             const token = argv[idx];
             if (token.startsWith('-'))
                 break;
-            const entry = current.#subcommandsList.find(e => e.name === token || e.aliases.includes(token));
+            const entry = current.#findSubcommandEntry(token);
             if (!entry)
                 break;
             current = entry.command;

package/lib/types/index.d.ts

@@ -224,7 +224,7 @@ interface ICommandParseResult {
     rawArgs: string[];
 }
 /** Error kinds for command parsing */
-type ICommanderErrorKind = 'InvalidOptionFormat' | 'InvalidNegativeOption' | 'NegativeOptionWithValue' | 'NegativeOptionType' | 'UnknownOption' | 'UnexpectedArgument' | 'MissingValue' | 'InvalidType' | 'UnsupportedShortSyntax' | 'OptionConflict' | 'MissingRequired' | 'InvalidChoice' | 'InvalidBooleanValue' | 'MissingRequiredArgument' | 'TooManyArguments' | 'ConfigurationError';
+type ICommanderErrorKind = 'InvalidOptionFormat' | 'InvalidNegativeOption' | 'NegativeOptionWithValue' | 'NegativeOptionType' | 'UnknownOption' | 'UnknownSubcommand' | 'UnexpectedArgument' | 'MissingValue' | 'InvalidType' | 'UnsupportedShortSyntax' | 'OptionConflict' | 'MissingRequired' | 'InvalidChoice' | 'InvalidBooleanValue' | 'MissingRequiredArgument' | 'TooManyArguments' | 'ConfigurationError';
 /** Commander error with structured information */
 declare class CommanderError extends Error {
     readonly kind: ICommanderErrorKind;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@guanghechen/commander",
-  "version": "4.3.0",
+  "version": "4.4.0",
   "description": "A minimal, type-safe command-line interface builder with fluent API",
   "author": {
     "name": "guanghechen",