[docblocks] Add MergePhpstanDocTagIntoNativeRector to merge @phpstan-* doc tags into native tags

rules-tests/TypeDeclarationDocblocks/Rector/Property/MergePhpstanDocTagIntoNativeRector/Fixture/method_param_and_return.php.inc

@@ -0,0 +1,39 @@
+<?php
+
+namespace Rector\Tests\TypeDeclarationDocblocks\Rector\Property\MergePhpstanDocTagIntoNativeRector\Fixture;
+
+final class MethodParamAndReturn
+{
+    /**
+     * @param array $values
+     * @phpstan-param array<int, string> $values
+     *
+     * @return array
+     * @phpstan-return array<int, string>
+     */
+    public function process($values)
+    {
+        return $values;
+    }
+}
+
+?>
+-----
+<?php
+
+namespace Rector\Tests\TypeDeclarationDocblocks\Rector\Property\MergePhpstanDocTagIntoNativeRector\Fixture;
+
+final class MethodParamAndReturn
+{
+    /**
+     * @param array<int, string> $values
+     *
+     * @return array<int, string>
+     */
+    public function process($values)
+    {
+        return $values;
+    }
+}
+
+?>

rules-tests/TypeDeclarationDocblocks/Rector/Property/MergePhpstanDocTagIntoNativeRector/Fixture/phpstan_only_var.php.inc

@@ -0,0 +1,27 @@
+<?php
+
+namespace Rector\Tests\TypeDeclarationDocblocks\Rector\Property\MergePhpstanDocTagIntoNativeRector\Fixture;
+
+final class PhpstanOnlyVar
+{
+    /**
+     * @phpstan-var Collection<int, string>
+     */
+    private $items;
+}
+
+?>
+-----
+<?php
+
+namespace Rector\Tests\TypeDeclarationDocblocks\Rector\Property\MergePhpstanDocTagIntoNativeRector\Fixture;
+
+final class PhpstanOnlyVar
+{
+    /**
+     * @var Collection<int, string>
+     */
+    private $items;
+}
+
+?>

rules-tests/TypeDeclarationDocblocks/Rector/Property/MergePhpstanDocTagIntoNativeRector/Fixture/property_var.php.inc

@@ -0,0 +1,29 @@
+<?php
+
+namespace Rector\Tests\TypeDeclarationDocblocks\Rector\Property\MergePhpstanDocTagIntoNativeRector\Fixture;
+
+final class PropertyVar
+{
+    /**
+     * @var Collection
+     *
+     * @phpstan-var Collection<int, string>
+     */
+    private $items;
+}
+
+?>
+-----
+<?php
+
+namespace Rector\Tests\TypeDeclarationDocblocks\Rector\Property\MergePhpstanDocTagIntoNativeRector\Fixture;
+
+final class PropertyVar
+{
+    /**
+     * @var Collection<int, string>
+     */
+    private $items;
+}
+
+?>

rules-tests/TypeDeclarationDocblocks/Rector/Property/MergePhpstanDocTagIntoNativeRector/Fixture/skip_no_phpstan_tag.php.inc

@@ -0,0 +1,11 @@
+<?php
+
+namespace Rector\Tests\TypeDeclarationDocblocks\Rector\Property\MergePhpstanDocTagIntoNativeRector\Fixture;
+
+final class SkipNoPhpstanTag
+{
+    /**
+     * @var Collection
+     */
+    private $items;
+}

rules-tests/TypeDeclarationDocblocks/Rector/Property/MergePhpstanDocTagIntoNativeRector/MergePhpstanDocTagIntoNativeRectorTest.php

@@ -0,0 +1,28 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Rector\Tests\TypeDeclarationDocblocks\Rector\Property\MergePhpstanDocTagIntoNativeRector;
+
+use Iterator;
+use PHPUnit\Framework\Attributes\DataProvider;
+use Rector\Testing\PHPUnit\AbstractRectorTestCase;
+
+final class MergePhpstanDocTagIntoNativeRectorTest extends AbstractRectorTestCase
+{
+    #[DataProvider('provideData')]
+    public function test(string $filePath): void
+    {
+        $this->doTestFile($filePath);
+    }
+
+    public static function provideData(): Iterator
+    {
+        return self::yieldFilesFromDirectory(__DIR__ . '/Fixture');
+    }
+
+    public function provideConfigFilePath(): string
+    {
+        return __DIR__ . '/config/configured_rule.php';
+    }
+}

rules-tests/TypeDeclarationDocblocks/Rector/Property/MergePhpstanDocTagIntoNativeRector/config/configured_rule.php

