commander 11.1.0 → 12.0.0-0

package/Readme.md

@@ -967,6 +967,8 @@ program.parse(); // Implicit, and auto-detect electron
 program.parse(['-f', 'filename'], { from: 'user' });
 ```
 
+If you want to parse multiple times, create a new program each time. Calling parse does not clear out any previous state.
+
 ### Parsing Configuration
 
 If the default parsing does not suit your needs, there are some behaviours to support other usage patterns.
@@ -1136,7 +1138,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 v16.
+The current version of Commander is fully supported on Long Term Support versions of Node.js, and requires at least v18.
 (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/index.js

@@ -4,13 +4,11 @@ const { CommanderError, InvalidArgumentError } = require('./lib/error.js');
 const { Help } = require('./lib/help.js');
 const { Option } = require('./lib/option.js');
 
-/**
- * Expose the root command.
- */
+exports.program = new Command();
 
-exports = module.exports = new Command();
-exports.program = exports; // More explicit access to global command.
-// createArgument, createCommand, and createOption are implicitly available as they are methods on program.
+exports.createCommand = (name) => new Command(name);
+exports.createOption = (flags, description) => new Option(flags, description);
+exports.createArgument = (name, description) => new Argument(name, description);
 
 /**
  * Expose classes

package/lib/argument.js

@@ -50,7 +50,7 @@ class Argument {
   }
 
   /**
-   * @api private
+   * @package internal use only
    */
 
   _concatValue(value, previous) {
@@ -130,7 +130,7 @@ class Argument {
  *
  * @param {Argument} arg
  * @return {string}
- * @api private
+ * @private
  */
 
 function humanReadableArgName(arg) {

package/lib/command.js

@@ -110,7 +110,7 @@ class Command extends EventEmitter {
 
   /**
    * @returns {Command[]}
-   * @api private
+   * @private
    */
 
   _getCommandAndAncestors() {
@@ -165,7 +165,7 @@ class Command extends EventEmitter {
     cmd._hidden = !!(opts.noHelp || opts.hidden); // noHelp is deprecated old name for hidden
     cmd._executableFile = opts.executableFile || null; // Custom name for executable file, set missing to null to match constructor
     if (args) cmd.arguments(args);
-    this.commands.push(cmd);
+    this._registerCommand(cmd);
     cmd.parent = this;
     cmd.copyInheritedSettings(this);
 
@@ -282,8 +282,10 @@ class Command extends EventEmitter {
     if (opts.isDefault) this._defaultCommandName = cmd._name;
     if (opts.noHelp || opts.hidden) cmd._hidden = true; // modifying passed command due to existing implementation
 
-    this.commands.push(cmd);
+    this._registerCommand(cmd);
     cmd.parent = this;
+    cmd._checkForBrokenPassThrough();
+
     return this;
   }
 
@@ -392,7 +394,7 @@ class Command extends EventEmitter {
 
   /**
    * @return {boolean}
-   * @api private
+   * @package internal use only
    */
 
   _hasImplicitHelpCommand() {
@@ -453,7 +455,7 @@ Expecting one of '${allowedValues.join("', '")}'`);
    * @param {string} code an id string representing the error
    * @param {string} message human-readable description of the error
    * @return never
-   * @api private
+   * @private
    */
 
   _exit(exitCode, code, message) {
@@ -519,7 +521,7 @@ Expecting one of '${allowedValues.join("', '")}'`);
    * @param {string} value
    * @param {*} previous
    * @param {string} invalidArgumentMessage
-   * @api private
+   * @private
    */
 
   _callParseArg(target, value, previous, invalidArgumentMessage) {
@@ -534,6 +536,49 @@ Expecting one of '${allowedValues.join("', '")}'`);
     }
   }
 
