Override existing dummy @return array with more precise one

rules-tests/TypeDeclarationDocblocks/Rector/ClassMethod/AddReturnDocblockForArrayDimAssignedObjectRector/Fixture/override_dummy_array.php.inc

@@ -0,0 +1,47 @@
+<?php
+
+namespace Rector\Tests\TypeDeclarationDocblocks\Rector\ClassMethod\AddReturnDocblockForArrayDimAssignedObjectRector\Fixture;
+
+use Rector\Tests\TypeDeclarationDocblocks\Rector\ClassMethod\AddReturnDocblockForArrayDimAssignedObjectRector\Source\SomeItem;
+
+final class OverrideDummyArray
+{
+    /**
+     * @return array
+     */
+    public function provide(array $keys): array
+    {
+        $items = [];
+        foreach ($keys as $key) {
+            $items[] = new SomeItem($key);
+        }
+
+        return $items;
+    }
+}
+
+?>
+-----
+<?php
+
+namespace Rector\Tests\TypeDeclarationDocblocks\Rector\ClassMethod\AddReturnDocblockForArrayDimAssignedObjectRector\Fixture;
+
+use Rector\Tests\TypeDeclarationDocblocks\Rector\ClassMethod\AddReturnDocblockForArrayDimAssignedObjectRector\Source\SomeItem;
+
+final class OverrideDummyArray
+{
+    /**
+     * @return \Rector\Tests\TypeDeclarationDocblocks\Rector\ClassMethod\AddReturnDocblockForArrayDimAssignedObjectRector\Source\SomeItem[]
+     */
+    public function provide(array $keys): array
+    {
+        $items = [];
+        foreach ($keys as $key) {
+            $items[] = new SomeItem($key);
+        }
+
+        return $items;
+    }
+}
+
+?>

rules-tests/TypeDeclarationDocblocks/Rector/ClassMethod/AddReturnDocblockForCommonObjectDenominatorRector/Fixture/override_dummy_array.php.inc

@@ -0,0 +1,45 @@
+<?php
+
+namespace Rector\Tests\TypeDeclarationDocblocks\Rector\ClassMethod\AddReturnDocblockForCommonObjectDenominatorRector\Fixture;
+
+use Rector\Tests\TypeDeclarationDocblocks\Rector\ClassMethod\AddReturnDocblockForCommonObjectDenominatorRector\Source\FirstExtension;
+use Rector\Tests\TypeDeclarationDocblocks\Rector\ClassMethod\AddReturnDocblockForCommonObjectDenominatorRector\Source\SecondExtension;
+
+final class OverrideDummyArray
+{
+    /**
+     * @return array
+     */
+    public function getExtensions(): array
+    {
+        return [
+            new FirstExtension(),
+            new SecondExtension()
+        ];
+    }
+}
+
+?>
+-----
+<?php
+
+namespace Rector\Tests\TypeDeclarationDocblocks\Rector\ClassMethod\AddReturnDocblockForCommonObjectDenominatorRector\Fixture;
+
+use Rector\Tests\TypeDeclarationDocblocks\Rector\ClassMethod\AddReturnDocblockForCommonObjectDenominatorRector\Source\FirstExtension;
+use Rector\Tests\TypeDeclarationDocblocks\Rector\ClassMethod\AddReturnDocblockForCommonObjectDenominatorRector\Source\SecondExtension;
+
+final class OverrideDummyArray
+{
+    /**
+     * @return \Rector\Tests\TypeDeclarationDocblocks\Rector\ClassMethod\AddReturnDocblockForCommonObjectDenominatorRector\Source\Contract\ExtensionInterface[]
+     */
+    public function getExtensions(): array
+    {
+        return [
+            new FirstExtension(),
+            new SecondExtension()
+        ];
+    }
+}
+
+?>

rules-tests/TypeDeclarationDocblocks/Rector/ClassMethod/AddReturnDocblockForJsonArrayRector/Fixture/override_dummy_array.php.inc

@@ -0,0 +1,37 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Rector\Tests\TypeDeclarationDocblocks\Rector\ClassMethod\AddReturnDocblockForJsonArrayRector\Fixture;
+
+final class OverrideDummyArray
+{
+    /**
+     * @return array
+     */
+    public function provide(string $contents): array
+    {
+        return json_decode($contents, true);
+    }
+}
+
+?>
+-----
+<?php
+
+declare(strict_types=1);
+
+namespace Rector\Tests\TypeDeclarationDocblocks\Rector\ClassMethod\AddReturnDocblockForJsonArrayRector\Fixture;
+
+final class OverrideDummyArray
+{
+    /**
+     * @return array<string, mixed>
+     */
+    public function provide(string $contents): array
+    {
+        return json_decode($contents, true);
+    }
+}
+
+?>

