[type-declaration-docblocks] Add AddParamArrayDocblockFromAssignsParamToParamReferenceRector

rules-tests/TypeDeclarationDocblocks/Rector/ClassMethod/AddParamArrayDocblockFromAssignsParamToParamReferenceRector/AddParamArrayDocblockFromAssignsParamToParamReferenceRectorTest.php

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

@@ -0,0 +1,11 @@
+<?php
+
+namespace Rector\Tests\TypeDeclarationDocblocks\Rector\ClassMethod\AddParamArrayDocblockFromAssignsParamToParamReferenceRector\Fixture;
+
+final class SkipDimFetchAssingDeep
+{
+    public function run(array &$items)
+    {
+        $items[][] = 'John';
+    }
+}

rules-tests/TypeDeclarationDocblocks/Rector/ClassMethod/AddParamArrayDocblockFromAssignsParamToParamReferenceRector/Fixture/skip_multiple_assigns.php.inc

@@ -0,0 +1,12 @@
+<?php
+
+namespace Rector\Tests\TypeDeclarationDocblocks\Rector\ClassMethod\AddParamArrayDocblockFromAssignsParamToParamReferenceRector\Fixture;
+
+final class SkipMultipleAssigns
+{
+    public function run(array &$items)
+    {
+        $items[] = 'John';
+        $items[] = 1000;
+    }
+}

rules-tests/TypeDeclarationDocblocks/Rector/ClassMethod/AddParamArrayDocblockFromAssignsParamToParamReferenceRector/Fixture/some_class.php.inc

@@ -0,0 +1,30 @@
+<?php
+
+namespace Rector\Tests\TypeDeclarationDocblocks\Rector\ClassMethod\AddParamArrayDocblockFromAssignsParamToParamReferenceRector\Fixture;
+
+final class SomeClass
+{
+    public function run(array &$items)
+    {
+        $items[] = 'John';
+    }
+}
+
+?>
+-----
+<?php
+
+namespace Rector\Tests\TypeDeclarationDocblocks\Rector\ClassMethod\AddParamArrayDocblockFromAssignsParamToParamReferenceRector\Fixture;
+
+final class SomeClass
+{
+    /**
+     * @param string[] $items
+     */
+    public function run(array &$items)
+    {
+        $items[] = 'John';
+    }
+}
+
+?>

rules-tests/TypeDeclarationDocblocks/Rector/ClassMethod/AddParamArrayDocblockFromAssignsParamToParamReferenceRector/config/configured_rule.php

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

rules/TypeDeclarationDocblocks/NodeFinder/DimFetchFinder.php → rules/TypeDeclarationDocblocks/NodeFinder/ArrayDimFetchFinder.php

@@ -5,19 +5,50 @@
 namespace Rector\TypeDeclarationDocblocks\NodeFinder;
 
 use PhpParser\Node;
+use PhpParser\Node\Expr;
 use PhpParser\Node\Expr\ArrayDimFetch;
+use PhpParser\Node\Expr\Assign;
 use PhpParser\Node\Expr\Variable;
+use PhpParser\Node\Stmt\ClassMethod;
 use Rector\NodeNameResolver\NodeNameResolver;
 use Rector\PhpParser\Node\BetterNodeFinder;
 
