feat: Clickable rule names in TextReporter pointing to official documentation

src/AbstractFixer.php

@@ -81,6 +81,19 @@ public function isRisky(): bool
  return false;
  }
 
+ public function getHelpUri(): string
+ {
+ $nameParts = explode('\\', static::class);
+ $group = $nameParts[\count($nameParts) - 2];
+ $name = substr(end($nameParts), 0, -\strlen('Fixer'));
+
+ return sprintf(
+ 'https://cs.symfony.com/doc/rules/%s/%s.html',
+ Utils::camelCaseToUnderscore($group),
+ Utils::camelCaseToUnderscore($name)
+ );
+ }
+
  public function getName(): string
  {
  $nameParts = explode('\\', static::class);

src/Console/Report/FixReport/ReportSummary.php

@@ -22,7 +22,7 @@
 final class ReportSummary
 {
  /**
- * @var array<string, array{appliedFixers: list<string>, diff: string}>
+ * @var array<string, array{appliedFixers: list<string>, diff: string, extraInfoFixers: array{helpUri: array<string, string>}|array{}}>
  */
  private array $changed;
 
@@ -39,9 +39,9 @@ final class ReportSummary
  private bool $isDecoratedOutput;
 
  /**
- * @param array<string, array{appliedFixers: list<string>, diff: string}> $changed
- * @param int $time duration in milliseconds
- * @param int $memory memory usage in bytes
+ * @param array<string, array{appliedFixers: list<string>, diff: string, extraInfoFixers: array{helpUri: array<string, string>}|array{}}> $changed
+ * @param int  $time duration in milliseconds
+ * @param int  $memory memory usage in bytes
  */
  public function __construct(
  array $changed,
@@ -72,7 +72,7 @@ public function isDryRun(): bool
  }
 
  /**
- * @return array<string, array{appliedFixers: list<string>, diff: string}>
+ * @return array<string, array{appliedFixers: list<string>, diff: string, extraInfoFixers: array{helpUri: array<string, string>}|array{}}>
  */
  public function getChanged(): array
  {

src/Console/Report/FixReport/TextReporter.php

@@ -15,6 +15,7 @@
 namespace PhpCsFixer\Console\Report\FixReport;
 
 use PhpCsFixer\Differ\DiffConsoleFormatter;
+use Symfony\Component\Console\Formatter\OutputFormatter;
 
 /**
  * @author Boris Gorbylev <[email protected]>
@@ -41,6 +42,7 @@ public function generate(ReportSummary $reportSummary): string
  $output .= $this->getAppliedFixers(
  $reportSummary->isDecoratedOutput(),
  $fixResult['appliedFixers'],
+ $fixResult['extraInfoFixers']
  );
  }
 
@@ -58,13 +60,32 @@ public function generate(ReportSummary $reportSummary): string
  }
 
  /**
- * @param list<string> $appliedFixers
+ * @param list<string> $appliedFixers
+ * @param array{helpUri: array<string, string>|array{}}|array{} $extraInfoFixers
  */
- private function getAppliedFixers(bool $isDecoratedOutput, array $appliedFixers): string
+ private function getAppliedFixers(bool $isDecoratedOutput, array $appliedFixers, array $extraInfoFixers = []): string
  {
+ if (!isset($extraInfoFixers['helpUri'])) {
+ return sprintf(
+ $isDecoratedOutput ? ' (<comment>%s</comment>)' : ' (%s)',
+ implode(', ', $appliedFixers)
+ );
+ }
+
+ $fixers = [];
+
+ foreach ($appliedFixers as $appliedFixer) {
+ $url = $extraInfoFixers['helpUri'][$appliedFixer] ?? '';
+ if ($isDecoratedOutput && '' !== $url) {
+ $fixers[] = sprintf('<href=%s;fg=yellow>%s</>', OutputFormatter::escape($url), $appliedFixer);
+ } else {
+ $fixers[] = $appliedFixer;
+ }
+ }
+
  return sprintf(
- $isDecoratedOutput ? ' (<comment>%s</comment>)' : ' (%s)',
- implode(', ', $appliedFixers)
+ ' (<comment>%s</comment>)',
+ implode(', ', $fixers)
  );
  }
 

src/Fixer/FixerInterface.php

@@ -54,6 +54,12 @@ public function fix(\SplFileInfo $file, Tokens $tokens): void;
  */
  public function getDefinition(): FixerDefinitionInterface;
 
+ /**
+ * Returns the absolute URI [RFC3986](http://www.rfc-editor.org/info/rfc3986)
+ * of the primary documentation for the fixer.
+ */
+ public function getHelpUri(): string;
+
  /**
  * Returns the name of the fixer.
  *

src/Runner/Runner.php

@@ -92,7 +92,7 @@
  }
 
  /**
- * @return array<string, array{appliedFixers: list<string>, diff: string}>
+ * @return array<string, array{appliedFixers: list<string>, diff: string, extraInfoFixers: array{helpUri: array<string, string>}|array{}}>
  */
  public function fix(): array
  {
@@ -130,7 +130,7 @@
  }
 
  /**
- * @return null|array{appliedFixers: list<string>, diff: string}
+ * @return null|array{appliedFixers: list<string>, diff: string, extraInfoFixers: array{helpUri: array<string, string>}|array{}}
  */
  private function fixFile(\SplFileInfo $file, LintingResultInterface $lintingResult): ?array
  {
@@ -158,8 +158,9 @@
  $newHash = $oldHash;
 
  $appliedFixers = [];
+ $extraInfoFixers = [];
 
  try {
  foreach ($this->fixers as $fixer) {
  // for custom fixers we don't know is it safe to run `->fix()` without checking `->supports()` and `->isCandidate()`,
  // thus we need to check it and conditionally skip fixing
@@ -176,6 +177,10 @@
  $tokens->clearEmptyTokens();
  $tokens->clearChanged();
  $appliedFixers[] = $fixer->getName();
+
+ if (!isset($extraInfoFixers['helpUri'][$fixer->getName()])) {
+ $extraInfoFixers['helpUri'][$fixer->getName()] = $fixer->getHelpUri();
+ }
  }
  }
  } catch (\ParseError $e) {
@@ -208,6 +213,7 @@
  $fixInfo = [
  'appliedFixers' => $appliedFixers,
  'diff' => $this->differ->diff($old, $new, $file),
+ 'extraInfoFixers' => $extraInfoFixers,
  ];
 
  try {

tests/AbstractProxyFixerTest.php

@@ -168,6 +168,11 @@ public function getDefinition(): FixerDefinitionInterface
  throw new \BadMethodCallException('Not implemented.');
  }
 
+ public function getHelpUri(): string
+ {
+ throw new \BadMethodCallException('Not implemented.');
+ }
+
  public function getName(): string
  {
  return uniqid('abstract_proxy_test_');
@@ -211,6 +216,11 @@ public function fix(\SplFileInfo $file, Tokens $tokens): void
  throw new \BadMethodCallException('Not implemented.');
  }
 
+ public function getHelpUri(): string
+ {
+ throw new \BadMethodCallException('Not implemented.');
+ }
+
  public function getName(): string
  {
  return uniqid('abstract_proxy_aware_test_');

tests/Console/Command/DescribeCommandTest.php

@@ -379,6 +379,11 @@ public function getDefinition(): FixerDefinition
  return new FixerDefinition('Fixes stuff.', []);
  }
 
+ public function getHelpUri(): string
+ {
+ throw new \LogicException('Not implemented.');
+ }
+
  public function getName(): string
  {
  return 'Foo/bar_baz';
@@ -578,6 +583,11 @@ public function getDefinition(): FixerDefinition
  );
  }
 
+ public function getHelpUri(): string
+ {
+ throw new \LogicException('Not implemented.');
+ }
+
  public function getName(): string
  {
  return 'Foo/bar';

tests/Console/Report/FixReport/AbstractReporterTestCase.php

@@ -94,6 +94,7 @@ class Foo
  {
  }
  }',
+ 'extraInfoFixers' => [],
  ],
  ],
  10,
@@ -122,6 +123,7 @@ class Foo
  {
  }
  }',
