17899394524

Committed 21 Sep 2025 09:49PM UTC coverage: 94.396% (-0.2%) from 94.55%

Build # 17899394524

Build Type

push

github

Committed by

web-flow

Commit Message

refactor: introduce concept of AutomaticRuleSet (#9067)

Run Details

99 of 150 new or added lines in 6 files covered. (66.0%)

4 existing lines in 2 files now uncovered.

28486 of 30177 relevant lines covered (94.4%)

45.35 hits per line

Source File
Press 'n' to go to next uncovered line, 'b' for previous

94.87

/src/Documentation/RuleSetDocumentationGenerator.php

<?php

declare(strict_types=1);

/*
 * This file is part of PHP CS Fixer.
 *
 * (c) Fabien Potencier <fabien@symfony.com>
 *     Dariusz Rumiński <dariusz.ruminski@gmail.com>
 *
 * This source file is subject to the MIT license that is bundled
 * with this source code in the file LICENSE.
 */

namespace PhpCsFixer\Documentation;

use PhpCsFixer\Fixer\FixerInterface;
use PhpCsFixer\Preg;
use PhpCsFixer\RuleSet\AutomaticRuleSetDescriptionInterface;
use PhpCsFixer\RuleSet\DeprecatedRuleSetDescriptionInterface;
use PhpCsFixer\RuleSet\RuleSetDescriptionInterface;
use PhpCsFixer\Utils;

/**
 * @readonly
 *
 * @internal
 *
 * @no-named-arguments Parameter names are not covered by the backward compatibility promise.
 */
final class RuleSetDocumentationGenerator
{
    private DocumentationLocator $locator;

    public function __construct(DocumentationLocator $locator)
    {
        $this->locator = $locator;
    }

    /**
     * @param list<FixerInterface> $fixers
     */
    public function generateRuleSetsDocumentation(RuleSetDescriptionInterface $definition, array $fixers): string
    {
        $fixerNames = [];

        foreach ($fixers as $fixer) {
            $fixerNames[$fixer->getName()] = $fixer;
        }

        $title = "Rule set ``{$definition->getName()}``";
        $titleLine = str_repeat('=', \strlen($title));
        $doc = "{$titleLine}\n{$title}\n{$titleLine}\n\n".$definition->getDescription();

        $warnings = [];
        if ($definition instanceof DeprecatedRuleSetDescriptionInterface) {
            $deprecationDescription = <<<'RST'

                This rule set is deprecated and will be removed in the next major version
                ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
                RST;
            $alternatives = $definition->getSuccessorsNames();

            if (0 !== \count($alternatives)) {
                $deprecationDescription .= RstUtils::toRst(
                    \sprintf(
                        "\n\nYou should use %s instead.",
                        Utils::naturalLanguageJoinWithBackticks($alternatives)
                    ),
                    0
                );
            } else {
                $deprecationDescription .= 'No replacement available.';
            }

            $warnings[] = $deprecationDescription;
        }

        if ($definition->isRisky()) {
            $warnings[] = <<<'RST'

                This set contains rules that are risky
                ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

                Using this rule set may lead to changes in your code's logic and behaviour. Use it with caution and review changes before incorporating them into your code base.
                RST;
        }

        if ([] !== $warnings) {
            $warningsHeader = 1 === \count($warnings) ? 'Warning' : 'Warnings';

            $warningsHeaderLine = str_repeat('-', \strlen($warningsHeader));
            $doc .= "\n\n".implode(
                "\n",
                [
                    $warningsHeader,
                    $warningsHeaderLine,
                    ...$warnings,
                ]
            );
        }

        if ($definition instanceof AutomaticRuleSetDescriptionInterface) {
            $doc .= "\n\nRules\n-----\n\n"
.strip_tags(AutomaticRuleSetDescriptionInterface::WARNING_MESSAGE_DECORATED);
        } else {
            $rules = $definition->getRules();

            if ([] === $rules) {
                $doc .= "\n\nThis is an empty set.";
            } else {
                $enabledRules = array_filter($rules, static fn ($config) => false !== $config);
                $disabledRules = array_filter($rules, static fn ($config) => false === $config);

                $listRules = function (array $rules) use (&$doc, $fixerNames): void {
                    foreach ($rules as $rule => $config) {
                        if (str_starts_with($rule, '@')) {
                            $ruleSetPath = $this->locator->getRuleSetsDocumentationFilePath($rule);
                            $ruleSetPath = substr($ruleSetPath, strrpos($ruleSetPath, '/'));

                            $doc .= "\n- `{$rule} <.{$ruleSetPath}>`_";
                        } else {
                            $path = Preg::replace(
                                '#^'.preg_quote($this->locator->getFixersDocumentationDirectoryPath(), '#').'/#',
                                './../rules/',
                                $this->locator->getFixerDocumentationFilePath($fixerNames[$rule])
                            );

                            $doc .= "\n- `{$rule} <{$path}>`_";
                        }

                        if (!\is_bool($config)) {
                            $doc .= " with config:\n\n  ``".Utils::toString($config)."``\n";
                        }
                    }
                };

                if ([] !== $enabledRules) {
                    $doc .= "\n\nRules\n-----\n";
                    $listRules($enabledRules);
                }

                if ([] !== $disabledRules) {
                    $doc .= "\n\nDisabled rules\n--------------\n";
                    $listRules($disabledRules);
                }
            }
        }

        return $doc."\n";
    }

    /**
     * @param array<string, RuleSetDescriptionInterface> $setDefinitions
     */
    public function generateRuleSetsDocumentationIndex(array $setDefinitions): string
    {
        $documentation = <<<'RST'
            ===========================
            List of Available Rule sets
            ===========================
            RST;

        foreach ($setDefinitions as $path => $definition) {
            $path = substr($path, strrpos($path, '/'));

            $attributes = [];

            if ($definition instanceof DeprecatedRuleSetDescriptionInterface) {
                $attributes[] = 'deprecated';
            }

            $attributes = 0 === \count($attributes)
                ? ''
                : ' *('.implode(', ', $attributes).')*';

            $documentation .= "\n- `{$definition->getName()} <.{$path}>`_{$attributes}";
        }

        return $documentation."\n";
    }
}

1	<?php
2
3	declare(strict_types=1);
4
5	/*
6	* This file is part of PHP CS Fixer.
7	*
8	* (c) Fabien Potencier <fabien@symfony.com>
9	* Dariusz Rumiński <dariusz.ruminski@gmail.com>
10	*
11	* This source file is subject to the MIT license that is bundled
12	* with this source code in the file LICENSE.
13	*/
14
15	namespace PhpCsFixer\Documentation;
16
17	use PhpCsFixer\Fixer\FixerInterface;
18	use PhpCsFixer\Preg;
19	use PhpCsFixer\RuleSet\AutomaticRuleSetDescriptionInterface;
20	use PhpCsFixer\RuleSet\DeprecatedRuleSetDescriptionInterface;
21	use PhpCsFixer\RuleSet\RuleSetDescriptionInterface;
22	use PhpCsFixer\Utils;
23
24	/**
25	* @readonly
26	*
27	* @internal
28	*
29	* @no-named-arguments Parameter names are not covered by the backward compatibility promise.
30	*/
31	final class RuleSetDocumentationGenerator
32	{
33	private DocumentationLocator $locator;
34
35	public function __construct(DocumentationLocator $locator)
36	{
37	$this->locator = $locator;	3✔
38	}
39
40	/**
41	* @param list<FixerInterface> $fixers
42	*/
43	public function generateRuleSetsDocumentation(RuleSetDescriptionInterface $definition, array $fixers): string
44	{
45	$fixerNames = [];	2✔
46
47	foreach ($fixers as $fixer) {	2✔
48	$fixerNames[$fixer->getName()] = $fixer;	2✔
49	}
50
51	$title = "Rule set ``{$definition->getName()}``";	2✔
52	$titleLine = str_repeat('=', \strlen($title));	2✔
53	$doc = "{$titleLine}\n{$title}\n{$titleLine}\n\n".$definition->getDescription();	2✔
54
55	$warnings = [];	2✔
56	if ($definition instanceof DeprecatedRuleSetDescriptionInterface) {	2✔
57	$deprecationDescription = <<<'RST'	1✔
58
59	This rule set is deprecated and will be removed in the next major version
60	~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
61	RST;	1✔
62	$alternatives = $definition->getSuccessorsNames();	1✔
63
64	if (0 !== \count($alternatives)) {	1✔
65	$deprecationDescription .= RstUtils::toRst(	1✔
66	\sprintf(	1✔
67	"\n\nYou should use %s instead.",	1✔
68	Utils::naturalLanguageJoinWithBackticks($alternatives)	1✔
69	),	1✔
70	0	1✔
71	);	1✔
72	} else {
73	$deprecationDescription .= 'No replacement available.';	×
74	}
75
76	$warnings[] = $deprecationDescription;	1✔
77	}
78
79	if ($definition->isRisky()) {	2✔
80	$warnings[] = <<<'RST'	1✔
81
82	This set contains rules that are risky
83	~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
84
85	Using this rule set may lead to changes in your code's logic and behaviour. Use it with caution and review changes before incorporating them into your code base.
86	RST;	1✔
87	}
88
89	if ([] !== $warnings) {	2✔
90	$warningsHeader = 1 === \count($warnings) ? 'Warning' : 'Warnings';	2✔
91
92	$warningsHeaderLine = str_repeat('-', \strlen($warningsHeader));	2✔
93	$doc .= "\n\n".implode(	2✔
94	"\n",	2✔
95	[	2✔
96	$warningsHeader,	2✔
97	$warningsHeaderLine,	2✔
98	...$warnings,	2✔
99	]	2✔
100	);	2✔
101	}
102
103	if ($definition instanceof AutomaticRuleSetDescriptionInterface) {	2✔
NEW 104	$doc .= "\n\nRules\n-----\n\n"	×
NEW 105	.strip_tags(AutomaticRuleSetDescriptionInterface::WARNING_MESSAGE_DECORATED);	×
106	} else {
107	$rules = $definition->getRules();	2✔
108
109	if ([] === $rules) {	2✔
NEW 110	$doc .= "\n\nThis is an empty set.";	×
111	} else {
112	$enabledRules = array_filter($rules, static fn ($config) => false !== $config);	2✔
113	$disabledRules = array_filter($rules, static fn ($config) => false === $config);	2✔
114
115	$listRules = function (array $rules) use (&$doc, $fixerNames): void {	2✔
116	foreach ($rules as $rule => $config) {	2✔
117	if (str_starts_with($rule, '@')) {	2✔
118	$ruleSetPath = $this->locator->getRuleSetsDocumentationFilePath($rule);	2✔
119	$ruleSetPath = substr($ruleSetPath, strrpos($ruleSetPath, '/'));	2✔
120
121	$doc .= "\n- `{$rule} <.{$ruleSetPath}>`_";	2✔
122	} else {
123	$path = Preg::replace(	1✔
124	'#^'.preg_quote($this->locator->getFixersDocumentationDirectoryPath(), '#').'/#',	1✔
125	'./../rules/',	1✔
126	$this->locator->getFixerDocumentationFilePath($fixerNames[$rule])	1✔
127	);	1✔
128
129	$doc .= "\n- `{$rule} <{$path}>`_";	1✔
130	}
131
132	if (!\is_bool($config)) {	2✔
133	$doc .= " with config:\n\n ``".Utils::toString($config)."``\n";	1✔
134	}
135	}
136	};	2✔
137
138	if ([] !== $enabledRules) {	2✔
139	$doc .= "\n\nRules\n-----\n";	2✔
140	$listRules($enabledRules);	2✔
141	}
142
143	if ([] !== $disabledRules) {	2✔
144	$doc .= "\n\nDisabled rules\n--------------\n";	1✔
145	$listRules($disabledRules);	1✔
146	}
147	}
148	}
149
150	return $doc."\n";	2✔
151	}
152
153	/**
154	* @param array<string, RuleSetDescriptionInterface> $setDefinitions
155	*/
156	public function generateRuleSetsDocumentationIndex(array $setDefinitions): string
157	{
158	$documentation = <<<'RST'	1✔
159	===========================
160	List of Available Rule sets
161	===========================
162	RST;	1✔
163
164	foreach ($setDefinitions as $path => $definition) {	1✔
165	$path = substr($path, strrpos($path, '/'));	1✔
166
167	$attributes = [];	1✔
168
169	if ($definition instanceof DeprecatedRuleSetDescriptionInterface) {	1✔
170	$attributes[] = 'deprecated';	1✔
171	}
172
173	$attributes = 0 === \count($attributes)	1✔
174	? ''	1✔
175	: ' ('.implode(', ', $attributes).')';	1✔
176
177	$documentation .= "\n- `{$definition->getName()} <.{$path}>`_{$attributes}";	1✔
178	}
179
180	return $documentation."\n";	1✔
181	}
182	}

keradus / PHP-CS-Fixer / 17899394524

Source File Press 'n' to go to next uncovered line, 'b' for previous

Source File
Press 'n' to go to next uncovered line, 'b' for previous