commander 12.0.0 → 13.0.0-0

package/lib/option.js

@@ -93,7 +93,7 @@ class Option {
    *   .addOption(new Option('--log', 'write logging information to file'))
    *   .addOption(new Option('--trace', 'log extra details').implies({ log: 'trace.txt' }));
    *
-   * @param {Object} impliedOptionValues
+   * @param {object} impliedOptionValues
    * @return {Option}
    */
   implies(impliedOptionValues) {
@@ -158,7 +158,7 @@ class Option {
   }
 
   /**
-   * @package internal use only
+   * @package
    */
 
   _concatValue(value, previous) {
@@ -180,7 +180,9 @@ class Option {
     this.argChoices = values.slice();
     this.parseArg = (arg, previous) => {
       if (!this.argChoices.includes(arg)) {
-        throw new InvalidArgumentError(`Allowed choices are ${this.argChoices.join(', ')}.`);
+        throw new InvalidArgumentError(
+          `Allowed choices are ${this.argChoices.join(', ')}.`,
+        );
       }
       if (this.variadic) {
         return this._concatValue(arg, previous);
@@ -205,13 +207,16 @@ class Option {
 
   /**
    * Return option name, in a camelcase format that can be used
-   * as a object attribute key.
+   * as an object attribute key.
    *
    * @return {string}
    */
 
   attributeName() {
-    return camelcase(this.name().replace(/^no-/, ''));
+    if (this.negate) {
+      return camelcase(this.name().replace(/^no-/, ''));
+    }
+    return camelcase(this.name());
   }
 
   /**
@@ -219,7 +224,7 @@ class Option {
    *
    * @param {string} arg
    * @return {boolean}
-   * @package internal use only
+   * @package
    */
 
   is(arg) {
@@ -232,7 +237,7 @@ class Option {
    * Options are one of boolean, negated, required argument, or optional argument.
    *
    * @return {boolean}
-   * @package internal use only
+   * @package
    */
 
   isBoolean() {
@@ -255,7 +260,7 @@ class DualOptions {
     this.positiveOptions = new Map();
     this.negativeOptions = new Map();
     this.dualOptions = new Set();
-    options.forEach(option => {
+    options.forEach((option) => {
       if (option.negate) {
         this.negativeOptions.set(option.attributeName(), option);
       } else {
@@ -282,7 +287,7 @@ class DualOptions {
 
     // Use the value to deduce if (probably) came from the option.
     const preset = this.negativeOptions.get(optionKey).presetArg;
-    const negativeValue = (preset !== undefined) ? preset : false;
+    const negativeValue = preset !== undefined ? preset : false;
     return option.negate === (negativeValue === value);
   }
 }
@@ -310,16 +315,32 @@ function camelcase(str) {
 function splitOptionFlags(flags) {
   let shortFlag;
   let longFlag;
-  // Use original very loose parsing to maintain backwards compatibility for now,
-  // which allowed for example unintended `-sw, --short-word` [sic].
-  const flagParts = flags.split(/[ |,]+/);
-  if (flagParts.length > 1 && !/^[[<]/.test(flagParts[1])) shortFlag = flagParts.shift();
-  longFlag = flagParts.shift();
-  // Add support for lone short flag without significantly changing parsing!
-  if (!shortFlag && /^-[^-]$/.test(longFlag)) {
-    shortFlag = longFlag;
-    longFlag = undefined;
-  }
+  // short flag, single dash and single character
+  const shortFlagExp = /^-[^-]$/;
+  // long flag, double dash and at least one character
+  const longFlagExp = /^--[^-]/;
+
+  const flagParts = flags.split(/[ |,]+/).concat('guard');
+  if (shortFlagExp.test(flagParts[0])) shortFlag = flagParts.shift();
+  if (longFlagExp.test(flagParts[0])) longFlag = flagParts.shift();
+
+  // Check for some unsupported flags that people try.
+  if (/^-[^-][^-]/.test(flagParts[0]))
+    throw new Error(
+      `invalid Option flags, short option is dash and single character: '${flags}'`,
+    );
+  if (shortFlag && shortFlagExp.test(flagParts[0]))
+    throw new Error(
+      `invalid Option flags, more than one short flag: '${flags}'`,
+    );
+  if (longFlag && longFlagExp.test(flagParts[0]))
+    throw new Error(
+      `invalid Option flags, more than one long flag: '${flags}'`,
+    );
+  // Generic error if failed to find a flag or an unexpected flag left over.
+  if (!(shortFlag || longFlag) || flagParts[0].startsWith('-'))
+    throw new Error(`invalid Option flags: '${flags}'`);
+
   return { shortFlag, longFlag };
 }
 

package/lib/suggestSimilar.js

@@ -6,7 +6,8 @@ function editDistance(a, b) {
   // (Simple implementation.)
 
   // Quick early exit, return worst case.
-  if (Math.abs(a.length - b.length) > maxDistance) return Math.max(a.length, b.length);
+  if (Math.abs(a.length - b.length) > maxDistance)
+    return Math.max(a.length, b.length);
 
   // distance between prefix substrings of a and b
   const d = [];
@@ -32,7 +33,7 @@ function editDistance(a, b) {
       d[i][j] = Math.min(
         d[i - 1][j] + 1, // deletion
         d[i][j - 1] + 1, // insertion
-        d[i - 1][j - 1] + cost // substitution
+        d[i - 1][j - 1] + cost, // substitution
       );
       // transposition
       if (i > 1 && j > 1 && a[i - 1] === b[j - 2] && a[i - 2] === b[j - 1]) {
@@ -60,7 +61,7 @@ function suggestSimilar(word, candidates) {
   const searchingOptions = word.startsWith('--');
   if (searchingOptions) {
     word = word.slice(2);
-    candidates = candidates.map(candidate => candidate.slice(2));
+    candidates = candidates.map((candidate) => candidate.slice(2));
   }
 
   let similar = [];
@@ -85,7 +86,7 @@ function suggestSimilar(word, candidates) {
 
   similar.sort((a, b) => a.localeCompare(b));
   if (searchingOptions) {
-    similar = similar.map(candidate => `--${candidate}`);
+    similar = similar.map((candidate) => `--${candidate}`);
   }
 
   if (similar.length > 1) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "commander",
-  "version": "12.0.0",
+  "version": "13.0.0-0",
   "description": "the complete solution for node.js command-line programs",
   "keywords": [
     "commander",
@@ -19,14 +19,18 @@
     "url": "git+https://github.com/tj/commander.js.git"
   },
   "scripts": {
-    "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 typecheck-ts",
-    "test-esm": "node ./tests/esm-imports-test.mjs",
-    "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"
+    "check": "npm run check:type && npm run check:lint && npm run check:format",
+    "check:format": "prettier --check .",
+    "check:lint": "eslint .",
+    "check:type": "npm run check:type:js && npm run check:type:ts",
+    "check:type:ts": "tsd && tsc -p tsconfig.ts.json",
+    "check:type:js": "tsc -p tsconfig.js.json",
+    "fix": "npm run fix:lint && npm run fix:format",
+    "fix:format": "prettier --write .",
+    "fix:lint": "eslint --fix .",
+    "test": "jest && npm run check:type:ts",
+    "test-all": "jest && npm run test-esm && npm run check",
+    "test-esm": "node ./tests/esm-imports-test.mjs"
   },
   "files": [
     "index.js",
@@ -56,21 +60,19 @@
     }
   },
   "devDependencies": {
+    "@eslint/js": "^9.4.0",
     "@types/jest": "^29.2.4",
-    "@types/node": "^20.2.5",
-    "@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": "^40.0.0",
-    "eslint-plugin-import": "^2.26.0",
-    "eslint-plugin-jest": "^27.1.7",
-    "eslint-plugin-n": "^16.2.0",
-    "eslint-plugin-promise": "^6.1.1",
+    "@types/node": "^22.7.4",
+    "eslint": "^8.57.1",
+    "eslint-config-prettier": "^9.1.0",
+    "eslint-plugin-jest": "^28.3.0",
+    "globals": "^15.7.0",
     "jest": "^29.3.1",
+    "prettier": "^3.2.5",
     "ts-jest": "^29.0.3",
-    "tsd": "^0.30.4",
-    "typescript": "^5.0.4"
+    "tsd": "^0.31.0",
+    "typescript": "^5.0.4",
+    "typescript-eslint": "^8.12.2"
   },
   "types": "typings/index.d.ts",
   "engines": {

package/typings/index.d.ts

@@ -11,7 +11,9 @@
 // - 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>);
+type LiteralUnion<LiteralType, BaseType extends string | number> =
+  | LiteralType
+  | (BaseType & Record<never, never>);
 
 export class CommanderError extends Error {
   code: string;
@@ -24,7 +26,6 @@ export class CommanderError extends Error {
    * @param exitCode - suggested exit code which could be used with process.exit
    * @param code - an id string representing the error
    * @param message - human-readable description of the error
-   * @constructor
    */
   constructor(exitCode: number, code: string, message: string);
 }
@@ -33,13 +34,13 @@ export class InvalidArgumentError extends CommanderError {
   /**
    * Constructs the InvalidArgumentError class
    * @param message - explanation of why argument is invalid
-   * @constructor
    */
   constructor(message: string);
 }
 export { InvalidArgumentError as InvalidOptionArgumentError }; // deprecated old name
 
-export interface ErrorOptions { // optional parameter for error()
+export interface ErrorOptions {
+  // optional parameter for error()
   /** an id string representing the error */
   code?: string;
   /** suggested exit code which could be used with process.exit */
@@ -162,11 +163,6 @@ export class Option {
    */
   env(name: string): this;
 
-  /**
-   * Calculate the full description, including defaultValue etc.
-   */
-  fullDescription(): string;
-
   /**
    * Set the custom handler for processing CLI option arguments into option values.
    */
@@ -194,7 +190,7 @@ export class Option {
 
   /**
    * Return option name, in a camelcase format that can be used
-   * as a object attribute key.
+   * as an object attribute key.
    */
   attributeName(): string;
 
@@ -209,12 +205,25 @@ export class Option {
 export class Help {
   /** output helpWidth, long lines are wrapped to fit */
   helpWidth?: number;
+  minWidthToWrap: number;
   sortSubcommands: boolean;
   sortOptions: boolean;
   showGlobalOptions: boolean;
 
   constructor();
 
+  /*
+   * prepareContext is called by Commander after applying overrides from `Command.configureHelp()`
+   * and just before calling `formatHelp()`.
+   *
+   * Commander just uses the helpWidth and the others are provided for subclasses.
+   */
+  prepareContext(contextOptions: {
+    error?: boolean;
+    helpWidth?: number;
+    outputHasColors?: boolean;
+  }): void;
+
   /** Get the command term to show in the list of subcommands. */
   subcommandTerm(cmd: Command): string;
   /** Get the command summary to show in the list of subcommands. */
@@ -250,14 +259,61 @@ export class Help {
   longestGlobalOptionTermLength(cmd: Command, helper: Help): number;
   /** Get the longest argument term length. */
   longestArgumentTermLength(cmd: Command, helper: Help): number;
+
+  /** Return display width of string, ignoring ANSI escape sequences. Used in padding and wrapping calculations. */
+  displayWidth(str: string): number;
+
+  /** Style the titles. Called with 'Usage:', 'Options:', etc. */
+  styleTitle(title: string): string;
+
+  /** Usage: <str> */
+  styleUsage(str: string): string;
+  /** Style for command name in usage string.  */
+  styleCommandText(str: string): string;
+
+  styleCommandDescription(str: string): string;
+  styleOptionDescription(str: string): string;
+  styleSubcommandDescription(str: string): string;
+  styleArgumentDescription(str: string): string;
+  /** Base style used by descriptions. */
+  styleDescriptionText(str: string): string;
+
+  styleOptionTerm(str: string): string;
+  styleSubcommandTerm(str: string): string;
+  styleArgumentTerm(str: string): string;
+
+  /** Base style used in terms and usage for options. */
+  styleOptionText(str: string): string;
+  /** Base style used in terms and usage for subcommands. */
+  styleSubcommandText(str: string): string;
+  /** Base style used in terms and usage for arguments. */
+  styleArgumentText(str: string): string;
+
   /** Calculate the pad width from the maximum term length. */
   padWidth(cmd: Command, helper: Help): number;
 
   /**
-   * Wrap the given string to width characters per line, with lines after the first indented.
-   * Do not wrap if insufficient room for wrapping (minColumnWidth), or string is manually formatted.
+   * Wrap a string at whitespace, preserving existing line breaks.
+   * Wrapping is skipped if the width is less than `minWidthToWrap`.
+   */
+  boxWrap(str: string, width: number): string;
+
+  /** Detect manually wrapped and indented strings by checking for line break followed by whitespace. */
+  preformatted(str: string): boolean;
+
+  /**
+   * Format the "item", which consists of a term and description. Pad the term and wrap the description, indenting the following lines.
+   *
+   * So "TTT", 5, "DDD DDDD DD DDD" might be formatted for this.helpWidth=17 like so:
+   *   TTT    DDD DDDD
+   *          DD DDD
    */
-  wrap(str: string, width: number, indent: number, minColumnWidth?: number): string;
+  formatItem(
+    term: string,
+    termWidth: number,
+    description: string,
+    helper: Help,
+  ): string;
 
   /** Generate the built-in help text. */
   formatHelp(cmd: Command, helper: Help): string;
@@ -267,26 +323,34 @@ export type HelpConfiguration = Partial<Help>;
 export interface ParseOptions {
   from: 'node' | 'electron' | 'user';
 }
-export interface HelpContext { // optional parameter for .help() and .outputHelp()
+export interface HelpContext {
+  // optional parameter for .help() and .outputHelp()
   error: boolean;
 }
-export interface AddHelpTextContext { // passed to text function used with .addHelpText()
+export interface AddHelpTextContext {
+  // passed to text function used with .addHelpText()
   error: boolean;
   command: Command;
 }
 export interface OutputConfiguration {
   writeOut?(str: string): void;
   writeErr?(str: string): void;
+  outputError?(str: string, write: (str: string) => void): void;
+
   getOutHelpWidth?(): number;
   getErrHelpWidth?(): number;
-  outputError?(str: string, write: (str: string) => void): void;
 
+  getOutHasColors?(): boolean;
+  getErrHasColors?(): boolean;
+  stripColor?(str: string): string;
 }
 
 export type AddHelpTextPosition = 'beforeAll' | 'before' | 'after' | 'afterAll';
 export type HookEvent = 'preSubcommand' | 'preAction' | 'postAction';
 // 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 OptionValueSource =
+  | LiteralUnion<'default' | 'config' | 'env' | 'cli' | 'implied', string>
+  | undefined;
 
 export type OptionValues = Record<string, any>;
 
@@ -334,7 +398,10 @@ export class Command {
    * @param opts - configuration options
    * @returns new command
    */
-  command(nameAndArgs: string, opts?: CommandOptions): ReturnType<this['createCommand']>;
+  command(
+    nameAndArgs: string,
+    opts?: CommandOptions,
+  ): ReturnType<this['createCommand']>;
   /**
    * Define a command, implemented in a separate executable file.
    *
@@ -353,7 +420,11 @@ export class Command {
    * @param opts - configuration options
    * @returns `this` command for chaining
    */
-  command(nameAndArgs: string, description: string, opts?: ExecutableCommandOptions): this;
+  command(
+    nameAndArgs: string,
+    description: string,
+    opts?: ExecutableCommandOptions,
+  ): this;
 
   /**
    * Factory routine to create a new unattached command.
@@ -394,7 +465,12 @@ export class Command {
    *
    * @returns `this` command for chaining
    */
-  argument<T>(flags: string, description: string, fn: (value: string, previous: T) => T, defaultValue?: T): this;
+  argument<T>(
+    flags: string,
+    description: string,
+    fn: (value: string, previous: T) => T,
+    defaultValue?: T,
+  ): this;
   argument(name: string, description?: string, defaultValue?: unknown): this;
 
   /**
@@ -444,7 +520,13 @@ export class Command {
   /**
    * Add hook for life cycle event.
    */
-  hook(event: HookEvent, listener: (thisCommand: Command, actionCommand: Command) => void | Promise<void>): this;
+  hook(
+    event: HookEvent,
+    listener: (
+      thisCommand: Command,
+      actionCommand: Command,
+    ) => void | Promise<void>,
+  ): this;
 
   /**
    * Register callback to use as replacement for calling process.exit.
@@ -522,7 +604,7 @@ export class Command {
    *
    * @returns `this` command for chaining
    */
-  action(fn: (...args: any[]) => void | Promise<void>): this;
+  action(fn: (this: this, ...args: any[]) => void | Promise<void>): this;
 
   /**
    * Define option with `flags`, `description`, and optional argument parsing function or `defaultValue` or both.
@@ -544,10 +626,24 @@ export class Command {
    *
    * @returns `this` command for chaining
    */
-  option(flags: string, description?: string, defaultValue?: string | boolean | string[]): this;
-  option<T>(flags: string, description: string, parseArg: (value: string, previous: T) => T, defaultValue?: T): this;
+  option(
+    flags: string,
+    description?: string,
+    defaultValue?: string | boolean | string[],
+  ): 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;
+  option(
+    flags: string,
+    description: string,
+    regexp: RegExp,
+    defaultValue?: string | boolean | string[],
+  ): this;
 
   /**
    * Define a required option, which must have a value after parsing. This usually means
@@ -555,10 +651,24 @@ 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, parseArg: (value: string, previous: T) => T, defaultValue?: T): this;
+  requiredOption(
+    flags: string,
+    description?: string,
+    defaultValue?: string | boolean | string[],
+  ): 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;
+  requiredOption(
+    flags: string,
+    description: string,
+    regexp: RegExp,
+    defaultValue?: string | boolean | string[],
+  ): this;
 
   /**
    * Factory routine to create a new unattached option.
@@ -583,7 +693,9 @@ export class Command {
    * @returns `this` command for chaining
    */
   storeOptionsAsProperties<T extends OptionValues>(): this & T;
-  storeOptionsAsProperties<T extends OptionValues>(storeAsProperties: true): this & T;
+  storeOptionsAsProperties<T extends OptionValues>(
+    storeAsProperties: true,
+  ): this & T;
   storeOptionsAsProperties(storeAsProperties?: boolean): this;
 
   /**
@@ -599,7 +711,11 @@ export class Command {
   /**
    * Store option value and where the value came from.
    */
-  setOptionValueWithSource(key: string, value: unknown, source: OptionValueSource): this;
+  setOptionValueWithSource(
+    key: string,
+    value: unknown,
+    source: OptionValueSource,
+  ): this;
 
   /**
    * Get source of option value.
@@ -607,7 +723,7 @@ export class Command {
   getOptionValueSource(key: string): OptionValueSource | undefined;
 
   /**
-    * Get source of option value. See also .optsWithGlobals().
+   * Get source of option value. See also .optsWithGlobals().
    */
   getOptionValueSourceWithGlobals(key: string): OptionValueSource | undefined;
 
@@ -663,38 +779,49 @@ export class Command {
   /**
    * Parse `argv`, setting options and invoking commands when defined.
    *
-   * The default expectation is that the arguments are from node and have the application as argv[0]
-   * and the script being run in argv[1], with user parameters after that.
+   * Use parseAsync instead of parse if any of your action handlers are async.
+   *
+   * Call with no parameters to parse `process.argv`. Detects Electron and special node options like `node --eval`. Easy mode!
+   *
+   * Or call with an array of strings to parse, and optionally where the user arguments start by specifying where the arguments are `from`:
+   * - `'node'`: default, `argv[0]` is the application and `argv[1]` is the script being run, with user arguments after that
+   * - `'electron'`: `argv[0]` is the application and `argv[1]` varies depending on whether the electron application is packaged
+   * - `'user'`: just user arguments
    *
    * @example
    * ```
-   * program.parse(process.argv);
-   * program.parse(); // implicitly use process.argv and auto-detect node vs electron conventions
+   * program.parse(); // parse process.argv and auto-detect electron and special node flags
+   * program.parse(process.argv); // assume argv[0] is app and argv[1] is script
    * program.parse(my-args, { from: 'user' }); // just user supplied arguments, nothing special about argv[0]
    * ```
    *
    * @returns `this` command for chaining
    */
-  parse(argv?: readonly string[], options?: ParseOptions): this;
+  parse(argv?: readonly string[], parseOptions?: ParseOptions): this;
 
   /**
    * Parse `argv`, setting options and invoking commands when defined.
    *
-   * Use parseAsync instead of parse if any of your action handlers are async. Returns a Promise.
+   * Call with no parameters to parse `process.argv`. Detects Electron and special node options like `node --eval`. Easy mode!
    *
-   * The default expectation is that the arguments are from node and have the application as argv[0]
-   * and the script being run in argv[1], with user parameters after that.
+   * Or call with an array of strings to parse, and optionally where the user arguments start by specifying where the arguments are `from`:
+   * - `'node'`: default, `argv[0]` is the application and `argv[1]` is the script being run, with user arguments after that
+   * - `'electron'`: `argv[0]` is the application and `argv[1]` varies depending on whether the electron application is packaged
+   * - `'user'`: just user arguments
    *
    * @example
    * ```
-   * program.parseAsync(process.argv);
-   * program.parseAsync(); // implicitly use process.argv and auto-detect node vs electron conventions
-   * program.parseAsync(my-args, { from: 'user' }); // just user supplied arguments, nothing special about argv[0]
+   * await program.parseAsync(); // parse process.argv and auto-detect electron and special node flags
+   * await program.parseAsync(process.argv); // assume argv[0] is app and argv[1] is script
+   * await program.parseAsync(my-args, { from: 'user' }); // just user supplied arguments, nothing special about argv[0]
    * ```
    *
    * @returns Promise
    */
-  parseAsync(argv?: readonly string[], options?: ParseOptions): Promise<this>;
+  parseAsync(
+    argv?: readonly string[],
+    parseOptions?: ParseOptions,
+  ): Promise<this>;
 
   /**
    * Parse options from `argv` removing known options,
@@ -869,7 +996,10 @@ export class Command {
    * and 'beforeAll' or 'afterAll' to affect this command and all its subcommands.
    */
   addHelpText(position: AddHelpTextPosition, text: string): this;
-  addHelpText(position: AddHelpTextPosition, text: (context: AddHelpTextContext) => string): this;
+  addHelpText(
+    position: AddHelpTextPosition,
+    text: (context: AddHelpTextContext) => string,
+  ): this;
 
   /**
    * Add a listener (callback) for when events occur. (Implemented using EventEmitter.)