Merge pull request #2140 from tj/release/12.x

.github/workflows/tests.yml

@@ -12,7 +12,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        node-version: [16.x, 18.x, 20.x]
+        node-version: [18.x, 20.x]
         os: [ubuntu-latest, windows-latest, macos-latest]
 
     steps:

CHANGELOG.md

@@ -8,6 +8,63 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.
 <!-- markdownlint-disable MD024 -->
 <!-- markdownlint-disable MD004 -->
 
+## [12.0.0] (2024-02-03)
+
+### Added
+
+- `.addHelpOption()` as another way of configuring built-in help option ([#2006])
+- `.helpCommand()` for configuring built-in help command ([#2087])
+
+### Fixed
+
+- *Breaking:* use non-zero exit code when spawned executable subcommand terminates due to a signal ([#2023])
+- *Breaking:* check `passThroughOptions` constraints when using `.addCommand` and throw if parent command does not have `.enablePositionalOptions()` enabled ([#1937])
+
+### Changed
+
+- *Breaking:* Commander 12 requires Node.js v18 or higher ([#2027])
+- *Breaking:* throw an error if add an option with a flag which is already in use ([#2055])
+- *Breaking:* throw an error if add a command with name or alias which is already in use ([#2059])
+- *Breaking:* throw error when calling `.storeOptionsAsProperties()` after setting an option value ([#1928])
+- replace non-standard JSDoc of `@api private` with documented `@private` ([#1949])
+- `.addHelpCommand()` now takes a Command (passing string or boolean still works as before but deprecated) ([#2087])
+- refactor internal implementation of built-in help option ([#2006])
+- refactor internal implementation of built-in help command ([#2087])
+
+### Deprecated
+
+- `.addHelpCommand()` passing string or boolean (use `.helpCommand()` or pass a Command) ([#2087])
+
+### Removed
+
+- *Breaking:* removed default export of a global Command instance from CommonJS (use the named `program` export instead) ([#2017])
+
+### Migration Tips
+
+**global program**
+
+If you are using the [deprecated](./docs/deprecated.md#default-import-of-global-command-object) default import of the global Command object, you need to switch to using a named import (or create a new `Command`).
+
+```js
+// const program = require('commander');
+const { program } = require('commander');
+```
+
+**option and command clashes**
+
+A couple of configuration problems now throw an error, which will pick up issues in existing programs:
+
+- adding an option which uses the same flag as a previous option
+- adding a command which uses the same name or alias as a previous command
+
+## [12.0.0-1] (2024-01-20)
+
+(Released in 12.0.0)
+
+## [12.0.0-0] (2023-11-11)
+
+(Released in 12.0.0)
+
 ## [11.1.0] (2023-10-13)
 
 ### Fixed
@@ -1188,13 +1245,23 @@ program
 [#1874]: https://github.com/tj/commander.js/pull/1874
 [#1886]: https://github.com/tj/commander.js/pull/1886
 [#1896]: https://github.com/tj/commander.js/pull/1896
+[#1928]: https://github.com/tj/commander.js/pull/1928
 [#1930]: https://github.com/tj/commander.js/pull/1930
+[#1937]: https://github.com/tj/commander.js/pull/1937
+[#1949]: https://github.com/tj/commander.js/pull/1949
 [#1965]: https://github.com/tj/commander.js/pull/1965
 [#1969]: https://github.com/tj/commander.js/pull/1969
 [#1982]: https://github.com/tj/commander.js/pull/1982
 [#1983]: https://github.com/tj/commander.js/pull/1983
+[#2006]: https://github.com/tj/commander.js/pull/2006
 [#2010]: https://github.com/tj/commander.js/pull/2010
+[#2017]: https://github.com/tj/commander.js/pull/2017
 [#2019]: https://github.com/tj/commander.js/pull/2019
+[#2023]: https://github.com/tj/commander.js/pull/2023
+[#2027]: https://github.com/tj/commander.js/pull/2027
+[#2055]: https://github.com/tj/commander.js/pull/2055
+[#2059]: https://github.com/tj/commander.js/pull/2059
+[#2087]: https://github.com/tj/commander.js/pull/2087
 
 <!-- Referenced in 5.x -->
 [#1]: https://github.com/tj/commander.js/issues/1
@@ -1274,6 +1341,9 @@ program
 [#1028]: https://github.com/tj/commander.js/pull/1028
 
 [Unreleased]: https://github.com/tj/commander.js/compare/master...develop
+[12.0.0]: https://github.com/tj/commander.js/compare/v11.1.0...v12.0.0
+[12.0.0-1]: https://github.com/tj/commander.js/compare/v12.0.0-0...v12.0.0-1
+[12.0.0-0]: https://github.com/tj/commander.js/compare/v11.1.0...v12.0.0-0
 [11.1.0]: https://github.com/tj/commander.js/compare/v11.0.0...v11.1.0
 [11.0.0]: https://github.com/tj/commander.js/compare/v10.0.1...v11.0.0
 [10.0.1]: https://github.com/tj/commander.js/compare/v10.0.0...v10.0.1

Readme.md

@@ -37,7 +37,7 @@ Read this in other languages: English | [简体中文](./Readme_zh-CN.md)
     - [.usage](#usage)
     - [.description and .summary](#description-and-summary)
     - [.helpOption(flags, description)](#helpoptionflags-description)
-    - [.addHelpCommand()](#addhelpcommand)
+    - [.helpCommand()](#helpcommand)
     - [More configuration](#more-configuration-2)
   - [Custom event listeners](#custom-event-listeners)
   - [Bits and pieces](#bits-and-pieces)
@@ -904,16 +904,20 @@ program
   .helpOption('-e, --HELP', 'read more information');
 ```
 
-### .addHelpCommand()
+(Or use `.addHelpOption()` to add an option you construct yourself.)
 
-A help command is added by default if your command has subcommands. You can explicitly turn on or off the implicit help command with `.addHelpCommand()` and `.addHelpCommand(false)`.
+### .helpCommand()
+
+A help command is added by default if your command has subcommands. You can explicitly turn on or off the implicit help command with `.helpCommand(true)` and `.helpCommand(false)`.
 
 You can both turn on and customise the help command by supplying the name and description:
 
 ```js
-program.addHelpCommand('assist [command]', 'show assistance');
+program.helpCommand('assist [command]', 'show assistance');
 ```
 
+(Or use `.addHelpCommand()` to add a command you construct yourself.)
+
 ### More configuration
 
 The built-in help is formatted using the Help class.
@@ -1139,7 +1143,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.

Readme_zh-CN.md

@@ -1059,7 +1059,7 @@ program
 
 ## 支持
 
-当前版本的 Commander 在 LTS 版本的 Node.js 上完全支持。并且至少需要 v16。
+当前版本的 Commander 在 LTS 版本的 Node.js 上完全支持。并且至少需要 v18。
 （使用更低版本 Node.js 的用户建议安装更低版本的 Commander）
 
 社区支持请访问项目的 [Issues](https://github.com/tj/commander.js/issues)。

SECURITY.md

@@ -6,8 +6,8 @@ Old versions receive security updates for six months.
 
 | Version | Supported                                  |
 | ------- | ------------------------------------------ |
-| 10.x    | :white_check_mark: support ends 2024-01-16 |
-| < 10    | :x:                                        |
+| 11.x    | :white_check_mark: support ends 2024-07-03 |
+| < 11    | :x:                                        |
 
 Pull Requests for security issues will be considered for older versions back to 2.x.
 

docs/deprecated.md

@@ -4,20 +4,22 @@ These features are deprecated, which means they may go away in a future major ve
 They are currently still available for backwards compatibility, but should not be used in new code.
 
 - [Deprecated](#deprecated)
-  - [RegExp .option() parameter](#regexp-option-parameter)
-  - [noHelp](#nohelp)
-  - [Default import of global Command object](#default-import-of-global-command-object)
-  - [Callback to .help() and .outputHelp()](#callback-to-help-and-outputhelp)
-  - [.on('--help')](#on--help)
-  - [.on('command:\*')](#oncommand)
-  - [.command('\*')](#command)
-  - [cmd.description(cmdDescription, argDescriptions)](#cmddescriptioncmddescription-argdescriptions)
-  - [InvalidOptionArgumentError](#invalidoptionargumenterror)
-  - [Short option flag longer than a single character](#short-option-flag-longer-than-a-single-character)
-  - [Import from `commander/esm.mjs`](#import-from-commanderesmmjs)
-  - [cmd.\_args](#cmd_args)
-
-## RegExp .option() parameter
+    - [RegExp .option() parameter](#regexp-option-parameter)
+    - [noHelp](#nohelp)
+    - [Callback to .help() and .outputHelp()](#callback-to-help-and-outputhelp)
+    - [.on('--help')](#on--help)
+    - [.on('command:\*')](#oncommand)
+    - [.command('\*')](#command)
+    - [cmd.description(cmdDescription, argDescriptions)](#cmddescriptioncmddescription-argdescriptions)
+    - [InvalidOptionArgumentError](#invalidoptionargumenterror)
+    - [Short option flag longer than a single character](#short-option-flag-longer-than-a-single-character)
+    - [Import from `commander/esm.mjs`](#import-from-commanderesmmjs)
+    - [cmd.\_args](#cmd_args)
+    - [.addHelpCommand(string|boolean|undefined)](#addhelpcommandstringbooleanundefined)
+  - [Removed](#removed)
+    - [Default import of global Command object](#default-import-of-global-command-object)
+
+### RegExp .option() parameter
 
 The `.option()` method allowed a RegExp as the third parameter to restrict what values were accepted.
 
@@ -29,7 +31,7 @@ Removed from README in Commander v3. Deprecated from Commander v7.
 
 The newer functionality is the Option `.choices()` method, or using a custom option processing function.
 
-## noHelp
+### noHelp
 
 This was an option passed to `.command()` to hide the command from the built-in help:
 
@@ -39,28 +41,7 @@ program.command('example', 'example command', { noHelp: true });
 
 The option was renamed `hidden` in Commander v5.1. Deprecated from Commander v7.
 
-## Default import of global Command object
-
-The default import was a global Command object.
-
-```js
-const program = require('commander');
-```
-
-The global Command object is exported as `program` from Commander v5, or import the Command object.
-
-```js
-const { program } = require('commander');
-// or
-const { Command } = require('commander');
-const program = new Command()
-```
-
-- Removed from README in Commander v5.
-- Deprecated from Commander v7.
-- Removed from TypeScript declarations in Commander v8.
-
-## Callback to .help() and .outputHelp()
+### Callback to .help() and .outputHelp()
 
 These routines allowed a callback parameter to process the built-in help before display.
 
@@ -78,7 +59,7 @@ console.error(colors.red(program.helpInformation()));
 
 Deprecated from Commander v7.
 
-## .on('--help')
+### .on('--help')
 
 This was the way to add custom help after the built-in help. From Commander v3.0.0 this used the custom long help option flags, if changed.
 
@@ -103,7 +84,7 @@ Examples:
 
 Deprecated from Commander v7.
 
-## .on('command:*')
+### .on('command:*')
 
 This was emitted when the command argument did not match a known subcommand (as part of the implementation of `.command('*')`).
 
@@ -114,7 +95,7 @@ or for custom behaviour catch the `commander.unknownCommand` error.
 
 Deprecated from Commander v8.3.
 
-## .command('*')
+### .command('*')
 
 This was used to add a default command to the program.
 
@@ -134,7 +115,7 @@ program
 
 Removed from README in Commander v5. Deprecated from Commander v8.3.
 
-## cmd.description(cmdDescription, argDescriptions)
+### cmd.description(cmdDescription, argDescriptions)
 
 This was used to add command argument descriptions for the help.
 
@@ -157,7 +138,7 @@ program
 
 Deprecated from Commander v8.
 
-## InvalidOptionArgumentError
+### InvalidOptionArgumentError
 
 This was used for throwing an error from custom option processing, for a nice error message.
 
@@ -187,13 +168,13 @@ function myParseInt(value, dummyPrevious) {
 
 Deprecated from Commander v8.
 
-## Short option flag longer than a single character
+### Short option flag longer than a single character
 
 Short option flags like `-ws` were never supported, but the old README did not make this clear. The README now states that short options are a single character.
 
 README updated in Commander v3. Deprecated from Commander v9.
 
-## Import from `commander/esm.mjs`
+### Import from `commander/esm.mjs`
 
 The first support for named imports required an explicit entry file.
 
@@ -209,7 +190,7 @@ import { Command } from 'commander';
 
 README updated in Commander v9. Deprecated from Commander v9.
 
-## cmd._args
+### cmd._args
 
 This was always private, but was previously the only way to access the command `Argument` array.
 
@@ -224,3 +205,48 @@ const registeredArguments = program.registeredArguments;
 ```
 
 Deprecated from Commander v11.
+
+### .addHelpCommand(string|boolean|undefined)
+
+This was originally used with a variety of parameters, but not by passing a Command object despite the "add" name.
+
+```js
+program.addHelpCommand('assist  [command]');
+program.addHelpCommand('assist', 'show assistance');
+program.addHelpCommand(false);
+
+```
+
+In new code you configure the help command with `.helpCommand()`. Or use `.addHelpCommand()` which now takes a Command object, like `.addCommand()`.
+
+```js
+program.helpCommand('assist [command]');
+program.helpCommand('assist', 'show assistance');
+program.helpCommand(false);
+
+program.addHelpCommand(new Command('assist').argument('[command]').description('show assistance'));
+
+```
+## Removed
+
+### Default import of global Command object
+
+The default import was a global Command object.
+
+```js
+const program = require('commander');
+```
+
+The global Command object is exported as `program` from Commander v5, or import the Command object.
+
+```js
+const { program } = require('commander');
+// or
+const { Command } = require('commander');
+const program = new Command()
+```
+
+- Removed from README in Commander v5.
+- Deprecated from Commander v7.
+- Removed from TypeScript declarations in Commander v8.
+- Removed from CommonJS in Commander v12. Deprecated and gone!

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

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) {