From f6053a399514983ec712cdbecb892480216ac797 Mon Sep 17 00:00:00 2001
From: Rodrigo Primo <rodrigosprimo@gmail.com>
Date: Fri, 11 Oct 2024 15:56:31 -0300
Subject: [PATCH] Squiz/PostStatementComment: use a different error code for
 annotations

This commit changes `Squiz.Commenting.PostStatementComment` to use a
different error code when an annotation is found. This will allow
ruleset maintainers to selectively exclude the flagging of trailing
annotations from their ruleset. For example, for PHPCS itself, this will
make it possible to use the `// @codeCoverageIgnore` annotation where
needed.

An annotation is defined as any comment that starts with an optional
space, followed by a `@` and any character, as long as it is not a
whitespace. For now, only `//` comments are supported as this is the only
type of comment supported by this sniff.

This change only applies to PHP code as support for JS will be dropped
soon, and JS doesn't seem to follow the same convention of annotations
starting with `@`.
---
 .../Squiz/Sniffs/Commenting/PostStatementCommentSniff.php | 8 ++++++++
 .../Tests/Commenting/PostStatementCommentUnitTest.inc     | 4 ++++
 .../Commenting/PostStatementCommentUnitTest.inc.fixed     | 5 +++++
 .../Tests/Commenting/PostStatementCommentUnitTest.php     | 3 +++
 4 files changed, 20 insertions(+)

diff --git a/src/Standards/Squiz/Sniffs/Commenting/PostStatementCommentSniff.php b/src/Standards/Squiz/Sniffs/Commenting/PostStatementCommentSniff.php
index 9b36abe76f..a0d91d3445 100644
--- a/src/Standards/Squiz/Sniffs/Commenting/PostStatementCommentSniff.php
+++ b/src/Standards/Squiz/Sniffs/Commenting/PostStatementCommentSniff.php
@@ -109,6 +109,14 @@ public function process(File $phpcsFile, $stackPtr)
             }
         }
 
+        if ($phpcsFile->tokenizerType === 'PHP'
+            && preg_match('|//\s?@[^\s]+|', $tokens[$stackPtr]['content']) === 1
+        ) {
+            $error = 'Annotations may not appear after statements';
+            $phpcsFile->addError($error, $stackPtr, 'AnnotationFound');
+            return;
+        }
+
         $error = 'Comments may not appear after statements';
         $fix   = $phpcsFile->addFixableError($error, $stackPtr, 'Found');
         if ($fix === true) {
diff --git a/src/Standards/Squiz/Tests/Commenting/PostStatementCommentUnitTest.inc b/src/Standards/Squiz/Tests/Commenting/PostStatementCommentUnitTest.inc
index b83469613f..d4ee337459 100644
--- a/src/Standards/Squiz/Tests/Commenting/PostStatementCommentUnitTest.inc
+++ b/src/Standards/Squiz/Tests/Commenting/PostStatementCommentUnitTest.inc
@@ -52,3 +52,7 @@ $match = match($foo // comment
 ) {
     1 => 1, // comment
 };
+
+$a = 1; // @codeCoverageIgnore
+$b = 2; //@phpstan-ignore variable.undefined
+$c = 3; //  @thisIsNotAnAnnotation - more than one space before the @ symbol.
diff --git a/src/Standards/Squiz/Tests/Commenting/PostStatementCommentUnitTest.inc.fixed b/src/Standards/Squiz/Tests/Commenting/PostStatementCommentUnitTest.inc.fixed
index 21a4bbe032..4cbd871617 100644
--- a/src/Standards/Squiz/Tests/Commenting/PostStatementCommentUnitTest.inc.fixed
+++ b/src/Standards/Squiz/Tests/Commenting/PostStatementCommentUnitTest.inc.fixed
@@ -57,3 +57,8 @@ $match = match($foo // comment
     1 => 1, 
 // comment
 };
+
+$a = 1; // @codeCoverageIgnore
+$b = 2; //@phpstan-ignore variable.undefined
+$c = 3; 
+//  @thisIsNotAnAnnotation - more than one space before the @ symbol.
diff --git a/src/Standards/Squiz/Tests/Commenting/PostStatementCommentUnitTest.php b/src/Standards/Squiz/Tests/Commenting/PostStatementCommentUnitTest.php
index b9751f6147..de09d0c773 100644
--- a/src/Standards/Squiz/Tests/Commenting/PostStatementCommentUnitTest.php
+++ b/src/Standards/Squiz/Tests/Commenting/PostStatementCommentUnitTest.php
@@ -40,6 +40,9 @@ public function getErrorList($testFile='')
                 18 => 1,
                 35 => 1,
                 53 => 1,
+                56 => 1,
+                57 => 1,
+                58 => 1,
             ];
 
         case 'PostStatementCommentUnitTest.1.js':