Saving a file no longer re-analyses every other open tab

Author: AJenbo

docs/CHANGELOG.md

@@ -60,6 +60,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - **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.
+- **Saving a file no longer re-analyses every other open tab.** A save used to re-run the full diagnostic pass, the most expensive thing PHPantom does, on all open files in case any of them depended on the saved one. It now works out what the save actually changed (a class, one of its members, a function, a constant) and re-analyses only the open files that mention one of those names. Editing a method body reaches only the files that use the class, and renaming or retyping a member reaches only the files that use that member; unrelated tabs are left alone, so completion and hover stay responsive right after a save. Cases the comparison cannot narrow, such as saving a Laravel config, translation, or route file, still refresh every open file as before.
 
 ### Removed
 

docs/todo.md

@@ -199,7 +199,6 @@ unlikely to move the needle for most users.
 | P30 | [Evaluate migrating parse/resolve/docblock pipeline to `mago-hir`](todo/performance.md#p30-evaluate-migrating-parseresolvedocblock-pipeline-to-mago-hir) (parked — re-evaluated at mago 1.45.0, still no `mago-hir` consumers upstream) | Medium-High | High        |
 | 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      |
 | 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

@@ -497,44 +497,6 @@ diagnostic layer.
 
 ---
 
-## P22. Signature change re-queues slow diagnostics for every open file
-
-**Impact: Medium-High · Effort: Medium**
-
-When a file is saved, `schedule_diagnostics_for_open_files`
-(`src/diagnostics/mod.rs`, called from `did_save` in
-`src/server.rs`) queues **all** open files (minus the saved one)
-for a full slow-diagnostic pass — unknown classes, unknown
-members, argument checks. The per-file cost of that pass is the
-most expensive thing the server does (see the Appendix: tens of
-seconds on pathological files, hundreds of ms on ordinary ones).
-
-A user with 20 tabs open therefore pays 20 full-file analysis
-passes per save, regardless of whether those files reference the
-edited class at all. (This used to fire on every signature-changing
-edit; it is now save-gated, which caps the frequency but not the
-O(open files) fan-out.) During the burst the diagnostic worker
-saturates blocking threads that completion/hover also need.
-
-### Fix
-
-Queue only files that can observe the change. The resolved-class
-cache already maintains a dependency index for transitive
-eviction (`evict_fqn`), and ER4 tracks which members changed.
-Build a reverse map (FQN → open files that reference it) — either
-from each file's `resolved_names` (which byte-offset FQN lookups
-already exist for) or by recording, during each diagnostic pass,
-which FQNs the pass touched. On signature change, queue only the
-dependent files. Falls back to all-open-files when the dependency
-data is missing (e.g. right after startup).
-
-Synergy: P21 (offset-shifting) reduces the cost of re-diagnosing
-the *edited* file; this item reduces the *count* of other files
-re-diagnosed. Together they make the slow pass proportional to
-the blast radius of an edit.
-
----
-
 ## P46. `mago-phpdoc-syntax` cannot parse `@method static (…) name()`
 
 **Impact: Low · Effort: Low (upstream)**

src/diagnostics/mod.rs

@@ -177,6 +177,7 @@
 mod argument_count;
 pub(crate) mod class_case_mismatch;
 pub(crate) mod class_name_mismatch;
+pub(crate) mod cross_file;
 mod deprecated;
 mod external;
 pub(crate) mod helpers;
@@ -882,31 +883,30 @@ impl Backend {
         self.schedule_mago_analyze(uri);
     }
 
-    /// Invalidate diagnostics for all open files after a cross-file change.
+    /// Invalidate diagnostics for the open files a save can affect.
     ///
-    /// Called when a class signature changes in one file, because
-    /// diagnostics in other open files (unknown member, unknown class,
-    /// deprecated usage) may depend on the changed class.  The edited
-    /// file itself is excluded (it is already scheduled by the caller).
+    /// Diagnostics in other open files (unknown member, unknown class,
+    /// deprecated usage, argument checks) can depend on the saved file, so
+    /// they have to be recomputed — but only for the files that reference
+    /// something the save changed.  [`open_files_affected_by_save`] works
+    /// out which those are, and falls back to every open file when it
+    /// cannot tell.  The saved file itself is excluded (it is already
+    /// scheduled by the caller).
     ///
-    /// **Push mode:** Queues all open files for the background worker.
+    /// **Push mode:** Queues those files for the background worker.
     ///
     /// **Pull mode:** Invalidates cached full diagnostics and sends
     /// `workspace/diagnostic/refresh` so the editor re-pulls.
