The analyze and fix CLI subcommands no longer build the cross-file

reference index

Author: AJenbo

docs/CHANGELOG.md

@@ -55,6 +55,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - **Repeated class lookups are remembered instead of searched again.** Answering "which class does this name refer to?" is the single most frequent thing PHPantom does: analysing a large Laravel project asks it millions of times, over only a few thousand distinct classes. Every question used to hash the name and take a read lock on two shared indexes, so with one worker per CPU core the workers spent much of their time queueing behind each other instead of analysing. Each worker now remembers the answers it has already looked up and drops them the moment the class indexes change, so a repeated question costs a single pointer comparison. Whole-project analysis is 8-12% faster on large Laravel projects and uses up to a third less CPU, with identical results and no measurable change in memory use. Hover, completion, and go-to-definition resolve names through the same path and get the same saving.
 - **Vendor package scanning no longer reads every file twice.** Startup used to scan each vendor file once to find its classes, functions, and constants, then read and scan it again just to classify which package it came from for completion ranking. Each file's package is now known before it is scanned, so both are done in a single parallel pass, roughly halving the I/O and CPU cost of the vendor scan.
 - **Whole-workspace class pre-resolution now spreads across cores.** Resolving every known class in dependency order after indexing ran on a single core, leaving a single-threaded pause between the parallel index and the parallel diagnostic pass that grew with the number of classes in the project. That work is now shared across a pool of workers, which cuts the phase to roughly a quarter of its previous time on large Laravel projects and takes close to 20% off whole-project analysis on the largest of them. The editor's post-startup pre-resolution goes through the same path, so a large project becomes fully warm sooner. Results are unchanged.
+- **The `analyze` and `fix` CLI subcommands no longer build the cross-file reference index.** That index only serves Find References, Rename, and reference-count inlay hints, none of which the CLI subcommands ever query, so every file they parsed was still paying to populate it. Skipping the build removes that wasted CPU and short-lived allocation from whole-project `analyze` and `fix` runs; the editor's LSP session is unaffected.
 
 ### Removed
 

docs/todo.md

