Help.php

<?php
/**
 * Print the Help information.
 *
 * ---------------------------------------------------------------------------------------------
 * This class is intended for internal use only and is not part of the public API.
 * This also means that it has no promise of backward compatibility. Use at your own risk.
 * ---------------------------------------------------------------------------------------------
 *
 * @internal
 *
 * @author    Juliette Reinders Folmer <phpcs_nospam@adviesenzo.nl>
 * @copyright 2024 Juliette Reinders Folmer. All rights reserved.
 * @license   https://github.com/PHPCSStandards/PHP_CodeSniffer/blob/master/licence.txt BSD Licence
 */

namespace PHP_CodeSniffer\Util;

use InvalidArgumentException;
use PHP_CodeSniffer\Config;
use PHP_CodeSniffer\Util\Common;

final class Help
{


    /**
     * Short options which are available for both the `phpcs` as well as the `phpcbf` command.
     *
     * @var string
     */
    const DEFAULT_SHORT_OPTIONS = '-hilnpqvw';

    /**
     * Long options which are available for both the `phpcs` as well as the `phpcbf` command.
     *
     * {@internal This should be a constant array, but those aren't supported until PHP 5.6.}
     *
     * @var string Comma-separated list of the option names.
     */
    const DEFAULT_LONG_OPTIONS = 'basepath,bootstrap,colors,encoding,error-severity,exclude,extensions,file,file-list,filter,ignore,ignore-annotations,no-colors,parallel,php-ini,report-width,runtime-set,severity,sniffs,standard,stdin-path,tab-width,version,vv,vvv,warning-severity';

    /**
     * Minimum screen width.
     *
     * The help info needs room to display, so this is the minimum acceptable width.
     *
     * @var integer
     */
    const MIN_WIDTH = 60;

    /**
     * Indent option lines.
     *
     * @var string
     */
    const INDENT = '  ';

    /**
     * Gutter spacing for between the option argument info and the option description.
     *
     * @var string
     */
    const GUTTER = ' ';

    /**
     * The current PHPCS Configuration.
     *
     * @var \PHP_CodeSniffer\Config
     */
    private $config;

    /**
     * The options which should be shown for this help screen.
     *
     * @var array<string>
     */
    private $requestedOptions = [];

    /**
     * Active options per category (after filtering).
     *
     * @var array<string, array<string, array<string, string>>>
     */
    private $activeOptions = [];

    /**
     * Width of the indent for option lines.
     *
     * @var integer
     */
    private $indentWidth = 0;

    /**
     * Width of the gutter spacing.
     *
     * @var integer
     */
    private $gutterWidth = 0;

    /**
     * Width of longest option argument info entry.
     *
     * @var integer
     */
    private $maxOptionNameLength = 0;


    /**
     * Constructor.
     *
     * @param \PHP_CodeSniffer\Config $config       Configuration object.
     * @param array<string>           $longOptions  The long options which should be shown.
     * @param string                  $shortOptions The short options which should be shown.
     *
     * @throws \InvalidArgumentException When $shortOptions is not a string.
     */
    public function __construct(Config $config, array $longOptions, $shortOptions='')
    {
        if (is_string($shortOptions) === false) {
            throw new InvalidArgumentException('The $shortOptions parameter must be a string');
        }

        $this->config           = $config;
        $this->requestedOptions = array_merge($longOptions, str_split($shortOptions));

        $this->filterOptions();

        $this->indentWidth = strlen(self::INDENT);
        $this->gutterWidth = strlen(self::GUTTER);

        $this->setMaxOptionNameLength();

    }//end __construct()


    /**
     * Display the help info.
     *
     * @return void
     */
    public function display()
    {
        $this->printUsage();
        $this->printCategories();

    }//end display()


    /**
     * Filter the available options based on the requested options.
     *
     * @return void
     */
    private function filterOptions()
    {
        $filteredOptions = $this->getAllOptions();

        foreach ($filteredOptions as $category => $options) {
            // Initial state set to "true" to prevent a spacer at the start of an array.
            $lastWasSpacer = true;
            $spacerCount   = 0;

            foreach ($options as $name => $option) {
                if ($lastWasSpacer !== true && strpos($name, 'blank-line') === 0) {
                    ++$spacerCount;
                    $lastWasSpacer = true;
                    continue;
                }

                if (in_array($name, $this->requestedOptions, true) === false) {
                    unset($filteredOptions[$category][$name]);
                    continue;
                }

                $lastWasSpacer = false;
            }

            // Make sure the final array doesn't contain a spacer at the end.
            if (empty($filteredOptions[$category]) === false) {
                end($filteredOptions[$category]);
                $key = key($filteredOptions[$category]);
                if (strpos($key, 'blank-line') === 0) {
                    unset($filteredOptions[$category][$key]);
                    --$spacerCount;
                }
            }

            // Remove categories now left empty.
            if (empty($filteredOptions[$category]) === true || count($filteredOptions[$category]) === $spacerCount) {
                unset($filteredOptions[$category]);
            }
        }//end foreach

        $this->activeOptions = $filteredOptions;

    }//end filterOptions()


