@guanghechen/commander 4.7.3 → 4.7.4

package/CHANGELOG.md

@@ -1,5 +1,14 @@
 # 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

package/lib/cjs/browser.cjs

@@ -864,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) {
@@ -872,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)),
             });
         }

package/lib/cjs/node.cjs

@@ -877,7 +877,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) {
@@ -885,7 +893,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)),
             });
         }
@@ -2133,6 +2142,12 @@ class Coerce {
 function camelToKebabCase(str) {
     return str.replace(/[A-Z]/g, m => '-' + m.toLowerCase());
 }
+function canGenerateNegativeCompletion(opt) {
+    return (opt.type === 'boolean' && opt.args === 'none' && opt.long !== 'help' && opt.long !== 'version');
+}
+function optionTakesValue(opt) {
+    return opt.args !== 'none';
+}
 const COMPLETION_SHELL_STATE = Symbol('completion-shell-state');
 function getCommandPath(ctx) {
     const names = ctx.chain
@@ -2295,7 +2310,7 @@ class BashCompletion {
             if (opt.short)
                 optParts.push(this.#escapeWord(`-${opt.short}`));
             optParts.push(this.#escapeWord(`--${kebabLong}`));
-            if (!opt.takesValue) {
+            if (canGenerateNegativeCompletion(opt)) {
                 optParts.push(this.#escapeWord(`--no-${kebabLong}`));
             }
         }
@@ -2327,7 +2342,7 @@ class BashCompletion {
         return words.map(choice => this.#escapeWord(choice)).join(' ');
     }
     #appendChoiceLogicForCommand(lines, indent, cmd, depth) {
-        const valueOptions = cmd.options.filter(opt => opt.takesValue);
+        const valueOptions = cmd.options.filter(optionTakesValue);
         const valueOptionsWithChoices = valueOptions.filter(opt => opt.choices && opt.choices.length > 0);
         const valueLongPatterns = valueOptions.map(opt => `--${camelToKebabCase(opt.long)}`);
         const valueShortPatterns = valueOptions
@@ -2454,7 +2469,7 @@ class FishCompletion {
                 line += ` -xa '${opt.choices.map(choice => this.#escapeChoice(choice)).join(' ')}'`;
             }
             lines.push(line);
-            if (!opt.takesValue) {
+            if (canGenerateNegativeCompletion(opt)) {
                 let noLine = `complete -c ${this.#programName}`;
                 if (condition)
                     noLine += ` -n '${condition}'`;
@@ -2464,11 +2479,11 @@ class FishCompletion {
             }
         }
         const valueOptionLongs = cmd.options
-            .filter(opt => opt.takesValue)
+            .filter(optionTakesValue)
             .map(opt => camelToKebabCase(opt.long))
             .join(',');
         const valueOptionShorts = cmd.options
-            .filter(opt => opt.takesValue && opt.short)
+            .filter(opt => optionTakesValue(opt) && opt.short)
             .map(opt => opt.short)
             .join(',');
         const argCount = cmd.arguments.length;
@@ -2667,7 +2682,7 @@ class PwshCompletion {
             '    if ($token.StartsWith("--")) {',
             '      if ($token.Contains("=")) { continue }',
             '      foreach ($opt in $cmd.options) {',
-            '        if ($token -eq "--$($opt.long)" -and $opt.takesValue) {',
+            '        if ($token -eq "--$($opt.long)" -and $opt.args -ne "none") {',
             '          $expectValue = $true',
             '          break',
             '        }',
@@ -2677,7 +2692,7 @@ class PwshCompletion {
             '    if ($token.StartsWith("-") -and $token -ne "-") {',
             '      if ($token.Length -eq 2) {',
             '        foreach ($opt in $cmd.options) {',
-            '          if ($opt.short -and $token -eq "-$($opt.short)" -and $opt.takesValue) {',
+            '          if ($opt.short -and $token -eq "-$($opt.short)" -and $opt.args -ne "none") {',
             '            $expectValue = $true',
             '            break',
             '          }',
@@ -2729,7 +2744,7 @@ class PwshCompletion {
             '          $opt.description',
             '        )',
             '      }',
-            '      if ($opt.isBoolean -and "--no-$($opt.long)" -like "$current*") {',
+            '      if ($opt.canNegate -and "--no-$($opt.long)" -like "$current*") {',
             '        $completions += [System.Management.Automation.CompletionResult]::new(',
             '          "--no-$($opt.long)",',
             '          "no-$($opt.long)",',
@@ -2779,8 +2794,9 @@ class PwshCompletion {
                 lines.push(`${indent}    short = '${opt.short}'`);
             lines.push(`${indent}    long = '${kebabLong}'`);
             lines.push(`${indent}    description = '${this.#escape(opt.desc)}'`);
-            lines.push(`${indent}    isBoolean = $${!opt.takesValue}`);
-            lines.push(`${indent}    takesValue = $${opt.takesValue}`);
+            lines.push(`${indent}    type = '${opt.type}'`);
+            lines.push(`${indent}    args = '${opt.args}'`);
+            lines.push(`${indent}    canNegate = $${canGenerateNegativeCompletion(opt)}`);
             if (opt.choices) {
                 lines.push(`${indent}    choices = @('${opt.choices
                     .map(choice => this.#escape(choice))

package/lib/esm/browser.mjs

@@ -862,7 +862,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) {
@@ -870,7 +878,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)),
             });
         }

package/lib/esm/node.mjs

@@ -875,7 +875,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) {
@@ -883,7 +891,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)),
             });
         }
@@ -2131,6 +2140,12 @@ class Coerce {
 function camelToKebabCase(str) {
     return str.replace(/[A-Z]/g, m => '-' + m.toLowerCase());
 }
+function canGenerateNegativeCompletion(opt) {
+    return (opt.type === 'boolean' && opt.args === 'none' && opt.long !== 'help' && opt.long !== 'version');
+}
+function optionTakesValue(opt) {
+    return opt.args !== 'none';
+}
 const COMPLETION_SHELL_STATE = Symbol('completion-shell-state');
 function getCommandPath(ctx) {
     const names = ctx.chain
@@ -2293,7 +2308,7 @@ class BashCompletion {
             if (opt.short)
                 optParts.push(this.#escapeWord(`-${opt.short}`));
             optParts.push(this.#escapeWord(`--${kebabLong}`));
-            if (!opt.takesValue) {
+            if (canGenerateNegativeCompletion(opt)) {
                 optParts.push(this.#escapeWord(`--no-${kebabLong}`));
             }
         }
@@ -2325,7 +2340,7 @@ class BashCompletion {
         return words.map(choice => this.#escapeWord(choice)).join(' ');
     }
     #appendChoiceLogicForCommand(lines, indent, cmd, depth) {
-        const valueOptions = cmd.options.filter(opt => opt.takesValue);
+        const valueOptions = cmd.options.filter(optionTakesValue);
         const valueOptionsWithChoices = valueOptions.filter(opt => opt.choices && opt.choices.length > 0);
         const valueLongPatterns = valueOptions.map(opt => `--${camelToKebabCase(opt.long)}`);
         const valueShortPatterns = valueOptions
@@ -2452,7 +2467,7 @@ class FishCompletion {
                 line += ` -xa '${opt.choices.map(choice => this.#escapeChoice(choice)).join(' ')}'`;
             }
             lines.push(line);
-            if (!opt.takesValue) {
+            if (canGenerateNegativeCompletion(opt)) {
                 let noLine = `complete -c ${this.#programName}`;
                 if (condition)
                     noLine += ` -n '${condition}'`;
@@ -2462,11 +2477,11 @@ class FishCompletion {
             }
         }
         const valueOptionLongs = cmd.options
-            .filter(opt => opt.takesValue)
+            .filter(optionTakesValue)
             .map(opt => camelToKebabCase(opt.long))
             .join(',');
         const valueOptionShorts = cmd.options
-            .filter(opt => opt.takesValue && opt.short)
+            .filter(opt => optionTakesValue(opt) && opt.short)
             .map(opt => opt.short)
             .join(',');
         const argCount = cmd.arguments.length;
@@ -2665,7 +2680,7 @@ class PwshCompletion {
             '    if ($token.StartsWith("--")) {',
             '      if ($token.Contains("=")) { continue }',
             '      foreach ($opt in $cmd.options) {',
-            '        if ($token -eq "--$($opt.long)" -and $opt.takesValue) {',
+            '        if ($token -eq "--$($opt.long)" -and $opt.args -ne "none") {',
             '          $expectValue = $true',
             '          break',
             '        }',
@@ -2675,7 +2690,7 @@ class PwshCompletion {
             '    if ($token.StartsWith("-") -and $token -ne "-") {',
             '      if ($token.Length -eq 2) {',
             '        foreach ($opt in $cmd.options) {',
-            '          if ($opt.short -and $token -eq "-$($opt.short)" -and $opt.takesValue) {',
+            '          if ($opt.short -and $token -eq "-$($opt.short)" -and $opt.args -ne "none") {',
             '            $expectValue = $true',
             '            break',
             '          }',
@@ -2727,7 +2742,7 @@ class PwshCompletion {
             '          $opt.description',
             '        )',
             '      }',
-            '      if ($opt.isBoolean -and "--no-$($opt.long)" -like "$current*") {',
+            '      if ($opt.canNegate -and "--no-$($opt.long)" -like "$current*") {',
             '        $completions += [System.Management.Automation.CompletionResult]::new(',
             '          "--no-$($opt.long)",',
             '          "no-$($opt.long)",',
@@ -2777,8 +2792,9 @@ class PwshCompletion {
                 lines.push(`${indent}    short = '${opt.short}'`);
             lines.push(`${indent}    long = '${kebabLong}'`);
             lines.push(`${indent}    description = '${this.#escape(opt.desc)}'`);
-            lines.push(`${indent}    isBoolean = $${!opt.takesValue}`);
-            lines.push(`${indent}    takesValue = $${opt.takesValue}`);
+            lines.push(`${indent}    type = '${opt.type}'`);
+            lines.push(`${indent}    args = '${opt.args}'`);
+            lines.push(`${indent}    canNegate = $${canGenerateNegativeCompletion(opt)}`);
             if (opt.choices) {
                 lines.push(`${indent}    choices = @('${opt.choices
                     .map(choice => this.#escape(choice))

package/lib/types/browser.d.ts

@@ -365,8 +365,10 @@ interface ICompletionOptionMeta {
     short?: string;
     /** Description */
     desc: string;
-    /** Whether option takes value (args !== 'none') */
-    takesValue: boolean;
+    /** Option type */
+    type: ICommandOptionType;
+    /** Option args mode */
+    args: ICommandOptionArgs;
     /** Allowed values */
     choices?: string[];
 }

package/lib/types/node.d.ts

@@ -365,8 +365,10 @@ interface ICompletionOptionMeta {
     short?: string;
     /** Description */
     desc: string;
-    /** Whether option takes value (args !== 'none') */
-    takesValue: boolean;
+    /** Option type */
+    type: ICommandOptionType;
+    /** Option args mode */
+    args: ICommandOptionArgs;
     /** Allowed values */
     choices?: string[];
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@guanghechen/commander",
-  "version": "4.7.3",
+  "version": "4.7.4",
   "description": "A minimal, type-safe command-line interface builder with fluent API",
   "author": {
     "name": "guanghechen",
@@ -44,8 +44,8 @@
     "README.md"
   ],
   "dependencies": {
-    "@guanghechen/env": "^2.0.2",
-    "@guanghechen/reporter": "^3.3.0"
+    "@guanghechen/reporter": "^3.3.0",
+    "@guanghechen/env": "^2.0.2"
   },
   "scripts": {
     "build": "rollup -c ../../rollup.config.mjs",