commander 11.0.0 → 12.0.0-0

package/lib/command.js

@@ -10,8 +10,6 @@ const { Help } = require('./help.js');
 const { Option, splitOptionFlags, DualOptions } = require('./option.js');
 const { suggestSimilar } = require('./suggestSimilar');
 
-// @ts-check
-
 class Command extends EventEmitter {
   /**
    * Initialize a new `Command`.
@@ -29,7 +27,8 @@ class Command extends EventEmitter {
     this._allowUnknownOption = false;
     this._allowExcessArguments = true;
     /** @type {Argument[]} */
-    this._args = [];
+    this.registeredArguments = [];
+    this._args = this.registeredArguments; // deprecated old name
     /** @type {string[]} */
     this.args = []; // cli args with options removed
     this.rawArgs = [];
@@ -109,6 +108,19 @@ class Command extends EventEmitter {
     return this;
   }
 
+  /**
+   * @returns {Command[]}
+   * @private
+   */
+
+  _getCommandAndAncestors() {
+    const result = [];
+    for (let command = this; command; command = command.parent) {
+      result.push(command);
+    }
+    return result;
+  }
+
   /**
    * Define a command.
    *
@@ -153,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);
 
@@ -270,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;
   }
 
@@ -343,14 +357,14 @@ class Command extends EventEmitter {
    * @return {Command} `this` command for chaining
    */
   addArgument(argument) {
-    const previousArgument = this._args.slice(-1)[0];
+    const previousArgument = this.registeredArguments.slice(-1)[0];
     if (previousArgument && previousArgument.variadic) {
       throw new Error(`only the last argument can be variadic '${previousArgument.name()}'`);
     }
     if (argument.required && argument.defaultValue !== undefined && argument.parseArg === undefined) {
       throw new Error(`a default value for a required argument is never used: '${argument.name()}'`);
     }
-    this._args.push(argument);
+    this.registeredArguments.push(argument);
     return this;
   }
 
@@ -380,7 +394,7 @@ class Command extends EventEmitter {
 
   /**
    * @return {boolean}
-   * @api private
+   * @package internal use only
    */
 
   _hasImplicitHelpCommand() {
@@ -441,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) {
@@ -470,7 +484,7 @@ Expecting one of '${allowedValues.join("', '")}'`);
   action(fn) {
     const listener = (args) => {
       // The .action callback takes an extra parameter which is the command or options.
-      const expectedArgsCount = this._args.length;
+      const expectedArgsCount = this.registeredArguments.length;
       const actionArgs = args.slice(0, expectedArgsCount);
       if (this._storeOptionsAsProperties) {
         actionArgs[expectedArgsCount] = this; // backwards compatible "options"
@@ -500,6 +514,71 @@ Expecting one of '${allowedValues.join("', '")}'`);
     return new Option(flags, description);
   }
 
+  /**
+   * Wrap parseArgs to catch 'commander.invalidArgument'.
+   *
+   * @param {Option | Argument} target
+   * @param {string} value
+   * @param {*} previous
+   * @param {string} invalidArgumentMessage
+   * @private
+   */
+
+  _callParseArg(target, value, previous, invalidArgumentMessage) {
+    try {
+      return target.parseArg(value, previous);
+    } catch (err) {
+      if (err.code === 'commander.invalidArgument') {
+        const message = `${invalidArgumentMessage} ${err.message}`;
+        this.error(message, { exitCode: err.exitCode, code: err.code });
+      }
+      throw err;
+    }
+  }
+
+  /**
+   * 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.
    *
@@ -507,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();
 
@@ -521,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.
@@ -535,15 +613,7 @@ Expecting one of '${allowedValues.join("', '")}'`);
       // custom processing
       const oldValue = this.getOptionValue(name);
       if (val !== null && option.parseArg) {
-        try {
-          val = option.parseArg(val, oldValue);
-        } catch (err) {
-          if (err.code === 'commander.invalidArgument') {
-            const message = `${invalidValueMessage} ${err.message}`;
-            this.error(message, { exitCode: err.exitCode, code: err.code });
-          }
-          throw err;
-        }
+        val = this._callParseArg(option, val, oldValue, invalidValueMessage);
       } else if (val !== null && option.variadic) {
         val = option._concatValue(val, oldValue);
       }
@@ -579,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) {
@@ -605,57 +675,29 @@ Expecting one of '${allowedValues.join("', '")}'`);
   }
 
   /**
-   * Define option with `flags`, `description` and optional
-   * coercion `fn`.
+   * Define option with `flags`, `description`, and optional argument parsing function or `defaultValue` or both.
    *
-   * The `flags` string contains the short and/or long flags,
-   * separated by comma, a pipe or space. The following are all valid
-   * all will output this way when `--help` is used.
+   * The `flags` string contains the short and/or long flags, separated by comma, a pipe or space. A required
+   * option-argument is indicated by `<>` and an optional option-argument by `[]`.
    *
-   *     "-p, --pepper"
-   *     "-p|--pepper"
-   *     "-p --pepper"
+   * See the README for more details, and see also addOption() and requiredOption().
    *
    * @example
-   * // simple boolean defaulting to undefined
-   * program.option('-p, --pepper', 'add pepper');
-   *
-   * program.pepper
-   * // => undefined
-   *
-   * --pepper
-   * program.pepper
-   * // => true
-   *
-   * // simple boolean defaulting to true (unless non-negated option is also defined)
-   * program.option('-C, --no-cheese', 'remove cheese');
-   *
-   * program.cheese
-   * // => true
-   *
-   * --no-cheese
-   * program.cheese
-   * // => false
-   *
-   * // required argument
-   * program.option('-C, --chdir <path>', 'change the working directory');
-   *
-   * --chdir /tmp
-   * program.chdir
-   * // => "/tmp"
-   *
-   * // optional argument
-   * program.option('-c, --cheese [type]', 'add cheese [marble]');
+   * program
+   *     .option('-p, --pepper', 'add pepper')
+   *     .option('-p, --pizza-type <TYPE>', 'type of pizza') // required option-argument
+   *     .option('-c, --cheese [CHEESE]', 'add extra cheese', 'mozzarella') // optional option-argument with default
+   *     .option('-t, --tip <VALUE>', 'add tip to purchase cost', parseFloat) // custom parse function
    *
    * @param {string} flags
    * @param {string} [description]
-   * @param {Function|*} [fn] - custom option processing function or default value
+   * @param {Function|*} [parseArg] - custom option processing function or default value
    * @param {*} [defaultValue]
    * @return {Command} `this` command for chaining
    */
 
-  option(flags, description, fn, defaultValue) {
-    return this._optionEx({}, flags, description, fn, defaultValue);
+  option(flags, description, parseArg, defaultValue) {
+    return this._optionEx({}, flags, description, parseArg, defaultValue);
   }
 
   /**
@@ -666,13 +708,13 @@ Expecting one of '${allowedValues.join("', '")}'`);
   *
   * @param {string} flags
   * @param {string} [description]
-  * @param {Function|*} [fn] - custom option processing function or default value
+  * @param {Function|*} [parseArg] - custom option processing function or default value
   * @param {*} [defaultValue]
   * @return {Command} `this` command for chaining
   */
 
-  requiredOption(flags, description, fn, defaultValue) {
-    return this._optionEx({ mandatory: true }, flags, description, fn, defaultValue);
+  requiredOption(flags, description, parseArg, defaultValue) {
+    return this._optionEx({ mandatory: true }, flags, description, parseArg, defaultValue);
   }
 
   /**
@@ -735,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().
@@ -750,10 +800,13 @@ Expecting one of '${allowedValues.join("', '")}'`);
     */
 
   storeOptionsAsProperties(storeAsProperties = true) {
-    this._storeOptionsAsProperties = !!storeAsProperties;
     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');
+    }
+    this._storeOptionsAsProperties = !!storeAsProperties;
     return this;
   }
 
@@ -825,7 +878,7 @@ Expecting one of '${allowedValues.join("', '")}'`);
   getOptionValueSourceWithGlobals(key) {
     // global overwrites local, like optsWithGlobals
     let source;
-    getCommandAndParents(this).forEach((cmd) => {
+    this._getCommandAndAncestors().forEach((cmd) => {
       if (cmd.getOptionValueSource(key) !== undefined) {
         source = cmd.getOptionValueSource(key);
       }
@@ -837,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) {
@@ -940,7 +993,7 @@ Expecting one of '${allowedValues.join("', '")}'`);
   /**
    * Execute a sub-command executable.
    *
-   * @api private
+   * @private
    */
 
   _executeSubCommand(subcommand, args) {
@@ -1027,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') {
@@ -1065,30 +1118,30 @@ Expecting one of '${allowedValues.join("', '")}'`);
   }
 
   /**
-   * @api private
+   * @private
    */
 
   _dispatchSubcommand(commandName, operands, unknown) {
     const subCommand = this._findCommand(commandName);
     if (!subCommand) this.help({ error: true });
 
-    let hookResult;
-    hookResult = this._chainOrCallSubCommandHook(hookResult, subCommand, 'preSubcommand');
-    hookResult = this._chainOrCall(hookResult, () => {
+    let promiseChain;
+    promiseChain = this._chainOrCallSubCommandHook(promiseChain, subCommand, 'preSubcommand');
+    promiseChain = this._chainOrCall(promiseChain, () => {
       if (subCommand._executableHandler) {
         this._executeSubCommand(subCommand, operands.concat(unknown));
       } else {
         return subCommand._parseCommand(operands, unknown);
       }
     });
-    return hookResult;
+    return promiseChain;
   }
 
   /**
    * Invoke help directly if possible, or dispatch if necessary.
    * e.g. help foo
    *
-   * @api private
+   * @private
    */
 
   _dispatchHelpCommand(subcommandName) {
@@ -1101,35 +1154,37 @@ Expecting one of '${allowedValues.join("', '")}'`);
     }
 
     // Fallback to parsing the help flag to invoke the help.