-final readonly class DimFetchFinder
+final readonly class ArrayDimFetchFinder
 {
     public function __construct(
         private BetterNodeFinder $betterNodeFinder,
         private NodeNameResolver $nodeNameResolver
     ) {
     }
 
+    /**
+     * @return Expr[]
+     */
+    public function findDimFetchAssignToVariableName(ClassMethod $classMethod, string $variableName): array
+    {
+        $assigns = $this->betterNodeFinder->findInstancesOfScoped((array) $classMethod->stmts, Assign::class);
+
+        $exprs = [];
+        foreach ($assigns as $assign) {
+            if (! $assign->var instanceof ArrayDimFetch) {
+                continue;
+            }
+
+            $arrayDimFetch = $assign->var;
+            if (! $arrayDimFetch->var instanceof Variable) {
+                continue;
+            }
+
+            if (! $this->nodeNameResolver->isName($arrayDimFetch->var, $variableName)) {
+                continue;
+            }
+
+            $exprs[] = $assign->expr;
+        }
+
+        return $exprs;
+    }
+
     /**
      * @return ArrayDimFetch[]
      */

rules/TypeDeclarationDocblocks/Rector/ClassMethod/AddParamArrayDocblockFromAssignsParamToParamReferenceRector.php

@@ -0,0 +1,138 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Rector\TypeDeclarationDocblocks\Rector\ClassMethod;
+
+use PhpParser\Node;
+use PhpParser\Node\Identifier;
+use PhpParser\Node\Stmt\ClassMethod;
+use PHPStan\PhpDocParser\Ast\PhpDoc\ParamTagValueNode;
+use PHPStan\Type\ArrayType;
+use PHPStan\Type\MixedType;
+use Rector\BetterPhpDocParser\PhpDocInfo\PhpDocInfoFactory;
+use Rector\Rector\AbstractRector;
+use Rector\TypeDeclarationDocblocks\NodeDocblockTypeDecorator;
+use Rector\TypeDeclarationDocblocks\NodeFinder\ArrayDimFetchFinder;
+use Symplify\RuleDocGenerator\ValueObject\CodeSample\CodeSample;
+use Symplify\RuleDocGenerator\ValueObject\RuleDefinition;
+
+/**
+ * @see \Rector\Tests\TypeDeclarationDocblocks\Rector\ClassMethod\AddParamArrayDocblockFromAssignsParamToParamReferenceRector\AddParamArrayDocblockFromAssignsParamToParamReferenceRectorTest
+ */
+final class AddParamArrayDocblockFromAssignsParamToParamReferenceRector extends AbstractRector
+{
+    public function __construct(
+        private readonly PhpDocInfoFactory $phpDocInfoFactory,
+        private readonly ArrayDimFetchFinder $arrayDimFetchFinder,
+        private readonly NodeDocblockTypeDecorator $nodeDocblockTypeDecorator,
+    ) {
+    }
+
+    public function getRuleDefinition(): RuleDefinition
+    {
+        return new RuleDefinition(
+            'Add @param docblock array type, based on type to assigned parameter reference',
+            [
+                new CodeSample(
+                    <<<'CODE_SAMPLE'
+final class SomeClass
+{
+    public function run(array &$names): void
+    {
+        $names[] = 'John';
+    }
+}
+CODE_SAMPLE
+                    ,
+                    <<<'CODE_SAMPLE'
+final class SomeClass
+{
+    /**
+     * @param string[] $names
+     */
+    public function run(array &$names): void
+    {
+        $names[] = 'John';
+    }
+}
+CODE_SAMPLE
+                ),
+
+            ]
+        );
+    }
+
+    /**
+     * @return array<class-string<Node>>
+     */
+    public function getNodeTypes(): array
+    {
+        return [ClassMethod::class];
+    }
+
+    /**
+     * @param ClassMethod $node
+     */
+    public function refactor(Node $node): ?Node
+    {
+        $hasChanged = false;
+
+        if ($node->getParams() === []) {
+            return null;
+        }
+
+        $phpDocInfo = $this->phpDocInfoFactory->createFromNodeOrEmpty($node);
+
+        foreach ($node->getParams() as $param) {
+            if (! $param->byRef) {
+                continue;
+            }
+
+            if (! $param->type instanceof Identifier) {
+                continue;
+            }
+
+            if (! $this->isName($param->type, 'array')) {
+                continue;
+            }
+
+            $paramName = $this->getName($param);
+            $paramTagValueNode = $phpDocInfo->getParamTagValueByName($paramName);
+
+            // already defined, lets skip it
+            if ($paramTagValueNode instanceof ParamTagValueNode) {
+                continue;
+            }
+
+            $exprs = $this->arrayDimFetchFinder->findDimFetchAssignToVariableName($node, $paramName);
+
+            // to kick off with one
+            if (count($exprs) !== 1) {
+                continue;
+            }
+
+            $assignedExprType = $this->getType($exprs[0]);
+            $iterableType = new ArrayType(new MixedType(), $assignedExprType);
+
+            $hasParamTypeChanged = $this->nodeDocblockTypeDecorator->decorateGenericIterableParamType(
+                $iterableType,
+                $phpDocInfo,
+                $node,
+                $paramName
+            );
+
+            if (! $hasParamTypeChanged) {
+                continue;
+            }
+
+            $hasChanged = true;
+        }
+
+        if (! $hasChanged) {
+            return null;
+        }
+
+        return $node;
+    }
+}

rules/TypeDeclarationDocblocks/Rector/ClassMethod/AddParamArrayDocblockFromDimFetchAccessRector.php

@@ -15,7 +15,7 @@
 use Rector\BetterPhpDocParser\PhpDocInfo\PhpDocInfoFactory;
 use Rector\Comments\NodeDocBlock\DocBlockUpdater;
 use Rector\Rector\AbstractRector;
-use Rector\TypeDeclarationDocblocks\NodeFinder\DimFetchFinder;
+use Rector\TypeDeclarationDocblocks\NodeFinder\ArrayDimFetchFinder;
 use Symplify\RuleDocGenerator\ValueObject\CodeSample\CodeSample;
 use Symplify\RuleDocGenerator\ValueObject\RuleDefinition;
 
@@ -26,7 +26,7 @@ final class AddParamArrayDocblockFromDimFetchAccessRector extends AbstractRector
 {
     public function __construct(
         private readonly PhpDocInfoFactory $phpDocInfoFactory,
-        private readonly DimFetchFinder $dimFetchFinder,
+        private readonly ArrayDimFetchFinder $arrayDimFetchFinder,
         private readonly DocBlockUpdater $docBlockUpdater
     ) {
     }
@@ -109,7 +109,7 @@ public function refactor(Node $node): ?Node
                 continue;
             }
 
-            $dimFetches = $this->dimFetchFinder->findByVariableName($node, $paramName);
+            $dimFetches = $this->arrayDimFetchFinder->findByVariableName($node, $paramName);
             if ($dimFetches === []) {
                 continue;
             }