+ 'extraInfoFixers' => [],
  ],
  ],
  10,
@@ -140,6 +142,7 @@ class Foo
  'someFile.php' => [
  'appliedFixers' => ['some_fixer_name_here_1', 'some_fixer_name_here_2'],
  'diff' => '',
+ 'extraInfoFixers' => [],
  ],
  ],
  10,
@@ -168,6 +171,7 @@ class Foo
  {
  }
  }',
+ 'extraInfoFixers' => [],
  ],
  ],
  10,
@@ -186,10 +190,12 @@ class Foo
  'someFile.php' => [
  'appliedFixers' => ['some_fixer_name_here_1', 'some_fixer_name_here_2'],
  'diff' => 'this text is a diff ;)',
+ 'extraInfoFixers' => [],
  ],
  'anotherFile.php' => [
  'appliedFixers' => ['another_fixer_name_here'],
  'diff' => 'another diff here ;)',
+ 'extraInfoFixers' => [],
  ],
  ],
  10,

tests/Console/Report/FixReport/ReportSummaryTest.php

@@ -30,6 +30,7 @@ public function testReportSummary(): void
  'someFile.php' => [
  'appliedFixers' => ['some_fixer_name_here'],
  'diff' => 'this text is a diff ;)',
+ 'extraInfoFixers' => [],
  ],
  ];
  $filesCount = 10;

