Improve startup performance

Author: AJenbo

docs/CHANGELOG.md

@@ -35,7 +35,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Changed
 
-- **Classes are pre-resolved for the whole workspace after startup.** Once the background index completes, every known class is resolved in dependency order even when workspace diagnostics are disabled, so the first completion, hover, or go-to-definition against any class reads a warm cache instead of resolving on demand. Edits still re-resolve only the affected classes. Contributed by @AJenbo.
+- **Classes are pre-resolved for the whole workspace after startup.** Once the background index completes, every known class is resolved in dependency order even when workspace diagnostics are disabled, so the first completion, hover, or go-to-definition against any class reads a warm cache instead of resolving on demand. Edits still re-resolve only the affected classes.
 - **Continuous progress reporting.** The indexing progress bar now advances file by file with live counts (e.g. "Scanning vendor packages (3201/8544 files)") instead of jumping between a few fixed milestones. This covers single-project, monorepo, and non-Composer workspaces. Go to Implementation, Find References, and Type Hierarchy show the same live progress while they scan, including when one of them triggers the first full workspace index.
 - **Property hover now shows effective types as a `var` detail line.** Property hovers now mirror method hovers by displaying the resolved/effective property type above the PHP snippet as `**var**`, while the snippet itself shows only the native PHP property declaration. This keeps docblock-inferred, virtual, and schema-derived property types out of the generated signature block. Contributed by @calebdw.
 - **Updated the bundled mago toolchain to 1.43.0.** The parser, docblock parser, formatter, and supporting crates are refreshed to the latest upstream release. Contributed by @enwi in https://github.com/PHPantom-dev/phpantom_lsp/pull/234.
@@ -46,7 +46,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Fixed
 
-- **Member resolution no longer degrades on deeply nested class dependencies.** Class resolution previously cut off at internal nesting limits, silently returning incomplete member sets (missing completions, spurious unknown-member diagnostics) on projects with deeply intertwined hierarchies and virtual members. Those limits are gone: only genuine dependency cycles, such as two Eloquent models whose relationships reference each other, fall back to a partial view, and they now do so deterministically instead of depending on which class happened to resolve first on a given thread. Contributed by @AJenbo.
+- **Member resolution no longer degrades on deeply nested class dependencies.** Class resolution previously cut off at internal nesting limits, silently returning incomplete member sets (missing completions, spurious unknown-member diagnostics) on projects with deeply intertwined hierarchies and virtual members. Those limits are gone: only genuine dependency cycles, such as two Eloquent models whose relationships reference each other, fall back to a partial view, and they now do so deterministically instead of depending on which class happened to resolve first on a given thread.
 - **Completion works after closing a multi-line closure argument on the same line as the next chain operator.** Typing `->` immediately after a call like `->map(function (...) { ... })->` now resolves the full receiver instead of returning no member suggestions until the operator is moved to a new line. Contributed by @calebdw.
 - **Conditional return types recognize interpolated strings as strings.** A function with a conditional return type like `($key is string ? mixed : null)` now correctly resolves the `string` branch when called with an interpolated string argument (e.g. `config("{$prefix}.host")`). Previously the interpolated string was not recognized as a string literal, causing the return type to fall through to the else branch and resolve as `null`. Contributed by @calebdw.
 - **Renaming a constructor-promoted property parameter now cascades to `$this->prop` usages.** Renaming `private int $someField` in a constructor's parameter list previously only updated the parameter declaration itself, leaving every `$this->someField` reference elsewhere in the class stale. Rename, find references, document highlight, and linked editing now treat a promoted property parameter the same as an ordinary property declaration.

docs/todo/performance.md

@@ -927,6 +927,67 @@ Fixes, cheapest first (each stands alone):
 
 ---
 