@@ -0,0 +1,9 @@
+<?php
+
+declare(strict_types=1);
+
+use Rector\Config\RectorConfig;
+use Rector\TypeDeclarationDocblocks\Rector\Property\MergePhpstanDocTagIntoNativeRector;
+
+return RectorConfig::configure()
+    ->withRules([MergePhpstanDocTagIntoNativeRector::class]);

rules/TypeDeclarationDocblocks/Rector/Property/MergePhpstanDocTagIntoNativeRector.php

@@ -0,0 +1,192 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Rector\TypeDeclarationDocblocks\Rector\Property;
+
+use PhpParser\Node;
+use PhpParser\Node\Param;
+use PhpParser\Node\Stmt\ClassConst;
+use PhpParser\Node\Stmt\ClassMethod;
+use PhpParser\Node\Stmt\Function_;
+use PhpParser\Node\Stmt\Property;
+use PHPStan\PhpDocParser\Ast\PhpDoc\ParamTagValueNode;
+use PHPStan\PhpDocParser\Ast\PhpDoc\PhpDocTagNode;
+use PHPStan\PhpDocParser\Ast\PhpDoc\PhpDocTextNode;
+use PHPStan\PhpDocParser\Ast\PhpDoc\ReturnTagValueNode;
+use PHPStan\PhpDocParser\Ast\PhpDoc\VarTagValueNode;
+use Rector\BetterPhpDocParser\PhpDocInfo\PhpDocInfo;
+use Rector\BetterPhpDocParser\PhpDocInfo\PhpDocInfoFactory;
+use Rector\Comments\NodeDocBlock\DocBlockUpdater;
+use Rector\Rector\AbstractRector;
+use Symplify\RuleDocGenerator\ValueObject\CodeSample\CodeSample;
+use Symplify\RuleDocGenerator\ValueObject\RuleDefinition;
+
+/**
+ * @see \Rector\Tests\TypeDeclarationDocblocks\Rector\Property\MergePhpstanDocTagIntoNativeRector\MergePhpstanDocTagIntoNativeRectorTest
+ */
+final class MergePhpstanDocTagIntoNativeRector extends AbstractRector
+{
+    /**
+     * @var array<string, string>
+     */
+    private const array PHPSTAN_TAG_TO_NATIVE_TAG = [
+        '@phpstan-var' => '@var',
+        '@phpstan-param' => '@param',
+        '@phpstan-return' => '@return',
+    ];
+
+    public function __construct(
+        private readonly DocBlockUpdater $docBlockUpdater,
+        private readonly PhpDocInfoFactory $phpDocInfoFactory,
+    ) {
+    }
+
+    public function getRuleDefinition(): RuleDefinition
+    {
+        return new RuleDefinition(
+            'Merge more precise @phpstan-var/@phpstan-param/@phpstan-return docblock tag into its native @var/@param/@return tag',
+            [
+                new CodeSample(
+                    <<<'CODE_SAMPLE'
+final class SomeClass
+{
+    /**
+     * @var Collection
+     *
+     * @phpstan-var Collection<int, string>
+     */
+    private $items;
+}
+CODE_SAMPLE
+                    ,
+                    <<<'CODE_SAMPLE'
+final class SomeClass
+{
+    /**
+     * @var Collection<int, string>
+     */
+    private $items;
+}
+CODE_SAMPLE
+                ),
+            ]
+        );
+    }
+
+    /**
+     * @return array<class-string<Node>>
+     */
+    public function getNodeTypes(): array
+    {
+        return [Property::class, Param::class, ClassConst::class, ClassMethod::class, Function_::class];
+    }
+
+    /**
+     * @param Property|Param|ClassConst|ClassMethod|Function_ $node
+     */
+    public function refactor(Node $node): ?Node
+    {
+        $phpDocInfo = $this->phpDocInfoFactory->createFromNode($node);
+        if (! $phpDocInfo instanceof PhpDocInfo) {
+            return null;
+        }
+
+        $phpDocNode = $phpDocInfo->getPhpDocNode();
+
+        $phpstanParamNames = [];
+        $phpstanVarNames = [];
+        $hasPhpstanReturn = false;
+
+        foreach ($phpDocNode->children as $phpDocChildNode) {
+            if (! $phpDocChildNode instanceof PhpDocTagNode) {
+                continue;
+            }
+
+            if ($phpDocChildNode->name === '@phpstan-param' && $phpDocChildNode->value instanceof ParamTagValueNode) {
+                $phpstanParamNames[] = $phpDocChildNode->value->parameterName;
+            } elseif ($phpDocChildNode->name === '@phpstan-var' && $phpDocChildNode->value instanceof VarTagValueNode) {
+                $phpstanVarNames[] = $phpDocChildNode->value->variableName;
+            } elseif ($phpDocChildNode->name === '@phpstan-return' && $phpDocChildNode->value instanceof ReturnTagValueNode) {
+                $hasPhpstanReturn = true;
+            }
+        }
+
+        if ($phpstanParamNames === [] && $phpstanVarNames === [] && ! $hasPhpstanReturn) {
+            return null;
+        }
+
+        $hasChanged = false;
+
+        foreach ($phpDocNode->children as $key => $phpDocChildNode) {
+            if (! $phpDocChildNode instanceof PhpDocTagNode) {
+                continue;
+            }
+
+            // drop the weaker native tag that the @phpstan-* variant overrules
+            if ($this->isOverruledNativeTag(
+                $phpDocChildNode,
+                $phpstanParamNames,
+                $phpstanVarNames,
+                $hasPhpstanReturn
+            )) {
+                unset($phpDocNode->children[$key]);
+                $hasChanged = true;
+                continue;
+            }
+
+            // promote the @phpstan-* tag to its native counterpart
+            $nativeTagName = self::PHPSTAN_TAG_TO_NATIVE_TAG[$phpDocChildNode->name] ?? null;
+            if ($nativeTagName !== null) {
+                $phpDocNode->children[$key] = new PhpDocTagNode($nativeTagName, $phpDocChildNode->value);
+                $hasChanged = true;
+            }
+        }
+
+        if (! $hasChanged) {
+            return null;
+        }
+
+        $phpDocNode->children = array_values($phpDocNode->children);
+
+        // drop a leading empty line left behind by a removed native tag
+        while ($phpDocNode->children !== []) {
+            $firstChildNode = $phpDocNode->children[0];
+            if ($firstChildNode instanceof PhpDocTextNode && trim($firstChildNode->text) === '') {
+                array_shift($phpDocNode->children);
+                continue;
+            }
+
+            break;
+        }
+
+        $this->docBlockUpdater->updateRefactoredNodeWithPhpDocInfo($node);
+
+        return $node;
+    }
+
+    /**
+     * @param string[] $phpstanParamNames
+     * @param string[] $phpstanVarNames
+     */
+    private function isOverruledNativeTag(
+        PhpDocTagNode $phpDocTagNode,
+        array $phpstanParamNames,
+        array $phpstanVarNames,
+        bool $hasPhpstanReturn
+    ): bool {
+        if ($phpDocTagNode->name === '@param' && $phpDocTagNode->value instanceof ParamTagValueNode) {
+            return in_array($phpDocTagNode->value->parameterName, $phpstanParamNames, true);
+        }
+
+        if ($phpDocTagNode->name === '@var' && $phpDocTagNode->value instanceof VarTagValueNode) {
+            return in_array($phpDocTagNode->value->variableName, $phpstanVarNames, true);
+        }
+
+        if ($phpDocTagNode->name === '@return' && $phpDocTagNode->value instanceof ReturnTagValueNode) {
+            return $hasPhpstanReturn;
+        }
+
+        return false;
+    }
+}