@@ -214,7 +214,6 @@ unlikely to move the needle for most users.
 | P21 | [Offset-shifting for cached diagnostics on partial edits](todo/performance.md#p21-offset-shifting-for-cached-diagnostics-on-partial-edits)                                  | Medium      | Medium      |
 | P23 | [`workspace/symbol` lowercases every symbol name per request](todo/performance.md#p23-workspacesymbol-allocates-a-lowercase-copy-of-every-symbol-name-per-request)          | Low-Medium  | Low         |
 | P28 | [`process_assert_narrowing` clones the scope per variable for every statement](todo/performance.md#p28-process_assert_narrowing-clones-the-top-level-scope-once-per-variable-for-every-statement) | Low-Medium  | Low         |
-| P42 | [Reference index is built during the headless `analyze` pipeline but never queried there](todo/performance.md#p42-reference-index-is-built-during-the-headless-analyze-pipeline-but-never-queried-there) | Low-Medium  | Low         |
 |     | **[Indexing](todo/indexing.md)**                                                                                                                                            |             |             |
 | X3  | Completion item detail on demand (`completionItem/resolve`)                                                                                                                 | Medium      | Medium      |
 | X7  | [Recency tracking](todo/indexing.md#x7-recency-tracking)                                                                                                                    | Medium      | Medium      |

docs/todo/performance.md

@@ -1049,28 +1049,6 @@ real ceiling than the hashing was.
 
 ---
 
-## P42. Reference index is built during the headless `analyze` pipeline but never queried there
-
-**Impact: Low-Medium · Effort: Low**
-
-`reindex_references_for_symbol_maps_batch` (`src/reference_index.rs`)
-runs on every `update_ast`, including from the parallel index workers
-in `src/analyse/run.rs` that back the headless `analyze` CLI
-subcommand. That pipeline never calls
-`reference_candidate_uris_for_keys` or any other reader of
-`reference_index` (it has no find-references, rename, or inlay-hints
-request to serve), so every span the workers walk to build index
-entries there is wasted CPU and short-lived allocation.
-
-Skip the build in that mode: add a per-`Backend` flag (not a
-process-global static or thread-local, so test isolation between
-`Backend` instances is preserved) that `Backend::new_headless` sets
-and `reindex_references_for_symbol_maps_batch` checks before doing any
-work, so the skip applies uniformly to every caller of `update_ast` in
-headless mode rather than special-casing the `analyze` call site.
-
----
-
 ## P43. `init_single_project` is the longest single-threaded stretch of a run
 
 **Impact: Medium-High · Effort: Medium**

src/lib.rs

@@ -446,6 +446,13 @@ pub struct Backend {
     /// candidate files, then run their existing semantic checks for aliases,
     /// inheritance, Laravel declarations, and `self/static/parent`.
     pub(crate) reference_index: reference_index::ReferenceIndex,
+    /// Skip building [`reference_index`] from `update_ast`.
+    ///
+    /// Set by [`Backend::new_headless`] for the `analyze`/`fix` CLI
+    /// subcommands, which parse every file but never issue a
+    /// find-references, rename, or inlay-hints request, so populating
+    /// the index would be pure wasted CPU and short-lived allocation.
+    pub(crate) skip_reference_index: bool,
     /// Per-file parse errors from the Mago parser.
     ///
     /// Each entry is `(message, start_byte_offset, end_byte_offset)`.
@@ -849,6 +856,7 @@ impl Backend {
             open_files: Arc::new(RwLock::new(HashMap::new())),
             symbol_maps: Arc::new(RwLock::new(HashMap::new())),
             reference_index: reference_index::new_reference_index(),
+            skip_reference_index: false,
             symbols: SymbolIndex::new(),
             workspace: WorkspaceEnv::new(),
             parse_errors: Arc::new(RwLock::new(HashMap::new())),
@@ -936,6 +944,7 @@ impl Backend {
             open_files: Arc::new(RwLock::new(HashMap::new())),
             symbol_maps: Arc::new(RwLock::new(HashMap::new())),
             reference_index: reference_index::new_reference_index(),
+            skip_reference_index: false,
             symbols: SymbolIndex::new(),
             workspace: WorkspaceEnv::new(),
             parse_errors: Arc::new(RwLock::new(HashMap::new())),
@@ -1021,7 +1030,10 @@ impl Backend {
     /// where there is no LSP client but the backend still needs access to
     /// the PHP standard library stubs.
     pub fn new_headless() -> Self {
-        Self::defaults()
+        Self {
+            skip_reference_index: true,
+            ..Self::defaults()
+        }
     }
 
     /// Create a `Backend` without an LSP client (for unit / integration tests).
@@ -1556,6 +1568,7 @@ impl Backend {
             open_files: Arc::clone(&self.open_files),
             symbol_maps: Arc::clone(&self.symbol_maps),
             reference_index: Arc::clone(&self.reference_index),
+            skip_reference_index: self.skip_reference_index,
             symbols: self.symbols.clone(),
             parse_errors: Arc::clone(&self.parse_errors),
             did_change_parse_locks: Arc::clone(&self.did_change_parse_locks),

src/reference_index.rs

@@ -125,7 +125,7 @@ impl Backend {
         &self,
         items: Vec<(String, Arc<SymbolMap>)>,
     ) {
-        if items.is_empty() {
+        if items.is_empty() || self.skip_reference_index {
             return;
         }
 
@@ -498,6 +498,19 @@ mod tests {
         assert!(backend.reference_index.read().is_empty());
     }
 
+    #[test]
+    fn headless_backend_skips_reference_indexing() {
+        let backend = Backend::new_headless();
+        let uri = "file:///project/src/Foo.php".to_string();
+
+        backend.reindex_references_for_symbol_maps_batch(vec![(
+            uri,
+            class_declaration_symbol_map("App\\Foo"),
+        )]);
+
+        assert!(backend.reference_index.read().is_empty());
+    }
+
     #[test]
     fn batch_reindex_skips_vendor_and_stub_uris() {
         let dir = tempfile::tempdir().expect("temp dir");