[type-declaration-docblocks] Add DocblockVarArrayFromGetterReturnRector

config/set/type-declaration-docblocks.php

@@ -7,6 +7,7 @@
 use Rector\TypeDeclaration\Rector\ClassMethod\AddReturnDocblockForScalarArrayFromAssignsRector;
 use Rector\TypeDeclarationDocblocks\Rector\Class_\AddReturnDocblockDataProviderRector;
 use Rector\TypeDeclarationDocblocks\Rector\Class_\ClassMethodArrayDocblockParamFromLocalCallsRector;
+use Rector\TypeDeclarationDocblocks\Rector\Class_\DocblockVarArrayFromGetterReturnRector;
 use Rector\TypeDeclarationDocblocks\Rector\Class_\DocblockVarArrayFromPropertyDefaultsRector;
 use Rector\TypeDeclarationDocblocks\Rector\Class_\DocblockVarFromParamDocblockInConstructorRector;
 use Rector\TypeDeclarationDocblocks\Rector\ClassMethod\AddParamArrayDocblockFromDataProviderRector;
@@ -24,6 +25,7 @@
         // property var
         DocblockVarFromParamDocblockInConstructorRector::class,
         DocblockVarArrayFromPropertyDefaultsRector::class,
+        DocblockVarArrayFromGetterReturnRector::class,
 
         // param
         AddParamArrayDocblockFromDimFetchAccessRector::class,

rules-tests/TypeDeclarationDocblocks/Rector/Class_/DocblockVarArrayFromGetterReturnRector/DocblockVarArrayFromGetterReturnRectorTest.php

@@ -0,0 +1,28 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Rector\Tests\TypeDeclarationDocblocks\Rector\Class_\DocblockVarArrayFromGetterReturnRector;
+
+use Iterator;
+use PHPUnit\Framework\Attributes\DataProvider;
+use Rector\Testing\PHPUnit\AbstractRectorTestCase;
+
+final class DocblockVarArrayFromGetterReturnRectorTest 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/Class_/DocblockVarArrayFromGetterReturnRector/Fixture/skip_missing_array.php.inc

@@ -0,0 +1,16 @@
+<?php
+
+namespace Rector\Tests\TypeDeclarationDocblocks\Rector\Class_\DocblockVarArrayFromGetterReturnRector\Fixture;
+
+final class SkipMissingArray
+{
+    private $names;
+
+    /**
+     * @return string[]
+     */
+    public function getNames(): array
+    {
+        return $this->names;
+    }
+}

rules-tests/TypeDeclarationDocblocks/Rector/Class_/DocblockVarArrayFromGetterReturnRector/Fixture/skip_missing_return_on_getter.php.inc

@@ -0,0 +1,13 @@
+<?php
+
+namespace Rector\Tests\TypeDeclarationDocblocks\Rector\Class_\DocblockVarArrayFromGetterReturnRector\Fixture;
+
+final class SkipMissingReturnOnGetter
+{
+    private array $names;
+
+    public function getNames(): array
+    {
+        return $this->names;
+    }
+}

rules-tests/TypeDeclarationDocblocks/Rector/Class_/DocblockVarArrayFromGetterReturnRector/Fixture/some_class.php.inc

@@ -0,0 +1,40 @@
+<?php
+
+namespace Rector\Tests\TypeDeclarationDocblocks\Rector\Class_\DocblockVarArrayFromGetterReturnRector\Fixture;
+
+final class SomeClass
+{
+    private array $names;
+
+    /**
+     * @return string[]
+     */
+    public function getNames(): array
+    {
+        return $this->names;
+    }
+}
+
+?>
+-----
+<?php
+
+namespace Rector\Tests\TypeDeclarationDocblocks\Rector\Class_\DocblockVarArrayFromGetterReturnRector\Fixture;
+
+final class SomeClass
+{
+    /**
+     * @var string[]
+     */
+    private array $names;
+
+    /**
+     * @return string[]
+     */
+    public function getNames(): array
+    {
+        return $this->names;
+    }
+}
+
+?>

rules-tests/TypeDeclarationDocblocks/Rector/Class_/DocblockVarArrayFromGetterReturnRector/config/configured_rule.php

@@ -0,0 +1,10 @@
+<?php
+
+declare(strict_types=1);
+
+use Rector\Config\RectorConfig;
+use Rector\TypeDeclarationDocblocks\Rector\Class_\DocblockVarArrayFromGetterReturnRector;
+
+return static function (RectorConfig $rectorConfig): void {
+    $rectorConfig->rule(DocblockVarArrayFromGetterReturnRector::class);
+};

rules/TypeDeclarationDocblocks/NodeFinder/PropertyGetterFinder.php

