Narrow foreach body to non-empty behind an opt-in toggle

Inside a foreach body the iterated expression is provably non-empty, so it
can be narrowed (list to non-empty-list, array to non-empty-array) at body
entry. Before, this happened only when polluteScopeWithAlwaysIterableForeach
was on, so with the flag off (as phpstan-strict-rules sets it) the narrowing
disappeared even though the body is only entered when the iteratee is
non-empty.

The narrowing is gated behind the new feature toggle narrowForeachBodyNonEmpty,
off by default. With it off the body scope is built exactly as before, so no
behaviour changes. With it on, the body narrows regardless of the flag.

Narrowing the body also feeds the loop-exit scope, which with the flag off
must stay conservative: it must not conclude the loop always iterated. After
the body pass the iterated expression's possibly-empty-ness is restored in the
after-loop scope, keeping any element types the body refined. This containment
is partial: definedness that flows through variables the body builds (rather
than through the iterated expression itself) still reaches the after-loop
scope. Because of that residual, the toggle is not enabled under bleedingEdge
yet; it is opt-in until the leak is fully contained.

Closes phpstan/phpstan#13312

Author: zonuexe

conf/config.neon

@@ -46,6 +46,7 @@ parameters:
 		rawMessageInBaseline: false
 		reportNestedTooWideType: false
 		assignToByRefForeachExpr: false
+		narrowForeachBodyNonEmpty: false
 		curlSetOptArrayTypes: false
 		magicDirInInclude: false
 		checkDateIntervalConstructor: false

conf/parametersSchema.neon

@@ -44,6 +44,7 @@ parametersSchema:
 		rawMessageInBaseline: bool()
 		reportNestedTooWideType: bool()
 		assignToByRefForeachExpr: bool()
+		narrowForeachBodyNonEmpty: bool()
 		curlSetOptArrayTypes: bool()
 		magicDirInInclude: bool()
 		checkDateIntervalConstructor: bool()

src/Analyser/NodeScopeResolver.php

@@ -144,6 +144,7 @@
 use PHPStan\ShouldNotHappenException;
 use PHPStan\TrinaryLogic;
 use PHPStan\Type\ClosureType;
+use PHPStan\Type\Constant\ConstantArrayType;
 use PHPStan\Type\Constant\ConstantIntegerType;
 use PHPStan\Type\Constant\ConstantStringType;
 use PHPStan\Type\FileTypeMapper;
