Replay the recorded fixpoint pass instead of repeating the final loop walk

Both convergence break paths guarantee the final walk's entry scope
equals the last pass's entry, making the final walk an exact repetition
of that pass. Convergence passes now record their (node, scope) emissions
(RecordingNodeCallback); when the recorded pass consumed nothing (its
recording is complete - convergence consumption skips subtree emissions)
and its entry is the fixpoint, the final walk is replaced by replaying
the recording through the real callback and adopting the pass's storage
and statement result.

The convergence mode becomes a stack of per-pass gap flags: a consumption
is attributed to the innermost active pass only, so inner convergence
(a by-ref closure inside a loop body) does not gap the outer recording,
which received the inner final walk's emissions in full.

Applies to While, Do-While, Foreach (non-unrolled finals) and the by-ref
closure convergence, whose replay runs through the gathering callback on
the pass's own entry scope - the gathering filter compares the
anonymous-function reflection by identity. A body containing constructs
that analyse differently at deep context than in the top-level final
(nested loop/label fixpoints, statement-level classes) is not replayed;
For keeps its real final walk (it applies inferForLoopExpressions there,
which the passes do not).

Author: ondrejmirtes

src/Analyser/NodeScopeResolver.php

@@ -105,6 +105,7 @@
 use function array_last;
 use function array_map;
 use function array_merge;
+use function array_pop;
 use function array_slice;
 use function array_values;
 use function count;
@@ -144,12 +145,20 @@ class NodeScopeResolver
 	private bool $consumeStoredExpressionResults = false;
 
 	/**
-	 * Convergence-pass mode (see enterConvergencePass()): a fixpoint re-walk
-	 * may consume the previous pass's stored result of an effect-free
-	 * expression whose read variables did not change - only the loop-carried
-	 * parts of the body re-walk.
+	 * The stack of active convergence passes (see enterConvergencePass()),
+	 * innermost last; a fixpoint re-walk may consume the previous pass's
+	 * stored result of an effect-free expression whose read variables did not
+	 * change - only the loop-carried parts of the body re-walk. Each entry
+	 * records whether that pass consumed anything: a consumed subtree's
+	 * emissions are missing from the pass's recording, so only a gap-free
+	 * pass's recording can replace the final walk. A consumption is
+	 * attributed to the innermost active pass only - inner convergence
+	 * (a by-ref closure inside a loop body) does not gap the outer recording,
+	 * which received the inner FINAL walk's emissions in full.
+	 *
+	 * @var array<int, bool>
 	 */
-	private bool $consumeEffectFreeStoredResults = false;
+	private array $convergencePassGaps = [];
 
 	/** Whether the PHPSTAN_GUARD_NW diagnostic is enabled (cached from the env). */
 	public static bool $guardNewWorld = false;
