[Annotation] Add RemovePropertyVariableNameDescriptionFixer (#68)

Author: TomasVotruba

README.md

@@ -145,6 +145,22 @@ Fixes @param, @return, `@var` and inline `@var` annotations broken formats
 
 <br>
 
+## RemovePropertyVariableNameDescriptionFixer
+
+Remove docblock descriptions which duplicate their property name
+
+- class: [`Symplify\CodingStandard\Fixer\Annotation\RemovePropertyVariableNameDescriptionFixer`](../src/Fixer/Annotation/RemovePropertyVariableNameDescriptionFixer.php)
+
+```diff
+ /**
+- * @var string $name
++ * @var string
+  */
+ private $name;
+```
+
+<br>
+
 ## RemoveMethodNameDuplicateDescriptionFixer
 
 Remove docblock descriptions which duplicate their method name

config/symplify.php

@@ -3,8 +3,9 @@
 declare(strict_types=1);
 
 use PhpCsFixer\Fixer\Phpdoc\GeneralPhpdocAnnotationRemoveFixer;
-use Symplify\CodingStandard\Fixer\Annotation\RemovePHPStormAnnotationFixer;
 use Symplify\CodingStandard\Fixer\Annotation\RemoveMethodNameDuplicateDescriptionFixer;
+use Symplify\CodingStandard\Fixer\Annotation\RemovePHPStormAnnotationFixer;
+use Symplify\CodingStandard\Fixer\Annotation\RemovePropertyVariableNameDescriptionFixer;
 use Symplify\CodingStandard\Fixer\ArrayNotation\ArrayListItemNewlineFixer;
 use Symplify\CodingStandard\Fixer\ArrayNotation\ArrayOpenerAndCloserNewlineFixer;
 use Symplify\CodingStandard\Fixer\Commenting\ParamReturnAndVarTagMalformsFixer;
@@ -23,6 +24,7 @@
         ParamReturnAndVarTagMalformsFixer::class,
         RemoveUselessDefaultCommentFixer::class,
         RemoveMethodNameDuplicateDescriptionFixer::class,
+        RemovePropertyVariableNameDescriptionFixer::class,
 
         // arrays
         ArrayListItemNewlineFixer::class,

src/Fixer/Annotation/RemoveMethodNameDuplicateDescriptionFixer.php

@@ -62,7 +62,7 @@ public function fix(SplFileInfo $fileInfo, Tokens $tokens): void
             }
 
             $methodName = $this->methodNameResolver->resolve($tokens, $index);
