Refactor help option and improve option parsing from parent when default command is invoked implicitly

[aweebit]

An extension of #1929 refactoring the help option.

Has been merged with the already approved tiny fixes PR #1930 because the parent #1929 has been merged with it.

Problem

4788f70 introduced outputHelpIfNecessary() as part of a solution to #2. It was later renamed to outputHelpIfRequested() in #1131 and is used in the library code to this day. However, its use is inconsistent with how all other options are parsed, namely in the .parseOptions() method.

Solution

Eliminate outputHelpIfRequested() and incorporate help option parsing into .parseOptions() instead.

The object returned by .parseOptions() now includes a displayHelp property indicating whether a help flag had been found before encountering a subcommand, or before encountering either a subcommand or a command-argument when the default command is being invoked implicitly.

The last part definitely needs clarification. The problem is that currently, there is an inconsistency between the way the default command invoked implicitly and explicitly invoked commands are handled: while the parent command ignores help flags found in the input part pertaining to the subcommand (args placed after the subcommand name) when invoked explicitly, the flags are always "robbed" by the parent command when the default command is implicitly invoked.

Here is an example to demonstrate the discrepancy:

program.command('sub <arg>', { isDefault: true });
program.parse(['sub', 'arg', '--help'], { from: 'user' }); // help for sub is displayed

program.command('sub <arg>', { isDefault: true });
program.parse(['arg', '--help'], { from: 'user' }); // help for program is displayed

This is very unlikely to be what the users of the library expect.

However, we do want the parent command to handle the help option in certain cases, for example when a help flag is placed in the first arg passed to it.

The PR fixes the problem by only letting the implicitly invoked default command's parent consume help flags encountered before the first arg that is not an option (could be a subcommand or a command-argument).

A visual explanation could be that the default subcommand's name is implicitly inserted before the first arg that is not a known option (although that is not what really happens internally), so that --global-option --unknown-option arg --help turns into --global-option sub --unknown-option arg --help.

Additionally, improvements to the .parseOptions() code have been made, first and foremost to the comments.

ChangeLog

Added

• displayHelp property in the object returned by .parseOption() indicating whether a help flag had been found before encountering a subcommand (or before encountering either a subcommand or a command-argument when the default command is being invoked implicitly)

Changed

• (from #1929) Breaking: use .createOption() in .helpOption() to support custom option flag extraction
• Breaking: make option handling when the default command is invoked implicitly consistent with how options are handled for subcommands invoked explicitly via the name or an alias (parent only processes arguments before encountering a subcommand when using enablePositionalOptions, or either a subcommand or a command-argument when using passThroughOptions)

[shadowspawn]

Quick comment. I have wondered at times whether the help option and command should be custom, but decided each time that they do have some deliberately special behaviours. There is special checks and treatment of the help option scattered through the code. Some for historical reasons, but some carefully crafted to achieve the desired outcome.

[aweebit]

Converted to draft since obscured help flags are currently not handled correctly.

[aweebit]

(Force push is due to a commit amendment changing a commit message that had mixed up options and commands.)

[aweebit]

The revert is due to the fact that stopping processing at unknown options when passThroughOptions is on is expected behavior, as explained in #1936 (comment).

For consistency with how other options work, the help option will be conceded to the subcommand if encountered after an unknown option and both passThroughOptions and allowUnknownOption are on. Consider this expected behavior.

[aweebit]

Please check out the updated PR description. I hope I could make my motivation and some implementation details more clear.

[shadowspawn]

This is two different things, neither of which I am convinced of the need for at this time. Reducing my review workload by closing this without further discussion.