+  /**
+   * Check for option flag conflicts.
+   * Register option if no conflicts found, or throw on conflict.
+   *
+   * @param {Option} option
+   * @api private
+   */
+
+  _registerOption(option) {
+    const matchingOption = (option.short && this._findOption(option.short)) ||
+      (option.long && this._findOption(option.long));
+    if (matchingOption) {
+      const matchingFlag = (option.long && this._findOption(option.long)) ? option.long : option.short;
+      throw new Error(`Cannot add option '${option.flags}'${this._name && ` to command '${this._name}'`} due to conflicting flag '${matchingFlag}'
+-  already used by option '${matchingOption.flags}'`);
+    }
+
+    this.options.push(option);
+  }
+
+  /**
+   * Check for command name and alias conflicts with existing commands.
+   * Register command if no conflicts found, or throw on conflict.
+   *
+   * @param {Command} command
+   * @api private
+   */
+
+  _registerCommand(command) {
+    const knownBy = (cmd) => {
+      return [cmd.name()].concat(cmd.aliases());
+    };
+
+    const alreadyUsed = knownBy(command).find((name) => this._findCommand(name));
+    if (alreadyUsed) {
+      const existingCmd = knownBy(this._findCommand(alreadyUsed)).join('|');
+      const newCmd = knownBy(command).join('|');
+      throw new Error(`cannot add command '${newCmd}' as already have command '${existingCmd}'`);
+    }
+
+    this.commands.push(command);
+  }
+
   /**
    * Add an option.
    *
@@ -541,6 +586,8 @@ Expecting one of '${allowedValues.join("', '")}'`);
    * @return {Command} `this` command for chaining
    */
   addOption(option) {
+    this._registerOption(option);
+
     const oname = option.name();
     const name = option.attributeName();
 
@@ -555,9 +602,6 @@ Expecting one of '${allowedValues.join("', '")}'`);
       this.setOptionValueWithSource(name, option.defaultValue, 'default');
     }
 
-    // register the option
-    this.options.push(option);
-
     // handler for cli and env supplied values
     const handleOptionValue = (val, invalidValueMessage, valueSource) => {
       // val is null for optional option used without an optional-argument.
@@ -605,7 +649,7 @@ Expecting one of '${allowedValues.join("', '")}'`);
   /**
    * Internal implementation shared by .option() and .requiredOption()
    *
-   * @api private
+   * @private
    */
   _optionEx(config, flags, description, fn, defaultValue) {
     if (typeof flags === 'object' && flags instanceof Option) {
@@ -733,12 +777,20 @@ Expecting one of '${allowedValues.join("', '")}'`);
    */
   passThroughOptions(passThrough = true) {
     this._passThroughOptions = !!passThrough;
-    if (!!this.parent && passThrough && !this.parent._enablePositionalOptions) {
-      throw new Error('passThroughOptions can not be used without turning on enablePositionalOptions for parent command(s)');
-    }
+    this._checkForBrokenPassThrough();
     return this;
   }
 
+  /**
+   * @private
+   */
+
+  _checkForBrokenPassThrough() {
+    if (this.parent && this._passThroughOptions && !this.parent._enablePositionalOptions) {
+      throw new Error(`passThroughOptions cannot be used for '${this._name}' without turning on enablePositionalOptions for parent command(s)`);
+    }
+  }
+
   /**
     * Whether to store option values as properties on command object,
     * or store separately (specify false). In both cases the option values can be accessed using .opts().
@@ -751,9 +803,9 @@ Expecting one of '${allowedValues.join("', '")}'`);
     if (this.options.length) {
       throw new Error('call .storeOptionsAsProperties() before adding options');
     }
-    // if (Object.keys(this._optionValues).length) {
-    //   throw new Error('call .storeOptionsAsProperties() before setting option values');
-    // }
+    if (Object.keys(this._optionValues).length) {
+      throw new Error('call .storeOptionsAsProperties() before setting option values');
+    }
     this._storeOptionsAsProperties = !!storeAsProperties;
     return this;
   }
