Fix loop-carried assignment type flow in loops

Author: AJenbo

docs/CHANGELOG.md

@@ -66,6 +66,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - **Inline `@var` cast no longer overrides the variable type on the RHS of the same assignment.** `/** @var array<string, mixed> */ $data = $data->toArray()` previously resolved the RHS `$data` as `array<string, mixed>` instead of its previous type, producing false "method not found" errors. The cast now applies only after the assignment completes.
 - **Single generic argument on collections bound to the wrong template parameter.** Writing `Collection<SectionTranslation>` on a class with `@template TKey of array-key` and `@template TValue` assigned the argument to `TKey` (by position), leaving `TValue` unsubstituted. When fewer generic arguments are provided than template parameters and the leading parameters have key-like bounds (`array-key`, `int`, `string`), the arguments are now right-aligned so they bind to the value parameters. Method-level template parameters whose bound parameter was not passed at the call site and defaults to `null` now resolve to `null` instead of remaining as raw template names. Together these fixes mean `Collection<SectionTranslation>::first()` correctly resolves to `SectionTranslation|null`.
 - **Nullable return types losing `|null` after template substitution.** When a method declared `@return TValue|null` and `TValue` was substituted with a concrete class through `@extends`, the `|null` component was silently dropped. Hover showed `AdminUser` instead of `AdminUser|null` for calls like `AdminUser::first()`. The docblock type extraction pipeline now preserves nullable unions so that `|null` survives through substitution, hover display, and variable type resolution.
+- **Loop-body assignments not visible inside the same loop iteration.** When a variable was initialized as `null` and reassigned later in a loop body, code earlier in the loop (reached on subsequent iterations) only saw `null`. The variable resolution walker now pre-scans the entire loop body for assignments before the positional walk, so the union of all assignments is available at every point inside the loop. Combined with `!== null` narrowing, variables like `$lastPaidEnd` correctly resolve to the assigned class type. Applies to `foreach`, `while`, `for`, and `do-while` loops.
 
 ## [0.6.0] - 2026-03-26
 

docs/todo.md

