Peer PRs

Requires changes when merged with…

• Add async custom processing support. Add chainArgParserCalls() for configuration. Additionally await thenable implicit and default option values and thenable default argument values #1915
• Warn about obscured help option #1931
• Add support for sharing and stand-alone parsing of subcommands. Warn about parse calls on commands added with .command() #1938
• Warn about async calls in .parse() #1940

👉 ❗ 💬 This PR is the place for discussions about the warning model that apply to all of the PRs listed above!

Incompatible with…

• React to wrong library usage #1917: parse methods shall never be called on subcommands, so if warnings about such calls are added, the JSDoc and the ChangeLog entry for .suppressWarnings() introduced here become incorrect. The fact there is currently no well-defined meaning for such calls is one of the reasons why #1938 and #1940 should be preferred over #1917!

Changes summary

Proposed mistake handling model

Based on #1940 (comment). Could be added to the docs.

• suspicious library usage patterns (although not always entirely wrong): assume author mistake and show a warning unless suppressWarnings is on – a setting added specifically so that warnings can be hidden from end users
• end user mistakes, including arguments deemed invalid by argParsers: display an error message and exit the program (by default)
• other errors originating in callbacks (argParsers, hooks, actions): throw the error for the author to handle – should not be seen by end user

ChangeLog

Added

• .suppressWarnings() to suppress warnings about presumably wrong library usage

Some explanations

Why .suppressWarning() instead of an environment variable such as NODE_ENV (as originally proposed)?

Environment variables are used for stuff the end user should be able to control, but in our case, the tool author is the one to decide whether the warnings are to be shown.

See also: #1940 (comment).