@@ -838,7 +890,7 @@ Expecting one of '${allowedValues.join("', '")}'`);
    * Get user arguments from implied or explicit arguments.
    * Side-effects: set _scriptPath if args included script. Used for default program name, and subcommand searches.
    *
-   * @api private
+   * @private
    */
 
   _prepareUserArgs(argv, parseOptions) {
@@ -941,7 +993,7 @@ Expecting one of '${allowedValues.join("', '")}'`);
   /**
    * Execute a sub-command executable.
    *
-   * @api private
+   * @private
    */
 
   _executeSubCommand(subcommand, args) {
@@ -1028,15 +1080,15 @@ Expecting one of '${allowedValues.join("', '")}'`);
     }
 
     // By default terminate process when spawned process terminates.
-    // Suppressing the exit if exitCallback defined is a bit messy and of limited use, but does allow process to stay running!
     const exitCallback = this._exitCallback;
-    if (!exitCallback) {
-      proc.on('close', process.exit.bind(process));
-    } else {
-      proc.on('close', () => {
-        exitCallback(new CommanderError(process.exitCode || 0, 'commander.executeSubCommandAsync', '(close)'));
-      });
-    }
+    proc.on('close', (code, _signal) => {
+      code = code ?? 1; // code is null if spawned process terminated due to a signal
+      if (!exitCallback) {
+        process.exit(code);
+      } else {
+        exitCallback(new CommanderError(code, 'commander.executeSubCommandAsync', '(close)'));
+      }
+    });
     proc.on('error', (err) => {
       // @ts-ignore
       if (err.code === 'ENOENT') {
@@ -1066,7 +1118,7 @@ Expecting one of '${allowedValues.join("', '")}'`);
   }
 
   /**
-   * @api private
+   * @private
    */
 
   _dispatchSubcommand(commandName, operands, unknown) {
@@ -1089,7 +1141,7 @@ Expecting one of '${allowedValues.join("', '")}'`);
    * Invoke help directly if possible, or dispatch if necessary.
    * e.g. help foo
    *
-   * @api private
+   * @private
    */
 
   _dispatchHelpCommand(subcommandName) {
@@ -1110,7 +1162,7 @@ Expecting one of '${allowedValues.join("', '")}'`);
   /**
    * Check this.args against expected this.registeredArguments.
    *
-   * @api private
+   * @private
    */
 
   _checkNumberOfArguments() {
@@ -1132,7 +1184,7 @@ Expecting one of '${allowedValues.join("', '")}'`);
   /**
    * Process this.args using this.registeredArguments and save as this.processedArgs!
    *
-   * @api private
+   * @private
    */
 
   _processArguments() {
@@ -1180,7 +1232,7 @@ Expecting one of '${allowedValues.join("', '")}'`);
    * @param {Promise|undefined} promise
    * @param {Function} fn
    * @return {Promise|undefined}
-   * @api private
+   * @private
    */
 
   _chainOrCall(promise, fn) {
@@ -1198,7 +1250,7 @@ Expecting one of '${allowedValues.join("', '")}'`);
    * @param {Promise|undefined} promise
    * @param {string} event
    * @return {Promise|undefined}
-   * @api private
+   * @private
    */
 
   _chainOrCallHooks(promise, event) {
@@ -1230,7 +1282,7 @@ Expecting one of '${allowedValues.join("', '")}'`);
    * @param {Command} subCommand
    * @param {string} event
    * @return {Promise|undefined}
-   * @api private
+   * @private
    */
 
   _chainOrCallSubCommandHook(promise, subCommand, event) {
@@ -1249,7 +1301,7 @@ Expecting one of '${allowedValues.join("', '")}'`);
    * Process arguments in context of this command.
    * Returns action result, in case it is a promise.
    *
-   * @api private
+   * @private
    */
 
   _parseCommand(operands, unknown) {
@@ -1267,7 +1319,7 @@ Expecting one of '${allowedValues.join("', '")}'`);
       return this._dispatchHelpCommand(operands[1]);
     }
     if (this._defaultCommandName) {
-      outputHelpIfRequested(this, unknown); // Run the help for default command from parent rather than passing to default command
+      this._outputHelpIfRequested(unknown); // Run the help for default command from parent rather than passing to default command
       return this._dispatchSubcommand(this._defaultCommandName, operands, unknown);
     }
     if (this.commands.length && this.args.length === 0 && !this._actionHandler && !this._defaultCommandName) {
@@ -1275,7 +1327,7 @@ Expecting one of '${allowedValues.join("', '")}'`);
       this.help({ error: true });
     }
 
-    outputHelpIfRequested(this, parsed.unknown);
+    this._outputHelpIfRequested(parsed.unknown);
     this._checkForMissingMandatoryOptions();
     this._checkForConflictingOptions();
 
@@ -1333,7 +1385,7 @@ Expecting one of '${allowedValues.join("', '")}'`);
   /**
    * Find matching command.
    *
-   * @api private
+   * @private
    */
   _findCommand(name) {
     if (!name) return undefined;
@@ -1345,7 +1397,7 @@ Expecting one of '${allowedValues.join("', '")}'`);
    *
    * @param {string} arg
    * @return {Option}
-   * @api private
+   * @package internal use only
    */
 
   _findOption(arg) {
@@ -1356,7 +1408,7 @@ Expecting one of '${allowedValues.join("', '")}'`);
    * Display an error message if a mandatory option does not have a value.
    * Called after checking for help flags in leaf subcommand.
    *
