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

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('|//\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) {

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.

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.

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':