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 and not enabled under bleedingEdge. With it off the body scope
is built exactly as before, so no behaviour changes. With it on, the body
narrows regardless of polluteScopeWithAlwaysIterableForeach; the narrowing also
sharpens the after-loop scope, so a value variable can be seen as defined where
the iteratee is later proven non-empty. That is why the toggle stays opt-in for
now.

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

@@ -263,6 +263,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 +1513,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();
 

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'),