@@ -0,0 +1,69 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Rector\TypeDeclarationDocblocks\NodeFinder;
+
+use PhpParser\Node\Expr\PropertyFetch;
+use PhpParser\Node\Expr\Variable;
+use PhpParser\Node\Stmt\Class_;
+use PhpParser\Node\Stmt\ClassMethod;
+use PhpParser\Node\Stmt\Property;
+use PhpParser\Node\Stmt\Return_;
+use Rector\NodeNameResolver\NodeNameResolver;
+
+final readonly class PropertyGetterFinder
+{
+    public function __construct(
+        private NodeNameResolver $nodeNameResolver
+    ) {
+    }
+
+    public function find(Property $property, Class_ $class): ?ClassMethod
+    {
+        $propertyName = $this->nodeNameResolver->getName($property);
+        foreach ($class->getMethods() as $classMethod) {
+            if ($classMethod->isMagic()) {
+                continue;
+            }
+
+            if ($classMethod->isAbstract()) {
+                continue;
+            }
+
+            if ($classMethod->stmts === null) {
+                continue;
+            }
+
+            if (count($classMethod->stmts) !== 1) {
+                continue;
+            }
+
+            $onlyStmt = $classMethod->stmts[0];
+            if (! $onlyStmt instanceof Return_) {
+                continue;
+            }
+
+            if (! $onlyStmt->expr instanceof PropertyFetch) {
+                continue;
+            }
+
+            $propertyFetch = $onlyStmt->expr;
+            if (! $propertyFetch->var instanceof Variable) {
+                continue;
+            }
+
+            if (! $this->nodeNameResolver->isName($propertyFetch->var, 'this')) {
+                continue;
+            }
+
+            if (! $this->nodeNameResolver->isName($propertyFetch->name, $propertyName)) {
+                continue;
+            }
+
+            return $classMethod;
+        }
+
+        return null;
+    }
+}

rules/TypeDeclarationDocblocks/Rector/Class_/DocblockVarArrayFromGetterReturnRector.php

@@ -0,0 +1,131 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Rector\TypeDeclarationDocblocks\Rector\Class_;
+
+use PhpParser\Node;
+use PhpParser\Node\Identifier;
+use PhpParser\Node\Stmt\Class_;
+use PhpParser\Node\Stmt\ClassMethod;
+use PHPStan\PhpDocParser\Ast\PhpDoc\ReturnTagValueNode;
+use PHPStan\PhpDocParser\Ast\PhpDoc\VarTagValueNode;
+use Rector\BetterPhpDocParser\PhpDocInfo\PhpDocInfoFactory;
+use Rector\Comments\NodeDocBlock\DocBlockUpdater;
+use Rector\Rector\AbstractRector;
+use Rector\TypeDeclarationDocblocks\NodeFinder\PropertyGetterFinder;
+use Symplify\RuleDocGenerator\ValueObject\CodeSample\CodeSample;
+use Symplify\RuleDocGenerator\ValueObject\RuleDefinition;
+
+/**
+ * @see \Rector\Tests\TypeDeclarationDocblocks\Rector\Class_\DocblockVarArrayFromGetterReturnRector\DocblockVarArrayFromGetterReturnRectorTest
+ */
+final class DocblockVarArrayFromGetterReturnRector extends AbstractRector
+{
+    public function __construct(
+        private readonly PhpDocInfoFactory $phpDocInfoFactory,
+        private readonly PropertyGetterFinder $propertyGetterFinder,
+        private readonly DocBlockUpdater $docBlockUpdater
+    ) {
+    }
+
+    public function getNodeTypes(): array
+    {
+        return [Class_::class];
+    }
+
+    public function getRuleDefinition(): RuleDefinition
+    {
+        return new RuleDefinition('Add @var array property docblock from its getter @return', [
+            new CodeSample(
+                <<<'CODE_SAMPLE'
+class SomeClass
+{
+    private array $items;
+
+    /**
+     * @return int[]
+     */
+    public function getItems(): array
+    {
+        return $this->items;
+    }
+}
+CODE_SAMPLE
+                ,
+                <<<'CODE_SAMPLE'
+class SomeClass
+{
+    /**
+     * @var int[]
+     */
+    private array $items;
+
+    /**
+     * @return int[]
+     */
+    public function getItems(): array
+    {
+        return $this->items;
+    }
+}
+CODE_SAMPLE
+            ),
+        ]);
+    }
+
+    /**
+     * @param Class_ $node
+     */
+    public function refactor(Node $node): ?Node
+    {
+        $hasChanged = false;
+
+        foreach ($node->getProperties() as $property) {
+            // property type must be known
+            if (! $property->type instanceof Identifier) {
+                continue;
+            }
+
+            if (! $this->isName($property->type, 'array')) {
+                continue;
+            }
+
+            if (count($property->props) > 1) {
+                continue;
+            }
+
+            $propertyPhpDocInfo = $this->phpDocInfoFactory->createFromNodeOrEmpty($property);
+
+            // type is already known, skip it
+            if ($propertyPhpDocInfo->getVarTagValueNode() instanceof VarTagValueNode) {
+                continue;
+            }
+
+            $propertyGetterMethod = $this->propertyGetterFinder->find($property, $node);
+            if (! $propertyGetterMethod instanceof ClassMethod) {
+                continue;
+            }
+
+            $classMethodDocInfo = $this->phpDocInfoFactory->createFromNodeOrEmpty($propertyGetterMethod);
+            $returnTagValueNode = $classMethodDocInfo->getReturnTagValue();
+            if (! $returnTagValueNode instanceof ReturnTagValueNode) {
+                continue;
+            }
+
+            $varTagValeNode = new VarTagValueNode($returnTagValueNode->type, '', '');
+
+            // find matching getter and its @return docblock
+            $propertyPhpDocInfo->addTagValueNode($varTagValeNode);
+            $this->docBlockUpdater->updateRefactoredNodeWithPhpDocInfo($property);
+
+            $hasChanged = true;
+        }
+
+        if (! $hasChanged) {
+            return null;
+        }
+
+        return $node;
+    }
+}