Apply the effects of a closure's by-ref uses where it is invoked

[ondrejmirtes]

A closure with use (&$x) is analysed today once, at its creation, with a fixpoint entry: $x is the union of every state any number of runs could leave, both inside the body and outside from the creation on. The type inside the closure is therefore too wide when the closure runs once from a known state, and stale when $x changes between creation and invocation.

This PR reuses the two-pass observation from #6332 and #6604 (merged) to follow where the closure runs:

$x = 1;
$c = function () use (&$x): void {
	assertType('1', $x);      // was 1|'a'
	$x = 'a';
};
assertType('1', $x);          // was 1|'a'
$c();
assertType("'a'", $x);        // was 1|'a'

$y = 1;
$d = function () use (&$y): void {
	assertType("'b'", $y);    // was 1 - the body never saw 'b'
};
$y = 'b';
$d();

How it works

• A closure written where nothing types it gets a marker per by-ref use (a new trailing byRefUseTypes on ClosureType). The observation classifies each closure:
  • Local: every invocation was seen.
    • At creation nothing runs; an undefined $x becomes null.
    • Each invocation walks the body from the state of $x there and writes back the exit types and the throw points.
    • The body's rules run in one deferred walk at the end of the enclosing body's second pass. That walk is entered with the union of $x at the invocations, or the creation state when there was none.
  • Escaped: the value went somewhere it can be invoked at any time (argument, return, yield, property, capture by another closure or arrow function). The creation-time fixpoint stays, seeded with the invocation states seen. Local invocations of an escaped closure run the fixpoint from the current state, which also fixes a soundness hole: a closure passed away and invoked locally now changes $x at the local call.
• The first pass runs the fixpoint from the current state at each invocation, so it contains whatever the second pass computes. An invocation from within the creation's fixpoint skips the walk. That needs accepted arguments and a body with no throw points (a catch could see mid-run states).
• Captured by-value uses, and the check that an invocation runs in the function-like that created the closure, come from the creation's stored expression result. The persistent fact tree is flattened only once, at the end of the body.
• Not followed: generators, a closure invoking its own by-ref variable, closures with their own @template, top-level code and non-closed bodies (the two-pass driver doesn't run there).
• Gated by featureToggles.closureSignaturesFromUsages. Native twins are ported in the same commit.

Verification

• Tests: new NSRT fixture closure-byref-uses-at-invocation.php (inside and after the closure: once, twice, in loops, conditional, never invoked, modified in between, undefined, by-value captures, accumulators, catch, escapes, invocations before throw/return/break), a toggle-off fixture, and a rule test. Several existing fixtures pinned the old fixpoint types and got more precise.
• Full suite passes with and without turbo, as do make phpstan and cs. Side-by-side, signature parity, smoke (with a new by-ref frame differential) pass; walk-trace is identical.
• Slevomat (PHP mode): 125 = 125 errors. Two messages carry a more precise array shape; both are true positives.
• Downstream, turbo phars, one ABBA pair each, user CPU vs Infer signatures of closures from where their values are sent #6604 (the machine was busy):
  • Slevomat: 369.5 s → 365.8 s (−1.0%, pairs −3.0% / +1.1%). The same 125 errors; two messages carry a more precise array shape (true positives).
  • ShipMonk: 857.1 s → 872.9 s (+1.8%, pairs +0.3% / +3.4%). The same 374 errors.
• Pathological cases (PHP mode, analysis time vs Infer signatures of closures from where their values are sent #6604):
  • 150 by-ref closures in one body: +54%
  • one closure invoked 200 times: +27%
  • invocations in nested loops, escapes, invocations inside ifs: at most +18%
  • Nested by-ref closures, each invoked twice by its parent, stay exponential in depth with a larger base: 3^d body walks become ~5.5^d (depth 4 +100%, depth 6 +1000%). Every walk of a parent body re-runs the child's creation fixpoint and its invocations; caching that across parent walks would need state outside the walk.

Issues

Both reproducers are top-level code, where the two-pass observation doesn't run. The regression tests (nsrt/bug-7751.php, nsrt/bug-14248.php, StrictComparisonOfDifferentTypesRuleTest::testBug14248) wrap them in a function; they fail on #6604.

Closes phpstan/phpstan#7751
Closes phpstan/phpstan#14248

🤖 Generated with Claude Code

https://claude.ai/code/session_01VpbB99tJfUmeArX74xqvHv

A closure with by-ref uses is left out of #6604's per-invocation return types: what it returns depends on its by-ref variables where it runs, which the invocation walk here follows.

[phpstan-bot]

This pull request has been marked as ready for review.