@guanghechen/commander 4.7.2 → 4.7.4

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # Change Log
 
+## 4.7.4
+
+### Patch Changes
+
+- Fix commander completion metadata and negative option rules.
+  - Include built-in control options (help/version) in completion metadata.
+  - Prevent generating negative completions for reserved controls (--no-help/--no-version).
+  - Align completion option metadata with explicit type/args semantics.
+
+## 4.7.3
+
+### Patch Changes
+
+- Align commander optional/subcommand parsing with spec and keep release notes in sync. Upgrade
+  tooling dependencies and pin changesets packages to fixed versions.
+
 ## 4.7.2
 
 ### Patch Changes

package/lib/cjs/browser.cjs

@@ -294,6 +294,30 @@ function parsePrimitiveNumber(rawValue) {
     }
     return value;
 }
+function normalizeSubcommandNameForDistance(name) {
+    return camelToKebabCase(name).toLowerCase();
+}
+function levenshteinDistance(left, right) {
+    if (left === right) {
+        return 0;
+    }
+    if (left.length === 0) {
+        return right.length;
+    }
+    if (right.length === 0) {
+        return left.length;
+    }
+    let prev = Array.from({ length: right.length + 1 }, (_, i) => i);
+    for (let i = 0; i < left.length; i += 1) {
+        const current = [i + 1];
+        for (let j = 0; j < right.length; j += 1) {
+            const substitutionCost = left[i] === right[j] ? 0 : 1;
+            current[j + 1] = Math.min(current[j] + 1, prev[j + 1] + 1, prev[j] + substitutionCost);
+        }
+        prev = current;
+    }
+    return prev[right.length];
+}
 function tokenizeLongOption(arg, commandPath) {
     const eqIdx = arg.indexOf('=');
     const namePart = eqIdx !== -1 ? arg.slice(0, eqIdx) : arg;
@@ -696,7 +720,10 @@ class Command {
             const kebabLong = camelToKebabCase(opt.long);
             let sig = opt.short ? `-${opt.short}, ` : '    ';
             sig += `--${kebabLong}`;
-            if (opt.args !== 'none') {
+            if (opt.args === 'optional') {
+                sig += ' [value]';
+            }
+            else if (opt.args !== 'none') {
                 sig += ' <value>';
             }
             let desc = opt.desc;
@@ -837,7 +864,15 @@ class Command {
         return `  ${outputLabel}  ${desc}`;
     }
     getCompletionMeta() {
-        const allOptions = this.#resolveOptionPolicy().mergedOptions;
+        const optionMap = new Map();
+        for (const option of this.#resolveOptionPolicy().mergedOptions) {
+            optionMap.set(option.long, option);
+        }
+        optionMap.set('help', BUILTIN_HELP_OPTION);
+        if (this.#supportsBuiltinVersion()) {
+            optionMap.set('version', BUILTIN_VERSION_OPTION);
+        }
+        const allOptions = Array.from(optionMap.values());
         const options = [];
         const argumentsMeta = [];
         for (const opt of allOptions) {
@@ -845,7 +880,8 @@ class Command {
                 long: opt.long,
                 short: opt.short,
                 desc: opt.desc,
-                takesValue: opt.args !== 'none',
+                type: opt.type,
+                args: opt.args,
                 choices: opt.choices?.map(choice => String(choice)),
             });
         }
@@ -1315,6 +1351,14 @@ class Command {
                             consumed.push(tokens[i]);
                         }
                     }
+                    else if (opt.args === 'optional') {
+                        if (!token.resolved.includes('=') &&
+                            i + 1 < tokens.length &&
+                            tokens[i + 1].type === 'none') {
+                            i += 1;
+                            consumed.push(tokens[i]);
+                        }
+                    }
                     else if (opt.args === 'variadic') {
                         if (!token.resolved.includes('=')) {
                             while (i + 1 < tokens.length && tokens[i + 1].type === 'none') {
@@ -1340,6 +1384,12 @@ class Command {
                             consumed.push(tokens[i]);
                         }
                     }
+                    else if (opt.args === 'optional') {
+                        if (i + 1 < tokens.length && tokens[i + 1].type === 'none') {
+                            i += 1;
+                            consumed.push(tokens[i]);
+                        }
+                    }
                     else if (opt.args === 'variadic') {
                         while (i + 1 < tokens.length && tokens[i + 1].type === 'none') {
                             i += 1;
@@ -1381,6 +1431,7 @@ class Command {
                 leafLocalOpts[opt.long] = leafParsedOpts[opt.long];
             }
         }
+        leafCommand.#assertUnknownSubcommand(ctx.sources.user.argv);
         const rawArgStrings = [...argTokens.map(t => t.original), ...restArgs];
         const { args, rawArgs } = leafCommand.#parseArguments(rawArgStrings);
         const parseCtx = {
@@ -1463,6 +1514,23 @@ class Command {
                 i += 1;
                 continue;
             }
+            if (opt.args === 'optional') {
+                const eqIdx = token.resolved.indexOf('=');
+                if (eqIdx !== -1) {
+                    opts[opt.long] = this.#convertValue(opt, token.resolved.slice(eqIdx + 1));
+                    i += 1;
+                    continue;
+                }
+                if (i + 1 < tokens.length && tokens[i + 1].type === 'none') {
+                    opts[opt.long] = this.#convertValue(opt, tokens[i + 1].original);
+                    i += 1;
+                }
+                else {
+                    opts[opt.long] = undefined;
+                }
+                i += 1;
+                continue;
+            }
             if (opt.args === 'variadic') {
                 const values = Array.isArray(opts[opt.long]) ? opts[opt.long] : [];
                 const eqIdx = token.resolved.indexOf('=');
@@ -1482,7 +1550,7 @@ class Command {
             i += 1;
         }
         for (const opt of allOptions) {
-            if (opt.required && opts[opt.long] === undefined) {
+            if (opt.required && !Object.prototype.hasOwnProperty.call(opts, opt.long)) {
                 throw new CommanderError('MissingRequired', `missing required option "--${camelToKebabCase(opt.long)}"`, this.#getCommandPath());
             }
         }
@@ -1519,6 +1587,9 @@ class Command {
     #parseArguments(rawArgs) {
         const argumentDefs = this.#arguments;
         const args = {};
+        if (argumentDefs.length === 0 && rawArgs.length > 0) {
+            throw new CommanderError('UnexpectedArgument', `unexpected argument "${rawArgs[0]}"`, this.#getCommandPath());
+        }
         const missing = [];
         let remaining = rawArgs.length;
         for (const def of argumentDefs) {
@@ -1559,25 +1630,23 @@ class Command {
             }
             if (def.kind === 'some') {
                 const rest = rawArgs.slice(index);
-                if (rest.length === 0) {
-                    throw new CommanderError('MissingRequiredArgument', `missing required argument(s): ${def.name}`, this.#getCommandPath());
-                }
                 args[def.name] = rest.map(raw => this.#convertArgument(def, raw));
                 index = rawArgs.length;
                 break;
             }
-            const raw = rawArgs[index];
-            if (raw === undefined) {
-                if (def.kind === 'optional') {
+            if (def.kind === 'optional') {
+                const raw = rawArgs[index];
+                if (raw === undefined) {
                     args[def.name] = def.default ?? undefined;
                     continue;
                 }
-                throw new CommanderError('MissingRequiredArgument', `missing required argument(s): ${def.name}`, this.#getCommandPath());
-            }
-            else {
                 args[def.name] = this.#convertArgument(def, raw);
                 index += 1;
+                continue;
             }
+            const raw = rawArgs[index];
+            args[def.name] = this.#convertArgument(def, raw);
+            index += 1;
         }
         const hasRestArgument = argumentDefs.some(a => a.kind === 'variadic' || a.kind === 'some');
         if (!hasRestArgument && index < rawArgs.length) {
@@ -1611,6 +1680,50 @@ class Command {
         }
         return value;
     }
+    #assertUnknownSubcommand(userTailArgv) {
+        if (this.#subcommandsList.length === 0) {
+            return;
+        }
+        const token = userTailArgv[0];
+        if (token === undefined || token.startsWith('-') || token === 'help') {
+            return;
+        }
+        if (this.#findSubcommandEntry(token) !== undefined) {
+            return;
+        }
+        const hints = [];
+        if (this.#arguments.length === 0) {
+            hints.push(`Hint: command "${this.#getCommandPath()}" does not accept positional arguments.`);
+        }
+        const candidate = this.#resolveDidYouMeanSubcommandName(token);
+        if (candidate !== undefined) {
+            hints.push(`Hint: did you mean "${candidate}"?`);
+        }
+        const details = hints.length > 0 ? `\n${hints.join('\n')}` : '';
+        throw new CommanderError('UnknownSubcommand', `unknown subcommand "${token}" for command "${this.#getCommandPath()}"${details}`, this.#getCommandPath());
+    }
+    #resolveDidYouMeanSubcommandName(token) {
+        const source = normalizeSubcommandNameForDistance(token);
+        let minDistance = Number.POSITIVE_INFINITY;
+        let bestName;
+        let isUniqueBest = false;
+        for (const entry of this.#subcommandsList) {
+            const target = normalizeSubcommandNameForDistance(entry.name);
+            const distance = levenshteinDistance(source, target);
+            if (distance < minDistance) {
+                minDistance = distance;
+                bestName = entry.name;
+                isUniqueBest = true;
+            }
+            else if (distance === minDistance) {
+                isUniqueBest = false;
+            }
+        }
+        if (minDistance <= 2 && isUniqueBest) {
+            return bestName;
+        }
+        return undefined;
+    }
     #hasUserOption(long) {
         return this.#options.some(option => option.long === long);
     }
@@ -1654,11 +1767,9 @@ class Command {
         return optionPolicyMap;
     }
     #mustGetOptionPolicy(optionPolicyMap, cmd) {
-        const policy = optionPolicyMap.get(cmd);
-        if (policy !== undefined) {
-            return policy;
-        }
-        throw new CommanderError('ConfigurationError', `missing option policy for command "${cmd.#getCommandPath()}"`, this.#getCommandPath());
+        const policy = optionPolicyMap.get(cmd) ?? cmd.#resolveOptionPolicy();
+        optionPolicyMap.set(cmd, policy);
+        return policy;
     }
     #validateMergedShortOptions(chain, optionPolicyMap) {
         const mergedByLong = new Map();
@@ -1687,7 +1798,10 @@ class Command {
             throw new CommanderError('ConfigurationError', `boolean option "--${opt.long}" must have args: 'none'`, this.#getCommandPath());
         }
         if ((opt.type === 'string' || opt.type === 'number') && opt.args === 'none') {
-            throw new CommanderError('ConfigurationError', `${opt.type} option "--${opt.long}" must have args: 'required' or 'variadic'`, this.#getCommandPath());
+            throw new CommanderError('ConfigurationError', `${opt.type} option "--${opt.long}" must have args: 'required', 'optional', or 'variadic'`, this.#getCommandPath());
+        }
+        if (opt.type === 'number' && opt.args === 'optional') {
+            throw new CommanderError('ConfigurationError', `number option "--${opt.long}" does not support args: 'optional'`, this.#getCommandPath());
         }
         if (opt.long.startsWith('no')) {
             throw new CommanderError('ConfigurationError', `option long name cannot start with "no": "${opt.long}"`, this.#getCommandPath());
@@ -1704,6 +1818,9 @@ class Command {
         if (opt.type === 'boolean' && opt.required) {
             throw new CommanderError('ConfigurationError', `boolean option "--${opt.long}" cannot be required`, this.#getCommandPath());
         }
+        if (opt.required && opt.args !== 'required') {
+            throw new CommanderError('ConfigurationError', `required option "--${opt.long}" must use args: 'required'`, this.#getCommandPath());
+        }
     }
     #checkOptionUniqueness(opt) {
         if (this.#options.some(o => o.long === opt.long)) {