tests/FixerFactoryTest.php

@@ -365,6 +365,11 @@ public function getDefinition(): FixerDefinitionInterface
  throw new \LogicException('Not implemented.');
  }
 
+ public function getHelpUri(): string
+ {
+ throw new \LogicException('Not implemented.');
+ }
+
  public function getName(): string
  {
  return 'foo';
@@ -458,6 +463,11 @@ public function getDefinition(): FixerDefinitionInterface
  throw new \LogicException('Not implemented.');
  }
 
+ public function getHelpUri(): string
+ {
+ throw new \LogicException('Not implemented.');
+ }
+
  public function getName(): string
  {
  return 'foo';
@@ -531,6 +541,11 @@ public function getDefinition(): FixerDefinitionInterface
  throw new \LogicException('Not implemented.');
  }
 
+ public function getHelpUri(): string
+ {
+ throw new \LogicException('Not implemented.');
+ }
+
  public function getName(): string
  {
  return 'foo';
@@ -586,6 +601,11 @@ public function getDefinition(): FixerDefinitionInterface
  throw new \LogicException('Not implemented.');
  }
 
+ public function getHelpUri(): string
+ {
+ throw new \LogicException('Not implemented.');
+ }
+
  public function getName(): string
  {
  return $this->name;

tests/Runner/RunnerTest.php

@@ -52,6 +52,9 @@ public function testThatFixSuccessfully(): void
  $expectedChangedInfo = [
  'appliedFixers' => ['visibility_required'],
  'diff' => '',
+ 'extraInfoFixers' => [
+ 'helpUri' => ['visibility_required' => 'https://cs.symfony.com/doc/rules/class_notation/visibility_required.html'],
+ ],
  ];
 
  $path = __DIR__.\DIRECTORY_SEPARATOR.'..'.\DIRECTORY_SEPARATOR.'Fixtures'.\DIRECTORY_SEPARATOR.'FixerTest'.\DIRECTORY_SEPARATOR.'fix';

tests/UtilsTest.php

@@ -479,6 +479,11 @@ public function isRisky(): bool
  throw new \LogicException('Not implemented.');
  }
 
+ public function getHelpUri(): string
+ {
+ throw new \LogicException('Not implemented.');
+ }
+
  public function fix(\SplFileInfo $file, Tokens $tokens): void
  {
  throw new \LogicException('Not implemented.');