-            if (is_null($methodName)) {
+            if ($methodName === null) {
                 continue;
             }
 

src/Fixer/Annotation/RemovePropertyVariableNameDescriptionFixer.php

@@ -0,0 +1,94 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Symplify\CodingStandard\Fixer\Annotation;
+
+use Nette\Utils\Strings;
+use PhpCsFixer\FixerDefinition\FixerDefinition;
+use PhpCsFixer\FixerDefinition\FixerDefinitionInterface;
+use PhpCsFixer\Tokenizer\Token;
+use PhpCsFixer\Tokenizer\Tokens;
+use SplFileInfo;
+use Symplify\CodingStandard\Fixer\AbstractSymplifyFixer;
+use Symplify\CodingStandard\Fixer\Naming\PropertyNameResolver;
+use Symplify\CodingStandard\TokenRunner\Traverser\TokenReverser;
+
+/**
+ * @see \Symplify\CodingStandard\Tests\Fixer\Annotation\RemovePropertyVariableNameDescriptionFixer\RemovePropertyVariableNameDescriptionFixerTest
+ */
+final class RemovePropertyVariableNameDescriptionFixer extends AbstractSymplifyFixer
+{
+    /**
+     * @var string
+     */
+    private const ERROR_MESSAGE = 'Remove useless "$variable" from @var tag';
+
+    private readonly PropertyNameResolver $propertyNameResolver;
+
+    public function __construct(
+        private readonly TokenReverser $tokenReverser
+    ) {
+        $this->propertyNameResolver = new PropertyNameResolver();
+    }
+
+    public function getDefinition(): FixerDefinitionInterface
+    {
+        return new FixerDefinition(self::ERROR_MESSAGE, []);
+    }
+
+    /**
+     * @param Tokens<Token> $tokens
+     */
+    public function isCandidate(Tokens $tokens): bool
+    {
+        if (! $tokens->isTokenKindFound(T_VARIABLE)) {
+            return false;
+        }
+
+        return $tokens->isAnyTokenKindsFound([T_DOC_COMMENT, T_COMMENT]);
+    }
+
+    /**
+     * @param Tokens<Token> $tokens
+     */
+    public function fix(SplFileInfo $fileInfo, Tokens $tokens): void
+    {
+        $reversedTokens = $this->tokenReverser->reverse($tokens);
+
+        foreach ($reversedTokens as $index => $token) {
+            if (! $token->isGivenKind([T_DOC_COMMENT, T_COMMENT])) {
+                continue;
+            }
+
+            $propertyName = $this->propertyNameResolver->resolve($tokens, $index);
+            if ($propertyName === null) {
+                continue;
+            }
+
+            // skip if not setter or getter
+            $originalDocContent = $token->getContent();
+
+            $hasChanged = false;
+
+            $docblockLines = explode("\n", $originalDocContent);
+            foreach ($docblockLines as $key => $docblockLine) {
+                if (! str_ends_with($docblockLine, ' ' . $propertyName)) {
+                    continue;
+                }
+
+                // remove last x characters
+                $docblockLine = Strings::substring($docblockLine, 0, -strlen(' ' . $propertyName));
+
+                $hasChanged = true;
+                $docblockLines[$key] = rtrim($docblockLine);
+            }
+
+            if (! $hasChanged) {
+                continue;
+            }
+
+            $tokens[$index] = new Token([T_DOC_COMMENT, implode("\n", $docblockLines)]);
+        }
+    }
+}

src/Fixer/Naming/MethodNameResolver.php

@@ -6,7 +6,6 @@
 
 use PhpCsFixer\Tokenizer\Token;
 use PhpCsFixer\Tokenizer\Tokens;
-use SplFileInfo;
 
 final class MethodNameResolver
 {

src/Fixer/Naming/PropertyNameResolver.php

@@ -0,0 +1,31 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Symplify\CodingStandard\Fixer\Naming;
+
+use PhpCsFixer\Tokenizer\Token;
+use PhpCsFixer\Tokenizer\Tokens;
+
+final class PropertyNameResolver
+{
+    /**
+     * @param Tokens<Token> $tokens
+     */
+    public function resolve(Tokens $tokens, int $currentPosition): ?string
+    {
+        foreach ($tokens as $position => $token) {
+            if ($position <= $currentPosition) {
+                continue;
+            }
+
+            if (! $token->isGivenKind([T_VARIABLE])) {
+                continue;
+            }
+
+            return $token->getContent();
+        }
+
+        return null;
+    }
+}

tests/Fixer/Annotation/RemovePropertyVariableNameDescriptionFixer/Fixture/simple_annotation.php.inc

@@ -0,0 +1,27 @@
+<?php
+
+namespace Symplify\CodingStandard\Tests\Fixer\Annotation\RemovePropertyVariableNameDescriptionFixer\Fixture;
+
+final class SimpleAnnotation
+{
+    /**
+     * @var string $name
+     */
+    public $name;
+}
+
+?>
+-----
+<?php
+
+namespace Symplify\CodingStandard\Tests\Fixer\Annotation\RemovePropertyVariableNameDescriptionFixer\Fixture;
+
+final class SimpleAnnotation
+{
+    /**
+     * @var string
+     */
+    public $name;
+}
+
+?>

tests/Fixer/Annotation/RemovePropertyVariableNameDescriptionFixer/Fixture/skip_name_in_the_middle.php.inc

@@ -0,0 +1,11 @@
+<?php
+
+namespace Symplify\CodingStandard\Tests\Fixer\Annotation\RemovePropertyVariableNameDescriptionFixer\Fixture;
+
+final class SkipNameInTheMiddle
+{
+    /**
+     * @var string not $name my
+     */
+    public $name;
+}

tests/Fixer/Annotation/RemovePropertyVariableNameDescriptionFixer/RemovePropertyVariableNameDescriptionFixerTest.php

@@ -0,0 +1,28 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Symplify\CodingStandard\Tests\Fixer\Annotation\RemovePropertyVariableNameDescriptionFixer;
+
+use Iterator;
+use PHPUnit\Framework\Attributes\DataProvider;
+use Symplify\EasyCodingStandard\Testing\PHPUnit\AbstractCheckerTestCase;
+
+final class RemovePropertyVariableNameDescriptionFixerTest extends AbstractCheckerTestCase
+{
+    #[DataProvider('provideData')]
+    public function test(string $filePath): void
+    {
+        $this->doTestFile($filePath);
+    }
+
+    public static function provideData(): Iterator
+    {
+        return self::yieldFiles(__DIR__ . '/Fixture');
+    }
+
+    public function provideConfig(): string
+    {
+        return __DIR__ . '/config/configured_rule.php';
+    }
+}

tests/Fixer/Annotation/RemovePropertyVariableNameDescriptionFixer/config/configured_rule.php

@@ -0,0 +1,12 @@
+<?php
+
+declare(strict_types=1);
+
+use Symplify\CodingStandard\Fixer\Annotation\RemovePropertyVariableNameDescriptionFixer;
+use Symplify\EasyCodingStandard\Config\ECSConfig;
+
+return static function (ECSConfig $ecsConfig): void {
+    $ecsConfig->rules([
+        RemovePropertyVariableNameDescriptionFixer::class,
+    ]);
+};