commander 13.1.0 → 14.0.0

package/Readme.md

@@ -38,6 +38,7 @@ Read this in other languages: English | [简体中文](./Readme_zh-CN.md)
     - [.description and .summary](#description-and-summary)
     - [.helpOption(flags, description)](#helpoptionflags-description)
     - [.helpCommand()](#helpcommand)
+    - [Help Groups](#help-groups)
     - [More configuration](#more-configuration-2)
   - [Custom event listeners](#custom-event-listeners)
   - [Bits and pieces](#bits-and-pieces)
@@ -334,7 +335,8 @@ add cheese type mozzarella
 ```
 
 Options with an optional option-argument are not greedy and will ignore arguments starting with a dash.
-So `id` behaves as a boolean option for `--id -5`, but you can use a combined form if needed like `--id=-5`.
+So `id` behaves as a boolean option for `--id -ABCD`, but you can use a combined form if needed like `--id=-ABCD`.
+Negative numbers are special and are accepted as an option-argument.
 
 For information about possible ambiguous cases, see [options taking varying arguments](./docs/options-in-depth.md).
 
@@ -926,6 +928,14 @@ program.helpCommand('assist [command]', 'show assistance');
 
 (Or use `.addHelpCommand()` to add a command you construct yourself.)
 
+### Help Groups
+
+The help by default lists options under the the heading `Options:` and commands under `Commands:`. You can create your own groups
+with different headings. The high-level way is to set the desired group heading while adding the options and commands,
+using `.optionsGroup()` and `.commandsGroup()`. The low-level way is using `.helpGroup()` on an individual `Option` or `Command`
+
+Example file: [help-groups.js](./examples/help-groups.js)
+
 ### More configuration
 
 The built-in help is formatted using the Help class.
@@ -933,7 +943,7 @@ You can configure the help by modifying data properties and methods using `.conf
 
 Simple properties include `sortSubcommands`, `sortOptions`, and `showGlobalOptions`. You can add color using the style methods like `styleTitle()`.
 
-For more detail and examples of changing the displayed text, color, and layout see (./docs/help-in-depth.md)
+For more detail and examples of changing the displayed text, color, and layout see (./docs/help-in-depth.md).
 
 ## Custom event listeners
 
@@ -999,8 +1009,8 @@ program arg --port=80
 
 By default, the option processing shows an error for an unknown option. To have an unknown option treated as an ordinary command-argument and continue looking for options, use `.allowUnknownOption()`. This lets you mix known and unknown options.
 
-By default, the argument processing does not display an error for more command-arguments than expected.
-To display an error for excess arguments, use`.allowExcessArguments(false)`.
+By default, the argument processing displays an error for more command-arguments than expected.
+To suppress the error for excess arguments, use`.allowExcessArguments()`.
 
 ### Legacy options as properties
 
@@ -1137,7 +1147,7 @@ There is more information available about:
 
 ## Support
 
-The current version of Commander is fully supported on Long Term Support versions of Node.js, and requires at least v18.
+The current version of Commander is fully supported on Long Term Support versions of Node.js, and requires at least v20.
 (For older versions of Node.js, use an older version of Commander.)
 
 The main forum for free and community support is the project [Issues](https://github.com/tj/commander.js/issues) on GitHub.

package/lib/command.js

@@ -80,6 +80,12 @@ class Command extends EventEmitter {
     /** @type {Command} */
     this._helpCommand = undefined; // lazy initialised, inherited
     this._helpConfiguration = {};
+    /** @type {string | undefined} */
+    this._helpGroupHeading = undefined; // soft initialised when added to parent
+    /** @type {string | undefined} */
+    this._defaultCommandGroup = undefined;
+    /** @type {string | undefined} */
+    this._defaultOptionGroup = undefined;
   }
 
   /**
@@ -239,7 +245,11 @@ class Command extends EventEmitter {
   configureOutput(configuration) {
     if (configuration === undefined) return this._outputConfiguration;
 
-    Object.assign(this._outputConfiguration, configuration);
+    this._outputConfiguration = Object.assign(
+      {},
+      this._outputConfiguration,
+      configuration,
+    );
     return this;
   }
 
@@ -320,16 +330,16 @@ class Command extends EventEmitter {
    *
    * @param {string} name
    * @param {string} [description]
-   * @param {(Function|*)} [fn] - custom argument processing function
+   * @param {(Function|*)} [parseArg] - custom argument processing function or default value
    * @param {*} [defaultValue]
    * @return {Command} `this` command for chaining
    */
-  argument(name, description, fn, defaultValue) {
+  argument(name, description, parseArg, defaultValue) {
     const argument = this.createArgument(name, description);
-    if (typeof fn === 'function') {
-      argument.default(defaultValue).argParser(fn);
+    if (typeof parseArg === 'function') {
+      argument.default(defaultValue).argParser(parseArg);
     } else {
-      argument.default(fn);
+      argument.default(parseArg);
     }
     this.addArgument(argument);
     return this;
@@ -400,11 +410,15 @@ class Command extends EventEmitter {
   helpCommand(enableOrNameAndArgs, description) {
     if (typeof enableOrNameAndArgs === 'boolean') {
       this._addImplicitHelpCommand = enableOrNameAndArgs;
+      if (enableOrNameAndArgs && this._defaultCommandGroup) {
+        // make the command to store the group
+        this._initCommandGroup(this._getHelpCommand());
+      }
       return this;
     }
 
-    enableOrNameAndArgs = enableOrNameAndArgs ?? 'help [command]';
-    const [, helpName, helpArgs] = enableOrNameAndArgs.match(/([^ ]+) *(.*)/);
+    const nameAndArgs = enableOrNameAndArgs ?? 'help [command]';
+    const [, helpName, helpArgs] = nameAndArgs.match(/([^ ]+) *(.*)/);
     const helpDescription = description ?? 'display help for command';
 
     const helpCommand = this.createCommand(helpName);
@@ -414,6 +428,8 @@ class Command extends EventEmitter {
 
     this._addImplicitHelpCommand = true;
     this._helpCommand = helpCommand;
+    // init group unless lazy create
+    if (enableOrNameAndArgs || description) this._initCommandGroup(helpCommand);
 
     return this;
   }
@@ -435,6 +451,7 @@ class Command extends EventEmitter {
 
     this._addImplicitHelpCommand = true;
     this._helpCommand = helpCommand;
+    this._initCommandGroup(helpCommand);
     return this;
   }
 
@@ -613,6 +630,7 @@ Expecting one of '${allowedValues.join("', '")}'`);
 -  already used by option '${matchingOption.flags}'`);
     }
 
+    this._initOptionGroup(option);
     this.options.push(option);
   }
 
@@ -640,6 +658,7 @@ Expecting one of '${allowedValues.join("', '")}'`);
       );
     }
 
+    this._initCommandGroup(command);
     this.commands.push(command);
   }
 
@@ -1737,6 +1756,17 @@ Expecting one of '${allowedValues.join("', '")}'`);
       return arg.length > 1 && arg[0] === '-';
     }
 
+    const negativeNumberArg = (arg) => {
+      // return false if not a negative number
+      if (!/^-\d*\.?\d+(e[+-]?\d+)?$/.test(arg)) return false;
+      // negative number is ok unless digit used as an option in command hierarchy
+      return !this._getCommandAndAncestors().some((cmd) =>
+        cmd.options
+          .map((opt) => opt.short)
+          .some((short) => /^-\d$/.test(short)),
+      );
+    };
+
     // parse options
     let activeVariadicOption = null;
     while (args.length) {
@@ -1749,7 +1779,10 @@ Expecting one of '${allowedValues.join("', '")}'`);
         break;
       }
 
-      if (activeVariadicOption && !maybeOption(arg)) {
+      if (
+        activeVariadicOption &&
+        (!maybeOption(arg) || negativeNumberArg(arg))
+      ) {
         this.emit(`option:${activeVariadicOption.name()}`, arg);
         continue;
       }
@@ -1766,7 +1799,10 @@ Expecting one of '${allowedValues.join("', '")}'`);
           } else if (option.optional) {
             let value = null;
             // historical behaviour is optional value is following arg unless an option
-            if (args.length > 0 && !maybeOption(args[0])) {
+            if (
+              args.length > 0 &&
+              (!maybeOption(args[0]) || negativeNumberArg(args[0]))
+            ) {
               value = args.shift();
             }
             this.emit(`option:${option.name()}`, value);
@@ -1812,7 +1848,12 @@ Expecting one of '${allowedValues.join("', '")}'`);
       // Might be a command-argument, or subcommand option, or unknown option, or help command or option.
 
       // An unknown option means further arguments also classified as unknown so can be reprocessed by subcommands.
-      if (maybeOption(arg)) {
+      // A negative number in a leaf command is not an unknown option.
+      if (
+        dest === operands &&
+        maybeOption(arg) &&
+        !(this.commands.length === 0 && negativeNumberArg(arg))
+      ) {
         dest = unknown;
       }
 
@@ -2294,6 +2335,75 @@ Expecting one of '${allowedValues.join("', '")}'`);
     return this;
   }
 
+  /**
+   * Set/get the help group heading for this subcommand in parent command's help.
+   *
+   * @param {string} [heading]
+   * @return {Command | string}
+   */
+
+  helpGroup(heading) {
+    if (heading === undefined) return this._helpGroupHeading ?? '';
+    this._helpGroupHeading = heading;
+    return this;
+  }
+
+  /**
+   * Set/get the default help group heading for subcommands added to this command.
+   * (This does not override a group set directly on the subcommand using .helpGroup().)
+   *
+   * @example
+   * program.commandsGroup('Development Commands:);
+   * program.command('watch')...
+   * program.command('lint')...
+   * ...
+   *
+   * @param {string} [heading]
+   * @returns {Command | string}
+   */
+  commandsGroup(heading) {
+    if (heading === undefined) return this._defaultCommandGroup ?? '';
+    this._defaultCommandGroup = heading;
+    return this;
+  }
+
+  /**
+   * Set/get the default help group heading for options added to this command.
+   * (This does not override a group set directly on the option using .helpGroup().)
+   *
+   * @example
+   * program
+   *   .optionsGroup('Development Options:')
+   *   .option('-d, --debug', 'output extra debugging')
+   *   .option('-p, --profile', 'output profiling information')
+   *
+   * @param {string} [heading]
+   * @returns {Command | string}
+   */
+  optionsGroup(heading) {
+    if (heading === undefined) return this._defaultOptionGroup ?? '';
+    this._defaultOptionGroup = heading;
+    return this;
+  }
+
+  /**
+   * @param {Option} option
+   * @private
+   */
+  _initOptionGroup(option) {
+    if (this._defaultOptionGroup && !option.helpGroupHeading)
+      option.helpGroup(this._defaultOptionGroup);
+  }
+
+  /**
+   * @param {Command} cmd
+   * @private
+   */
+  _initCommandGroup(cmd) {
+    if (this._defaultCommandGroup && !cmd.helpGroup())
+      cmd.helpGroup(this._defaultCommandGroup);
+  }
+
   /**
    * Set the name of the command from script filename, such as process.argv[1],
    * or require.main.filename, or __filename.
@@ -2448,12 +2558,14 @@ Expecting one of '${allowedValues.join("', '")}'`);
    */
 
   helpOption(flags, description) {
-    // Support disabling built-in help option.
+    // Support enabling/disabling built-in help option.
     if (typeof flags === 'boolean') {
-      // true is not an expected value. Do something sensible but no unit-test.
-      // istanbul ignore if
       if (flags) {
-        this._helpOption = this._helpOption ?? undefined; // preserve existing option
+        if (this._helpOption === null) this._helpOption = undefined; // reenable
+        if (this._defaultOptionGroup) {
+          // make the option to store the group
+          this._initOptionGroup(this._getHelpOption());
+        }
       } else {
         this._helpOption = null; // disable
       }
@@ -2461,9 +2573,12 @@ Expecting one of '${allowedValues.join("', '")}'`);
     }
 
     // Customise flags and description.
-    flags = flags ?? '-h, --help';
-    description = description ?? 'display help for command';
-    this._helpOption = this.createOption(flags, description);
+    this._helpOption = this.createOption(
+      flags ?? '-h, --help',
+      description ?? 'display help for command',
+    );
+    // init group unless lazy create
+    if (flags || description) this._initOptionGroup(this._helpOption);
 
     return this;
   }
@@ -2492,6 +2607,7 @@ Expecting one of '${allowedValues.join("', '")}'`);
    */
   addHelpOption(option) {
     this._helpOption = option;
+    this._initOptionGroup(option);
     return this;
   }
 

package/lib/help.js

@@ -352,7 +352,11 @@ class Help {
       extraInfo.push(`env: ${option.envVar}`);
     }
     if (extraInfo.length > 0) {
-      return `${option.description} (${extraInfo.join(', ')})`;
+      const extraDescription = `(${extraInfo.join(', ')})`;
+      if (option.description) {
+        return `${option.description} ${extraDescription}`;
+      }
+      return extraDescription;
     }
 
     return option.description;
@@ -388,6 +392,46 @@ class Help {
     return argument.description;
   }
 
+  /**
+   * Format a list of items, given a heading and an array of formatted items.
+   *
+   * @param {string} heading
+   * @param {string[]} items
+   * @param {Help} helper
+   * @returns string[]
+   */
+  formatItemList(heading, items, helper) {
+    if (items.length === 0) return [];
+
+    return [helper.styleTitle(heading), ...items, ''];
+  }
+
+  /**
+   * Group items by their help group heading.
+   *
+   * @param {Command[] | Option[]} unsortedItems
+   * @param {Command[] | Option[]} visibleItems
+   * @param {Function} getGroup
+   * @returns {Map<string, Command[] | Option[]>}
+   */
+  groupItems(unsortedItems, visibleItems, getGroup) {
+    const result = new Map();
+    // Add groups in order of appearance in unsortedItems.
+    unsortedItems.forEach((item) => {
+      const group = getGroup(item);
+      if (!result.has(group)) result.set(group, []);
+    });
+    // Add items in order of appearance in visibleItems.
+    visibleItems.forEach((item) => {
+      const group = getGroup(item);
+      if (!result.has(group)) {
+        result.set(group, []);
+      }
+      result.get(group).push(item);
+    });
+    return result;
+  }
+
   /**
    * Generate the built-in help text.
    *
@@ -429,28 +473,25 @@ class Help {
         helper.styleArgumentDescription(helper.argumentDescription(argument)),
       );
     });
-    if (argumentList.length > 0) {
-      output = output.concat([
-        helper.styleTitle('Arguments:'),
-        ...argumentList,
-        '',
-      ]);
-    }
+    output = output.concat(
+      this.formatItemList('Arguments:', argumentList, helper),
+    );
 
     // Options
-    const optionList = helper.visibleOptions(cmd).map((option) => {
-      return callFormatItem(
-        helper.styleOptionTerm(helper.optionTerm(option)),
-        helper.styleOptionDescription(helper.optionDescription(option)),
-      );
+    const optionGroups = this.groupItems(
+      cmd.options,
+      helper.visibleOptions(cmd),
+      (option) => option.helpGroupHeading ?? 'Options:',
+    );
+    optionGroups.forEach((options, group) => {
+      const optionList = options.map((option) => {
+        return callFormatItem(
+          helper.styleOptionTerm(helper.optionTerm(option)),
+          helper.styleOptionDescription(helper.optionDescription(option)),
+        );
+      });
+      output = output.concat(this.formatItemList(group, optionList, helper));
     });
-    if (optionList.length > 0) {
-      output = output.concat([
-        helper.styleTitle('Options:'),
-        ...optionList,
-        '',
-      ]);
-    }
 
     if (helper.showGlobalOptions) {
       const globalOptionList = helper
@@ -461,29 +502,26 @@ class Help {
             helper.styleOptionDescription(helper.optionDescription(option)),
           );
         });
-      if (globalOptionList.length > 0) {
-        output = output.concat([
-          helper.styleTitle('Global Options:'),
-          ...globalOptionList,
-          '',
-        ]);
-      }
+      output = output.concat(
+        this.formatItemList('Global Options:', globalOptionList, helper),
+      );
     }
 
     // Commands
-    const commandList = helper.visibleCommands(cmd).map((cmd) => {
-      return callFormatItem(
-        helper.styleSubcommandTerm(helper.subcommandTerm(cmd)),
-        helper.styleSubcommandDescription(helper.subcommandDescription(cmd)),
-      );
+    const commandGroups = this.groupItems(
+      cmd.commands,
+      helper.visibleCommands(cmd),
+      (sub) => sub.helpGroup() || 'Commands:',
+    );
+    commandGroups.forEach((commands, group) => {
+      const commandList = commands.map((sub) => {
+        return callFormatItem(
+          helper.styleSubcommandTerm(helper.subcommandTerm(sub)),
+          helper.styleSubcommandDescription(helper.subcommandDescription(sub)),
+        );
+      });
+      output = output.concat(this.formatItemList(group, commandList, helper));
     });
-    if (commandList.length > 0) {
-      output = output.concat([
-        helper.styleTitle('Commands:'),
-        ...commandList,
-        '',
-      ]);
-    }
 
     return output.join('\n');
   }

package/lib/option.js

@@ -33,6 +33,7 @@ class Option {
     this.argChoices = undefined;
     this.conflictsWith = [];
     this.implied = undefined;
+    this.helpGroupHeading = undefined; // soft initialised when option added to command
   }
 
   /**
@@ -219,6 +220,17 @@ class Option {
     return camelcase(this.name());
   }
 
+  /**
+   * Set the help group heading.
+   *
+   * @param {string} heading
+   * @return {Option}
+   */
+  helpGroup(heading) {
+    this.helpGroupHeading = heading;
+    return this;
+  }
+
   /**
    * Check if `arg` matches the short or long flag.
    *

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "commander",
-  "version": "13.1.0",
+  "version": "14.0.0",
   "description": "the complete solution for node.js command-line programs",
   "keywords": [
     "commander",
@@ -64,9 +64,9 @@
     "@types/jest": "^29.2.4",
     "@types/node": "^22.7.4",
     "eslint": "^9.17.0",
-    "eslint-config-prettier": "^9.1.0",
+    "eslint-config-prettier": "^10.0.1",
     "eslint-plugin-jest": "^28.3.0",
-    "globals": "^15.7.0",
+    "globals": "^16.0.0",
     "jest": "^29.3.1",
     "prettier": "^3.2.5",
     "ts-jest": "^29.0.3",
@@ -76,7 +76,7 @@
   },
   "types": "typings/index.d.ts",
   "engines": {
-    "node": ">=18"
+    "node": ">=20"
   },
   "support": true
 }

package/typings/index.d.ts

@@ -51,6 +51,7 @@ export class Argument {
   variadic: boolean;
   defaultValue?: any;
   defaultValueDescription?: string;
+  parseArg?: <T>(value: string, previous: T) => T;
   argChoices?: string[];
 
   /**
@@ -109,6 +110,7 @@ export class Option {
   parseArg?: <T>(value: string, previous: T) => T;
   hidden: boolean;
   argChoices?: string[];
+  helpGroupHeading?: string;
 
   constructor(flags: string, description?: string);
 
@@ -192,6 +194,11 @@ export class Option {
    */
   attributeName(): string;
 
+  /**
+   * Set the help group heading.
+   */
+  helpGroup(heading: string): this;
+
   /**
    * Return whether a boolean option.
    *
@@ -313,6 +320,20 @@ export class Help {
     helper: Help,
   ): string;
 
+  /**
+   * Format a list of items, given a heading and an array of formatted items.
+   */
+  formatItemList(heading: string, items: string[], helper: Help): string[];
+
+  /**
+   * Group items by their help group heading.
+   */
+  groupItems<T extends Command | Option>(
+    unsortedItems: T[],
+    visibleItems: T[],
+    getGroup: (item: T) => string,
+  ): Map<string, T[]>;
+
   /** Generate the built-in help text. */
   formatHelp(cmd: Command, helper: Help): string;
 }
@@ -466,7 +487,7 @@ export class Command {
   argument<T>(
     flags: string,
     description: string,
-    fn: (value: string, previous: T) => T,
+    parseArg: (value: string, previous: T) => T,
     defaultValue?: T,
   ): this;
   argument(name: string, description?: string, defaultValue?: unknown): this;
@@ -968,6 +989,53 @@ export class Command {
    */
   executableDir(): string | null;
 
+  /**
+   * Set the help group heading for this subcommand in parent command's help.
+   *
+   * @returns `this` command for chaining
+   */
+  helpGroup(heading: string): this;
+  /**
+   * Get the help group heading for this subcommand in parent command's help.
+   */
+  helpGroup(): string;
+
+  /**
+   * Set the default help group heading for subcommands added to this command.
+   * (This does not override a group set directly on the subcommand using .helpGroup().)
+   *
+   * @example
+   * program.commandsGroup('Development Commands:);
+   * program.command('watch')...
+   * program.command('lint')...
+   * ...
+   *
+   * @returns `this` command for chaining
+   */
+  commandsGroup(heading: string): this;
+  /**
+   * Get the default help group heading for subcommands added to this command.
+   */
+  commandsGroup(): string;
+
+  /**
+   * Set the default help group heading for options added to this command.
+   * (This does not override a group set directly on the option using .helpGroup().)
+   *
+   * @example
+   * program
+   *   .optionsGroup('Development Options:')
+   *   .option('-d, --debug', 'output extra debugging')
+   *   .option('-p, --profile', 'output profiling information')
+   *
+   * @returns `this` command for chaining
+   */
+  optionsGroup(heading: string): this;
+  /**
+   * Get the default help group heading for options added to this command.
+   */
+  optionsGroup(): string;
+
   /**
    * Output help information for this command.
    *