[type-declaration-docblocks] Re-use nested array types as deep as possible in TypeNormalizer

rules-tests/TypeDeclarationDocblocks/Rector/Class_/AddReturnDocblockDataProviderRector/Fixture/yield_provider_iterable.php.inc

@@ -0,0 +1,66 @@
+<?php
+
+namespace Rector\Tests\TypeDeclarationDocblocks\Rector\Class_\AddReturnDocblockDataProviderRector\Fixture;
+
+use PHPUnit\Framework\Attributes\DataProvider;
+use PHPUnit\Framework\TestCase;
+
+final class YieldProviderIterable extends TestCase
+{
+    #[DataProvider('provideData')]
+    public function testSomething()
+    {
+    }
+
+    public static function provideData()
+    {
+        yield [
+            [
+                'one' => [1, 2],
+                'two' => ['three'],
+            ],
+        ];
+        yield [
+            [
+                'four' => 'five',
+            ],
+        ];
+    }
+}
+
+?>
+-----
+<?php
+
+namespace Rector\Tests\TypeDeclarationDocblocks\Rector\Class_\AddReturnDocblockDataProviderRector\Fixture;
+
+use PHPUnit\Framework\Attributes\DataProvider;
+use PHPUnit\Framework\TestCase;
+
+final class YieldProviderIterable extends TestCase
+{
+    #[DataProvider('provideData')]
+    public function testSomething()
+    {
+    }
+
+    /**
+     * @return \Iterator<array<array<int, array<string, mixed>>, mixed>>
+     */
+    public static function provideData()
+    {
+        yield [
+            [
+                'one' => [1, 2],
+                'two' => ['three'],
+            ],
+        ];
+        yield [
+            [
+                'four' => 'five',
+            ],
+        ];
+    }
+}
+
+?>

rules/Privatization/TypeManipulator/ArrayTypeLeastCommonDenominatorResolver.php

@@ -0,0 +1,105 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Rector\Privatization\TypeManipulator;
+
+use PHPStan\Type\ArrayType;
+use PHPStan\Type\Constant\ConstantArrayType;
+use PHPStan\Type\MixedType;
+use PHPStan\Type\NeverType;
+use PHPStan\Type\Type;
+use PHPStan\Type\TypeCombinator;
+use PHPStan\Type\VerbosityLevel;
+
+/**
+ * Made with GPT-5
+ * @see https://chatgpt.com/share/68d2c183-7708-800a-848b-c63822c4625a
+ */
+final class ArrayTypeLeastCommonDenominatorResolver
+{
+    /**
+     * Return the deepest common "array structure" shared by all $types.
+     * - Keeps exact keys when all are ConstantArrayType with the same keys
+     * - Keeps generic key type (int|string) when consistent
+     * - Falls back to mixed at the first conflicting depth
+     */
+    public function sharedArrayStructure(Type ...$types): Type
+    {
+        if ($types === []) {
+            return new MixedType();
+        }
+
+        // If any is not an ArrayType, we cannot descend further.
+        foreach ($types as $type) {
+            if (! $type instanceof ArrayType) {
+                return new MixedType();
+            }
+        }
+
+        // If all are ConstantArrayType and have the *same* ordered key list -> preserve shape.
+        $allConstantArrayTypes = array_reduce($types, fn ($c, $t): bool => $c && $t instanceof ConstantArrayType, true);
+        if ($allConstantArrayTypes) {
+            /** @var ConstantArrayType[] $consts */
+            $consts = $types;
+
+            // Compare key sets (by stringified key types)
+            $firstKeys = array_map(
+                fn (Type $type): string => $type->describe(VerbosityLevel::typeOnly()),
+                $consts[0]->getKeyTypes()
+            );
+            foreach ($consts as $c) {
+                $keys = array_map(
+                    fn (Type $type): string => $type->describe(VerbosityLevel::typeOnly()),
+                    $c->getKeyTypes()
+                );
+                if ($keys !== $firstKeys) {
+                    $allConstantArrayTypes = false;
+                    break;
+                }
+            }
+
+            if ($allConstantArrayTypes) {
+                $resultKeyTypes = $consts[0]->getKeyTypes();
+                $valueColumns = [];
+                foreach ($consts as $const) {
+                    $valueColumns[] = $const->getValueTypes();
+                }
+
+                $resultValueTypes = [];
+                foreach (array_keys($resultKeyTypes) as $i) {
+                    $col = array_column($valueColumns, $i);
+                    $resultValueTypes[] = $this->sharedArrayStructure(...$col);
+                }
+
+                return new ConstantArrayType($resultKeyTypes, $resultValueTypes);
+            }
+        }
+
+        // Generic ArrayType path: reconcile key type + recurse into item types
+        /** @var ArrayType[] $types */
+        /** @var ArrayType[] $arrayTypes */
+        $arrayTypes = $types;
+
+        // Try to keep a compatible key type (intersection; fall back to mixed if impossible)
+        $firstArrayType = array_shift($arrayTypes);
+        if (! $firstArrayType instanceof ArrayType) {
+            return new MixedType();
+        }
+
+        $keyType = $firstArrayType->getKeyType();
+        foreach ($arrayTypes as $arr) {
+            $keyType = TypeCombinator::intersect($keyType, $arr->getKeyType());
+        }
+
+        if ($keyType instanceof NeverType) {
+            $keyType = new MixedType(); // incompatible key types
+        }
+
+        // Recurse on item types; if mixed is returned, that’s our stop depth.
+        $itemTypes = array_map(fn (ArrayType $arrayType): Type => $arrayType->getItemType(), $types);
+        $itemType = $this->sharedArrayStructure(...$itemTypes);
+
+        return new ArrayType($keyType, $itemType);
+    }
+}

rules/Privatization/TypeManipulator/TypeNormalizer.php

@@ -31,7 +31,8 @@
 
     public function __construct(
         private TypeFactory $typeFactory,
-        private StaticTypeMapper $staticTypeMapper
+        private StaticTypeMapper $staticTypeMapper,
+        private ArrayTypeLeastCommonDenominatorResolver $arrayTypeLeastCommonDenominatorResolver
     ) {
 
     }
@@ -107,6 +108,11 @@ public function generalizeConstantTypes(Type $type): Type
 
                     // too long
                     if (strlen((string) $unionedDocType) > self::MAX_PRINTED_UNION_DOC_LENGHT) {
+                        $alwaysKnownArrayType = $this->narrowToAlwaysKnownArrayType($generalizedUnionType);
+                        if ($alwaysKnownArrayType instanceof ArrayType) {
+                            return $alwaysKnownArrayType;
+                        }
+
                         return new MixedType();
                     }
 
@@ -145,4 +151,15 @@ private function isImplicitNumberedListKeyType(ConstantArrayType $constantArrayT
 
         return true;
     }
+
+    private function narrowToAlwaysKnownArrayType(UnionType $unionType): ?ArrayType
+    {
+        // always an array?
+        if (count($unionType->getArrays()) !== count($unionType->getTypes())) {
+            return null;
+        }
+
+        $arrayUniqueKeyType = $this->arrayTypeLeastCommonDenominatorResolver->sharedArrayStructure(...$unionType->getTypes());
+        return new ArrayType($arrayUniqueKeyType, new MixedType());
+    }
 }