Add new `--debug=...` CLI option

[jrfnl]

Is your feature request related to a problem?

Currently, PHPCS allows for displaying debug information in three "verbosity" levels:

• -v = Print processed files and general progress info.
• -vv = Everything from level 1 + print ruleset and token output.
• -vvv = Everything from level 2 + print sniff processing information.

When using the -vv or -vvv options, the output will quickly be pretty huge. For a simple 15 line file, the output can easily be > 1000 lines.
This also means that if these options are used by an unsuspecting end-user when running over a complete codebase, the output might be gigabytes of data, which will be neigh impossible to analyse and find anything useful in.

Based on working on PR #1010 (sending debug, error and progress info and such to STDERR), I've so far identified the following "categories" of debug information - note: this list is not yet complete!

• Progress (level 1)
• Ruleset interpretation (level 2)
• Cache handling (level 2)
• Tokenizer (level 2)
  With the following sub-categories:
  • PHP Tokenizer
  • Token map
  • Scope map
  • Level map
• Fixer (level 2)
• Reports (level 2) (there is not much there)
• Sniff processing (level 3)
• File diffs (fixer on level 3)
• Performance (level 3)

I suspect that in the fast majority of cases when someone is debugging something related to PHPCS, they only need one of the above categories of information, or at most a few, but rarely, if ever, all. However, it is currently not possible to indicate what debug information the user is interested in.

Describe the solution you'd like

I'd like to propose adding a new --debug=[comma separated list with one or more categories of debug info] option.

This option would - for now - be in addition to the pre-existing -v[vv] options, but could potentially, eventually, replace the -v[vv] options.

The new --debug... option would allow to get far more targeted and more selective debug information for just and only that part of the PHPCS processing the user is interested in.

It would also allow for maintainers, both of PHPCS itself, as well as of external standards, to ask end-users to run with --debug=cat1,cat2 when a particular issue isn't reproducible by the maintainers and may have system-specific behaviour.

Proposed implementation

Aside from adding handling for the CLI flag to the Config class, I propose introducing a new PHP_CodeSniffer\Util\Writers\DebugWriter class.

The DebugWriter would then handle checking whether debug information should be printed, or not, by checking the values set in the Config object. The actual "printing" of the debug information (to stdErr) will still be done via the StatusWriter class as introduced in #1010.

Additionally:

• The Config class would need a "translation" for the -v[vv] option to the new debug categories to allow for supporting both the -v[vv] options as well as the --debug flag in a unified manner.
• The Help class would need a new entry for the new --debug flag and should list the available categories.
• The Wiki should also be updated. There are some places ("Advanced Usage" page comes to mind) which discuss debug information, such as the token map and level map. The text of that documentation should be reviewed and updated.

Additional context

Currently, sending of debug information is typically wrapped within variants of if (PHP_CODESNIFFER_VERBOSITY > 0) {} conditions.

The test bootstrap file sets the global PHP_CODESNIFFER_VERBOSITY constant to 0 for test runs, which means that debug output cannot currently be tested.
It can be argued that debug information shouldn't be tested anyway, but a side-effect of those conditions is that they influence the code coverage reporting and make it less straight-forward to see if a class is fully tested or not, as the debug code is never executed, so will always be marked as uncovered.

When the DebugWriter is introduced, the fast majority of these wrappers can probably be removed and/or replaced by more selective conditions, fixing the code coverage reporting and making it more useful.

It should be investigated whether the global PHP_CODESNIFFER_VERBOSITY constant can be removed once the above has been actioned.

If it cannot be removed (yet), it should be documented why not and changes should be made to the test suite to have some test runs with different verbosity settings to, at the very least, safeguard that no PHP errors/notices etc are thrown from the debug info (like #956, which was discovered while investigating the above).

Open questions

• Should the -v[vv] options be deprecated and eventually removed ? Or should they remain ?

Opinions welcome!

• I have read the Contribution Guidelines and this is not a support question.
• I intend to create a pull request to implement this feature.