    /**
     * Determine the length of the longest option argument and store it.
     *
     * @return void
     */
    private function setMaxOptionNameLength()
    {
        $lengths = [];
        foreach ($this->activeOptions as $category => $options) {
            foreach ($options as $option) {
                if (isset($option['argument']) === false) {
                    continue;
                }

                $lengths[] = strlen($option['argument']);
            }
        }

        if (empty($lengths) === false) {
            $this->maxOptionNameLength = max($lengths);
        }

    }//end setMaxOptionNameLength()


    /**
     * Get the maximum width which can be used to display the help info.
     *
     * Independently of user preference/auto-determined width of the current screen,
     * a minimum width is needed to display information, so don't allow this to get too low.
     *
     * @return int
     */
    private function getMaxWidth()
    {
        return max(self::MIN_WIDTH, $this->config->reportWidth);

    }//end getMaxWidth()


    /**
     * Get the maximum width for the text in the option description column.
     *
     * @return int
     */
    private function getDescriptionColumnWidth()
    {
        return ($this->getMaxWidth() - $this->maxOptionNameLength - $this->indentWidth - $this->gutterWidth);

    }//end getDescriptionColumnWidth()


    /**
     * Get the length of the indentation needed for follow up lines when the description does not fit on one line.
     *
     * @return int
     */
    private function getDescriptionFollowupLineIndentLength()
    {
        return ($this->maxOptionNameLength + $this->indentWidth + $this->gutterWidth);

    }//end getDescriptionFollowupLineIndentLength()


    /**
     * Print basic usage information to the screen.
     *
     * @return void
     */
    private function printUsage()
    {
        $command = 'phpcs';
        if (defined('PHP_CODESNIFFER_CBF') === true && PHP_CODESNIFFER_CBF === true) {
            $command = 'phpcbf';
        }

        $this->printCategoryHeader('Usage');

        echo self::INDENT.$command.' [options] <file|directory>'.PHP_EOL;

    }//end printUsage()


    /**
     * Print details of all the requested options to the screen, sorted by category.
     *
     * @return void
     */
    private function printCategories()
    {
        foreach ($this->activeOptions as $category => $options) {
            $this->printCategoryHeader($category);
            $this->printCategoryOptions($options);
        }

    }//end printCategories()


    /**
     * Print a category header.
     *
     * @param string $header The header text.
     *
     * @return void
     */
    private function printCategoryHeader($header)
    {
        $header .= ':';
        if ($this->config->colors === true) {
            $header = "\033[33m{$header}\033[0m";
        }

        echo PHP_EOL.$header.PHP_EOL;

    }//end printCategoryHeader()


    /**
     * Print the options for a category.
     *
     * @param array<string, array<string, string>> $options The options to display.
     *
     * @return void
     */
    private function printCategoryOptions(array $options)
    {
        $maxDescriptionWidth = $this->getDescriptionColumnWidth();
        $maxTextWidth        = ($this->getMaxWidth() - $this->indentWidth);
        $secondLineIndent    = str_repeat(' ', $this->getDescriptionFollowupLineIndentLength());

        $output = '';
        foreach ($options as $option) {
            if (isset($option['spacer']) === true) {
                $output .= PHP_EOL;
            }

            if (isset($option['text']) === true) {
                $text    = wordwrap($option['text'], $maxTextWidth, "\n");
                $output .= self::INDENT.implode(PHP_EOL.self::INDENT, explode("\n", $text)).PHP_EOL;
            }

            if (isset($option['argument'], $option['description']) === true) {
                $argument = str_pad($option['argument'], $this->maxOptionNameLength);
                $argument = $this->colorizeVariableInput($argument);
                $output  .= self::INDENT."\033[32m{$argument}\033[0m";
                $output  .= self::GUTTER;

                $description = wordwrap($option['description'], $maxDescriptionWidth, "\n");
                $output     .= implode(PHP_EOL.$secondLineIndent, explode("\n", $description)).PHP_EOL;
            }
        }

        if ($this->config->colors === false) {
            $output = Common::stripColors($output);
        }

        echo $output;

    }//end printCategoryOptions()


    /**
     * Colorize "variable" input in the option argument info.
     *
     * For the purposes of this method, "variable" input is text between <> brackets.
     * The regex allows for multiple tags and nested tags.
     *
     * @param string $text The text to process.
     *
     * @return string
     */
    private function colorizeVariableInput($text)
    {
        return preg_replace('`(<(?:(?>[^<>]+)|(?R))*>)`', "\033[36m".'$1'."\033[32m", $text);

    }//end colorizeVariableInput()


