Faster Eloquent scope-method resolution

Author: AJenbo

docs/CHANGELOG.md

@@ -59,6 +59,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - **Faster diagnostics on method/function calls that resolve to no concrete class.** Checking whether such a call's result was actually a bare `object`/`?object` (still valid for member access) used to re-resolve the callee's whole receiver chain and method signature a second time from scratch. That check now reuses the resolution already performed, roughly halving diagnostics time on files with many unresolved or missing-method call chains.
 - **Argument checking no longer slows down quadratically with file size.** The argument-count and argument-type checks know the byte offset of every call they inspect, but used to convert it into an editor line/column position and immediately back again before looking up the called function. Each of those conversions re-read the file from the beginning to count characters, so the cost of checking one call grew with the size of the file around it and a file with thousands of calls spent nearly all its time on offset arithmetic. The offset is now used directly. On a 370 KB file containing 2200 calls the two checks together drop from 13.7 seconds to 0.2, taking the whole file from 16.7 seconds to 3.4, and analysing the project it belongs to is close to three times faster.
 - **Faster workspace symbol search.** Matching a symbol against the "Go to Symbol in Workspace" query no longer allocates a lowercased copy of every class, method, property, constant, and function name in the project on each keystroke; matching is now done byte-wise in place for the common case of ASCII identifiers.
+- **Faster Eloquent scope-method resolution.** Injecting a model's scope methods onto its Builder used to re-walk the model's full inheritance chain (traits and parent classes) from scratch on every `Builder<Model>` instantiation. That base resolution is now cached, so a file with many instantiations of the same model's Builder resolves its scopes once instead of repeatedly.
 
 ### Removed
 

docs/todo.md

