Merge branch 'develop' into release/12.x

jest.config.js

@@ -0,0 +1,12 @@
+const config = {
+  testEnvironment: 'node',
+  collectCoverage: true,
+  transform: {
+    '^.+\\.tsx?$': 'ts-jest'
+  },
+  testPathIgnorePatterns: [
+    '/node_modules/'
+  ]
+};
+
+module.exports = config;

lib/command.js

@@ -515,6 +515,28 @@ Expecting one of '${allowedValues.join("', '")}'`);
     return new Option(flags, description);
   }
 
+  /**
+   * Wrap parseArgs to catch 'commander.invalidArgument'.
+   *
+   * @param {Option | Argument} target
+   * @param {string} value
+   * @param {any} previous
+   * @param {string} invalidArgumentMessage
+   * @api 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;
+    }
+  }
+
   /**
    * Add an option.
    *
@@ -550,15 +572,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);
       }
@@ -1165,15 +1179,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;
     };
@@ -1828,17 +1835,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) {
@@ -1847,7 +1853,7 @@ 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();
+    this._versionOptionName = versionOption.attributeName(); // [sic] not defined in constructor, partly legacy, partly only needed at root
     this.options.push(versionOption);
     this.on('option:' + versionOption.name(), () => {
       this._outputConfiguration.writeOut(`${str}\n`);

package.json

@@ -73,16 +73,6 @@
     "typescript": "^5.0.4"
   },
   "types": "typings/index.d.ts",
-  "jest": {
-    "testEnvironment": "node",
-    "collectCoverage": true,
-    "transform": {
-      "^.+\\.tsx?$": "ts-jest"
-    },
-    "testPathIgnorePatterns": [
-      "/node_modules/"
-    ]
-  },
   "engines": {
     "node": ">=16"
   },

typings/index.d.ts

@@ -5,6 +5,14 @@
 /* eslint-disable @typescript-eslint/method-signature-style */
 /* eslint-disable @typescript-eslint/no-explicit-any */
 
+// This is a trick to encourage editor to suggest the known literals while still
+// allowing any BaseType value.
+// References:
+// - https://github.com/microsoft/TypeScript/issues/29729
+// - https://github.com/sindresorhus/type-fest/blob/main/source/literal-union.d.ts
+// - https://github.com/sindresorhus/type-fest/blob/main/source/primitive.d.ts
+type LiteralUnion<LiteralType, BaseType extends string | number> = LiteralType | (BaseType & Record<never, never>);
+
 export class CommanderError extends Error {
   code: string;
   exitCode: number;
@@ -272,7 +280,8 @@ export interface OutputConfiguration {
 
 export type AddHelpTextPosition = 'beforeAll' | 'before' | 'after' | 'afterAll';
 export type HookEvent = 'preSubcommand' | 'preAction' | 'postAction';
-export type OptionValueSource = 'default' | 'config' | 'env' | 'cli' | 'implied';
+// The source is a string so author can define their own too.
+export type OptionValueSource = LiteralUnion<'default' | 'config' | 'env' | 'cli' | 'implied', string> | undefined;
 
 export type OptionValues = Record<string, any>;
 
@@ -294,6 +303,10 @@ export class Command {
    * You can optionally supply the  flags and description to override the defaults.
    */
   version(str: string, flags?: string, description?: string): this;
+  /**
+   * Get the program version.
+   */
+  version(): string | undefined;
 
   /**
    * Define a command, implemented using an action handler.

typings/index.test-d.ts

@@ -36,6 +36,7 @@ expectType<commander.Command | null>(program.parent);
 expectType<commander.Command>(program.version('1.2.3'));
 expectType<commander.Command>(program.version('1.2.3', '-r,--revision'));
 expectType<commander.Command>(program.version('1.2.3', '-r,--revision', 'show revision information'));
+expectType<string | undefined>(program.version());
 
 // command (and CommandOptions)
 expectType<commander.Command>(program.command('action'));