add rules for phpDoc comments

src/PhpCs/FiveLab/ErrorCodes.php

@@ -18,19 +18,19 @@
  */
 final class ErrorCodes
 {
-    public const MISSED_LINE_AFTER             = 'MissedLineAfter';
-    public const MISSED_LINE_BEFORE            = 'MissedLineBefore';
-    public const MISSED                        = 'Missed';
-    public const WRONG_FORMAT                  = 'WrongFormat';
-    public const MULTIPLE                      = 'Multiple';
-    public const PROHIBITED                    = 'Prohibited';
-    public const UNUSED                        = 'Unused';
-    public const MISSED_PARAMETER_TYPE         = 'MissedFunctionParameterType';
-    public const MISSED_RETURN_TYPE            = 'MissedFunctionReturnType';
-    public const LINE_AFTER_NOT_ALLOWED        = 'LineAfterNotAllowed';
-    public const LINE_BEFORE_NOT_ALLOWED       = 'LineBeforeNotAllowed';
-    public const MISSED_CONSTANT_TYPE          = 'MissedConstantType';
-    public const NAMESPACE_WRONG               = 'NamespaceWrong';
-    public const ARRAYS_DOC_VECTOR             = 'ArraysDocVector';
-    public const COMMENT_OUTSIDE_FUNCTION_BODY = 'CommentOutsideFunctionBody';
+    public const MISSED_LINE_AFTER       = 'MissedLineAfter';
+    public const MISSED_LINE_BEFORE      = 'MissedLineBefore';
+    public const MISSED                  = 'Missed';
+    public const WRONG_FORMAT            = 'WrongFormat';
+    public const MULTIPLE                = 'Multiple';
+    public const PROHIBITED              = 'Prohibited';
+    public const UNUSED                  = 'Unused';
+    public const MISSED_PARAMETER_TYPE   = 'MissedFunctionParameterType';
+    public const MISSED_RETURN_TYPE      = 'MissedFunctionReturnType';
+    public const LINE_AFTER_NOT_ALLOWED  = 'LineAfterNotAllowed';
+    public const LINE_BEFORE_NOT_ALLOWED = 'LineBeforeNotAllowed';
+    public const MISSED_CONSTANT_TYPE    = 'MissedConstantType';
+    public const NAMESPACE_WRONG         = 'NamespaceWrong';
+    public const ARRAYS_DOC_VECTOR       = 'ArraysDocVector';
+    public const PHPDOC_NOT_ALLOWED      = 'PhpDocNotAllowed';
 }

src/PhpCs/FiveLab/Sniffs/Commenting/ProhibitedDocCommentsSniff.php

