Guard forward walker against exponential blowup on deep loop nesting

Author: AJenbo

docs/ARCHITECTURE.md

@@ -1051,6 +1051,13 @@ Each worker is created during `initialized` via `clone_for_diagnostic_worker`, w
 
 Non-`Arc` fields are snapshotted at spawn time: `php_version`, `vendor_uri_prefixes`, `vendor_dir_paths`, and `config`. These fields are only written during `initialized` (before the workers are spawned) and never change afterwards. If a future feature adds hot-reloading of `.phpantom.toml` or runtime PHP version changes, the workers would need to be notified or re-cloned. This invariant ("init-time fields are write-once") should be verified before adding any post-init mutation to these fields.
 
+## Forward Walker
+
+The forward walker (`src/completion/variable/forward_walk.rs`) walks
+method bodies top-to-bottom, building a scope of variable types at
+each statement boundary. It is shared by diagnostics, completion,
+hover, go-to-definition, and signature help.
+
 ## Name Resolution
 
 PHP class names go through resolution at parse time (`resolve_parent_class_names`):

docs/CHANGELOG.md

@@ -19,6 +19,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - **Import all missing classes.** A bulk code action that imports every unresolved class name in the file at once. Only names with a single unambiguous candidate are imported; ambiguous names are left for manual resolution via the single-class import action. Short-name conflicts are detected and skipped. Appears in the quick-fix menu when the cursor is on an unresolved class name and the file has two or more unresolved names.
 - **Context-aware import candidate filtering.** Import class actions now filter candidates by the syntactic context of the reference. After `implements` only interfaces are offered, after trait `use` only traits, after `extends` only classes or interfaces (as appropriate). This eliminates wrong-kind suggestions and reduces ambiguity for both single and bulk imports.
 
+### Fixed
+
+- **Analyzer and LSP no longer hang on files with deeply nested loops.** Files with multiple levels of foreach/while/for inside if-branches caused exponential blowup in the forward walker's two-pass loop strategy. A unified loop-depth guard now bounds re-walks regardless of code path (diagnostics, completion, hover), preventing hangs on previously stuck files across three test projects.
+
 ### Changed
 
 - **Rewritten variable resolver.** Variable type resolution now uses a single top-to-bottom pass through each function body on both the diagnostic and completion paths, with zero recursion and no depth limit.

docs/todo.md

@@ -25,6 +25,7 @@ within the same impact tier.
 
 | #   | Item                                                                                                                                                                | Impact   | Effort      |
 | --- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | ----------- |
+| P20 | [Forward walker: Mago-style assignment-depth-bounded loop iteration](todo/performance.md#p20-forward-walker-mago-style-assignment-depth-bounded-loop-iteration)      | High     | Medium      |
 | ER5 | [Mago-style separated metadata](todo/eager-resolution.md#er5--mago-style-separated-metadata) (pre-populated immutable codebase, O(1) method resolution)             | High     | High        |
 | P9  | [`resolved_class_cache` generic-arg specialisation](todo/performance.md#p9-resolved_class_cache-generic-arg-specialisation)                                         | Medium   | Medium      |
 | P18 | [Subtype result caching](todo/performance.md#p18-subtype-result-caching) (per-request HashMap for hierarchy walks)                                                  | Medium | Low         |

docs/todo/bugs.md

@@ -357,31 +357,6 @@ chosen, every URI stored in `ast_map`, `class_index`, `fqn_index`,
 absolute `file:///` URIs so that lookups and cache eviction work
 correctly regardless of how the tool was invoked.
 
-## B21 — `shared/src/database/Model/Products/Product.php` analysis hangs
-
-**Symptom:** `phpantom_lsp analyze --project-root shared -- src/database/Model/Products/Product.php`
-does not complete within 60 seconds (debug build). The other two
-baseline files (`BaseCsvProductUpdaterTemplate.php` and `Klarna.php`)
-complete in under 5 seconds. This was reproducible before and after
-the T25 backward-scanner removal, so it is not a regression from
-that work.
-
-**Likely cause:** The Product model is a large Eloquent model with
-many relations, scopes, accessors, and virtual members. The
-diagnostic pass likely triggers deep resolution chains (e.g.
-Builder generic substitution, relation return types, virtual member
-synthesis) that multiply into excessive work. A single expensive
-method body with many member-access diagnostics could account for
-the hang.
-
-**Where to fix:** Profile the analysis of this file to identify the
-hot path. Likely candidates: `resolve_target_classes` called
-repeatedly for the same subject within a single method body,
-`type_hint_to_classes` resolving the same generic type repeatedly
-without caching, or `inheritance::merge` being called redundantly
-for the same class. The `resolved_class_cache` (P9) may also help
-if generic-arg specialisation is implemented.
-
 ---
 
 ## B22 — `$this` resolves in static methods
@@ -454,3 +429,5 @@ statement. Possible causes:
 
 Once the root cause is understood, the re-entry guard can be removed
 in favour of a proper fix.
+
+

docs/todo/performance.md

@@ -772,6 +772,51 @@ resolution pipeline. See
 
 ---
 
+## P20. Forward walker: Mago-style assignment-depth-bounded loop iteration
+
+The forward walker's two-pass loop strategy (walk body once to
+discover assignments, merge, walk again) interacts multiplicatively
+with if-branch merging. Currently a `LOOP_DEPTH` counter hard-caps
+re-walks at depth 4 and bails out entirely at depth 8. This
+prevents hangs but sacrifices accuracy on deeply nested code.
+
+Mago (`references/mago/crates/analyzer/src/statement/loop/`) solves
+this properly with bounded iteration:
+
+1. **Assignment map.** Before analyzing a loop body, a cheap AST
+   walk (no type resolution) builds a map of which variables depend
+   on which other variables. The loop body is re-walked at most
+   `assignment_depth` times (typically 1–3), not proportional to
+   nesting depth.
+
+2. **Fixed-point early exit.** After each re-walk, check whether any
+   variable's type actually changed. If types have stabilized, stop.
+
+3. **Type widening.** Integer bounds widen (e.g. `int<0,5>` →
+   `int<0,max>`) to ensure convergence in few iterations.
+
+4. **Single-pass branch merging.** If/elseif/else branches are each
+   walked exactly once. Results are merged via type union into an
+   accumulator. Nesting an if inside a foreach does not multiply
+   walks.
+
+### Fix
+
+- Replace the `LOOP_DEPTH` hard cap with assignment-dependency-depth
+  counting.
+- Add fixed-point detection: compare scope before/after a re-walk
+  and stop when no types changed.
+- Consider type widening for integer literal types inside loops.
+
+### When to implement
+
+After the forward walker stabilizes (it is less than a week old).
+The current `LOOP_DEPTH` guard is sufficient to prevent hangs; this
+item improves accuracy on deeply nested loops without risking
+exponential blowup.
+
+---
+
 ## Appendix: Profiling
 
 ### Commands