@@ -263,6 +264,8 @@ public function __construct(
 		private readonly bool $polluteScopeWithLoopInitialAssignments,
 		#[AutowiredParameter]
 		private readonly bool $polluteScopeWithAlwaysIterableForeach,
+		#[AutowiredParameter(ref: '%featureToggles.narrowForeachBodyNonEmpty%')]
+		private readonly bool $narrowForeachBodyNonEmpty,
 		#[AutowiredParameter]
 		private readonly bool $polluteScopeWithBlock,
 		#[AutowiredParameter(ref: '%exceptions.implicitThrows%')]
@@ -1511,7 +1514,13 @@ public function processStmtNode(
 			$originalStorage = $storage;
 			$unrolledEndScope = null;
 			$unrolledTotalKeys = null;
-			$iterateeScope = $this->polluteScopeWithAlwaysIterableForeach ? $scope->filterByTruthyValue($arrayComparisonExpr) : $scope;
+			// The loop body is only entered when the iteratee is non-empty. Under
+			// narrowForeachBodyNonEmpty we narrow it there (list to non-empty-list,
+			// array to non-empty-array) even with polluteScopeWithAlwaysIterableForeach
+			// off; with the toggle off the body scope is unchanged.
+			$iterateeScope = $this->narrowForeachBodyNonEmpty || $this->polluteScopeWithAlwaysIterableForeach
+				? $scope->filterByTruthyValue($arrayComparisonExpr)
+				: $scope;
 			if ($context->isTopLevel()) {
 				$storage = $originalStorage->duplicate();
 
@@ -1699,6 +1708,33 @@ public function processStmtNode(
 			}
 
 			$isIterableAtLeastOnce = $exprType->isIterableAtLeastOnce();
+
+			$iterateeCertainty = $finalScope->hasExpressionType($stmt->expr);
+			if (
+				$this->narrowForeachBodyNonEmpty
+				&& !$this->polluteScopeWithAlwaysIterableForeach
+				&& !$iterateeCertainty->no()
+				&& !$isIterableAtLeastOnce->yes()
+			) {
+				// With the flag off the after-loop scope must not assume the loop ran, so
+				// undo the body narrowing: restore the iteratee's possibly-empty-ness
+				// (keeping element types the body refined). Only the non-emptiness the
+				// narrowing added is stripped; an iteratee already non-empty before the
+				// loop keeps it, and a literal like `foreach ([1, 2] as $v)` is skipped.
+				$finalIterateeType = $finalScope->getType($stmt->expr);
+				if ($finalIterateeType->isArray()->yes()) {
+					$finalIterateeNativeType = $finalScope->getNativeType($stmt->expr);
+					$finalScope = $finalScope->specifyExpressionType(
+						$stmt->expr,
+						TypeCombinator::union($finalIterateeType, new ConstantArrayType([], [])),
+						$finalIterateeNativeType->isArray()->yes()
+							? TypeCombinator::union($finalIterateeNativeType, new ConstantArrayType([], []))
+							: $finalIterateeNativeType,
+						$iterateeCertainty,
+					);
+				}
+			}
+
 			if ($isIterableAtLeastOnce->maybe() || $exprType->isIterable()->no()) {
 				$finalScope = $finalScope->mergeWith($scope->filterByTruthyValue(new BooleanOr(
 					new BinaryOp\Identical(

src/Testing/RuleTestCase.php

@@ -123,6 +123,7 @@ protected function createNodeScopeResolver(): NodeScopeResolver
 			self::createScopeFactory($reflectionProvider, $typeSpecifier),
 			$this->shouldPolluteScopeWithLoopInitialAssignments(),
 			$this->shouldPolluteScopeWithAlwaysIterableForeach(),
+			self::getContainer()->getParameter('featureToggles')['narrowForeachBodyNonEmpty'],
 			self::getContainer()->getParameter('polluteScopeWithBlock'),
 			self::getContainer()->getParameter('exceptions')['implicitThrows'],
 			$this->shouldTreatPhpDocTypesAsCertain(),

src/Testing/TypeInferenceTestCase.php

@@ -98,6 +98,7 @@ protected static function createNodeScopeResolver(): NodeScopeResolver
 			self::createScopeFactory($reflectionProvider, $typeSpecifier),
 			$container->getParameter('polluteScopeWithLoopInitialAssignments'),
 			$container->getParameter('polluteScopeWithAlwaysIterableForeach'),
+			$container->getParameter('featureToggles')['narrowForeachBodyNonEmpty'],
 			$container->getParameter('polluteScopeWithBlock'),
 			$container->getParameter('exceptions')['implicitThrows'],
 			$container->getParameter('treatPhpDocTypesAsCertain'),

tests/PHPStan/Analyser/AnalyserTest.php

@@ -839,6 +839,7 @@ private function createAnalyser(): Analyser
 			self::createScopeFactory($reflectionProvider, $typeSpecifier),
 			false,
 			true,
+			false,
 			true,
 			true,
 			$this->shouldTreatPhpDocTypesAsCertain(),

tests/PHPStan/Analyser/Bug13312NoPolluteTest.php

@@ -0,0 +1,36 @@
+<?php declare(strict_types = 1);
+
+namespace PHPStan\Analyser;
+
+use PHPStan\Testing\TypeInferenceTestCase;
+use PHPUnit\Framework\Attributes\DataProvider;
+
+class Bug13312NoPolluteTest extends TypeInferenceTestCase
+{
+
+	public static function dataFileAsserts(): iterable
+	{
+		yield from self::gatherAssertTypes(__DIR__ . '/data/bug-13312-no-pollute.php');
+	}
+
+	/**
+	 * @param mixed ...$args
+	 */
+	#[DataProvider('dataFileAsserts')]
+	public function testFileAsserts(
+		string $assertType,
+		string $file,
+		...$args,
+	): void
+	{
+		$this->assertFileAsserts($assertType, $file, ...$args);
+	}
+
+	public static function getAdditionalConfigFiles(): array
+	{
+		return [
+			__DIR__ . '/bug-13312-no-pollute.neon',
+		];
+	}
+
+}

tests/PHPStan/Analyser/Bug13312StableTest.php

@@ -0,0 +1,36 @@
+<?php declare(strict_types = 1);
+
+namespace PHPStan\Analyser;
+
+use PHPStan\Testing\TypeInferenceTestCase;
+use PHPUnit\Framework\Attributes\DataProvider;
+
+class Bug13312StableTest extends TypeInferenceTestCase
+{
+
+	public static function dataFileAsserts(): iterable
+	{
+		yield from self::gatherAssertTypes(__DIR__ . '/data/bug-13312-stable.php');
+	}
+
+	/**
+	 * @param mixed ...$args
+	 */
+	#[DataProvider('dataFileAsserts')]
+	public function testFileAsserts(
+		string $assertType,
+		string $file,
+		...$args,
+	): void
+	{
+		$this->assertFileAsserts($assertType, $file, ...$args);
+	}
+
+	public static function getAdditionalConfigFiles(): array
+	{
+		return [
+			__DIR__ . '/bug-13312-stable.neon',
+		];
+	}
+
+}

tests/PHPStan/Analyser/Fiber/FiberNodeScopeResolverRuleTest.php

@@ -143,6 +143,7 @@ protected function createNodeScopeResolver(): NodeScopeResolver
 			self::createScopeFactory($reflectionProvider, $typeSpecifier),
 			$this->shouldPolluteScopeWithLoopInitialAssignments(),
 			$this->shouldPolluteScopeWithAlwaysIterableForeach(),
+			self::getContainer()->getParameter('featureToggles')['narrowForeachBodyNonEmpty'],
 			self::getContainer()->getParameter('polluteScopeWithBlock'),
 			self::getContainer()->getParameter('exceptions')['implicitThrows'],
 			$this->shouldTreatPhpDocTypesAsCertain(),

tests/PHPStan/Analyser/Fiber/FiberNodeScopeResolverTest.php

@@ -76,6 +76,7 @@ protected static function createNodeScopeResolver(): NodeScopeResolver
 			self::createScopeFactory($reflectionProvider, $typeSpecifier),
 			$container->getParameter('polluteScopeWithLoopInitialAssignments'),
 			$container->getParameter('polluteScopeWithAlwaysIterableForeach'),
+			$container->getParameter('featureToggles')['narrowForeachBodyNonEmpty'],
 			$container->getParameter('polluteScopeWithBlock'),
 			$container->getParameter('exceptions')['implicitThrows'],
 			$container->getParameter('treatPhpDocTypesAsCertain'),