Preserve integer range bounds for sealed array values in loop generalization

When `generalizeType` merges two sealed constant-array shapes on the
fall-through ArrayType path, it kept the literal key union (so loop-bounded
counter keys stayed within range) but still recursed into `generalizeType`
for the values — which applies the loop-widening heuristic and widened e.g.
`int<0, 5>` to `int<0, max>`. Keep the literal value union too (with a
fallback to generalization when it outgrows the shape limit), so values like
loop-built `array{int<0, 5>, int<1, 6>}` keep their bounds.

Scoped to sealed shapes so the general `generalize()` widening contract for
legacy arrays (ScopeTest::testGeneralize) is unaffected.

Refs phpstan/phpstan#13647
Refs phpstan/phpstan#13637

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: ondrejmirtes

src/Analyser/MutatingScope.php

@@ -4264,14 +4264,15 @@ private function generalizeType(Type $a, Type $b, int $depth): Type
 
 					$resultTypes[] = $resultArrayBuilder->getArray();
 				} else {
-					// Both inputs are sealed constant array shapes — their
-					// key sets are finite by construction. When taking the
-					// fall-through ArrayType path we still recurse into
-					// `generalizeType` for the iterable key, which would
-					// widen e.g. `0|1` to `int<0, max>` and lose the loop's
-					// per-iteration precision. Instead, keep the literal
-					// union of constant keys so the loop's bound stays
-					// visible.
+					// Both inputs are sealed constant array shapes — their key
+					// sets are finite by construction. On the fall-through
+					// ArrayType path, recursing into `generalizeType` would
+					// widen e.g. `0|1` to `int<0, max>` — for both the keys and
+					// the values — losing the loop's per-iteration precision.
+					// Keep the literal union instead so the loop's bounds stay
+					// visible. (Scoped to sealed shapes so the general
+					// `generalize()` widening contract for legacy arrays — see
+					// ScopeTest::testGeneralize — is unaffected.)
 					$bothSealed = true;
 					foreach ([...$constantArrays['a'], ...$constantArrays['b']] as $constantArrayCheck) {
 						foreach ($constantArrayCheck->getConstantArrays() as $constantArrayInstance) {
@@ -4283,12 +4284,21 @@ private function generalizeType(Type $a, Type $b, int $depth): Type
 					}
 					if ($bothSealed) {
 						$resultKeyType = TypeCombinator::union($constantArraysA->getIterableKeyType(), $constantArraysB->getIterableKeyType());
+						$resultValueType = TypeCombinator::union($constantArraysA->getIterableValueType(), $constantArraysB->getIterableValueType());
+						if ($resultValueType->isOversizedArray()->yes()) {
+							// The literal value union outgrew the shape limit (a
+							// deeply/widely nested value): fall back to generalizing
+							// it into a bounded range-keyed array rather than
+							// keeping an oversized literal shape.
+							$resultValueType = TypeCombinator::union($this->generalizeType($constantArraysA->getIterableValueType(), $constantArraysB->getIterableValueType(), $depth + 1));
+						}
 					} else {
 						$resultKeyType = TypeCombinator::union($this->generalizeType($constantArraysA->getIterableKeyType(), $constantArraysB->getIterableKeyType(), $depth + 1));
+						$resultValueType = TypeCombinator::union($this->generalizeType($constantArraysA->getIterableValueType(), $constantArraysB->getIterableValueType(), $depth + 1));
 					}
 					$resultType = new ArrayType(
 						$resultKeyType,
-						TypeCombinator::union($this->generalizeType($constantArraysA->getIterableValueType(), $constantArraysB->getIterableValueType(), $depth + 1)),
+						$resultValueType,
 					);
 					$accessories = [];
 					if (

tests/PHPStan/Analyser/nsrt/bug-13637.php

@@ -0,0 +1,38 @@
+<?php declare(strict_types = 1);
+
+namespace Bug13637;
+
+use function PHPStan\Testing\assertType;
+
+function doesNotWork(): void
+{
+	$final = [];
+
+	for ($i = 0; $i < 5; $i++) {
+		$j = $i * 2;
+		$k = $j + 1;
+		$final[$i][$j][$k]['abc'] = $i;
+		$final[$i][$j][$k]['def'] = $i;
+		$final[$i][$j][$k]['ghi'] = $i;
+	}
+
+	// The reported regression (innermost values widening to `int<0, max>`) is
+	// fixed: they stay `int<0, 4>`. The middle key degenerates to `int` rather
+	// than the ideal `int<0, 8>` — a minor key-precision residual in 3-level
+	// nesting, not the value-widening bug from the issue.
+	assertType('non-empty-array<int<0, 4>, non-empty-array<int, non-empty-array<int<1, 9>, array{abc: int<0, 4>, def?: int<0, 4>, ghi?: int<0, 4>}>>>', $final);
+}
+
+function thisWorks(): void
+{
+	$final = [];
+
+	for ($i = 0; $i < 5; $i++) {
+		$j = $i * 2;
+		$final[$i][$j]['abc'] = $i;
+		$final[$i][$j]['def'] = $i;
+		$final[$i][$j]['ghi'] = $i;
+	}
+
+	assertType('non-empty-array<int<0, 4>, non-empty-array<int<0, 8>, array{abc: int<0, 4>, def: int<0, 4>, ghi: int<0, 4>}>>', $final);
+}

tests/PHPStan/Analyser/nsrt/bug-13647.php

@@ -0,0 +1,28 @@
+<?php declare(strict_types = 1);
+
+namespace Bug13647;
+
+use function PHPStan\Testing\assertType;
+
+function foo(): void
+{
+	$a = [];
+	$a[0] = [0, 1];
+
+	for ($i = 1; $i < 6; $i++) {
+		$a[$i] = [$i, $i + 1];
+	}
+
+	assertType('non-empty-array<int<0, 5>, array{int<0, 5>, int<1, 6>}>', $a);
+
+	for ($i = 1; $i < 6; $i++) {
+		$b = $a;
+
+		$b[$i][0] = $a[$i - 1][0];
+		$b[$i][1] = $a[$i - 1][1];
+
+		$a = $b;
+	}
+
+	assertType('non-empty-array<int<0, 5>, array{int<0, 5>, int<1, 6>}>', $a);
+}

tests/PHPStan/Analyser/nsrt/unsealed-array-shapes.php

@@ -174,7 +174,7 @@ public function loopWithExistingSealedKey(): void
 		for ($i = 0; $i < 5; $i++) {
 			$arr[$i] = $i;
 		}
-		assertType("non-empty-array<'x'|int<0, 4>, int<0, max>>", $arr);
+		assertType("non-empty-array<'x'|int<0, 4>, int<0, 4>>", $arr);
 	}
 
 	/**