npm - @guanghechen/commander - Versions diffs - 4.7.3 → 4.7.5 - Mend

@guanghechen/commander 4.7.3 → 4.7.5

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (8) hide show

package/CHANGELOG.md CHANGED Viewed

@@ -1,5 +1,20 @@
 # Change Log
+## 4.7.5
+### Patch Changes
+- Fix help output ordering and remove duplicated negative options in help output.
+## 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 CHANGED Viewed

@@ -715,8 +715,28 @@ class Command {
             const desc = metadata.length > 0 ? `${arg.desc} ${metadata.join(' ')}` : arg.desc;
             argumentsLines.push({ sig, desc });
         }
+        const sortedOptions = [...allOptions].sort((a, b) => {
+            const optionRank = (option) => {
+                if (option.long === 'help') {
+                    return 0;
+                }
+                if (option.long === 'version') {
+                    return 1;
+                }
+                if (option.required === true) {
+                    return 2;
+                }
+                return 3;
+            };
+            const rankA = optionRank(a);
+            const rankB = optionRank(b);
+            if (rankA !== rankB) {
+                return rankA - rankB;
+            }
+            return camelToKebabCase(a.long).localeCompare(camelToKebabCase(b.long));
+        });
         const options = [];
-        for (const opt of allOptions) {
+        for (const opt of sortedOptions) {
             const kebabLong = camelToKebabCase(opt.long);
             let sig = opt.short ? `-${opt.short}, ` : '    ';
             sig += `--${kebabLong}`;
@@ -734,21 +754,13 @@ class Command {
                 desc += ` [choices: ${opt.choices.map(choice => JSON.stringify(choice)).join(', ')}]`;
             }
             options.push({ sig, desc });
-            if (opt.type === 'boolean' &&
-                opt.args === 'none' &&
-                opt.long !== 'help' &&
-                opt.long !== 'version') {
-                options.push({
-                    sig: `    --no-${kebabLong}`,
-                    desc: `Negate --${kebabLong}`,
-                });
-            }
         }
         const commands = [];
         if (this.#subcommandsList.length > 0) {
             commands.push({ name: 'help', desc: 'Show help for a command' });
         }
-        for (const entry of this.#subcommandsList) {
+        const sortedSubcommands = [...this.#subcommandsList].sort((a, b) => a.name.localeCompare(b.name));
+        for (const entry of sortedSubcommands) {
             let name = entry.name;
             if (entry.aliases.length > 0) {
                 name += `, ${entry.aliases.join(', ')}`;
@@ -864,7 +876,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 +892,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 CHANGED Viewed

@@ -728,8 +728,28 @@ class Command {
             const desc = metadata.length > 0 ? `${arg.desc} ${metadata.join(' ')}` : arg.desc;
             argumentsLines.push({ sig, desc });
         }
+        const sortedOptions = [...allOptions].sort((a, b) => {
+            const optionRank = (option) => {
+                if (option.long === 'help') {
+                    return 0;
+                }
+                if (option.long === 'version') {
+                    return 1;
+                }
+                if (option.required === true) {
+                    return 2;
+                }
+                return 3;
+            };
+            const rankA = optionRank(a);
+            const rankB = optionRank(b);
+            if (rankA !== rankB) {
+                return rankA - rankB;
+            }
+            return camelToKebabCase$1(a.long).localeCompare(camelToKebabCase$1(b.long));
+        });
         const options = [];
-        for (const opt of allOptions) {
+        for (const opt of sortedOptions) {
             const kebabLong = camelToKebabCase$1(opt.long);
             let sig = opt.short ? `-${opt.short}, ` : '    ';
             sig += `--${kebabLong}`;
@@ -747,21 +767,13 @@ class Command {
                 desc += ` [choices: ${opt.choices.map(choice => JSON.stringify(choice)).join(', ')}]`;
             }
             options.push({ sig, desc });
-            if (opt.type === 'boolean' &&
-                opt.args === 'none' &&
-                opt.long !== 'help' &&
-                opt.long !== 'version') {
-                options.push({
-                    sig: `    --no-${kebabLong}`,
-                    desc: `Negate --${kebabLong}`,
-                });
-            }
         }
         const commands = [];
         if (this.#subcommandsList.length > 0) {
             commands.push({ name: 'help', desc: 'Show help for a command' });
         }
-        for (const entry of this.#subcommandsList) {
+        const sortedSubcommands = [...this.#subcommandsList].sort((a, b) => a.name.localeCompare(b.name));
+        for (const entry of sortedSubcommands) {
             let name = entry.name;
             if (entry.aliases.length > 0) {
                 name += `, ${entry.aliases.join(', ')}`;
@@ -877,7 +889,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 +905,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 +2154,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 +2322,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 +2354,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 +2481,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 +2491,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 +2694,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 +2704,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 +2756,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 +2806,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 CHANGED Viewed

@@ -713,8 +713,28 @@ class Command {
             const desc = metadata.length > 0 ? `${arg.desc} ${metadata.join(' ')}` : arg.desc;
             argumentsLines.push({ sig, desc });
         }
+        const sortedOptions = [...allOptions].sort((a, b) => {
+            const optionRank = (option) => {
+                if (option.long === 'help') {
+                    return 0;
+                }
+                if (option.long === 'version') {
+                    return 1;
+                }
+                if (option.required === true) {
+                    return 2;
+                }
+                return 3;
+            };
+            const rankA = optionRank(a);
+            const rankB = optionRank(b);
+            if (rankA !== rankB) {
+                return rankA - rankB;
+            }
+            return camelToKebabCase(a.long).localeCompare(camelToKebabCase(b.long));
+        });
         const options = [];
-        for (const opt of allOptions) {
+        for (const opt of sortedOptions) {
             const kebabLong = camelToKebabCase(opt.long);
             let sig = opt.short ? `-${opt.short}, ` : '    ';
             sig += `--${kebabLong}`;
@@ -732,21 +752,13 @@ class Command {
                 desc += ` [choices: ${opt.choices.map(choice => JSON.stringify(choice)).join(', ')}]`;
             }
             options.push({ sig, desc });
-            if (opt.type === 'boolean' &&
-                opt.args === 'none' &&
-                opt.long !== 'help' &&
-                opt.long !== 'version') {
-                options.push({
-                    sig: `    --no-${kebabLong}`,
-                    desc: `Negate --${kebabLong}`,
-                });
-            }
         }
         const commands = [];
         if (this.#subcommandsList.length > 0) {
             commands.push({ name: 'help', desc: 'Show help for a command' });
         }
-        for (const entry of this.#subcommandsList) {
+        const sortedSubcommands = [...this.#subcommandsList].sort((a, b) => a.name.localeCompare(b.name));
+        for (const entry of sortedSubcommands) {
             let name = entry.name;
             if (entry.aliases.length > 0) {
                 name += `, ${entry.aliases.join(', ')}`;
@@ -862,7 +874,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 +890,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 CHANGED Viewed

@@ -726,8 +726,28 @@ class Command {
             const desc = metadata.length > 0 ? `${arg.desc} ${metadata.join(' ')}` : arg.desc;
             argumentsLines.push({ sig, desc });
         }
+        const sortedOptions = [...allOptions].sort((a, b) => {
+            const optionRank = (option) => {
+                if (option.long === 'help') {
+                    return 0;
+                }
+                if (option.long === 'version') {
+                    return 1;
+                }
+                if (option.required === true) {
+                    return 2;
+                }
+                return 3;
+            };
+            const rankA = optionRank(a);
+            const rankB = optionRank(b);
+            if (rankA !== rankB) {
+                return rankA - rankB;
+            }
+            return camelToKebabCase$1(a.long).localeCompare(camelToKebabCase$1(b.long));
+        });
         const options = [];
-        for (const opt of allOptions) {
+        for (const opt of sortedOptions) {
             const kebabLong = camelToKebabCase$1(opt.long);
             let sig = opt.short ? `-${opt.short}, ` : '    ';
             sig += `--${kebabLong}`;
@@ -745,21 +765,13 @@ class Command {
                 desc += ` [choices: ${opt.choices.map(choice => JSON.stringify(choice)).join(', ')}]`;
             }
             options.push({ sig, desc });
-            if (opt.type === 'boolean' &&
-                opt.args === 'none' &&
-                opt.long !== 'help' &&
-                opt.long !== 'version') {
-                options.push({
-                    sig: `    --no-${kebabLong}`,
-                    desc: `Negate --${kebabLong}`,
-                });
-            }
         }
         const commands = [];
         if (this.#subcommandsList.length > 0) {
             commands.push({ name: 'help', desc: 'Show help for a command' });
         }
-        for (const entry of this.#subcommandsList) {
+        const sortedSubcommands = [...this.#subcommandsList].sort((a, b) => a.name.localeCompare(b.name));
+        for (const entry of sortedSubcommands) {
             let name = entry.name;
             if (entry.aliases.length > 0) {
                 name += `, ${entry.aliases.join(', ')}`;
@@ -875,7 +887,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 +903,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 +2152,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 +2320,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 +2352,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 +2479,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 +2489,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 +2692,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 +2702,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 +2754,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 +2804,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 CHANGED Viewed

@@ -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 CHANGED Viewed

@@ -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 CHANGED Viewed

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