@@ -24,7 +24,6 @@ within the same impact tier.
 | #   | Item                                                                                                                                       | Impact | Effort     |
 | --- | ------------------------------------------------------------------------------------------------------------------------------------------ | ------ | ---------- |
 | T18 | [Method-level template parameter resolution at call sites](todo/type-inference.md#t18-method-level-template-parameter-resolution-at-call-sites) | Medium | Medium     |
-| B20 | [Loop-body assignments not visible to null narrowing](todo/bugs.md#b20-loop-body-assignments-not-visible-to-null-narrowing-for-null-initialized-variables) | Low | Medium |
 | B21 | [Builder `__call` return type drops chain type for dynamic `where{Column}` calls](todo/bugs.md#b21-builder-__call-return-type-drops-chain-type-for-dynamic-wherecolumn-calls) | Medium | Medium     |
 | L12 | [`App::make` / `App::makeWith` class-string return type dispatch](todo/laravel.md#l12-appmake--appmakewith-class-string-return-type-dispatch) | Medium | Low        |
 |     | **Release 0.7.0**                                                                                                                          |        |            |

docs/todo/bugs.md

@@ -1,62 +1,5 @@
 # PHPantom — Bug Fixes
 
-#### B20. Loop-body assignments not visible to null narrowing for null-initialized variables
-
-| | |
-|---|---|
-| **Impact** | Low |
-| **Effort** | Medium |
-
-When a variable is initialized as `null` and reassigned inside a
-`foreach` or `while` loop body, the assignment type does not flow
-into the variable's resolved type for code inside the same loop
-iteration. The variable stays typed as `null` even though it was
-assigned a class instance on a previous iteration.
-
-**Reproducer:**
-
-```php
-$lastPaidEnd = null;
-
-foreach ($periods as $period) {
-    if ($lastPaidEnd !== null && $lastPaidEnd->diffInDays($periodStart) > 0) {
-        // Hover on $lastPaidEnd shows `null` — the Carbon assignment
-        // from the previous iteration is lost.
-    }
-    $lastPaidEnd = $period->ending->startOfDay();
-}
-```
-
-**Expected:** `$lastPaidEnd` should resolve to `null|Carbon` (the
-union of the initial `null` and the loop-body assignment). The
-`!== null` narrowing (B17, now fixed) would then strip `null`,
-leaving `Carbon` on the right side of `&&`.
-
-**Actual:** The loop-body assignment (`$lastPaidEnd = $period->ending->startOfDay()`)
-appears after the cursor position within the same iteration, so
-the variable resolution walker never picks it up. The resolved
-type is just `null`.
-
-**Root cause:** `walk_statements_for_assignments` walks statements
-sequentially and only accumulates assignments that appear before
-the cursor offset. Inside a loop body, an assignment that appears
-textually after the cursor can still be live on subsequent
-iterations. The walker would need a second pass (or a pre-scan of
-the loop body) to collect all assignments within the loop and
-union them into the variable's type for any position inside the
-loop.
-
-**Where to fix:**
-- `src/completion/variable/resolution.rs` — in `walk_foreach_statement`
-  and `walk_while_statement`, pre-scan the loop body for assignments
-  to the target variable and merge their types into the result set
-  before walking the body normally. This ensures that even assignments
-  after the cursor contribute to the union type.
-
-**Discovered in:** B17 QA (sandbox.php cases 1, 2, 8).
-
----
-
 #### B21. Builder `__call` return type drops chain type for dynamic `where{Column}` calls
 
 | | |

example.php

@@ -567,6 +567,37 @@ public function demo(array $pens): void
 }
 
 
+// ── Loop-Carried Assignment ─────────────────────────────────────────────────
+// When a variable is initialized as null and reassigned inside a loop body,
+// the assignment from a previous iteration is visible at the top of the loop.
+
+class LoopCarriedAssignmentDemo
+{
+    /** @param list<Pen> $pens */
+    public function demo(array $pens): void
+    {
+        // Pattern: null-init + reassignment after the usage point in the loop.
+        // On the second iteration, $prev holds the Pen from the prior iteration.
+        $prev = null;
+        foreach ($pens as $pen) {
+            if ($prev !== null) {
+                $prev->write();                   // Pen from previous iteration
+            }
+            $prev = $pen;
+        }
+
+        // Same pattern with a while loop
+        $lastOrder = null;
+        while ($row = rand(0, 1)) {
+            if ($lastOrder !== null) {
+                $lastOrder->getStatusCode();      // Response from previous iteration
+            }
+            $lastOrder = new Response(200, 'ok');
+        }
+    }
+}
+
+
 // ── Null Coalesce (`??`) Refinement ─────────────────────────────────────────
 
 class NullCoalesceDemo
@@ -5565,6 +5596,28 @@ function runDemoAssertions(): void
     assert(is_array($iBoxPens), 'ScaffoldingPenBox::getPens() must return array');
     assert($iBoxPens[0] instanceof Pen, 'ScaffoldingPenBox::getPens()[0] must be Pen');
 
+    // ── Loop-carried assignment ─────────────────────────────────────────
+    $lcPens = [new Pen('a'), new Pen('b')];
+    $lcPrev = null;
+    foreach ($lcPens as $lcPen) {
+        if ($lcPrev !== null) {
+            assert($lcPrev instanceof Pen, 'Loop-carried $lcPrev must be Pen on second iteration');
+        }
+        $lcPrev = $lcPen;
+    }
+    assert($lcPrev instanceof Pen, '$lcPrev must be Pen after foreach');
+
+    $lcLast = null;
+    $lcIter = 0;
+    while ($lcIter < 2) {
+        if ($lcLast !== null) {
+            assert($lcLast instanceof Response, 'Loop-carried $lcLast must be Response');
+        }
+        $lcLast = new Response(200, 'ok');
+        $lcIter++;
+    }
+    assert($lcLast instanceof Response, '$lcLast must be Response after while');
+
     // ── Constant type inference ─────────────────────────────────────────
     assert(ConstantTypeDemo::TIMEOUT === 30, 'ConstantTypeDemo::TIMEOUT must be 30');
     assert(ConstantTypeDemo::NAME === 'app', 'ConstantTypeDemo::NAME must be "app"');

src/completion/variable/resolution.rs

@@ -1252,15 +1252,55 @@ pub(in crate::completion) fn walk_statements_for_assignments<'b>(
             Statement::While(while_stmt) => {
                 walk_while_statement(while_stmt, ctx, results);
             }
-            Statement::For(for_stmt) => match &for_stmt.body {
-                ForBody::Statement(inner) => {
-                    check_statement_for_assignments(inner, ctx, results, true);
+            Statement::For(for_stmt) => {
+                // ── Pre-scan for loop-carried assignments ──
+                let for_body_span = for_stmt.body.span();
+                let for_header_start = for_stmt.r#for.span().start.offset;
+                let cursor_inside_for = ctx.cursor_offset >= for_header_start
+                    && ctx.cursor_offset <= for_body_span.end.offset;
+                if cursor_inside_for {
+                    match &for_stmt.body {
+                        ForBody::Statement(inner) => {
+                            prescan_loop_body_for_assignments(
+                                std::iter::once(*inner),
+                                for_body_span.end.offset,
+                                ctx,
+                                results,
+                            );
+                        }
+                        ForBody::ColonDelimited(body) => {
+                            prescan_loop_body_for_assignments(
+                                body.statements.iter(),
+                                for_body_span.end.offset,
+                                ctx,
+                                results,
+                            );
+                        }
+                    }
                 }
-                ForBody::ColonDelimited(body) => {
-                    walk_statements_for_assignments(body.statements.iter(), ctx, results, true);
+                match &for_stmt.body {
+                    ForBody::Statement(inner) => {
+                        check_statement_for_assignments(inner, ctx, results, true);
+                    }
+                    ForBody::ColonDelimited(body) => {
+                        walk_statements_for_assignments(body.statements.iter(), ctx, results, true);
+                    }
                 }
-            },
+            }
             Statement::DoWhile(dw) => {
+                // ── Pre-scan for loop-carried assignments ──
+                let dw_body_span = dw.statement.span();
+                let dw_header_start = dw.r#do.span().start.offset;
+                let cursor_inside_dw = ctx.cursor_offset >= dw_header_start
+                    && ctx.cursor_offset <= dw_body_span.end.offset;
+                if cursor_inside_dw {
+                    prescan_loop_body_for_assignments(
+                        std::iter::once(dw.statement),
+                        dw_body_span.end.offset,
+                        ctx,
+                        results,
+                    );
+                }
                 check_statement_for_assignments(dw.statement, ctx, results, true);
             }
             Statement::Try(try_stmt) => {
@@ -2094,6 +2134,41 @@ fn walk_if_branch_aware<'b>(
     None
 }
 
+/// Pre-scan a loop body for assignments to the target variable.
+///
+/// In a loop, an assignment that appears textually *after* the cursor
+/// can still be live on subsequent iterations.  This helper walks the
+/// loop body with `cursor_offset` set to `body_end` so that all
+/// assignments are visible, and merges any discovered types into
+/// `results` as conditional.  The caller should invoke this **before**
+/// the normal positional walk so that narrowing (e.g. `!== null`)
+/// applied during the normal walk can strip types contributed by the
+/// pre-scan.
+///
+/// Only types that are not already present in `results` are added,
+/// avoiding duplicates with assignments that the normal walk will
+/// also discover.
+fn prescan_loop_body_for_assignments<'b>(
+    statements: impl Iterator<Item = &'b Statement<'b>>,
+    body_end: u32,
+    ctx: &VarResolutionCtx<'_>,
+    results: &mut Vec<ResolvedType>,
+) {
+    // Only pre-scan when the cursor is actually inside the loop body.
+    // The caller is responsible for checking this, but as a safety
+    // measure we verify that the cursor is before the body end.
+    if ctx.cursor_offset >= body_end {
+        return;
+    }
+
+    let prescan_ctx = ctx.with_cursor_offset(body_end);
+    let mut prescan_results: Vec<ResolvedType> = Vec::new();
+    walk_statements_for_assignments(statements, &prescan_ctx, &mut prescan_results, true);
+
+    // Merge pre-scanned types into results as conditional additions.
+    ResolvedType::extend_unique(results, prescan_results);
+}
+
 /// Handle `foreach` statements during variable assignment walking.
 ///
 /// Resolves the foreach value/key variable and recurses into the body
@@ -2142,6 +2217,32 @@ fn walk_foreach_statement<'b>(
         super::foreach_resolution::try_resolve_foreach_key_type(foreach, ctx, results, conditional);
     }
 
+    // ── Pre-scan for loop-carried assignments ──
+    // When the cursor is inside the loop body, assignments that appear
+    // textually after the cursor are live on subsequent iterations.
+    // Pre-scan the body to pick them up as conditional types before the
+    // normal positional walk (which skips statements after the cursor).
+    if cursor_inside {
+        match &foreach.body {
+            ForeachBody::Statement(inner) => {
+                prescan_loop_body_for_assignments(
+                    std::iter::once(*inner),
+                    body_span.end.offset,
+                    ctx,
+                    results,
+                );
+            }
+            ForeachBody::ColonDelimited(body) => {
+                prescan_loop_body_for_assignments(
+                    body.statements.iter(),
+                    body_span.end.offset,
+                    ctx,
+                    results,
+                );
+            }
+        }
+    }
+
     // Always walk the foreach body for variable assignments, even when
     // the cursor is after the foreach.  A foreach body may execute zero
     // or more times, so any assignment inside is conditional.
@@ -2178,6 +2279,35 @@ fn walk_while_statement<'b>(
     // `while ($line = fgets($fp))` — register the assignment.
     check_condition_for_assignment(while_stmt.condition, ctx, results);
 
+    // Determine whether the cursor is inside this while loop for the
+    // pre-scan.  We check both body variants.
+    let while_body_span = while_stmt.body.span();
+    let while_header_start = while_stmt.r#while.span().start.offset;
+    let cursor_inside_while =
+        ctx.cursor_offset >= while_header_start && ctx.cursor_offset <= while_body_span.end.offset;
+
+    // ── Pre-scan for loop-carried assignments ──
+    if cursor_inside_while {
+        match &while_stmt.body {
+            WhileBody::Statement(inner) => {
+                prescan_loop_body_for_assignments(
+                    std::iter::once(*inner),
+                    while_body_span.end.offset,
+                    ctx,
+                    results,
+                );
+            }
+            WhileBody::ColonDelimited(body) => {
+                prescan_loop_body_for_assignments(
+                    body.statements.iter(),
+                    while_body_span.end.offset,
+                    ctx,
+                    results,
+                );
+            }
+        }
+    }
+
     match &while_stmt.body {
         WhileBody::Statement(inner) => {
             ResolvedType::apply_narrowing(results, |classes| {