@@ -290,24 +299,24 @@ public function processNodes(
 	 * flags - on-demand stored-result reuse and convergence-pass consumption
 	 * describe the walk that was interrupted, not the nested one.
 	 *
-	 * @return array{bool, bool, bool}
+	 * @return array{bool, bool, array<int, bool>}
 	 */
 	private function suspendWalkModes(): array
 	{
-		$modes = [$this->returnStoredExpressionResults, $this->consumeStoredExpressionResults, $this->consumeEffectFreeStoredResults];
+		$modes = [$this->returnStoredExpressionResults, $this->consumeStoredExpressionResults, $this->convergencePassGaps];
 		$this->returnStoredExpressionResults = false;
 		$this->consumeStoredExpressionResults = false;
-		$this->consumeEffectFreeStoredResults = false;
+		$this->convergencePassGaps = [];
 
 		return $modes;
 	}
 
 	/**
-	 * @param array{bool, bool, bool} $modes
+	 * @param array{bool, bool, array<int, bool>} $modes
 	 */
 	private function restoreWalkModes(array $modes): void
 	{
-		[$this->returnStoredExpressionResults, $this->consumeStoredExpressionResults, $this->consumeEffectFreeStoredResults] = $modes;
+		[$this->returnStoredExpressionResults, $this->consumeStoredExpressionResults, $this->convergencePassGaps] = $modes;
 	}
 
 	/**
@@ -479,7 +488,7 @@ private function resolveBackwardGotoScope(
 			}
 			$prevEntryScope = $bodyScope;
 			$tempStorage = ($previousPassStorage ?? $storage)->duplicate();
-			$previousConvergencePass = $this->enterConvergencePass();
+			$this->enterConvergencePass();
 			try {
 				$bodyScopeResult = $this->processStmtNodesInternal(
 					$parentNode,
@@ -490,7 +499,7 @@ private function resolveBackwardGotoScope(
 					$context,
 				);
 			} finally {
-				$this->exitConvergencePass($previousConvergencePass);
+				$this->exitConvergencePass();
 			}
 			$previousPassStorage = $tempStorage;
 
@@ -1006,20 +1015,23 @@ public function processExprNodeConsumingStored(Node\Stmt $stmt, Expr $expr, Muta
 	 * whose stored result is effect-free (ExpressionResult::isEffectFree())
 	 * and whose read variables did not change since the pass that stored it
 	 * are consumed instead of re-walked. The caller chains the previous pass's
-	 * storage as the new pass storage's fallback and restores the returned
-	 * previous mode in a finally block via exitConvergencePass().
+	 * storage as the new pass storage's fallback and pops the pass in a
+	 * finally block via exitConvergencePass().
 	 */
-	public function enterConvergencePass(): bool
+	public function enterConvergencePass(): void
 	{
-		$previous = $this->consumeEffectFreeStoredResults;
-		$this->consumeEffectFreeStoredResults = true;
-
-		return $previous;
+		$this->convergencePassGaps[] = false;
 	}
 
-	public function exitConvergencePass(bool $previous): void
+	/** Returns whether the exited pass consumed anything (a recording gap). */
+	public function exitConvergencePass(): bool
 	{
-		$this->consumeEffectFreeStoredResults = $previous;
+		$gapped = array_pop($this->convergencePassGaps);
+		if ($gapped === null) {
+			throw new ShouldNotHappenException();
+		}
+
+		return $gapped;
 	}
 
 	public function processExprOnDemand(Expr $expr, MutatingScope $scope, ExpressionResultStorage $storage): ExpressionResult
@@ -1233,7 +1245,7 @@ public function processExprNode(
 
 				return $reanchored;
 			}
-		} elseif ($this->consumeEffectFreeStoredResults) {
+		} elseif ($this->convergencePassGaps !== []) {
 			// a convergence pass: the previous pass's result answers exactly
 			// when the walk had no scope effects and nothing this expression
 			// reads changed between the passes - the loop-carried parts of the
@@ -1244,6 +1256,7 @@ public function processExprNode(
 				&& $storedResult->isEffectFree()
 				&& $storedResult->askScopeVariableStateMatches($scope, $scope->nativeTypesPromoted)
 			) {
+				$this->convergencePassGaps[count($this->convergencePassGaps) - 1] = true;
 				if ($storedResult->getBeforeScope() === $scope) {
 					return $storedResult;
 				}
@@ -1255,6 +1268,71 @@ public function processExprNode(
 		return $this->processExprNodeInternal($stmt, $expr, $scope, $storage, $nodeCallback, $context);
 	}
 
+	private const REPLAYABLE_BODY_ATTRIBUTE = 'convergenceReplayableBody';
+
+	/**
+	 * Whether a recorded convergence pass over the loop body can replace the
+	 * final walk. A pass runs at deep statement context, the final walk at top
+	 * level - constructs that analyse differently between the two (nested
+	 * loop/label fixpoints run only at top level, statement-level classes are
+	 * skipped at deep context) disqualify the body. Closure bodies process
+	 * context-independently and are not traversed.
+	 *
+	 * @param Node\Stmt[] $bodyStmts
+	 */
+	public function isReplayableConvergenceBody(Node $loopNode, array $bodyStmts): bool
+	{
+		$cached = $loopNode->getAttribute(self::REPLAYABLE_BODY_ATTRIBUTE);
+		if ($cached !== null) {
+			return $cached;
+		}
+
+		$replayable = true;
+		foreach ($bodyStmts as $bodyStmt) {
+			if ($this->hasContextSensitiveConstruct($bodyStmt)) {
+				$replayable = false;
+				break;
+			}
+		}
+		$loopNode->setAttribute(self::REPLAYABLE_BODY_ATTRIBUTE, $replayable);
+
+		return $replayable;
+	}
+
+	private function hasContextSensitiveConstruct(Node $node): bool
+	{
+		if ($node instanceof Expr\Closure) {
+			return false;
+		}
+		if (
+			$node instanceof Node\Stmt\While_
+			|| $node instanceof Node\Stmt\Do_
+			|| $node instanceof Node\Stmt\For_
+			|| $node instanceof Foreach_
+			|| $node instanceof Node\Stmt\Label
+			|| $node instanceof Node\Stmt\ClassLike
+		) {
+			return true;
+		}
+
+		foreach ($node->getSubNodeNames() as $subNodeName) {
+			$subNode = $node->$subNodeName;
+			if ($subNode instanceof Node) {
+				if ($this->hasContextSensitiveConstruct($subNode)) {
+					return true;
+				}
+			} elseif (is_array($subNode)) {
+				foreach ($subNode as $item) {
+					if ($item instanceof Node && $this->hasContextSensitiveConstruct($item)) {
+						return true;
+					}
+				}
+			}
+		}
+
+		return false;
+	}
+
 	/**
 	 * @param callable(Node $node, Scope $scope): void $nodeCallback
 	 */
@@ -1577,6 +1655,11 @@ private function processClosureNodeInternal(
 
 		$count = 0;
 		$closureResultScope = null;
+		$replayBodyRecording = null;
+		$replayPassStorage = null;
+		$replayPassResult = null;
+		$replayEntryScope = null;
+		$bodyIsReplayable = $this->isReplayableConvergenceBody($expr, $expr->stmts);
 		// each pass chains the previous pass's storage as its fallback, so
 		// the convergence-pass mode consumes unchanged effect-free subtrees
 		// instead of re-walking the whole body every round
@@ -1585,17 +1668,33 @@ private function processClosureNodeInternal(
 			$prevScope = $closureScope;
 
 			$storage = ($previousPassStorage ?? $originalStorage)->duplicate();
-			$previousConvergencePass = $this->enterConvergencePass();
+			$this->enterConvergencePass();
+			$passGapped = false;
+			$bodyRecording = $bodyIsReplayable ? new RecordingNodeCallback() : new NoopNodeCallback();
 			try {
 				// deep context, like the loop handlers' own convergence passes: inner
 				// loops walk single-pass here and only the final walk below (top-level)
 				// runs their full convergence - otherwise every closure-convergence
 				// pass would re-converge every inner loop from scratch
-				$intermediaryClosureScopeResult = $this->processStmtNodesInternal($expr, $expr->stmts, $closureScope, $storage, new NoopNodeCallback(), StatementContext::createDeep());
+				$intermediaryClosureScopeResult = $this->processStmtNodesInternal($expr, $expr->stmts, $closureScope, $storage, $bodyRecording, StatementContext::createDeep());
 			} finally {
-				$this->exitConvergencePass($previousConvergencePass);
+				$passGapped = $this->exitConvergencePass();
 			}
 			$previousPassStorage = $storage;
+			// a pass that consumed nothing has a complete recording - the
+			// candidate to replace the final walk when its entry turns out
+			// to be the fixpoint
+			if ($bodyRecording instanceof RecordingNodeCallback && !$passGapped) {
+				$replayBodyRecording = $bodyRecording;
+				$replayPassStorage = $storage;
+				$replayPassResult = $intermediaryClosureScopeResult;
+				$replayEntryScope = $prevScope;
+			} else {
+				$replayBodyRecording = null;
+				$replayPassStorage = null;
+				$replayPassResult = null;
+				$replayEntryScope = null;
+			}
 			$intermediaryClosureScope = $intermediaryClosureScopeResult->getScope();
 			foreach ($intermediaryClosureScopeResult->getExitPoints() as $exitPoint) {
 				$intermediaryClosureScope = $intermediaryClosureScope->mergeWith($exitPoint->getScope());
@@ -1623,7 +1722,20 @@ private function processClosureNodeInternal(
 		}
 
 		$storage = $originalStorage;
-		$statementResult = $this->processStmtNodesInternal($expr, $expr->stmts, $closureScope, $storage, $closureStmtsCallback, StatementContext::createTopLevel());
+		if ($replayBodyRecording !== null && $closureScope->equals($replayEntryScope)) {
+			// the final walk would repeat the recorded fixpoint pass exactly
+			// (same entry scope, deterministic walk) - adopt the pass's result
+			// and replay its emissions through the gathering callback instead.
+			// The pass's own entry scope takes over: the recorded pairs carry
+			// its anonymous-function reflection, which the gathering filter
+			// compares by identity (the state is equals-identical anyway).
+			$closureScope = $replayEntryScope;
+			$originalStorage->mergeResults($replayPassStorage);
+			$replayBodyRecording->replayThrough($closureStmtsCallback);
+			$statementResult = $replayPassResult;
+		} else {
+			$statementResult = $this->processStmtNodesInternal($expr, $expr->stmts, $closureScope, $storage, $closureStmtsCallback, StatementContext::createTopLevel());
+		}
 		$publicStatementResult = $statementResult->toPublic();
 		$closureReturnStatementsNodeScope = $this->refineClosureNodeScope($closureScope, $scope, $expr, $gatheredReturnStatementsWithScope, $gatheredYieldStatementsWithScope, $executionEnds, $statementResult->getThrowPoints(), array_merge($closureImpurePoints, $statementResult->getImpurePoints()), $invalidateExpressions, $storage);
 		$this->callNodeCallback($nodeCallback, new ClosureReturnStatementsNode(

src/Analyser/RecordingNodeCallback.php

@@ -0,0 +1,35 @@
+<?php declare(strict_types = 1);
+
+namespace PHPStan\Analyser;
+
+use PhpParser\Node;
+
+/**
+ * Records every (node, scope) emission of a convergence pass in order. When
+ * the pass turns out to be the fixpoint (the final entry scope equals the
+ * pass's entry and the pass consumed nothing), the final walk is replaced by
+ * replaying the recording through the real node callback - the scopes are
+ * state-equal to what the repeated walk would emit.
+ */
+final class RecordingNodeCallback
+{
+
+	/** @var list<array{Node, Scope}> */
+	private array $pairs = [];
+
+	public function __invoke(Node $node, Scope $scope): void
+	{
+		$this->pairs[] = [$node, $scope];
+	}
+
+	/**
+	 * @param callable(Node $node, Scope $scope): void $nodeCallback
+	 */
+	public function replayThrough(callable $nodeCallback): void
+	{
+		foreach ($this->pairs as [$node, $scope]) {
+			$nodeCallback($node, $scope);
+		}
+	}
+
+}