    /**
     * Retrieve the help details for all supported CLI arguments per category.
     *
     * @return array<string, array<string, array<string, string>>>
     */
    private function getAllOptions()
    {
        $options = [];

        // phpcs:disable Squiz.Strings.ConcatenationSpacing.PaddingFound -- Readability is more important.
        $options['Scan targets'] = [
            'file'       => [
                'argument'    => '<file|directory>',
                'description' => 'One or more files and/or directories to check, space separated.',
            ],
            '-'          => [
                'argument'    => '-',
                'description' => 'Check STDIN instead of local files and directories.',
            ],
            'stdin-path' => [
                'argument'    => '--stdin-path=<stdinPath>',
                'description' => 'If processing STDIN, the file path that STDIN will be processed as.',
            ],
            'file-list'  => [
                'argument'    => '--file-list=<fileList>',
                'description' => 'Check the files and/or directories which are defined in the file to which the path is provided (one per line).',
            ],
            'filter'     => [
                'argument'    => '--filter=<filter>',
                'description' => 'Check based on a predefined file filter. Use either the "GitModified" or "GitStaged" filter, or specify the path to a custom filter class.',
            ],
            'ignore'     => [
                'argument'    => '--ignore=<patterns>',
                'description' => 'Ignore files based on a comma-separated list of patterns matching files and/or directories.',
            ],
            'extensions' => [
                'argument'    => '--extensions=<extensions>',
                'description' => 'Check files with the specified file extensions (comma-separated list). Defaults to php,inc/php,js,css.'."\n"
                    .'The type of the file can be specified using: ext/type; e.g. module/php,es/js.',
            ],
            'l'          => [
                'argument'    => '-l',
                'description' => 'Check local directory only, no recursion.',
            ],
        ];

        $options['Rule Selection Options'] = [
            'standard'   => [
                'argument'    => '--standard=<standard>',
                'description' => 'The name of, or the path to, the coding standard to use. Can be a comma-separated list specifying multiple standards. If no standard is specified, PHP_CodeSniffer will look for a [.]phpcs.xml[.dist] custom ruleset file in the current directory and those above it.',
            ],
            'sniffs'     => [
                'argument'    => '--sniffs=<sniffs>',
                'description' => 'A comma-separated list of sniff codes to limit the scan to. All sniffs must be part of the standard in use.',
            ],
            'exclude'    => [
                'argument'    => '--exclude=<sniffs>',
                'description' => 'A comma-separated list of sniff codes to exclude from the scan. All sniffs must be part of the standard in use.',
            ],
            'blank-line' => ['spacer' => ''],

            'i'          => [
                'argument'    => '-i',
                'description' => 'Show a list of installed coding standards.',
            ],
            'e'          => [
                'argument'    => '-e',
                'description' => 'Explain a standard by showing the names of all the sniffs it includes.',
            ],
            'generator'  => [
                'argument'    => '--generator=<generator>',
                'description' => 'Show documentation for a standard. Use either the "HTML", "Markdown" or "Text" generator.',
            ],
        ];

        $options['Run Options'] = [
            'a'          => [
                'argument'    => '-a',
                'description' => 'Run in interactive mode, pausing after each file.',
            ],
            'bootstrap'  => [
                'argument'    => '--bootstrap=<bootstrap>',
                'description' => 'Run the specified file(s) before processing begins. A list of files can be provided, separated by commas.',
            ],
            'cache'      => [
                'argument'    => '--cache[=<cacheFile>]',
                'description' => 'Cache results between runs. Optionally, <cacheFile> can be provided to use a specific file for caching. Otherwise, a temporary file is used.',
            ],
            'no-cache'   => [
                'argument'    => '--no-cache',
                'description' => 'Do not cache results between runs (default).',
            ],
            'parallel'   => [
                'argument'    => '--parallel=<processes>',
                'description' => 'The number of files to be checked simultaneously. Defaults to 1 (no parallel processing).'."\n"
                    .'If enabled, this option only takes effect if the PHP PCNTL (Process Control) extension is available.',
            ],
            'suffix'     => [
                'argument'    => '--suffix=<suffix>',
                'description' => 'Write modified files to a filename using this suffix ("diff" and "patch" are not used in this mode).',
            ],
            'blank-line' => ['spacer' => ''],

            'php-ini'    => [
                'argument'    => '-d <key[=value]>',
                'description' => 'Set the [key] php.ini value to [value] or set to [true] if value is omitted.'."\n"
                    .'Note: only php.ini settings which can be changed at runtime are supported.',
            ],
        ];

        $options['Reporting Options'] = [
            'report'             => [
                'argument'    => '--report=<report>',
                'description' => 'Print either the "full", "xml", "checkstyle", "csv", "json", "junit", "emacs", "source", "summary", "diff", "svnblame", "gitblame", "hgblame", "notifysend" or "performance" report or specify the path to a custom report class. By default, the "full" report is displayed.',
            ],
            'report-file'        => [
                'argument'    => '--report-file=<reportFile>',
                'description' => 'Write the report to the specified file path.',
            ],
            'report-report'      => [
                'argument'    => '--report-<report>=<reportFile>',
                'description' => 'Write the report specified in <report> to the specified file path.',
            ],
            'report-width'       => [
                'argument'    => '--report-width=<reportWidth>',
                'description' => 'How many columns wide screen reports should be. Set to "auto" to use current screen width, where supported.',
            ],
            'basepath'           => [
                'argument'    => '--basepath=<basepath>',
                'description' => 'Strip a path from the front of file paths inside reports.',
            ],
            'blank-line-1'       => ['spacer' => ''],

            'w'                  => [
                'argument'    => '-w',
                'description' => 'Include both warnings and errors (default).',
            ],
            'n'                  => [
                'argument'    => '-n',
                'description' => 'Do not include warnings. Shortcut for "--warning-severity=0".',
            ],
            'severity'           => [
                'argument'    => '--severity=<severity>',
                'description' => 'The minimum severity required to display an error or warning. Defaults to 5.',
            ],
            'error-severity'     => [
                'argument'    => '--error-severity=<severity>',
                'description' => 'The minimum severity required to display an error. Defaults to 5.',
            ],
            'warning-severity'   => [
                'argument'    => '--warning-severity=<severity>',
                'description' => 'The minimum severity required to display a warning. Defaults to 5.',
            ],
            'blank-line-2'       => ['spacer' => ''],

            's'                  => [
                'argument'    => '-s',
                'description' => 'Show sniff error codes in all reports.',
            ],
            'ignore-annotations' => [
                'argument'    => '--ignore-annotations',
                'description' => 'Ignore all "phpcs:..." annotations in code comments.',
            ],
            'colors'             => [
                'argument'    => '--colors',
                'description' => 'Use colors in screen output.',
            ],
            'no-colors'          => [
                'argument'    => '--no-colors',
                'description' => 'Do not use colors in screen output (default).',
            ],
            'p'                  => [
                'argument'    => '-p',
                'description' => 'Show progress of the run.',
            ],
            'q'                  => [
                'argument'    => '-q',
                'description' => 'Quiet mode; disables progress and verbose output.',
            ],
            'm'                  => [
                'argument'    => '-m',
                'description' => 'Stop error messages from being recorded. This saves a lot of memory but stops many reports from being used.',
            ],
        ];

        $options['Configuration Options'] = [
            'encoding'       => [
                'argument'    => '--encoding=<encoding>',
                'description' => 'The encoding of the files being checked. Defaults to "utf-8".',
            ],
            'tab-width'      => [
                'argument'    => '--tab-width=<tabWidth>',
                'description' => 'The number of spaces each tab represents.',
            ],
            'blank-line'     => ['spacer' => ''],

            'config-explain' => [
                'text' => 'Default values for a selection of options can be stored in a user-specific CodeSniffer.conf configuration file.'."\n"
                    .'This applies to the following options: "default_standard", "report_format", "tab_width", "encoding", "severity", "error_severity", "warning_severity", "show_warnings", "report_width", "show_progress", "quiet", "colors", "cache", "parallel".',
            ],
            'config-show'    => [
                'argument'    => '--config-show',
                'description' => 'Show the configuration options which are currently stored in the applicable CodeSniffer.conf file.',
            ],
            'config-set'     => [
                'argument'    => '--config-set <key> <value>',
                'description' => 'Save a configuration option to the CodeSniffer.conf file.',
            ],
            'config-delete'  => [
                'argument'    => '--config-delete <key>',
                'description' => 'Delete a configuration option from the CodeSniffer.conf file.',
            ],
            'runtime-set'    => [
                'argument'    => '--runtime-set <key> <value>',
                'description' => 'Set a configuration option to be applied to the current scan run only.',
            ],
        ];

        $options['Miscellaneous Options'] = [
            'h'       => [
                'argument'    => '-h, -?, --help',
                'description' => 'Print this help message.',
            ],
            'version' => [
                'argument'    => '--version',
                'description' => 'Print version information.',
            ],
            'v'       => [
                'argument'    => '-v',
                'description' => 'Verbose output: Print processed files.',
            ],
            'vv'      => [
                'argument'    => '-vv',
                'description' => 'Verbose output: Print ruleset and token output.',
            ],
            'vvv'     => [
                'argument'    => '-vvv',
                'description' => 'Verbose output: Print sniff processing information.',
            ],
        ];
        // phpcs:enable

        return $options;

    }//end getAllOptions()


}//end class