Update: Ideally, this PR should be superseded by #1938 and #1940. See comment for details.

Partially fixes #1916. I think it is a good idea to react to wrong library uses even if they have not been featured in many issues.

Why console.warn() and not throw from within parse() / parseAsync()?

Errors thrown from parse() / parseAsync() are expected to have originated in user-supplied code (argParsers, hooks, actions).

An alternative could be to console.error() and process.exit() with a non-zero exit code, effectively forbidding all wrong usage, but what I don't like is the discrepancy between this approach and how all other library errors are simply thrown and can be handled by the user.

ChangeLog

Added

• Breaking: throw an error when trying to add a subcommand that already has a parent command
• warnings about parse calls on subcommands
• warnings about async hook and action calls made in .parse()

Peer PRs

Warnings need to be consistent 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

Parse call subroutine (_parseSubroutine()) needs to be consistent with…

• Clean up state from previous parse call when calling parse() / parseAsync() #1919

Incompatible with…

• Add .suppressWarnings() for warnings in #1915 #1931 #1938 #1940 #1955: 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 there 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 this PR (#1917)!