Squiz/PostStatementComment: use a different error code for annotations (#627)

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 `@`.

Author: rodrigoprimo

src/Standards/Squiz/Sniffs/Commenting/PostStatementCommentSniff.php

@@ -109,6 +109,14 @@ public function process(File $phpcsFile, $stackPtr)
             }
         }
 
+        if ($phpcsFile->tokenizerType === 'PHP'
+            && preg_match('|^//[ \t]*@[^\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) {

src/Standards/Squiz/Tests/Commenting/PostStatementCommentUnitTest.inc

@@ -52,3 +52,13 @@ $match = match($foo // comment
 ) {
     1 => 1, // comment
 };
+
+// Issue #560: Annotations should be reported separately and be non-auto-fixable as their meaning may change when moved.
+$a = 1; //@codeCoverageIgnore
+$b = 2; // @phpstan-ignore variable.undefined
+$c = 3; //  @phpstan-ignore variable.undefined
+$d = 4; //	@tabInsteadOfSpace
+
+// Comments that include `@`, but are not recognized as annotations by this sniff.
+$a = 1; // @ = add tag.
+$b = 2; // Some comment. // @username

src/Standards/Squiz/Tests/Commenting/PostStatementCommentUnitTest.inc.fixed

@@ -57,3 +57,15 @@ $match = match($foo // comment
     1 => 1, 
 // comment
 };
+
+// Issue #560: Annotations should be reported separately and be non-auto-fixable as their meaning may change when moved.
+$a = 1; //@codeCoverageIgnore
+$b = 2; // @phpstan-ignore variable.undefined
+$c = 3; //  @phpstan-ignore variable.undefined
+$d = 4; //	@tabInsteadOfSpace
+
+// Comments that include `@`, but are not recognized as annotations by this sniff.
+$a = 1; 
+// @ = add tag.
+$b = 2; 
+// Some comment. // @username

src/Standards/Squiz/Tests/Commenting/PostStatementCommentUnitTest.php

@@ -40,6 +40,12 @@ public function getErrorList($testFile='')
                 18 => 1,
                 35 => 1,
                 53 => 1,
+                57 => 1,
+                58 => 1,
+                59 => 1,
+                60 => 1,
+                63 => 1,
+                64 => 1,
             ];
 
         case 'PostStatementCommentUnitTest.1.js':