-   * @api private
+   * @private
    */
 
   _checkForMissingMandatoryOptions() {
@@ -1373,7 +1425,7 @@ Expecting one of '${allowedValues.join("', '")}'`);
   /**
    * Display an error message if conflicting options are used together in this.
    *
-   * @api private
+   * @private
    */
   _checkForConflictingLocalOptions() {
     const definedNonDefaultOptions = this.options.filter(
@@ -1404,7 +1456,7 @@ Expecting one of '${allowedValues.join("', '")}'`);
    * Display an error message if conflicting options are used together.
    * Called after checking for help flags in leaf subcommand.
    *
-   * @api private
+   * @private
    */
   _checkForConflictingOptions() {
     // Walk up hierarchy so can call in subcommand after checking for displaying help.
@@ -1608,7 +1660,7 @@ Expecting one of '${allowedValues.join("', '")}'`);
    * Apply any option related environment variables, if option does
    * not have a value from cli or client code.
    *
-   * @api private
+   * @private
    */
   _parseOptionsEnv() {
     this.options.forEach((option) => {
@@ -1631,7 +1683,7 @@ Expecting one of '${allowedValues.join("', '")}'`);
   /**
    * Apply any implied option values, if option is undefined or default value.
    *
-   * @api private
+   * @private
    */
   _parseOptionsImplied() {
     const dualHelper = new DualOptions(this.options);
@@ -1655,7 +1707,7 @@ Expecting one of '${allowedValues.join("', '")}'`);
    * Argument `name` is missing.
    *
    * @param {string} name
-   * @api private
+   * @private
    */
 
   missingArgument(name) {
@@ -1667,7 +1719,7 @@ Expecting one of '${allowedValues.join("', '")}'`);
    * `Option` is missing an argument.
    *
    * @param {Option} option
-   * @api private
+   * @private
    */
 
   optionMissingArgument(option) {
@@ -1679,7 +1731,7 @@ Expecting one of '${allowedValues.join("', '")}'`);
    * `Option` does not have a value, and is a mandatory option.
    *
    * @param {Option} option
-   * @api private
+   * @private
    */
 
   missingMandatoryOptionValue(option) {
@@ -1692,7 +1744,7 @@ Expecting one of '${allowedValues.join("', '")}'`);
    *
    * @param {Option} option
    * @param {Option} conflictingOption
-   * @api private
+   * @private
    */
   _conflictingOption(option, conflictingOption) {
     // The calling code does not know whether a negated option is the source of the
@@ -1729,7 +1781,7 @@ Expecting one of '${allowedValues.join("', '")}'`);
    * Unknown option `flag`.
    *
    * @param {string} flag
-   * @api private
+   * @private
    */
 
   unknownOption(flag) {
@@ -1758,7 +1810,7 @@ Expecting one of '${allowedValues.join("', '")}'`);
    * Excess arguments, more than expected.
    *
    * @param {string[]} receivedArgs
-   * @api private
+   * @private
    */
 
   _excessArguments(receivedArgs) {
@@ -1774,7 +1826,7 @@ Expecting one of '${allowedValues.join("', '")}'`);
   /**
    * Unknown command.
    *
-   * @api private
+   * @private
    */
 
   unknownCommand() {
@@ -1814,8 +1866,9 @@ Expecting one of '${allowedValues.join("', '")}'`);
     flags = flags || '-V, --version';
     description = description || 'output the version number';
     const versionOption = this.createOption(flags, description);
