Warn about obscured help option

[aweebit]

An extension of #1929 adding warnings about obscured help option as suggested in #1926 (comment).

Additionally proves the usefulness of storing the Option instance returned from createOption() in the _helpOption property (a change introduced by 9857b1e in #1929), since in the solution, not only the individual flags but also the originally provided flags value needs to be accessed, and in the future it could be the .name(), the .attributeName() or something else pertaining to the help option. It makes no sense to add a property to the Command instance each time such a property is needed, it is way better to simply store the Option instance.

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

Problem

States in which the help options is obscured are supported by the library (see Help.visibleOptions() and the corresponding unit tests), but definitely not desirable.

const desc = 'added via .option()';

var program = new Command();
program
  .option('-h, --help <arg>', desc) // help option is obscured
  .outputHelp();

var program = new Command();
program
  .option('-h, --host <arg>', desc)
  .option('--help <arg>', desc) // help option is obscured
  .outputHelp();

var program = new Command();
program
  .option('-c, --custom-help <arg>', desc)
  .helpOption('-c, --custom-help') // help option is obscured
  .outputHelp();

// Support for this option combination is currently missing because of a wrong Help.visibleOptions() implementation.
// I will open another PR to address that soon. (Update: Opened #1935)
var program = new Command();
program
  .option('-c, --custom-help <arg>', desc)
  .helpOption('-c') // help option is obscured
  .outputHelp();

var program = new Command();
program
  .option('-c, --custom-help <arg>', desc)
  .helpOption('--custom-help') // help option is obscured
  .outputHelp();

var program = new Command();
program
  .option('-c <arg>', desc)
  .option('--custom-help <arg>', desc)
  .helpOption('-c, --custom-help') // help option is obscured
  .outputHelp();

var program = new Command();
program
  .option('-c <arg>', desc)
  .helpOption('-c') // help option is obscured
  .outputHelp();

var program = new Command();
program
  .option('--custom-help <arg>', desc)
  .helpOption('--custom-help') // help option is obscured
  .outputHelp();

Solution

Add warnings when such a state is reached similar to those in #1915 and #1917.

ChangeLog

Added

• warnings about obscured help option

Changed

• (from #1929) Breaking: use .createOption() in .helpOption() to support custom option flag extraction

Peer PRs

…solving similar problems

• Prevent options with flags already in use from being added #1923 (introduces _registerOption(), too – watch out for merge conflicts!)

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
• React to wrong library usage #1917
• 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

Requires changes when merged with…

• Add .suppressWarnings() for warnings in #1915 #1931 #1938 #1940 #1955

[shadowspawn]

A quick reaction. I may not accept this PR, or at least not to "Warn about obscured help option". The zero-config obscuring was added in #1247 and raised in #645. The ability to explicitly suppress the built-in help option was added later in #1325 and perhaps the obscuring is no longer as appropriate, so I'll think about it a bit.

Separately, storing the help option configuration in an actual Option is something I considered again while working on #1910. I have not had a deep look yet myself. (I resisted attempting it in the same PR.)

[aweebit]

(I resisted attempting it in the same PR.)

I realized only later that I had had to do the change in the base #1929, that is why there is the empty 371751e.

[shadowspawn]

I think the commit specific to the title for this PR is d03566b

The current behaviour evolved out of a sort of auto-configuration for the implicit help option, which slowly became more robust as doing other work. I suspect the behaviour is more appropriate for simpler programs where the author uses -h say and we just get out of the way with the default help option.

That leads to an interesting thought that could treat explicit and implicit help options differently. But not solving a problem I am invested in for now, and behaviour is as intended.

(I have lost track of how many of your PRs have the help configuration refactored into a help option. That is something I am interested in as a concept, but not urgently, and may refer back to this in the future.)