+    ///
+    /// [`open_files_affected_by_save`]: Backend::open_files_affected_by_save
     pub(crate) fn schedule_diagnostics_for_open_files(&self, exclude_uri: &str) {
         if !self.init_complete.load(Ordering::Acquire) {
             return;
         }
 
         let pull_mode = self.supports_pull_diagnostics.load(Ordering::Acquire);
 
-        let uris: Vec<String> = self
-            .open_files
-            .read()
-            .keys()
-            .filter(|u| u.as_str() != exclude_uri)
-            .cloned()
-            .collect();
+        let uris = self.open_files_affected_by_save(exclude_uri);
         if uris.is_empty() {
             return;
         }

src/diagnostics/state.rs

@@ -38,6 +38,10 @@ pub(crate) struct DiagnosticState {
     pub(crate) workspace_diags: Arc<Mutex<WorkspaceDiagnostics>>,
     /// Prevents duplicate background workspace diagnostics passes.
     pub(crate) workspace_diag_pass_started: Arc<AtomicBool>,
+    /// What each open file declared when it was last opened or saved, used
+    /// to work out which other open files a save can affect.  See
+    /// [`crate::diagnostics::cross_file`].
+    pub(crate) decl_baselines: Arc<Mutex<crate::diagnostics::cross_file::DeclarationBaselines>>,
 }
 
 impl DiagnosticState {
@@ -53,6 +57,7 @@ impl DiagnosticState {
             suppressed: Arc::new(Mutex::new(Vec::new())),
             workspace_diags: Arc::new(Mutex::new(WorkspaceDiagnostics::default())),
             workspace_diag_pass_started: Arc::new(AtomicBool::new(false)),
+            decl_baselines: Arc::new(Mutex::new(HashMap::new())),
         }
     }
 }

src/reference_index.rs

@@ -121,6 +121,35 @@ impl Backend {
         Some(uris)
     }
 
+    /// Narrow `uris` to the files that reference one of `keys`.
+    ///
+    /// A file the index does not track at all is kept: the index skips
+    /// vendor files and stubs, and only records a file once it has been
+    /// parsed, so an absent entry means "references unknown" rather than
+    /// "references nothing".  Returns `false` without touching `uris` when
+    /// the index cannot answer yet (the workspace is still being indexed).
+    pub(crate) fn retain_reference_candidates(
+        &self,
+        keys: &[ReferenceIndexKey],
+        uris: &mut Vec<String>,
+    ) -> bool {
+        if !self.workspace_indexed.load(Ordering::Acquire) {
+            return false;
+        }
+
+        let index = self.reference_index.read();
+        let mut candidates = HashSet::new();
+        for key in keys {
+            if let Some(entries) = index.get(key) {
+                candidates.extend(entries.keys().map(Arc::as_ref));
+            }
+        }
+        uris.retain(|uri| {
+            candidates.contains(uri.as_str()) || !index.uri_keys.contains_key(uri.as_str())
+        });
+        true
+    }
+
     pub(crate) fn reindex_references_for_symbol_maps_batch(
         &self,
         items: Vec<(String, Arc<SymbolMap>)>,

src/server.rs

@@ -617,6 +617,10 @@ impl LanguageServer for Backend {
         // Parse and update AST map, use map, and namespace map
         self.update_ast(&uri, &text);
 
+        // Baseline for the first save: without it, that save would have to
+        // re-diagnose every open file to be safe.
+        self.capture_declaration_baseline(&uri);
+
         // Schedule diagnostics asynchronously so that the first-open
         // response is not blocked by lazy stub parsing (which can take
         // tens of seconds when many class references trigger cache-miss
@@ -750,6 +754,7 @@ impl LanguageServer for Backend {
 
         self.open_files.write().remove(&uri);
         self.did_change_parse_locks.lock().remove(&uri);
+        self.clear_declaration_baseline(&uri);
 
         // Drop coalescing state for this file so the maps don't grow unbounded
         // across an editing session.

src/types/mod.rs

@@ -2108,6 +2108,18 @@ impl ClassInfo {
     /// - `class_docblock` (adding/removing `@method`/`@property` tags)
     /// - `laravel` metadata (affects virtual member providers)
     pub fn signature_eq(&self, other: &ClassInfo) -> bool {
+        self.class_level_signature_eq(other) && self.members_signature_eq(other)
+    }
+
+    /// The class-level half of [`signature_eq`](Self::signature_eq):
+    /// everything except the declared methods, properties, and constants.
+    ///
+    /// A change here (a new parent, a different `@mixin`, an edited
+    /// class docblock, changed Laravel metadata) can alter *any* member's
+    /// resolution, so callers that want to know which members an edit
+    /// affected must treat the whole member surface as affected when this
+    /// returns `false`.
+    pub fn class_level_signature_eq(&self, other: &ClassInfo) -> bool {
         // ── Class-level metadata ────────────────────────────────────
         if self.kind != other.kind
             || self.name != other.name
@@ -2139,6 +2151,13 @@ impl ClassInfo {
             return false;
         }
 
+        true
+    }
+
+    /// The member half of [`signature_eq`](Self::signature_eq): the
+    /// declared methods, properties, and constants, compared as
+    /// name-keyed sets so reordering members in source is not a change.
+    pub fn members_signature_eq(&self, other: &ClassInfo) -> bool {
         // ── Methods (compared as a name-keyed set) ──────────────────
         if self.methods.len() != other.methods.len() {
             return false;