-    return this._dispatchSubcommand(subcommandName, [], [this._helpLongFlag]);
+    return this._dispatchSubcommand(subcommandName, [], [
+      this._helpLongFlag || this._helpShortFlag
+    ]);
   }
 
   /**
-   * Check this.args against expected this._args.
+   * Check this.args against expected this.registeredArguments.
    *
-   * @api private
+   * @private
    */
 
   _checkNumberOfArguments() {
     // too few
-    this._args.forEach((arg, i) => {
+    this.registeredArguments.forEach((arg, i) => {
       if (arg.required && this.args[i] == null) {
         this.missingArgument(arg.name());
       }
     });
     // too many
-    if (this._args.length > 0 && this._args[this._args.length - 1].variadic) {
+    if (this.registeredArguments.length > 0 && this.registeredArguments[this.registeredArguments.length - 1].variadic) {
       return;
     }
-    if (this.args.length > this._args.length) {
+    if (this.args.length > this.registeredArguments.length) {
       this._excessArguments(this.args);
     }
   }
 
   /**
-   * Process this.args using this._args and save as this.processedArgs!
+   * Process this.args using this.registeredArguments and save as this.processedArgs!
    *
-   * @api private
+   * @private
    */
 
   _processArguments() {
@@ -1137,15 +1192,8 @@ Expecting one of '${allowedValues.join("', '")}'`);
       // Extra processing for nice error message on parsing failure.
       let parsedValue = value;
       if (value !== null && argument.parseArg) {
-        try {
-          parsedValue = argument.parseArg(value, previous);
-        } catch (err) {
-          if (err.code === 'commander.invalidArgument') {
-            const message = `error: command-argument value '${value}' is invalid for argument '${argument.name()}'. ${err.message}`;
-            this.error(message, { exitCode: err.exitCode, code: err.code });
-          }
-          throw err;
-        }
+        const invalidValueMessage = `error: command-argument value '${value}' is invalid for argument '${argument.name()}'.`;
+        parsedValue = this._callParseArg(argument, value, previous, invalidValueMessage);
       }
       return parsedValue;
     };
@@ -1153,7 +1201,7 @@ Expecting one of '${allowedValues.join("', '")}'`);
     this._checkNumberOfArguments();
 
     const processedArgs = [];
-    this._args.forEach((declaredArg, index) => {
+    this.registeredArguments.forEach((declaredArg, index) => {
       let value = declaredArg.defaultValue;
       if (declaredArg.variadic) {
         // Collect together remaining arguments for passing together as an array.
@@ -1184,7 +1232,7 @@ Expecting one of '${allowedValues.join("', '")}'`);
    * @param {Promise|undefined} promise
    * @param {Function} fn
    * @return {Promise|undefined}
-   * @api private
+   * @private
    */
 
   _chainOrCall(promise, fn) {
@@ -1202,13 +1250,13 @@ Expecting one of '${allowedValues.join("', '")}'`);
    * @param {Promise|undefined} promise
    * @param {string} event
    * @return {Promise|undefined}
-   * @api private
+   * @private
    */
 
   _chainOrCallHooks(promise, event) {
     let result = promise;
     const hooks = [];
-    getCommandAndParents(this)
+    this._getCommandAndAncestors()
       .reverse()
       .filter(cmd => cmd._lifeCycleHooks[event] !== undefined)
       .forEach(hookedCommand => {
@@ -1234,7 +1282,7 @@ Expecting one of '${allowedValues.join("', '")}'`);
    * @param {Command} subCommand
    * @param {string} event
    * @return {Promise|undefined}
-   * @api private
+   * @private
    */
 
   _chainOrCallSubCommandHook(promise, subCommand, event) {
@@ -1253,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) {
@@ -1271,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) {
@@ -1279,7 +1327,7 @@ Expecting one of '${allowedValues.join("', '")}'`);
       this.help({ error: true });
     }
 
-    outputHelpIfRequested(this, parsed.unknown);
+    this._outputHelpIfRequested(parsed.unknown);
     this._checkForMissingMandatoryOptions();
     this._checkForConflictingOptions();
 
@@ -1295,16 +1343,16 @@ Expecting one of '${allowedValues.join("', '")}'`);
       checkForUnknownOptions();
       this._processArguments();
 
-      let actionResult;
-      actionResult = this._chainOrCallHooks(actionResult, 'preAction');
-      actionResult = this._chainOrCall(actionResult, () => this._actionHandler(this.processedArgs));
+      let promiseChain;
+      promiseChain = this._chainOrCallHooks(promiseChain, 'preAction');
+      promiseChain = this._chainOrCall(promiseChain, () => this._actionHandler(this.processedArgs));
       if (this.parent) {
-        actionResult = this._chainOrCall(actionResult, () => {
+        promiseChain = this._chainOrCall(promiseChain, () => {
           this.parent.emit(commandEvent, operands, unknown); // legacy
         });
       }
-      actionResult = this._chainOrCallHooks(actionResult, 'postAction');
-      return actionResult;
+      promiseChain = this._chainOrCallHooks(promiseChain, 'postAction');
+      return promiseChain;
     }
     if (this.parent && this.parent.listenerCount(commandEvent)) {
       checkForUnknownOptions();
@@ -1337,7 +1385,7 @@ Expecting one of '${allowedValues.join("', '")}'`);
   /**
    * Find matching command.
    *
-   * @api private
+   * @private
    */
   _findCommand(name) {
     if (!name) return undefined;
@@ -1349,7 +1397,7 @@ Expecting one of '${allowedValues.join("', '")}'`);
    *
    * @param {string} arg
    * @return {Option}
-   * @api private
+   * @package internal use only
    */
 
   _findOption(arg) {
@@ -1360,24 +1408,24 @@ 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() {
     // Walk up hierarchy so can call in subcommand after checking for displaying help.
-    for (let cmd = this; cmd; cmd = cmd.parent) {
+    this._getCommandAndAncestors().forEach((cmd) => {
       cmd.options.forEach((anOption) => {
         if (anOption.mandatory && (cmd.getOptionValue(anOption.attributeName()) === undefined)) {
           cmd.missingMandatoryOptionValue(anOption);
         }
       });
-    }
+    });
   }
 
   /**
    * Display an error message if conflicting options are used together in this.
    *
-   * @api private
+   * @private
    */
   _checkForConflictingLocalOptions() {
     const definedNonDefaultOptions = this.options.filter(
@@ -1408,13 +1456,13 @@ 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.
-    for (let cmd = this; cmd; cmd = cmd.parent) {
+    this._getCommandAndAncestors().forEach((cmd) => {
       cmd._checkForConflictingLocalOptions();
-    }
+    });
   }
 
   /**
@@ -1577,7 +1625,7 @@ Expecting one of '${allowedValues.join("', '")}'`);
    */
   optsWithGlobals() {
     // globals overwrite locals
-    return getCommandAndParents(this).reduce(
+    return this._getCommandAndAncestors().reduce(
       (combinedOptions, cmd) => Object.assign(combinedOptions, cmd.opts()),
       {}
     );
@@ -1612,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) => {
@@ -1635,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);
@@ -1659,7 +1707,7 @@ Expecting one of '${allowedValues.join("', '")}'`);
    * Argument `name` is missing.
    *
    * @param {string} name
-   * @api private
+   * @private
    */
 
   missingArgument(name) {
@@ -1671,7 +1719,7 @@ Expecting one of '${allowedValues.join("', '")}'`);
    * `Option` is missing an argument.
    *
    * @param {Option} option
-   * @api private
+   * @private
    */
 
   optionMissingArgument(option) {
@@ -1683,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) {
@@ -1696,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
@@ -1733,7 +1781,7 @@ Expecting one of '${allowedValues.join("', '")}'`);
    * Unknown option `flag`.
    *
    * @param {string} flag
-   * @api private
+   * @private
    */
 
   unknownOption(flag) {
@@ -1762,13 +1810,13 @@ Expecting one of '${allowedValues.join("', '")}'`);
    * Excess arguments, more than expected.
    *
    * @param {string[]} receivedArgs
-   * @api private
+   * @private
    */
 
   _excessArguments(receivedArgs) {
     if (this._allowExcessArguments) return;
 
-    const expected = this._args.length;
+    const expected = this.registeredArguments.length;
     const s = (expected === 1) ? '' : 's';
     const forSubcommand = this.parent ? ` for '${this.name()}'` : '';
     const message = `error: too many arguments${forSubcommand}. Expected ${expected} argument${s} but got ${receivedArgs.length}.`;
@@ -1778,7 +1826,7 @@ Expecting one of '${allowedValues.join("', '")}'`);
   /**
    * Unknown command.
    *
-   * @api private
+   * @private
    */
 
   unknownCommand() {
@@ -1800,17 +1848,16 @@ Expecting one of '${allowedValues.join("', '")}'`);
   }
 
   /**
-   * Set the program version to `str`.
+   * Get or set the program version.
    *
-   * This method auto-registers the "-V, --version" flag
-   * which will print the version number when passed.
+   * This method auto-registers the "-V, --version" option which will print the version number.
    *
-   * You can optionally supply the  flags and description to override the defaults.
+   * You can optionally supply the flags and description to override the defaults.
    *
-   * @param {string} str
+   * @param {string} [str]
    * @param {string} [flags]
    * @param {string} [description]
-   * @return {this | string} `this` command for chaining, or version string if no arguments
+   * @return {this | string | undefined} `this` command for chaining, or version string if no arguments
    */
 
   version(str, flags, description) {
@@ -1820,7 +1867,8 @@ Expecting one of '${allowedValues.join("', '")}'`);
     description = description || 'output the version number';
     const versionOption = this.createOption(flags, description);
     this._versionOptionName = versionOption.attributeName();
-    this.options.push(versionOption);
+    this._registerOption(versionOption);
+
     this.on('option:' + versionOption.name(), () => {
       this._outputConfiguration.writeOut(`${str}\n`);
       this._exit(0, 'commander.version', str);
@@ -1876,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;
@@ -1909,13 +1963,13 @@ Expecting one of '${allowedValues.join("', '")}'`);
     if (str === undefined) {
       if (this._usage) return this._usage;
 
-      const args = this._args.map((arg) => {
+      const args = this.registeredArguments.map((arg) => {
         return humanReadableArgName(arg);
       });
       return [].concat(
         (this.options.length || this._hasHelpOption ? '[options]' : []),
         (this.commands.length ? '[command]' : []),
-        (this._args.length ? args : [])
+        (this.registeredArguments.length ? args : [])
       ).join(' ');
     }
 
@@ -1964,7 +2018,7 @@ Expecting one of '${allowedValues.join("', '")}'`);
    * program.executableDir('subcommands');
    *
    * @param {string} [path]
-   * @return {string|Command}
+   * @return {string|null|Command}
    */
 
   executableDir(path) {
@@ -1989,7 +2043,7 @@ Expecting one of '${allowedValues.join("', '")}'`);
   }
 
   /**
-   * @api private
+   * @private
    */
 
   _getHelpContext(contextOptions) {
@@ -2022,7 +2076,7 @@ Expecting one of '${allowedValues.join("', '")}'`);
     }
     const context = this._getHelpContext(contextOptions);
 
-    getCommandAndParents(this).reverse().forEach(command => command.emit('beforeAllHelp', context));
+    this._getCommandAndAncestors().reverse().forEach(command => command.emit('beforeAllHelp', context));
     this.emit('beforeHelp', context);
 
     let helpInformation = this.helpInformation(context);
@@ -2034,9 +2088,11 @@ Expecting one of '${allowedValues.join("', '")}'`);
     }
     context.write(helpInformation);
 
-    this.emit(this._helpLongFlag); // deprecated
+    if (this._helpLongFlag) {
+      this.emit(this._helpLongFlag); // deprecated
+    }
     this.emit('afterHelp', context);
-    getCommandAndParents(this).forEach(command => command.emit('afterAllHelp', context));
+    this._getCommandAndAncestors().forEach(command => command.emit('afterAllHelp', context));
   }
 
   /**
@@ -2113,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)');
+    }
   }
 }
 
@@ -2137,7 +2192,7 @@ function outputHelpIfRequested(cmd, args) {
  *
  * @param {string[]} args - array of arguments from node.execArgv
  * @returns {string[]}
- * @api private
+ * @private
  */
 
 function incrementNodeInspectorPort(args) {
@@ -2179,18 +2234,4 @@ function incrementNodeInspectorPort(args) {
   });
 }
 
-/**
- * @param {Command} startCommand
- * @returns {Command[]}
- * @api private
- */
-
-function getCommandAndParents(startCommand) {
-  const result = [];
-  for (let command = startCommand; command; command = command.parent) {
-    result.push(command);
-  }
-  return result;
-}
-
 exports.Command = Command;