Explain: mark deprecated sniffs as such

This commit makes a small adjustment to the output of the `-e` (explain) command. Deprecated sniffs will now be marked with a trailing `*` asterix and if the standard contains deprecated sniffs, a line will show at the end of the output to explain that the `*` means that a sniff is deprecated. Includes a test documenting and safeguarding this behaviour.
PHPCSStandards · Jan 16, 2024 · 014bc9c · 014bc9c
1 parent f31d4c0
commit 014bc9c
Show file tree

Hide file tree

Showing 2 changed files with 50 additions and 0 deletions.
diff --git a/src/Ruleset.php b/src/Ruleset.php
@@ -301,10 +301,18 @@ public function explain()
                 }
             }//end if
 
+            if (isset($this->deprecatedSniffs[$sniff]) === true) {
+                $sniff .= ' *';
+            }
+
             $sniffsInStandard[] = $sniff;
             ++$lastCount;
         }//end foreach
 
+        if (count($this->deprecatedSniffs) > 0) {
+            echo PHP_EOL.'* Sniffs marked with an asterix are deprecated.'.PHP_EOL;
+        }
+
     }//end explain()
 
 

diff --git a/tests/Core/Ruleset/ExplainTest.php b/tests/Core/Ruleset/ExplainTest.php
@@ -166,6 +166,48 @@ public function testExplainCustomRuleset()
     }//end testExplainCustomRuleset()
 
 
+    /**
+     * Test the output of the "explain" command for a standard containing both deprecated
+     * and non-deprecated sniffs.
+     *
+     * Tests that:
+     * - Deprecated sniffs are marked with an asterix in the list.
+     * - A footnote is displayed explaining the asterix.
+     * - And that the "standard uses # deprecated sniffs" listing is **not** displayed.
+     *
+     * @return void
+     */
+    public function testExplainWithDeprecatedSniffs()
+    {
+        // Set up the ruleset.
+        $standard = __DIR__."/ShowSniffDeprecationsTest.xml";
+        $config   = new ConfigDouble(["--standard=$standard", '-e']);
+        $ruleset  = new Ruleset($config);
+
+        $expected  = PHP_EOL;
+        $expected .= 'The SniffDeprecationTest standard contains 9 sniffs'.PHP_EOL.PHP_EOL;
+
+        $expected .= 'Fixtures (9 sniffs)'.PHP_EOL;
+        $expected .= '-------------------'.PHP_EOL;
+        $expected .= '  Fixtures.Deprecated.WithLongReplacement *'.PHP_EOL;
+        $expected .= '  Fixtures.Deprecated.WithoutReplacement *'.PHP_EOL;
+        $expected .= '  Fixtures.Deprecated.WithReplacement *'.PHP_EOL;
+        $expected .= '  Fixtures.Deprecated.WithReplacementContainingLinuxNewlines *'.PHP_EOL;
+        $expected .= '  Fixtures.Deprecated.WithReplacementContainingNewlines *'.PHP_EOL;
+        $expected .= '  Fixtures.SetProperty.AllowedAsDeclared'.PHP_EOL;
+        $expected .= '  Fixtures.SetProperty.AllowedViaMagicMethod'.PHP_EOL;
+        $expected .= '  Fixtures.SetProperty.AllowedViaStdClass'.PHP_EOL;
+        $expected .= '  Fixtures.SetProperty.NotAllowedViaAttribute'.PHP_EOL.PHP_EOL;
+
+        $expected .= '* Sniffs marked with an asterix are deprecated.'.PHP_EOL;
+
+        $this->expectOutputString($expected);
+
+        $ruleset->explain();
+
+    }//end testExplainWithDeprecatedSniffs()
+
+
     /**
      * Test that each standard passed on the command-line is explained separately.
      *