rules-tests/TypeDeclarationDocblocks/Rector/ClassMethod/DocblockGetterReturnArrayFromPropertyDocblockVarRector/Fixture/override_dummy_array.php.inc

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

rules-tests/TypeDeclarationDocblocks/Rector/ClassMethod/DocblockReturnArrayFromDirectArrayInstanceRector/Fixture/override_bare_array.php.inc

@@ -0,0 +1,33 @@
+<?php
+
+namespace Rector\Tests\TypeDeclarationDocblocks\Rector\ClassMethod\DocblockReturnArrayFromDirectArrayInstanceRector\Fixture;
+
+/**
+ * @return array
+ */
+function overrideBareArray()
+{
+    return [
+        'first'  => [true],
+        'second' => [false],
+    ];
+}
+
+?>
+-----
+<?php
+
+namespace Rector\Tests\TypeDeclarationDocblocks\Rector\ClassMethod\DocblockReturnArrayFromDirectArrayInstanceRector\Fixture;
+
+/**
+ * @return array<string, bool[]>
+ */
+function overrideBareArray()
+{
+    return [
+        'first'  => [true],
+        'second' => [false],
+    ];
+}
+
+?>

rules/TypeDeclarationDocblocks/Rector/ClassMethod/AddReturnDocblockForArrayDimAssignedObjectRector.php

@@ -23,8 +23,10 @@
 use Rector\BetterPhpDocParser\PhpDocInfo\PhpDocInfoFactory;
 use Rector\BetterPhpDocParser\PhpDocManipulator\PhpDocTypeChanger;
 use Rector\Rector\AbstractRector;
+use Rector\StaticTypeMapper\StaticTypeMapper;
 use Rector\StaticTypeMapper\ValueObject\Type\NonExistingObjectType;
 use Rector\TypeDeclarationDocblocks\NodeFinder\ReturnNodeFinder;
+use Rector\TypeDeclarationDocblocks\TagNodeAnalyzer\UsefulArrayTagNodeAnalyzer;
 use Symplify\RuleDocGenerator\ValueObject\CodeSample\CodeSample;
 use Symplify\RuleDocGenerator\ValueObject\RuleDefinition;
 
@@ -37,6 +39,8 @@ public function __construct(
         private readonly PhpDocInfoFactory $phpDocInfoFactory,
         private readonly ReturnNodeFinder $returnNodeFinder,
         private readonly PhpDocTypeChanger $phpDocTypeChanger,
+        private readonly StaticTypeMapper $staticTypeMapper,
+        private readonly UsefulArrayTagNodeAnalyzer $usefulArrayTagNodeAnalyzer
     ) {
     }
 
@@ -101,7 +105,11 @@ public function refactor(Node $node): ?Node
         $phpDocInfo = $this->phpDocInfoFactory->createFromNodeOrEmpty($node);
         $returnType = $phpDocInfo->getReturnType();
 
-        if (! $returnType instanceof MixedType || $returnType->isExplicitMixed()) {
+        if ($returnType instanceof ArrayType && ! $returnType->getItemType() instanceof MixedType) {
+            return null;
+        }
+
+        if ($this->usefulArrayTagNodeAnalyzer->isUsefulArrayTag($phpDocInfo->getReturnTagValue())) {
             return null;
         }
 
@@ -124,10 +132,49 @@ public function refactor(Node $node): ?Node
             return null;
         }
 