scoper.php

@@ -126,7 +126,11 @@ static function (array $ruleDefinitionMatch) use ($prefix): string {
                         "#(<<<'?(?<label>CODE_SAMPLE|SAMPLE)'?\\R)(.*?)(\\R\\s*\\k<label>)#s",
                         static function (array $codeSampleMatch) use ($prefix): string {
                             $body = str_replace($prefix . '\\', '', $codeSampleMatch[3]);
-                            $body = Strings::replace($body, '#^[ \t]*namespace ' . preg_quote($prefix, '#') . ';\R\R?#m', '');
+                            $body = Strings::replace(
+                                $body,
+                                '#^[ \t]*namespace ' . preg_quote($prefix, '#') . ';\R\R?#m',
+                                ''
+                            );
                             $body = Strings::replace($body, '#\R[ \t]*\\\\class_alias\(.*?\);$#', '');
 
                             return $codeSampleMatch[1] . $body . $codeSampleMatch[4];

tests/Scoper/ScoperPatchersTest.php

@@ -4,10 +4,10 @@
 
 namespace Rector\Tests\Scoper;
 
-use Webmozart\Assert\Assert;
 use Closure;
 use PHPUnit\Framework\TestCase;
 use Symfony\Component\Finder\Finder;
+use Webmozart\Assert\Assert;
 
 final class ScoperPatchersTest extends TestCase
 {