@@ -200,7 +200,6 @@ unlikely to move the needle for most users.
 | P47 | [The resolved-class cache lock caps concurrent class resolution](todo/performance.md#p47-the-resolved-class-cache-lock-caps-concurrent-class-resolution)                     | Medium      | Medium-High |
 | P16 | [Pre-parsed stub format (eliminate raw PHP embedding)](todo/performance.md#p16-pre-parsed-stub-format-eliminate-raw-php-embedding)                                          | High        | Medium-High |
 | P22 | [Signature change re-queues slow diagnostics for every open file](todo/performance.md#p22-signature-change-re-queues-slow-diagnostics-for-every-open-file)                  | Medium-High | Medium      |
-| P11 | [Uncached base-resolution in `build_scope_methods_for_builder`](todo/performance.md#p11-uncached-base-resolution-in-build_scope_methods_for_builder)                        | Low-Medium  | Low         |
 | P3  | Parallel pre-filter in `find_implementors`                                                                                                                                  | Low-Medium  | Medium      |
 | P6  | O(n²) transitive eviction in `evict_fqn`                                                                                                                                    | Low         | Low         |
 | P15 | [Two-phase stub index construction (eliminate `RwLock` on stub maps)](todo/performance.md#p15-two-phase-stub-index-construction-eliminate-rwlock-on-stub-maps)              | Low         | Medium      |

docs/todo/performance.md

@@ -56,32 +56,6 @@ threshold (e.g. 8 files).
 
 ---
 
-## P11. Uncached base-resolution in `build_scope_methods_for_builder`
-
-**Impact: Low-Medium · Effort: Low**
-
-`build_scope_methods_for_builder` calls
-`resolve_class_with_inheritance` (base resolution) for the model
-class. This is not covered by the thread-local resolved-class
-cache, which stores fully-resolved classes (after virtual member
-injection), not base-resolved ones.
-
-Every time an Eloquent `Builder<Model>` is resolved with scope
-injection, the model is base-resolved from scratch. With many
-Builder instantiations in a single file this adds up.
-
-### Fix
-
-Either introduce a separate base-resolution cache (keyed by FQN),
-or restructure so `build_scope_methods_for_builder` accepts the
-already-resolved model class from the caller (which may already
-have it from the resolved-class cache). The caller
-(`inject_scopes_and_model_methods`) already has the resolved-class
-cache in scope — it passes it to `inject_model_virtual_methods`
-but not to this function.
-
----
-
 ## P15. Two-phase stub index construction (eliminate `RwLock` on stub maps)
 
 **Impact: Low · Effort: Medium**

src/virtual_members/laravel/scopes.rs

@@ -162,8 +162,10 @@ pub fn build_scope_methods_for_builder(
     // #[Scope] methods into their public-facing form (replacing the
     // original), which makes them invisible to `is_scope_method`.
     // Using the pre-provider resolution preserves the raw methods.
+    // Cached so that resolving many Builder instantiations of the same
+    // model in one file doesn't re-walk its inheritance chain each time.
     let resolved_model =
-        crate::inheritance::resolve_class_with_inheritance(&model_class, class_loader);
+        crate::virtual_members::resolve_class_base_cached(&model_class, class_loader);
     // Build a substitution map so that `static`, `$this`, and `self`
     // in scope return types resolve to the concrete model name.
     // The default scope return type is `\...\Builder<static>` where

src/virtual_members/mod.rs

@@ -60,6 +60,7 @@ pub use cache::{
 pub(crate) use cache::{
     TransformFingerprint, intern_transformed_method, intern_transformed_property,
 };
+pub(crate) use resolve::resolve_class_base_cached;
 pub use resolve::{
     populate_from_sorted, resolve_class_fully, resolve_class_fully_cached,
     resolve_class_fully_maybe_cached, resolve_class_fully_with_generics,

src/virtual_members/resolve.rs

@@ -27,7 +27,10 @@ use crate::util::short_name;
 use crate::virtual_members::laravel::patches::apply_laravel_patches;
 
 use super::laravel;
-use super::{ResolvedClassCache, ResolvedClassCacheKey, apply_virtual_members, default_providers};
+use super::{
+    ResolvedClassCache, ResolvedClassCacheKey, active_resolved_class_cache, apply_virtual_members,
+    default_providers,
+};
 
 // ─── Cycle breaking ─────────────────────────────────────────────────────────
 //
@@ -252,6 +255,56 @@ pub fn resolve_class_fully_maybe_cached(
     result
 }
 
+/// Reserved generic-args marker for [`resolve_class_base_cached`]'s cache
+/// key. Contains a NUL byte, which `PhpType::to_string()` never produces,
+/// so it can never collide with a real `(FQN, generic_args)` key.
+const BASE_RESOLUTION_MARKER: &str = "\0base";
+
+/// Resolve a class's base inheritance only (own members + traits +
+/// parent chain), skipping the walk on repeat lookups of the same class
+/// via the active [`ResolvedClassCache`].
+///
+/// This is the *pre-virtual-member-provider* stage of
+/// [`resolve_class_fully_inner`]: unlike [`resolve_class_fully`], it does
+/// not run virtual member providers, so scope methods (`scopeX` /
+/// `#[Scope]`) are still present in their raw, undecorated form — the
+/// Laravel provider replaces them with their public-facing scope method,
+/// which would make them invisible to callers that need to recognize the
+/// original scope declaration (e.g. Eloquent scope-method synthesis).
+///
+/// Stored under the same key space as the fully-resolved cache
+/// (`(FQN, generic_args)`), tagged with [`BASE_RESOLUTION_MARKER`] so it
+/// can never collide with a real generic instantiation. Sharing the key
+/// space means base-resolution entries ride along with the fully-resolved
+/// cache's existing FQN-keyed eviction (`evict_fqn`/`remove_all_variants`),
+/// which already removes every generic-arg variant of an invalidated FQN
+/// transitively through `reverse_deps` — a separate cache would have to
+/// duplicate that invalidation graph to stay correct.
+///
+/// Falls back to an uncached call to [`resolve_class_with_inheritance`]
+/// when no cache is active on this thread.
+pub(crate) fn resolve_class_base_cached(
+    class: &ClassInfo,
+    class_loader: &dyn Fn(&str) -> Option<Arc<ClassInfo>>,
+) -> Arc<ClassInfo> {
+    let Some(cache) = active_resolved_class_cache() else {
+        return Arc::new(resolve_class_with_inheritance(class, class_loader));
+    };
+
+    let key: ResolvedClassCacheKey = (class.fqn(), vec![BASE_RESOLUTION_MARKER.to_string()]);
+
+    {
+        let map = cache.read();
+        if let Some(cached) = map.get(&key) {
+            return Arc::clone(cached);
+        }
+    }
+
+    let result = Arc::new(resolve_class_with_inheritance(class, class_loader));
+    cache.write().insert(key, Arc::clone(&result));
+    result
+}
+
 /// Resolve a class fully and apply generic type argument substitution,
 /// caching the combined result under `(FQN, generic_arg_strings)`.
 ///