+        if ($this->isVariableExclusivelyArrayDimAssigned($node, $returnedVariableName) === false) {
+            return null;
+        }
+
+        $arrayObjectType = $this->matchArrayObjectType($returnedType);
+        if (! $arrayObjectType instanceof ObjectType) {
+            return null;
+        }
+
+        $objectTypeArrayType = new ArrayType(new MixedType(), $arrayObjectType);
+        $returnTypeNode = $this->staticTypeMapper->mapPHPStanTypeToPHPStanPhpDocTypeNode($objectTypeArrayType);
+        $this->phpDocTypeChanger->changeReturnTypeNode($node, $phpDocInfo, $returnTypeNode);
+
+        return $node;
+    }
+
+    private function matchArrayObjectType(Type $returnedType): ?Type
+    {
+        if ($returnedType instanceof IntersectionType) {
+            foreach ($returnedType->getTypes() as $intersectionedType) {
+                if ($intersectionedType instanceof AccessoryArrayListType) {
+                    continue;
+                }
+
+                if ($intersectionedType instanceof ArrayType && $intersectionedType->getItemType() instanceof ObjectType) {
+                    return $intersectionedType->getItemType();
+                }
+
+                return null;
+            }
+        }
+
+        return null;
+    }
+
+    private function isVariableExclusivelyArrayDimAssigned(
+        ClassMethod|Function_ $functionLike,
+        string $variableName
+    ): bool {
         $isVariableExclusivelyArrayDimAssigned = true;
 
-        $this->traverseNodesWithCallable((array) $node->stmts, function ($node) use (
-            $returnedVariableName,
+        $this->traverseNodesWithCallable((array) $functionLike->stmts, function ($node) use (
+            $variableName,
             &$isVariableExclusivelyArrayDimAssigned
         ): ?int {
             if ($node instanceof Assign) {
@@ -139,7 +186,7 @@ public function refactor(Node $node): ?Node
                         return null;
                     }
 
-                    if ($this->isName($arrayDimFetch->var, $returnedVariableName)) {
+                    if ($this->isName($arrayDimFetch->var, $variableName)) {
                         if ($arrayDimFetch->dim instanceof Expr) {
                             $isVariableExclusivelyArrayDimAssigned = false;
                         }
@@ -160,7 +207,7 @@ public function refactor(Node $node): ?Node
 
                 if ($node->var instanceof Variable && $this->isName(
                     $node->var,
-                    $returnedVariableName
+                    $variableName
                 ) && $node->expr instanceof Array_) {
                     if ($node->expr->items === []) {
                         // ignore empty array assignment
@@ -172,57 +219,21 @@ public function refactor(Node $node): ?Node
             }
 
             if ($node instanceof Return_ && $node->expr instanceof Variable) {
-                if ($this->isName($node->expr, $returnedVariableName)) {
+                if ($this->isName($node->expr, $variableName)) {
                     // ignore lower value
                     return NodeVisitor::DONT_TRAVERSE_CURRENT_AND_CHILDREN;
                 }
 
                 $isVariableExclusivelyArrayDimAssigned = false;
             }
 
-            if ($node instanceof Variable && $this->isName($node, $returnedVariableName)) {
+            if ($node instanceof Variable && $this->isName($node, $variableName)) {
                 $isVariableExclusivelyArrayDimAssigned = false;
             }
 
             return null;
         });
 
-        if ($isVariableExclusivelyArrayDimAssigned === false) {
-            return null;
-        }
-
-        $arrayObjectType = $this->matchArrayObjectType($returnedType);
-        if (! $arrayObjectType instanceof ObjectType) {
-            return null;
-        }
-
-        //$arrayReturnDocType = $this->staticTypeMapper->mapPHPStanTypeToPHPStanPhpDocTypeNode($arrayObjectType);
-
-        $objectTypeArrayType = new ArrayType(new MixedType(), $arrayObjectType);
-        $hasChanged = $this->phpDocTypeChanger->changeReturnType($node, $phpDocInfo, $objectTypeArrayType);
-        if (! $hasChanged) {
-            return null;
-        }
-
-        return $node;
-    }
-
-    private function matchArrayObjectType(Type $returnedType): ?Type
-    {
-        if ($returnedType instanceof IntersectionType) {
-            foreach ($returnedType->getTypes() as $intersectionedType) {
-                if ($intersectionedType instanceof AccessoryArrayListType) {
-                    continue;
-                }
-
-                if ($intersectionedType instanceof ArrayType && $intersectionedType->getItemType() instanceof ObjectType) {
-                    return $intersectionedType->getItemType();
-                }
-
-                return null;
-            }
-        }
-
-        return null;
+        return $isVariableExclusivelyArrayDimAssigned;
     }
 }

rules/TypeDeclarationDocblocks/Rector/ClassMethod/AddReturnDocblockForCommonObjectDenominatorRector.php

@@ -110,7 +110,7 @@ public function refactor(Node $node): ?Node
         $phpDocInfo = $this->phpDocInfoFactory->createFromNodeOrEmpty($node);
         $returnType = $phpDocInfo->getReturnType();
 
-        if (! $returnType instanceof MixedType || $returnType->isExplicitMixed()) {
+        if ($returnType instanceof ArrayType && ! $returnType->getItemType() instanceof MixedType) {
             return null;
         }
 
@@ -175,6 +175,7 @@ public function refactor(Node $node): ?Node
             $this->resolveKeyType($returnedType),
             new FullyQualifiedObjectType($firstSharedType)
         );
+
         $hasChanged = $this->phpDocTypeChanger->changeReturnType($node, $phpDocInfo, $objectTypeArrayType);
         if (! $hasChanged) {
             return null;