Invalidate mixin cache on file change to prevent stale members

Author: AJenbo

docs/CHANGELOG.md

@@ -59,6 +59,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Fixed
 
+- **Stale mixin members after editing.** Mixin class resolution (e.g. `@mixin Builder`) is now invalidated when any file changes, so newly added or removed methods on mixin targets appear immediately without restarting the server.
 - **Version-gated stub constants now filtered.** Constants with `@removed` tags (e.g. `MCRYPT_ENCRYPT`, removed in PHP 7.2) are now excluded from completion and resolution when the project targets a newer PHP version. Previously only classes and functions were filtered.
 - **Go-to-definition.** Fixed a potential deadlock when navigating to a vendor class that hadn't been parsed yet.
 - **LSP no longer freezes under heavy editor activity.** Server-to-client requests (diagnostic refresh, progress token creation) could deadlock the service loop when the editor was simultaneously sending bursts of open/close/hover messages. All server-to-client requests are now either fire-and-forget or time-bounded, long-running handlers are cancellation-safe, and the process exits cleanly if the service loop ever terminates unexpectedly.

docs/todo/refactor.md

@@ -258,15 +258,6 @@ only during diagnostic/analyse passes. Completion and hover re-resolve callable
 targets and re-parse files from scratch. Extending these to all consumers would
 avoid redundant work.
 
-### `MIXIN_CACHE` never invalidated
-
-`src/virtual_members/phpdoc.rs` `MIXIN_CACHE` is a thread-local
-`HashMap<String, Arc<ClassInfo>>` that caches resolved mixin classes. It is used
-by all consumers (completion, hover, diagnostics) but is never cleared during
-normal LSP operation. If a mixin class definition changes (e.g. a method is added
-to `Illuminate\Database\Eloquent\Builder`), the cache serves stale data until the
-thread dies. Needs content-hash or generation-counter invalidation.
-
 ---
 
 ## Redundant backwards text walkers

src/parser/ast_update.rs

@@ -33,6 +33,10 @@ impl Backend {
     /// changed (or a class was added/removed), meaning other open files
     /// that reference those classes may have stale diagnostics.
     pub fn update_ast(&self, uri: &str, content: &str) -> bool {
+        // Invalidate thread-local mixin cache so stale ClassInfo is not
+        // served after a file changes.
+        crate::virtual_members::phpdoc::bump_mixin_generation();
+
         let content_to_parse = if self.is_blade_file(uri) {
             let (virtual_php, source_map) = crate::blade::preprocessor::preprocess(content);
             self.blade_source_maps

src/virtual_members/phpdoc.rs

@@ -18,6 +18,7 @@
 
 use std::cell::RefCell;
 use std::collections::{HashMap, HashSet};
+use std::sync::atomic::{AtomicU64, Ordering};
 use std::sync::Arc;
 
 use crate::atom::{Atom, atom};
@@ -31,6 +32,17 @@ use crate::types::{
 };
 use crate::util::short_name;
 
+/// Global generation counter, incremented every time a file is re-parsed.
+/// Thread-local caches compare against this to detect staleness.
+static MIXIN_GENERATION: AtomicU64 = AtomicU64::new(0);
+
+/// Bump the mixin-cache generation so that all threads discard stale entries
+/// on their next access.  Called from [`Backend::update_ast`] whenever a file
+/// changes.
+pub fn bump_mixin_generation() {
+    MIXIN_GENERATION.fetch_add(1, Ordering::Relaxed);
+}
+
 thread_local! {
     /// Thread-local cache of base-resolved mixin classes.
     ///
@@ -40,11 +52,10 @@ thread_local! {
     /// `\Illuminate\Database\Eloquent\Builder`) are performed at most
     /// once per thread.
     ///
-    /// Must be cleared between test runs via [`clear_mixin_cache`]
-    /// because different tests may define classes with the same short
-    /// name but different members.
-    static MIXIN_CACHE: RefCell<HashMap<String, Arc<ClassInfo>>> =
-        RefCell::new(HashMap::new());
+    /// Automatically invalidated when the global generation counter
+    /// advances (i.e. when any file is re-parsed).
+    static MIXIN_CACHE: RefCell<(u64, HashMap<String, Arc<ClassInfo>>)> =
+        RefCell::new((0, HashMap::new()));
 }
 
 /// Clear the thread-local mixin resolution cache.
@@ -55,7 +66,24 @@ thread_local! {
 /// different members.  Call this function when creating a new test
 /// backend so that stale entries from a previous test do not leak.
 pub fn clear_mixin_cache() {
-    MIXIN_CACHE.with(|cache| cache.borrow_mut().clear());
+    MIXIN_CACHE.with(|cache| {
+        let mut inner = cache.borrow_mut();
+        inner.0 = MIXIN_GENERATION.load(Ordering::Relaxed);
+        inner.1.clear();
+    });
+}
+
+/// Ensure the thread-local cache is current with the global generation.
+/// Clears the cache if stale.
+fn ensure_mixin_cache_fresh() {
+    MIXIN_CACHE.with(|cache| {
+        let current_gen = MIXIN_GENERATION.load(Ordering::Relaxed);
+        let mut inner = cache.borrow_mut();
+        if inner.0 != current_gen {
+            inner.0 = current_gen;
+            inner.1.clear();
+        }
+    });
 }
 
 /// Tracks member names already seen during mixin collection.
@@ -603,6 +631,7 @@ fn collect_mixin_members(
         //
         // Results are cached in a thread-local map so that the same
         // mixin (e.g. Builder) is only resolved once per thread.
+        ensure_mixin_cache_fresh();
         let resolved_mixin = if let Some(c) = cache {
             let map = c.lock();
             if let Some(cached) = map.get(&(Atom::from(&resolved_mixin_name), Vec::new())) {
@@ -611,7 +640,7 @@ fn collect_mixin_members(
                 drop(map);
                 MIXIN_CACHE.with(|thread_cache| {
                     let mut map = thread_cache.borrow_mut();
-                    Arc::clone(map.entry(resolved_mixin_name.clone()).or_insert_with(|| {
+                    Arc::clone(map.1.entry(resolved_mixin_name.clone()).or_insert_with(|| {
                         Arc::new(crate::inheritance::resolve_class_with_inheritance(
                             &mixin_class,
                             class_loader,
@@ -622,7 +651,7 @@ fn collect_mixin_members(
         } else {
             MIXIN_CACHE.with(|thread_cache| {
                 let mut map = thread_cache.borrow_mut();
-                Arc::clone(map.entry(resolved_mixin_name.clone()).or_insert_with(|| {
+                Arc::clone(map.1.entry(resolved_mixin_name.clone()).or_insert_with(|| {
                     Arc::new(crate::inheritance::resolve_class_with_inheritance(
                         &mixin_class,
                         class_loader,