commander 11.0.0 → 12.0.0-0

package/lib/error.js

@@ -1,5 +1,3 @@
-// @ts-check
-
 /**
  * CommanderError class
  * @class

package/lib/help.js

@@ -8,8 +8,6 @@ const { humanReadableArgName } = require('./argument.js');
  * @typedef { import("./option.js").Option } Option
  */
 
-// @ts-check
-
 // Although this is a class, methods are static in style to allow override using subclass or just functions.
 class Help {
   constructor() {
@@ -101,8 +99,8 @@ class Help {
     if (!this.showGlobalOptions) return [];
 
     const globalOptions = [];
-    for (let parentCmd = cmd.parent; parentCmd; parentCmd = parentCmd.parent) {
-      const visibleOptions = parentCmd.options.filter((option) => !option.hidden);
+    for (let ancestorCmd = cmd.parent; ancestorCmd; ancestorCmd = ancestorCmd.parent) {
+      const visibleOptions = ancestorCmd.options.filter((option) => !option.hidden);
       globalOptions.push(...visibleOptions);
     }
     if (this.sortOptions) {
@@ -121,14 +119,14 @@ class Help {
   visibleArguments(cmd) {
     // Side effect! Apply the legacy descriptions before the arguments are displayed.
     if (cmd._argsDescription) {
-      cmd._args.forEach(argument => {
+      cmd.registeredArguments.forEach(argument => {
         argument.description = argument.description || cmd._argsDescription[argument.name()] || '';
       });
     }
 
     // If there are any arguments with a description then return all the arguments.
-    if (cmd._args.find(argument => argument.description)) {
-      return cmd._args;
+    if (cmd.registeredArguments.find(argument => argument.description)) {
+      return cmd.registeredArguments;
     }
     return [];
   }
@@ -142,7 +140,7 @@ class Help {
 
   subcommandTerm(cmd) {
     // Legacy. Ignores custom usage string, and nested commands.
-    const args = cmd._args.map(arg => humanReadableArgName(arg)).join(' ');
+    const args = cmd.registeredArguments.map(arg => humanReadableArgName(arg)).join(' ');
     return cmd._name +
       (cmd._aliases[0] ? '|' + cmd._aliases[0] : '') +
       (cmd.options.length ? ' [options]' : '') + // simplistic check for non-help option
@@ -240,11 +238,11 @@ class Help {
     if (cmd._aliases[0]) {
       cmdName = cmdName + '|' + cmd._aliases[0];
     }
-    let parentCmdNames = '';
-    for (let parentCmd = cmd.parent; parentCmd; parentCmd = parentCmd.parent) {
-      parentCmdNames = parentCmd.name() + ' ' + parentCmdNames;
+    let ancestorCmdNames = '';
+    for (let ancestorCmd = cmd.parent; ancestorCmd; ancestorCmd = ancestorCmd.parent) {
+      ancestorCmdNames = ancestorCmd.name() + ' ' + ancestorCmdNames;
     }
-    return parentCmdNames + cmdName + ' ' + cmd.usage();
+    return ancestorCmdNames + cmdName + ' ' + cmd.usage();
   }
 
   /**

package/lib/option.js

@@ -1,7 +1,5 @@
 const { InvalidArgumentError } = require('./error.js');
 
-// @ts-check
-
 class Option {
   /**
    * Initialize a new `Option` with the given `flags` and `description`.
@@ -40,7 +38,7 @@ class Option {
   /**
    * Set the default value, and optionally supply the description to be displayed in the help.
    *
-   * @param {any} value
+   * @param {*} value
    * @param {string} [description]
    * @return {Option}
    */
@@ -59,7 +57,7 @@ class Option {
    * new Option('--color').default('GREYSCALE').preset('RGB');
    * new Option('--donate [amount]').preset('20').argParser(parseFloat);
    *
-   * @param {any} arg
+   * @param {*} arg
    * @return {Option}
    */
 
@@ -160,7 +158,7 @@ class Option {
   }
 
   /**
-   * @api private
+   * @package internal use only
    */
 
   _concatValue(value, previous) {
@@ -210,7 +208,6 @@ class Option {
    * as a object attribute key.
    *
    * @return {string}
-   * @api private
    */
 
   attributeName() {
@@ -222,7 +219,7 @@ class Option {
    *
    * @param {string} arg
    * @return {boolean}
-   * @api private
+   * @package internal use only
    */
 
   is(arg) {
@@ -235,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() {
@@ -275,7 +272,7 @@ class DualOptions {
   /**
    * Did the value come from the option, and not from possible matching dual option?
    *
-   * @param {any} value
+   * @param {*} value
    * @param {Option} option
    * @returns {boolean}
    */
@@ -295,7 +292,7 @@ class DualOptions {
  *
  * @param {string} str
  * @return {string}
- * @api private
+ * @private
  */
 
 function camelcase(str) {
@@ -307,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.0.0",
+  "version": "12.0.0-0",
   "description": "the complete solution for node.js command-line programs",
   "keywords": [
     "commander",
@@ -22,11 +22,11 @@
     "lint": "npm run lint:javascript && npm run lint:typescript",
     "lint:javascript": "eslint index.js esm.mjs \"lib/*.js\" \"tests/**/*.js\"",
     "lint:typescript": "eslint typings/*.ts tests/*.ts",
-    "test": "jest && npm run test-typings",
+    "test": "jest && npm run typecheck-ts",
     "test-esm": "node ./tests/esm-imports-test.mjs",
-    "test-typings": "tsd",
-    "typescript-checkJS": "tsc --allowJS --checkJS index.js lib/*.js --noEmit",
-    "test-all": "npm run test && npm run lint && npm run typescript-checkJS && npm run test-esm"
+    "typecheck-ts": "tsd && tsc -p tsconfig.ts.json",
+    "typecheck-js": "tsc -p tsconfig.js.json",
+    "test-all": "npm run test && npm run lint && npm run typecheck-js && npm run test-esm"
   },
   "files": [
     "index.js",
@@ -58,33 +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",
-  "jest": {
-    "testEnvironment": "node",
-    "collectCoverage": true,
-    "transform": {
-      "^.+\\.tsx?$": "ts-jest"
-    },
-    "testPathIgnorePatterns": [
-      "/node_modules/"
-    ]
-  },
   "engines": {
-    "node": ">=16"
+    "node": ">=18"
   },
   "support": true
 }

package/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;
@@ -42,6 +50,9 @@ export class Argument {
   description: string;
   required: boolean;
   variadic: boolean;
+  defaultValue?: any;
+  defaultValueDescription?: string;
+  argChoices?: string[];
 
   /**
    * Initialize a new command argument with the given name and description.
@@ -94,6 +105,8 @@ export class Option {
   negate: boolean;
   defaultValue?: any;
   defaultValueDescription?: string;
+  presetArg?: unknown;
+  envVar?: string;
   parseArg?: <T>(value: string, previous: T) => T;
   hidden: boolean;
   argChoices?: string[];
@@ -272,7 +285,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>;
 
@@ -281,6 +295,7 @@ export class Command {
   processedArgs: any[];
   readonly commands: readonly Command[];
   readonly options: readonly Option[];
+  readonly registeredArguments: readonly Argument[];
   parent: Command | null;
 
   constructor(name?: string);
@@ -294,6 +309,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.
@@ -497,51 +516,27 @@ export class Command {
   action(fn: (...args: any[]) => void | Promise<void>): this;
 
   /**
-   * 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 false
-   *  program.option('-p, --pepper', 'add pepper');
    *
-   *  --pepper
-   *  program.pepper
-   *  // => Boolean
-   *
-   *  // simple boolean defaulting to true
-   *  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]');
+   * ```js
+   * 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
    * ```
    *
    * @returns `this` command for chaining
    */
   option(flags: string, description?: string, defaultValue?: string | boolean | string[]): this;
-  option<T>(flags: string, description: string, fn: (value: string, previous: T) => T, defaultValue?: T): this;
+  option<T>(flags: string, description: string, parseArg: (value: string, previous: T) => T, defaultValue?: T): this;
   /** @deprecated since v7, instead use choices or a custom function */
   option(flags: string, description: string, regexp: RegExp, defaultValue?: string | boolean | string[]): this;
 
@@ -552,7 +547,7 @@ export class Command {
    * The `flags` string contains the short and/or long flags, separated by comma, a pipe or space.
    */
   requiredOption(flags: string, description?: string, defaultValue?: string | boolean | string[]): this;
-  requiredOption<T>(flags: string, description: string, fn: (value: string, previous: T) => T, defaultValue?: T): this;
+  requiredOption<T>(flags: string, description: string, parseArg: (value: string, previous: T) => T, defaultValue?: T): this;
   /** @deprecated since v7, instead use choices or a custom function */
   requiredOption(flags: string, description: string, regexp: RegExp, defaultValue?: string | boolean | string[]): this;
 
@@ -819,7 +814,7 @@ export class Command {
   /**
    * Get the executable search directory.
    */
-  executableDir(): string;
+  executableDir(): string | null;
 
   /**
    * Output help information for this command.