Activate chain resolution cache for all LSP handlers

Author: AJenbo

docs/CHANGELOG.md

@@ -27,6 +27,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 - **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.
 - **Broader type narrowing.** `instanceof`, type-guard functions (`is_array`, `is_string`, etc.), `in_array()` strict mode, `assert()`, `@phpstan-assert-if-true`/`-if-false`, and compound `&&`/`||` conditions now narrow variable types in if/else branches, guard clauses, while-loop bodies, ternary expressions, and `match(true)` arms. Negated guards and compound conditions like `if (!$x instanceof A && !$x instanceof B) { return; }` are handled correctly.
+- **Chain resolution cache.** The per-request chain resolution cache that eliminates redundant re-resolution of shared chain prefixes is now active for all LSP handlers (completion, hover, go-to-definition, signature help, etc.), not just diagnostics.
 - **Closure and arrow function parameter inference.** Untyped closure and arrow function parameters are inferred from the enclosing call's callable signature, including through method chains that return `static`. Generic type substitution flows through to inferred parameters (e.g. a `callable(T)` parameter on a `Repository<Product>` resolves `T` to `Product`).
 - **Editing responsiveness.** Classes evicted from the resolved-class cache after a file edit are now eagerly re-populated in dependency order, eliminating lazy resolution delays for diagnostics and completions.
 - **Virtual member resolution.** Virtual member providers (PHPDoc mixins, Laravel model, Eloquent Builder) now resolve completely on every class, eliminating cases where mixins or Eloquent accessors were missing after edits.

docs/todo.md

@@ -25,7 +25,6 @@ within the same impact tier.
 
 | #   | Item                                                                                                                                                                | Impact      | Effort      |
 | --- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- | ----------- |
-| P26 | [Chain resolution cache only active during diagnostics](todo/performance.md#p26-chain-resolution-cache-only-active-during-diagnostics)                               | Medium      | Low         |
 | P24 | [`IN_ARRAY_KEY_ASSIGN` re-entry guard in forward walker](todo/performance.md#p24-in_array_key_assign-re-entry-guard-in-forward-walker)                              | Low         | Low         |
 | P20 | [Forward walker: bounded iteration and depth-cap cleanup](todo/performance.md#p20-forward-walker-bounded-iteration-and-depth-cap-cleanup)                            | High        | Medium      |
 | ER5 | [Mago-style separated metadata](todo/eager-resolution.md#er5--mago-style-separated-metadata)                                                                        | High        | High        |

docs/todo/performance.md

@@ -884,67 +884,4 @@ path entirely and the `IN_ARRAY_KEY_ASSIGN` guard can be removed.
 
 ---
 
-## P26. Chain resolution cache only active during diagnostics
 
-**Impact: Medium · Effort: Low**
-
-`completion/resolver.rs` lines ~41-65 define a `CHAIN_CACHE`
-thread-local that caches `resolve_target_classes` results by subject
-text. This cache is activated by `with_chain_resolution_cache` and
-is only enabled during diagnostic passes (via `analyse.rs`). During
-completion and hover, the cache is inactive and every chain prefix
-is re-resolved from scratch.
-
-This means that typing `$model->where(...)->orderBy(...)->` in a
-completion context re-resolves `$model->where(...)` even though it
-was just resolved moments ago for `$model->where(...)->orderBy(...)`.
-
-Similarly, the `DIAGNOSTIC_SCOPE` cache (forward walker scope
-snapshots, lines ~57-156) is only populated during diagnostic
-passes. Hover and completion use a separate code path
-(`resolve_variable_types` with backward scanning or forward walk
-without caching), which can produce subtly different results because
-the diagnostic path's forward walker records scope at every
-statement boundary while the completion path only walks to the
-cursor position.
-
-### What this causes
-
-1. **Completion is slower than diagnostics** for chain expressions,
-   because diagnostics benefit from the chain cache but completion
-   does not.
-2. **Hover and completion can disagree** on a variable's type when
-   the forward walker's single-cursor walk produces a different
-   scope state than the diagnostic pass's full-file walk (e.g. due
-   to branch merging order or loop depth cutoffs).
-
-### How the reference projects handle this
-
-PHPStan's `MutatingScope` stores a `$resolvedTypes` array that
-caches every expression type resolved via `getType()`. The scope is
-the same object regardless of whether the caller is a rule
-(diagnostic), a return type extension, or any other consumer. There
-is no consumer-specific mode.
-
-Phpactor has three caching layers that are all consumer-agnostic:
-(1) `NodeContextResolver` caches per AST node via `spl_object_id`.
-(2) `FrameResolver` caches the entire variable frame per scope node.
-(3) `MemonizedReflector` caches reflected classes. All three are
-active for every operation (completion, hover, go-to-definition).
-The source comment notes: "The cache should only have a lifetime of
-the current operation."
-
-### Fix
-
-1. Activate the chain resolution cache for completion and hover
-   requests, not just diagnostics. The cache is cheap (a HashMap
-   cleared per request) and the chain prefix re-resolution is the
-   dominant cost for fluent API chains.
-2. Unify the scope resolution path: when the diagnostic scope cache
-   is available (file has been analyzed), use it for hover and
-   completion as well. Fall back to cursor-targeted forward walk
-   only when no cached scopes exist.
-3. Long-term: move toward a per-request expression type cache
-   (similar to PHPStan's `$resolvedTypes` or Phpactor's
-   `spl_object_id` cache) that all consumers share, eliminating
-   the need for separate chain and scope caches.

src/completion/handler.rs

@@ -269,6 +269,11 @@ impl Backend {
         let content = self.get_file_content(&uri);
 
         if let Some(content) = content {
+            // Activate the chain resolution cache so that shared chain
+            // prefixes are resolved once and reused within this completion
+            // request.  The guard is re-entrant safe.
+            let _chain_guard = super::resolver::with_chain_resolution_cache();
+
             // Gather per-file context (classes, use-map, namespace) in one
             // call instead of three separate lock-and-unwrap blocks.
             let ctx = self.file_context(&uri);

src/completion/resolver.rs

@@ -51,10 +51,10 @@ use crate::virtual_members::resolve_class_fully_maybe_cached;
 // the first method call 5 times, etc. — O(depth²) total work.
 //
 // The chain cache stores `resolve_target_classes` results keyed by the
-// raw subject text string.  It is activated at the diagnostic loop level
-// (via [`with_chain_resolution_cache`]) and consulted by
-// `resolve_target_classes` before doing any work.  When the cache is not
-// active (completion, hover, etc.) the function behaves exactly as before.
+// raw subject text string.  It is activated per-request for all LSP
+// handlers (completion, hover, definition, diagnostics, etc.) via
+// [`with_chain_resolution_cache`] and consulted by
+// `resolve_target_classes` before doing any work.
 
 thread_local! {
     /// When `Some`, `resolve_target_classes` will consult and populate

src/server.rs

@@ -1022,6 +1022,12 @@ impl Backend {
         f: impl FnOnce(&str) -> T,
     ) -> Option<T> {
         let content = self.get_file_content(uri)?;
+        // Activate the chain resolution cache so that shared chain prefixes
+        // (e.g. `$model->where(...)` in `$model->where(...)->orderBy(...)`)
+        // are resolved once and reused across all LSP handlers, not just
+        // diagnostics.  The guard is re-entrant safe: if a diagnostic pass
+        // already activated the cache, this is a no-op.
+        let _chain_guard = crate::completion::resolver::with_chain_resolution_cache();
         crate::util::catch_panic_unwind_safe(handler_name, uri, position, || f(&content))
     }