feat: Clickable rule names in TextReporter pointing to official documentation

src/AbstractFixer.php

@@ -20,6 +20,7 @@
 use PhpCsFixer\Console\Application;
 use PhpCsFixer\Fixer\ConfigurableFixerInterface;
 use PhpCsFixer\Fixer\FixerInterface;
+use PhpCsFixer\Fixer\FixerReportInterface;
 use PhpCsFixer\Fixer\WhitespacesAwareFixerInterface;
 use PhpCsFixer\FixerConfiguration\DeprecatedFixerOption;
 use PhpCsFixer\FixerConfiguration\FixerConfigurationResolverInterface;
@@ -33,7 +34,7 @@
  *
  * @internal
  */
-abstract class AbstractFixer implements FixerInterface
+abstract class AbstractFixer implements FixerInterface, FixerReportInterface
 {
  /**
  * @var null|array<string, mixed>
@@ -65,6 +66,15 @@ public function __construct()
  }
  }
 
+ public function getExtraInfoFixers(): array
+ {
+ return [
+ 'helpUri' => $this->getHelpUri(),
+ 'definition' => $this->getDefinition(),
+ 'risky' => $this->isRisky(),
+ ];
+ }
+
  final public function fix(\SplFileInfo $file, Tokens $tokens): void
  {
  if ($this instanceof ConfigurableFixerInterface && null === $this->configuration) {
@@ -170,6 +180,19 @@ public function setWhitespacesConfig(WhitespacesFixerConfig $config): void
  $this->whitespacesConfig = $config;
  }
 
+ protected 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)
+ );
+ }
+
  abstract protected function applyFix(\SplFileInfo $file, Tokens $tokens): void;
 
  protected function createConfigurationDefinition(): FixerConfigurationResolverInterface

src/Console/Report/FixReport/ReportSummary.php

@@ -14,6 +14,8 @@
 
 namespace PhpCsFixer\Console\Report\FixReport;
 
+use PhpCsFixer\FixerDefinition\FixerDefinitionInterface;
+
 /**
  * @author Dariusz Rumiński <[email protected]>
  *
@@ -22,7 +24,11 @@
 final class ReportSummary
 {
  /**
- * @var array<string, array{appliedFixers: list<string>, diff: string}>
+ * @var array<string, array{
+ * appliedFixers: list<string>,
+ * diff: string,
+ * extraInfoFixers: array<string, array{"helpUri"?: string, "definition"?: FixerDefinitionInterface, "risky"?: bool}>
+ * }>
  */
  private array $changed;
 
@@ -39,9 +45,11 @@ 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<string, array{"helpUri"?: string, "definition"?: FixerDefinitionInterface, "risky"?: bool}>
+ * }> $changed
  */
  public function __construct(
  array $changed,
@@ -72,7 +80,11 @@ public function isDryRun(): bool
  }
 
  /**
- * @return array<string, array{appliedFixers: list<string>, diff: string}>
+ * @return array<string, array{
+ * appliedFixers: list<string>,
+ * diff: string,
+ * extraInfoFixers: array<string, array{"helpUri"?: string, "definition"?: FixerDefinitionInterface, "risky"?: bool}>
+ * }>
  */
  public function getChanged(): array
  {

src/Console/Report/FixReport/TextReporter.php

@@ -15,6 +15,8 @@
 namespace PhpCsFixer\Console\Report\FixReport;
 
 use PhpCsFixer\Differ\DiffConsoleFormatter;
+use PhpCsFixer\FixerDefinition\FixerDefinitionInterface;
+use Symfony\Component\Console\Formatter\OutputFormatter;
 
 /**
  * @author Boris Gorbylev <[email protected]>
@@ -41,6 +43,7 @@
  $output .= $this->getAppliedFixers(
  $reportSummary->isDecoratedOutput(),
  $fixResult['appliedFixers'],
+ $fixResult['extraInfoFixers']
  );
  }
 
@@ -58,13 +61,25 @@
  }
 
  /**
- * @param list<string> $appliedFixers
+ * @param list<string> $appliedFixers
+ * @param array<string, array{"helpUri"?: string, "definition"?: FixerDefinitionInterface, "risky"?: bool}> $extraInfoFixers
  */
- private function getAppliedFixers(bool $isDecoratedOutput, array $appliedFixers): string
+ private function getAppliedFixers(bool $isDecoratedOutput, array $appliedFixers, array $extraInfoFixers = []): string
  {
+ $fixers = [];
+
+ foreach ($appliedFixers as $appliedFixer) {
+ $url = $extraInfoFixers[$appliedFixer]['helpUri'] ?? '';
+ 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)
+ implode(', ', $fixers)
  );
  }
 

src/Fixer/FixerReportInterface.php

@@ -0,0 +1,31 @@
+<?php
+
+declare(strict_types=1);
+
+/*
+ * This file is part of PHP CS Fixer.
+ *
+ * (c) Fabien Potencier <[email protected]>
+ * Dariusz Rumiński <[email protected]>
+ *
+ * This source file is subject to the MIT license that is bundled
+ * with this source code in the file LICENSE.
+ */
+
+namespace PhpCsFixer\Fixer;
+
+use PhpCsFixer\FixerDefinition\FixerDefinitionInterface;
+
+/**
+ * @author Laurent Laville
+ */
+interface FixerReportInterface
+{
+ /**
+ * - "helpUri" identify the absolute URI [RFC3986](http://www.rfc-editor.org/info/rfc3986)
+ * * of the primary documentation for the fixer.
+ *
+ * @return array{"helpUri"?: string, "definition"?: FixerDefinitionInterface, "risky"?: bool}
+ */
+ public function getExtraInfoFixers(): array;
+}

src/Runner/Runner.php

@@ -23,6 +23,8 @@
 use PhpCsFixer\Error\ErrorsManager;
 use PhpCsFixer\FileReader;
 use PhpCsFixer\Fixer\FixerInterface;
+use PhpCsFixer\Fixer\FixerReportInterface;
+use PhpCsFixer\FixerDefinition\FixerDefinitionInterface;
 use PhpCsFixer\FixerFileProcessedEvent;
 use PhpCsFixer\Linter\LinterInterface;
 use PhpCsFixer\Linter\LintingException;
@@ -92,7 +94,11 @@
  }
 
  /**
- * @return array<string, array{appliedFixers: list<string>, diff: string}>
+ * @return array<string, array{
+ * appliedFixers: list<string>,
+ * diff: string,
+ * extraInfoFixers: array<string, array{"helpUri"?: string, "definition"?: FixerDefinitionInterface, "risky"?: bool}>
+ * }>
  */
  public function fix(): array
  {
@@ -130,7 +136,11 @@
  }
 
  /**
- * @return null|array{appliedFixers: list<string>, diff: string}
+ * @return null|array{
+ * appliedFixers: list<string>,
+ * diff: string,
+ * extraInfoFixers: array<string, array{"helpUri"?: string, "definition"?: FixerDefinitionInterface, "risky"?: bool}>
+ * }
  */
  private function fixFile(\SplFileInfo $file, LintingResultInterface $lintingResult): ?array
  {
@@ -158,8 +168,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 +187,10 @@
  $tokens->clearEmptyTokens();
  $tokens->clearChanged();
  $appliedFixers[] = $fixer->getName();
+
+ if ($fixer instanceof FixerReportInterface) {
+ $extraInfoFixers[$fixer->getName()] = $fixer->getExtraInfoFixers();
+ }
  }
  }
  } catch (\ParseError $e) {
@@ -208,6 +223,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;