@@ -0,0 +1,104 @@
+<?php
+
+declare(strict_types = 1);
+
+/*
+ * This file is part of the FiveLab CiRules package
+ *
+ * (c) FiveLab
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code
+ */
+
+namespace FiveLab\Component\CiRules\PhpCs\FiveLab\Sniffs\Commenting;
+
+use FiveLab\Component\CiRules\PhpCs\FiveLab\ErrorCodes;
+use PHP_CodeSniffer\Files\File;
+use PHP_CodeSniffer\Sniffs\Sniff;
+
+class ProhibitedDocCommentsSniff implements Sniff
+{
+    public function register(): array
+    {
+        return [
+            T_DOC_COMMENT_OPEN_TAG,
+        ];
+    }
+
+    public function process(File $phpcsFile, mixed $stackPtr): void
+    {
+        $tokens = $phpcsFile->getTokens();
+        $commentToken = $tokens[$stackPtr];
+
+        $possiblyDeclaration = $phpcsFile->findNext([
+            T_CLASS, T_INTERFACE, T_TRAIT, T_FUNCTION,
+            T_ABSTRACT, T_FINAL, T_ENUM
+        ], $commentToken['comment_closer'] + 1, local: true);
+
+        if ($possiblyDeclaration) {
+            return;
+        }
+
+        $varPtr = $phpcsFile->findNext(T_VARIABLE, $commentToken['comment_closer'] + 1, local: true);
+
+        if ($varPtr) {
+            $commentTokenPtr = $phpcsFile->findNext(T_DOC_COMMENT_TAG, ($stackPtr + 1), $commentToken['comment_closer'], local: true);
+
+            if (false === $commentTokenPtr) {
+                $phpcsFile->addError(
+                    'PHPDoc comment can contains only @var here.',
+                    $stackPtr,
+                    ErrorCodes::PHPDOC_NOT_ALLOWED
+                );
+
+                return;
+            }
+        }
+
+        $isOnlyVarTag = $this->isHasOnlyVarTag($phpcsFile, $stackPtr, $commentToken['comment_closer'], $tokens);
+
+        if (true === $isOnlyVarTag) {
+            return;
+        }
+
+        $phpcsFile->addError(
+            'PHPDoc comment is not allowed here.',
+            $stackPtr,
+            ErrorCodes::PHPDOC_NOT_ALLOWED
+        );
+    }
+
+    /**
+     * Check has T_DOC_COMMENT_TAG another tags
+     *
+     * @param File              $phpcsFile
+     * @param int               $startPtr
+     * @param int               $endPtr
+     * @param array<int, mixed> $tokens
+     *
+     * @return bool|null
+     */
+    private function isHasOnlyVarTag(File $phpcsFile, int $startPtr, int $endPtr, array $tokens): ?bool
+    {
+        $commentTokenPtr = $phpcsFile->findNext(T_DOC_COMMENT_TAG, ($startPtr + 1), $endPtr);
+
+        if (false === $commentTokenPtr) {
+            return null;
+        }
+
+        if ($commentTokenPtr && $tokens[$commentTokenPtr]['content'] !== '@var') {
+            $phpcsFile->addError(
+                \sprintf('PHPDoc comment tag %s is not allowed here.', $tokens[$commentTokenPtr]['content']),
+                $commentTokenPtr,
+                ErrorCodes::PHPDOC_NOT_ALLOWED
+            );
+
+            return false;
+        }
+
+        $this->isHasOnlyVarTag($phpcsFile, $commentTokenPtr, $endPtr, $tokens);
+
+        return true;
+    }
+}

tests/PhpCs/FiveLab/Sniffs/Commenting/ProhibitedDocCommentsSniffTest.php

@@ -0,0 +1,62 @@
+<?php
+
+declare(strict_types = 1);
+
+/*
+ * This file is part of the FiveLab CiRules package
+ *
+ * (c) FiveLab
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code
+ */
+
+namespace FiveLab\Component\CiRules\Tests\PhpCs\FiveLab\Sniffs\Commenting;
+
+use FiveLab\Component\CiRules\PhpCs\FiveLab\Sniffs\Commenting\ProhibitedDocCommentsSniff;
+use FiveLab\Component\CiRules\Tests\PhpCs\FiveLab\Sniffs\SniffTestCase;
+
+class ProhibitedDocCommentsSniffTest extends SniffTestCase
+{
+    protected function getSniffClass(): string
+    {
+        return ProhibitedDocCommentsSniff::class;
+    }
+
+    public static function provideDataSet(): array
+    {
+        return [
+            'success' => [
+                __DIR__.'/Resources/prohibited-doc-comments/success.php',
+            ],
+
+            'wrong' => [
+                __DIR__.'/Resources/prohibited-doc-comments/wrong.php',
+                [
+                    'message' => 'PHPDoc comment is not allowed here.',
+                    'source'  => 'FiveLab.Commenting.ProhibitedDocComments.PhpDocNotAllowed',
+                ],
+                [
+                    'message' => 'PHPDoc comment can contains only @var here.',
+                    'source'  => 'FiveLab.Commenting.ProhibitedDocComments.PhpDocNotAllowed',
+                ],
+                [
+                    'message' => 'PHPDoc comment can contains only @var here.',
+                    'source'  => 'FiveLab.Commenting.ProhibitedDocComments.PhpDocNotAllowed',
+                ],
+                [
+                    'message' => 'PHPDoc comment tag @return is not allowed here.',
+                    'source'  => 'FiveLab.Commenting.ProhibitedDocComments.PhpDocNotAllowed',
+                ],
+                [
+                    'message' => 'PHPDoc comment can contains only @var here.',
+                    'source'  => 'FiveLab.Commenting.ProhibitedDocComments.PhpDocNotAllowed',
+                ],
+                [
+                    'message' => 'PHPDoc comment is not allowed here.',
+                    'source'  => 'FiveLab.Commenting.ProhibitedDocComments.PhpDocNotAllowed',
+                ],
+            ],
+        ];
+    }
+}