+## P34. Eager class population is single-threaded
+
+**Impact: Medium · Effort: Medium**
+
+`populate_from_sorted` (`src/virtual_members/resolve.rs`) resolves the
+toposorted class list in a serial loop on one dedicated thread, in both
+the `analyze` Phase 1.5 and the LSP server's post-index
+`eager_populate_resolved_classes`. On a large Laravel project this is
+~1 s of single-core work in a release build and scales linearly with
+class count; on very large workspaces it is a visible single-threaded
+stretch between the (parallel) index and the (parallel) diagnostics
+pass.
+
+Resolution is already safe to run concurrently: the cycle-break
+in-flight set is keyed by `(thread, FQN)`, and two threads resolving
+the same class merely duplicate work, with one result winning the
+cache write. Two directions:
+
+1. **Work-stealing over the sorted list.** N workers pull indices from
+   an atomic counter over the existing toposorted vector. Most
+   dependencies are already cached by the time a dependent is pulled;
+   occasional duplicated resolution near list neighbours is bounded and
+   correct. Smallest change.
+2. **Topological generations.** Have the toposort emit levels
+   (classes whose dependencies are all in earlier levels) and fan each
+   level out across a scoped thread pool with a barrier between levels.
+   No duplicated work, slightly more coordination.
+
+Both need the workers on `PARSE_WORKER_STACK_SIZE` stacks, matching the
+current single populate thread.
+
+---
+
+## P35. Diagnostic passes reach only a fraction of available cores
+
+**Impact: Medium-High · Effort: Medium**
+
+Measured on a 32-core machine against a large Laravel project (release
+build): the `analyze` Phase 2 diagnostic pass runs at ~2 to ~13 cores,
+averaging roughly 4, despite spawning one worker per core with atomic
+work-stealing. Utilisation is lowest at the start of the pass and
+climbs as it progresses, which points at lock contention that eases as
+shared caches warm, rather than at work starvation. Likely suspects:
+`find_or_load_class` taking write locks while lazily parsing vendor
+files early in the pass, and write contention on the resolved-class
+cache and chain-resolution caches. The LSP workspace diagnostics pass
+uses the same collectors and likely has the same ceiling. Needs
+profiling to attribute the blocked time before picking a fix;
+re-measure after any change with the CPU-sampling loop in the Appendix.
+
+Projects that keep substantial code in `vendor/` (e.g. models shipped
+in a shared vendor package that the application depends on) hit this
+harder: eager population only walks classes from the indexed user
+files, so every vendor class is parsed lazily on first touch during
+the diagnostic pass. The observed CPU shape on such a project is
+bursty (alternating stalls and full-core bursts) consistent with one
+worker holding the load lock while the rest wait, then all proceeding
+until the next unparsed vendor class.
+
+---
+
 # Remaining anti-pattern fixes
 
 Most remaining depth-cap issues are addressed by ER5 (class

src/reference_index.rs

@@ -40,10 +40,36 @@ pub(crate) struct ReferenceIndexEntry {
     pub(crate) is_declaration: bool,
 }
 
-pub(crate) type ReferenceIndex = Arc<RwLock<HashMap<ReferenceIndexKey, Vec<ReferenceIndexEntry>>>>;
+/// The candidate index plus a reverse map of which keys each URI has
+/// entries under.
+///
+/// The reverse map keeps per-file eviction proportional to that file's
+/// own contributions.  Without it, evicting a URI means scanning every
+/// entry of every key in the index — an O(whole-index) pass under the
+/// write lock that serialises the parallel indexing workers (each file
+/// they publish evicts itself first) and grows with workspace size on
+/// every keystroke.
+#[derive(Default)]
+pub(crate) struct ReferenceIndexInner {
+    by_key: HashMap<ReferenceIndexKey, Vec<ReferenceIndexEntry>>,
+    uri_keys: HashMap<String, Vec<ReferenceIndexKey>>,
+}
+
+impl ReferenceIndexInner {
+    pub(crate) fn get(&self, key: &ReferenceIndexKey) -> Option<&Vec<ReferenceIndexEntry>> {
+        self.by_key.get(key)
+    }
+
+    #[cfg(test)]
+    pub(crate) fn is_empty(&self) -> bool {
+        self.by_key.is_empty()
+    }
+}
+
+pub(crate) type ReferenceIndex = Arc<RwLock<ReferenceIndexInner>>;
 
 pub(crate) fn new_reference_index() -> ReferenceIndex {
-    Arc::new(RwLock::new(HashMap::new()))
+    Arc::new(RwLock::new(ReferenceIndexInner::default()))
 }
 
 impl Backend {
@@ -103,12 +129,18 @@ impl Backend {
             .filter_map(|(idx, item)| keep[idx].then_some(item))
             .collect();
 
-        let batch_uris: HashSet<String> = rebuilt.iter().map(|(uri, _)| uri.clone()).collect();
         let mut index = self.reference_index.write();
-        evict_reference_index_uris_locked(&mut index, &batch_uris);
-        for (_uri, entries) in rebuilt {
+        for (uri, _) in &rebuilt {
+            evict_reference_index_uri_locked(&mut index, uri);
+        }
+        for (uri, entries) in rebuilt {
+            let mut keys: HashSet<ReferenceIndexKey> = HashSet::new();
             for (key, entry) in entries {
-                index.entry(key).or_default().push(entry);
+                index.by_key.entry(key.clone()).or_default().push(entry);
+                keys.insert(key);
+            }
+            if !keys.is_empty() {
+                index.uri_keys.insert(uri, keys.into_iter().collect());
             }
         }
     }
@@ -272,28 +304,18 @@ impl Backend {
     }
 }
 
-fn evict_reference_index_uri_locked(
-    index: &mut HashMap<ReferenceIndexKey, Vec<ReferenceIndexEntry>>,
-    uri: &str,
-) {
-    index.retain(|_, entries| {
-        entries.retain(|entry| entry.uri != uri);
-        !entries.is_empty()
-    });
-}
-
-fn evict_reference_index_uris_locked(
-    index: &mut HashMap<ReferenceIndexKey, Vec<ReferenceIndexEntry>>,
-    uris: &HashSet<String>,
-) {
-    if uris.is_empty() {
+fn evict_reference_index_uri_locked(index: &mut ReferenceIndexInner, uri: &str) {
+    let Some(keys) = index.uri_keys.remove(uri) else {
         return;
+    };
+    for key in keys {
+        if let Some(entries) = index.by_key.get_mut(&key) {
+            entries.retain(|entry| entry.uri != uri);
+            if entries.is_empty() {
+                index.by_key.remove(&key);
+            }
+        }
     }
-
-    index.retain(|_, entries| {
-        entries.retain(|entry| !uris.contains(entry.uri.as_str()));
-        !entries.is_empty()
-    });
 }
 
 fn normalize_symbol_name(name: impl AsRef<str>) -> String {
@@ -574,20 +596,23 @@ mod tests {
     }
 
     #[test]
-    fn empty_batch_evict_and_zero_member_offset_are_noops() {
-        let mut index = HashMap::new();
-        index.insert(
-            ReferenceIndexKey::Class("Foo".to_string()),
+    fn evicting_unknown_uri_and_zero_member_offset_are_noops() {
+        let mut index = ReferenceIndexInner::default();
+        let key = ReferenceIndexKey::Class("Foo".to_string());
+        let uri = "file:///project/src/Foo.php".to_string();
+        index.by_key.insert(
+            key.clone(),
             vec![ReferenceIndexEntry {
-                uri: "file:///project/src/Foo.php".to_string(),
+                uri: uri.clone(),
                 start: 0,
                 end: 3,
                 is_declaration: true,
             }],
         );
+        index.uri_keys.insert(uri, vec![key.clone()]);
 
-        evict_reference_index_uris_locked(&mut index, &HashSet::new());
-        assert!(index.contains_key(&ReferenceIndexKey::Class("Foo".to_string())));
+        evict_reference_index_uri_locked(&mut index, "file:///project/src/Other.php");
+        assert!(index.by_key.contains_key(&key));
         assert_eq!(member_range(0, "name", true), None);
     }