Add look up table for FQN to cache

Author: AJenbo

docs/CHANGELOG.md

@@ -26,6 +26,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - **Attribute constructor signature help.** Signature help and named parameter completion now fire inside PHP 8 attribute parentheses (`#[Route('/path', <>)]`), showing the attribute class's constructor parameters.
 - **Closure variable scope isolation.** Variables declared outside a closure are no longer offered as completions inside the closure body unless captured via `use()`. Previously outer variables leaked into closure scope.
 
+### Changed
+
+- **Faster class lookups.** Class resolution now uses an O(1) hash-map lookup by fully-qualified name instead of scanning every parsed file. Projects with hundreds of open files see reduced latency on completion, hover, and go-to-definition requests.
+
 ### Fixed
 
 - **Signature help on function definitions.** Signature help no longer fires when the cursor is inside a function or method definition's parameter list (e.g. `function foo(int $a, |)`). Previously it could incorrectly show the signature of a same-named global function.

docs/todo.md

@@ -76,11 +76,11 @@ parallel file processing.
 | 76 | Inline Variable | Medium | Code Actions | [actions.md §7](todo/actions.md#7-inline-variable) |
 | 77 | Extract Variable | Medium | Code Actions | [actions.md §8](todo/actions.md#8-extract-variable) |
 | 78 | Inline Function/Method | High | Code Actions | [actions.md §9](todo/actions.md#9-inline-functionmethod) |
-| 82 | FQN secondary index for `find_class_in_ast_map` | Low | Performance | [performance.md §1](todo/performance.md#1-fqn-secondary-index-for-find_class_in_ast_map) |
 | 84 | `HashSet` dedup in inheritance merging | Low | Performance | [performance.md §4](todo/performance.md#4-hashset-dedup-in-inheritance-merging) |
 | 87 | Reference-counted `ClassInfo` (`Arc<ClassInfo>`) | Medium | Performance | [performance.md §2](todo/performance.md#2-reference-counted-classinfo-arcclassinfo) |
 | 88 | Early-exit and `Cow` return in `apply_substitution` | Low | Performance | [performance.md §7](todo/performance.md#7-recursive-string-substitution-in-apply_substitution) |
 | 90 | Lazy autoload file indexing | Medium | Indexing | [indexing.md §2.5](todo/indexing.md#phase-25-lazy-autoload-file-indexing) |
+| 91 | Non-Composer function/constant discovery | Low | Indexing | [indexing.md §2.6](todo/indexing.md#phase-26-non-composer-function-and-constant-discovery) |
 
 ---
 

docs/todo/indexing.md

@@ -327,6 +327,102 @@ limitation applies to the classmap scanner today.
 
 ---
 
+## Phase 2.6: Non-Composer function and constant discovery
+
+**Goal:** In projects without Composer, discover standalone functions,
+`define()` constants, and top-level `const` declarations across the
+entire workspace so that function completion, go-to-definition, and
+constant resolution work without a `vendor/composer/autoload_files.php`
+manifest.
+
+### Problem
+
+Composer projects separate class discovery from function/constant
+discovery. Classes live in PSR-4/classmap directories and are found
+by namespace-to-path mapping. Functions and constants live in files
+listed explicitly in `autoload.files` (and transitively via
+`require_once` chains). PHPantom already handles both paths: the
+classmap scanner (Phase 1) covers classes, and the autoload-file
+walker covers functions and constants.
+
+Non-Composer projects have no such separation. A single PHP file may
+define classes, standalone functions, and constants side by side.
+Today PHPantom's self-scan (Phase 1 fallback) only extracts class
+names from these files. Functions and constants are invisible until
+the user happens to open the file that defines them, at which point
+`update_ast` populates `global_functions` and `global_defines`.
+
+This means non-Composer projects get no function name completion, no
+go-to-definition for cross-file functions, and no constant resolution
+for anything outside the currently open files.
+
+### Relationship to Phase 2.5
+
+Phase 2.5 replaces eager `update_ast` calls on Composer autoload files
+with a lightweight byte-level scan that extracts function names, constant
+names, and class names without building a full AST. The scanner design
+in Phase 2.5 (recognising `function`, `define(`, and `const` keywords
+alongside class keywords) is exactly what non-Composer discovery needs.
+
+The difference is scope, not mechanism:
+
+| Scenario | Files to scan for classes | Files to scan for functions/constants |
+|---|---|---|
+| **Composer** | PSR-4 + classmap directories + vendor packages | `autoload_files.php` entries only |
+| **Non-Composer** | All PHP files in workspace | All PHP files in workspace |
+
+In Composer mode, the classmap scan and the autoload-file scan are
+separate passes over disjoint file sets. In non-Composer mode, a single
+pass over all workspace files extracts classes, functions, and constants
+together. The byte-level scanner from Phase 2.5 handles both cases: it
+just runs on a wider set of files and populates additional indices.
+
+### Implementation
+
+Extend the Phase 1 self-scan fallback (the path taken when no
+`composer.json` exists) to also extract function and constant names:
+
+1. **Scanner.** Reuse the extended byte-level scanner from Phase 2.5.
+   When scanning a file, extract class declarations (as today) plus
+   function declarations and `define()`/`const` constants. This is a
+   single pass per file with no additional I/O.
+
+2. **Indices.** Populate three indices from the scan results:
+   - `classmap` — FQN → file path (already done by Phase 1).
+   - `autoload_function_index` — function FQN → file path (new,
+     same structure as Phase 2.5).
+   - `autoload_constant_index` — constant name → file path (new,
+     same structure as Phase 2.5).
+
+3. **Resolution.** No additional resolution changes beyond Phase 2.5.
+   `find_or_load_function` and constant resolution already consult
+   the autoload indices when Phase 2.5 is in place. The only
+   difference is that non-Composer mode populates those indices from
+   a workspace walk instead of from `autoload_files.php`.
+
+4. **Composer mode.** When Composer is present, the workspace-wide
+   function/constant scan is unnecessary because `autoload_files.php`
+   already tells us which files to scan. The broader scan only runs
+   in non-Composer mode (no `composer.json`) or `"self"` strategy
+   mode.
+
+### Effort and dependencies
+
+**Effort:** Low. This is a thin integration layer on top of Phase 2.5's
+scanner. The scanner already exists; the only new work is calling it on
+all workspace files (instead of just autoload files) and populating
+the function/constant indices from the results.
+
+**Dependencies:** Phase 2.5 (the scanner and the autoload indices must
+exist before this phase can populate them from a different file set).
+Phase 1 (the workspace file walk for non-Composer projects must exist).
+
+**Sequencing:** This phase should land immediately after Phase 2.5 or
+as part of the same PR, since the two share the scanner and index
+structures.
+
+---
+
 ## Phase 3: Parallel file processing
 
 **Goal:** Speed up workspace-wide operations (find references,
@@ -440,11 +536,9 @@ scanning, and complete completion item detail.
 
 **Prerequisites (from [performance.md](performance.md)):**
 
-- **§1 FQN secondary index.** The second pass calls `update_ast` on
-  every file, populating `ast_map` with thousands of entries. Without
-  a FQN index, every `find_class_in_ast_map` call (Phase 1 of
-  `find_or_load_class`) becomes an O(thousands) linear scan. With the
-  index, it is O(1).
+- **§1 FQN secondary index.** ✅ Done. `fqn_index` provides O(1)
+  lookups by fully-qualified name, so the second pass populating
+  `ast_map` with thousands of entries no longer causes linear scans.
 - **§2 `Arc<ClassInfo>`.** Full indexing stores a `ClassInfo` for every
   class in the project. Without `Arc`, every resolution clones the
   entire struct out of the map. With `Arc`, retrieval is a

docs/todo/performance.md

@@ -16,51 +16,20 @@ within the same impact tier.
 ---
 
 ## 1. FQN secondary index for `find_class_in_ast_map`
-**Impact: High · Effort: Low**
-
-`find_class_in_ast_map` is the Phase 1 lookup in `find_or_load_class`.
-It iterates **every file's classes** in the `ast_map` to find a class
-by short name + namespace match. In a project with hundreds of parsed
-files, this O(files × classes_per_file) scan runs for every class
-lookup in every resolution chain. A single completion request that
-resolves `$this->` can invoke this dozens of times as it walks the
-inheritance chain, loads traits, resolves interfaces, and processes
-mixins.
-
-The `class_index` (`HashMap<String, String>`) already maps FQN → URI
-but stops short: after finding the URI, the code still iterates all
-classes in that file to find the right one.
-
-Under full background indexing (indexing.md Phase 5), "all files"
-means every PHP file in the project. The linear scan becomes the
-dominant bottleneck.
-
-### Fix
-
-Add a secondary index `HashMap<String, ClassInfo>` (or
-`HashMap<String, Arc<ClassInfo>>` if §2 lands first) that maps
-fully-qualified class names directly to their parsed `ClassInfo`.
-This turns every Phase 1 lookup into an O(1) hash lookup.
-
-### Maintenance
-
-The index must be updated in `update_ast_inner` (when files are
-opened/changed) and in `parse_and_cache_content_versioned` (when
-files are loaded on demand via classmap, PSR-4, or stubs). Both
-code paths already maintain `ast_map` and `class_index`, so adding
-a third insertion is straightforward.
-
-When a file is re-parsed, remove all old entries for that file's
-classes (snapshot FQNs before overwriting `ast_map`) and insert
-the new ones. This mirrors the existing `class_index` maintenance
-in `update_ast_inner`.
-
-### Migration path
-
-Once the FQN index is in place, `find_class_in_ast_map` becomes a
-single hash lookup. The linear scan can be kept as a fallback for
-edge cases (e.g. anonymous classes that don't have stable FQNs) but
-should never be the primary path.
+**Impact: High · Effort: Low (fixed)**
+
+**Status:** Fixed. `Backend` now carries a `fqn_index`
+(`Arc<RwLock<HashMap<String, ClassInfo>>>`) that maps fully-qualified
+class names directly to their parsed `ClassInfo`.
+`find_class_in_ast_map` performs an O(1) hash lookup against this
+index before falling back to the linear `ast_map` scan (which now
+only serves as a safety net for anonymous classes or race conditions
+during initial indexing).
+
+The index is maintained in both `update_ast_inner` (stale entries
+removed via the `old_fqns` snapshot, new entries inserted alongside
+`class_index`) and `parse_and_cache_content_versioned` (entries
+inserted after the `ast_map` write).
 
 ---
 

src/lib.rs

@@ -190,6 +190,14 @@ pub struct Backend {
     /// Populated during `update_ast` (using the file's namespace + class
     /// short name) and during server initialization for autoload files.
     pub(crate) class_index: Arc<RwLock<HashMap<String, String>>>,
+    /// Secondary index mapping fully-qualified class names directly to
+    /// their parsed `ClassInfo`.
+    ///
+    /// This turns every Phase 1 lookup in [`find_or_load_class`] into an
+    /// O(1) hash lookup instead of scanning all files in `ast_map`.
+    /// Maintained alongside `class_index` in `update_ast_inner` and
+    /// `parse_and_cache_content_versioned`.
+    pub(crate) fqn_index: Arc<RwLock<HashMap<String, ClassInfo>>>,
     /// Composer classmap: fully-qualified class name → file path on disk.
     ///
     /// Parsed from `<vendor>/composer/autoload_classmap.php` during server
@@ -317,6 +325,7 @@ impl Backend {
             global_functions: Arc::new(RwLock::new(HashMap::new())),
             global_defines: Arc::new(RwLock::new(HashMap::new())),
             class_index: Arc::new(RwLock::new(HashMap::new())),
+            fqn_index: Arc::new(RwLock::new(HashMap::new())),
             classmap: Arc::new(RwLock::new(HashMap::new())),
             stub_index: stubs::build_stub_class_index(),
             stub_function_index: stubs::build_stub_function_index(),
@@ -458,6 +467,7 @@ impl Backend {
             global_functions: Arc::clone(&self.global_functions),
             global_defines: Arc::clone(&self.global_defines),
             class_index: Arc::clone(&self.class_index),
+            fqn_index: Arc::clone(&self.fqn_index),
             classmap: Arc::clone(&self.classmap),
             stub_index: self.stub_index.clone(),
             resolved_class_cache: Arc::clone(&self.resolved_class_cache),

src/parser/ast_update.rs

@@ -303,13 +303,20 @@ impl Backend {
         // that files with multiple namespace blocks produce correct FQNs.
         {
             let mut idx = self.class_index.write();
+            let mut fqn_idx = self.fqn_index.write();
             // Remove stale entries from previous parses of this file.
             // When a file's namespace changes (e.g. while the user is
             // typing a namespace declaration), old FQNs linger under
             // the previous namespace and pollute completions.
             idx.retain(|_, uri| uri != &uri_string);
 
-            for (class, class_ns) in &classes_with_ns {
+            // Remove stale fqn_index entries for FQNs that belonged to
+            // the previous version of this file.
+            for old_fqn in &old_fqns {
+                fqn_idx.remove(old_fqn);
+            }
+
+            for (i, (class, class_ns)) in classes_with_ns.iter().enumerate() {
                 // Anonymous classes (named `__anonymous@<offset>`) are
                 // internal bookkeeping — they should never appear in
                 // cross-file lookups or completion results.
@@ -321,7 +328,10 @@ impl Backend {
                 } else {
                     class.name.clone()
                 };
-                idx.insert(fqn, uri_string.clone());
+                idx.insert(fqn.clone(), uri_string.clone());
+                // The `classes` vec already has `file_namespace` set,
+                // so use it for the fqn_index entry.
+                fqn_idx.insert(fqn, classes[i].clone());
             }
         }
 

src/resolution.rs

@@ -201,6 +201,22 @@ impl Backend {
             .write()
             .insert(uri.to_owned(), file_namespace);
 
+        // Populate the fqn_index so that `find_class_in_ast_map` can
+        // resolve these classes via O(1) hash lookup.
+        {
+            let mut fqn_idx = self.fqn_index.write();
+            for cls in &classes {
+                if cls.name.starts_with("__anonymous@") {
+                    continue;
+                }
+                let fqn = match &cls.file_namespace {
+                    Some(ns) if !ns.is_empty() => format!("{}\\{}", ns, cls.name),
+                    _ => cls.name.clone(),
+                };
+                fqn_idx.insert(fqn, cls.clone());
+            }
+        }
+
         // Selectively invalidate the resolved-class cache for the
         // classes defined in this file.  Loading a new file from disk
         // (classmap, PSR-4, stubs) should not nuke cached resolutions

src/util.rs

@@ -621,6 +621,19 @@ impl Backend {
     /// Returns a cloned `ClassInfo` if found, or `None`.
     pub(crate) fn find_class_in_ast_map(&self, class_name: &str) -> Option<ClassInfo> {
         let normalized = class_name.strip_prefix('\\').unwrap_or(class_name);
+
+        // ── Fast path: O(1) lookup via fqn_index ──
+        // For namespace-qualified names the FQN is the normalized name
+        // itself.  For bare names (no backslash) the FQN equals the
+        // short name, which is also stored in the index.
+        if let Some(cls) = self.fqn_index.read().get(normalized) {
+            return Some(cls.clone());
+        }
+
+        // ── Slow fallback: linear scan of ast_map ──
+        // Covers edge cases where the fqn_index has not been populated
+        // yet (e.g. anonymous classes, or race conditions during initial
+        // indexing).
         let last_segment = short_name(normalized);
         let expected_ns: Option<&str> = if normalized.contains('\\') {
             Some(&normalized[..normalized.len() - last_segment.len() - 1])