-    this._versionOptionName = versionOption.attributeName(); // [sic] not defined in constructor, partly legacy, partly only needed at root
-    this.options.push(versionOption);
+    this._versionOptionName = versionOption.attributeName();
+    this._registerOption(versionOption);
+
     this.on('option:' + versionOption.name(), () => {
       this._outputConfiguration.writeOut(`${str}\n`);
       this._exit(0, 'commander.version', str);
@@ -1871,6 +1924,12 @@ Expecting one of '${allowedValues.join("', '")}'`);
     }
 
     if (alias === command._name) throw new Error('Command alias can\'t be the same as its name');
+    const matchingCommand = this.parent?._findCommand(alias);
+    if (matchingCommand) {
+      // c.f. _registerCommand
+      const existingCmd = [matchingCommand.name()].concat(matchingCommand.aliases()).join('|');
+      throw new Error(`cannot add alias '${alias}' to command '${this.name()}' as already have command '${existingCmd}'`);
+    }
 
     command._aliases.push(alias);
     return this;
@@ -1984,7 +2043,7 @@ Expecting one of '${allowedValues.join("', '")}'`);
   }
 
   /**
-   * @api private
+   * @private
    */
 
   _getHelpContext(contextOptions) {
@@ -2110,22 +2169,21 @@ Expecting one of '${allowedValues.join("', '")}'`);
     });
     return this;
   }
-}
 
-/**
- * Output help information if help flags specified
- *
- * @param {Command} cmd - command to output help for
- * @param {Array} args - array of options to search for help flags
- * @api private
- */
+  /**
+   * Output help information if help flags specified
+   *
+   * @param {Array} args - array of options to search for help flags
+   * @private
+   */
 
-function outputHelpIfRequested(cmd, args) {
-  const helpOption = cmd._hasHelpOption && args.find(arg => arg === cmd._helpLongFlag || arg === cmd._helpShortFlag);
-  if (helpOption) {
-    cmd.outputHelp();
-    // (Do not have all displayed text available so only passing placeholder.)
-    cmd._exit(0, 'commander.helpDisplayed', '(outputHelp)');
+  _outputHelpIfRequested(args) {
+    const helpOption = this._hasHelpOption && args.find(arg => arg === this._helpLongFlag || arg === this._helpShortFlag);
+    if (helpOption) {
+      this.outputHelp();
+      // (Do not have all displayed text available so only passing placeholder.)
+      this._exit(0, 'commander.helpDisplayed', '(outputHelp)');
+    }
   }
 }
 
@@ -2134,7 +2192,7 @@ function outputHelpIfRequested(cmd, args) {
  *
  * @param {string[]} args - array of arguments from node.execArgv
  * @returns {string[]}
- * @api private
+ * @private
  */
 
 function incrementNodeInspectorPort(args) {

package/lib/option.js

@@ -158,7 +158,7 @@ class Option {
   }
 
   /**
-   * @api private
+   * @package internal use only
    */
 
   _concatValue(value, previous) {
@@ -208,7 +208,6 @@ class Option {
    * as a object attribute key.
    *
    * @return {string}
-   * @api private
    */
 
   attributeName() {
@@ -220,7 +219,7 @@ class Option {
    *
    * @param {string} arg
    * @return {boolean}
-   * @api private
+   * @package internal use only
    */
 
   is(arg) {
@@ -233,7 +232,7 @@ class Option {
    * Options are one of boolean, negated, required argument, or optional argument.
    *
    * @return {boolean}
-   * @api private
+   * @package internal use only
    */
 
   isBoolean() {
@@ -293,7 +292,7 @@ class DualOptions {
  *
  * @param {string} str
  * @return {string}
- * @api private
+ * @private
  */
 
 function camelcase(str) {
@@ -305,7 +304,7 @@ function camelcase(str) {
 /**
  * Split the short and long flag out of something like '-m,--mixed <value>'
  *
- * @api private
+ * @private
  */
 
 function splitOptionFlags(flags) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "commander",
-  "version": "11.1.0",
+  "version": "12.0.0-0",
   "description": "the complete solution for node.js command-line programs",
   "keywords": [
     "commander",
@@ -58,23 +58,23 @@
   "devDependencies": {
     "@types/jest": "^29.2.4",
     "@types/node": "^20.2.5",
-    "@typescript-eslint/eslint-plugin": "^5.47.1",
-    "@typescript-eslint/parser": "^5.47.1",
+    "@typescript-eslint/eslint-plugin": "^6.7.5",
+    "@typescript-eslint/parser": "^6.7.5",
     "eslint": "^8.30.0",
     "eslint-config-standard": "^17.0.0",
-    "eslint-config-standard-with-typescript": "^33.0.0",
+    "eslint-config-standard-with-typescript": "^39.1.1",
     "eslint-plugin-import": "^2.26.0",
     "eslint-plugin-jest": "^27.1.7",
-    "eslint-plugin-n": "^15.6.0",
+    "eslint-plugin-n": "^16.2.0",
     "eslint-plugin-promise": "^6.1.1",
     "jest": "^29.3.1",
     "ts-jest": "^29.0.3",
-    "tsd": "^0.28.1",
+    "tsd": "^0.29.0",
     "typescript": "^5.0.4"
   },
   "types": "typings/index.d.ts",
   "engines": {
-    "node": ">=16"
+    "node": ">=18"
   },
   "support": true
 }