Rename ast_map and classmap to uri_classes_index and fqn_uri_index

Author: AJenbo

docs/ARCHITECTURE.md

@@ -58,6 +58,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Fixed
 
+- **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.
 - **Rename class preserves `self`, `static`, and `parent` keywords.** Renaming a class no longer replaces occurrences of `self::`, `static::`, or `parent::` with the new class name.
 - **Rename propagates into closures and arrow functions.** Renaming a variable now follows explicit `use ($var)` captures into closure bodies and implicit captures into arrow function bodies, instead of leaving those occurrences unchanged.

docs/CHANGELOG.md

@@ -322,7 +322,7 @@ On `<x-alert>`:
 
 1. Extract the component name.
 2. Look up in `blade_components` to get the FQN.
-3. Use `find_or_load_class` + `class_index` / `classmap` to find the
+3. Use `find_or_load_class` + `fqn_uri_index` to find the
    source file.
 4. Return a `Location` pointing to the class definition.
 

docs/todo/blade.md

@@ -257,7 +257,7 @@ and no go-to-definition because PHPantom has no record of the alias.
 
 3. **Cross-file aliases** — for aliases defined in autoloaded files
    (e.g. a `_ide_helper.php` or a framework bootstrap file), the alias
-   mapping needs to be stored in `class_index` or a parallel index so
+   mapping needs to be stored in `fqn_uri_index` or a parallel index so
    that it's available project-wide. This is the main effort: deciding
    where to persist the alias data and when to scan for it.
 
@@ -343,14 +343,14 @@ improves perceived latency on keystroke.
 **Impact: Low · Effort: Low**
 
 Same-namespace classes (source tier 2) already carry deprecation info
-because `ClassInfo` is available. Classes from `class_index`, classmap,
-and stubs (tiers 3-5) don't check for `@deprecated` because the class
+because `ClassInfo` is available. Classes from `fqn_uri_index`
+and stubs (tiers 3-4) don't check for `@deprecated` because the class
 may not be fully loaded at completion time.
 
 For classmap entries, a lightweight byte-level scan of the first
 docblock in the file (similar to `detect_stub_class_kind`) could detect
 `@deprecated` without a full parse. For stubs, the source is already
-in memory and could be scanned cheaply. For class_index entries, the
+in memory and could be scanned cheaply. For fqn_uri_index entries, the
 deprecation flag could be stored alongside the file path when the class
 is first indexed.
 

docs/todo/completion.md

@@ -85,7 +85,7 @@ dominates analysis time.
 - **Phase 1: MethodStore infrastructure.** Added
   `Backend.method_store: MethodStore` (an
   `Arc<RwLock<HashMap<(String, String), Arc<MethodInfo>>>>`)
-  populated alongside `fqn_index` in `update_ast_inner` and
+  populated alongside `fqn_class_index` in `update_ast_inner` and
   `parse_and_cache_content_versioned`. Eviction on re-parse
   via `evict_methods_for_fqns`.
 - **Phase 2: Centralised lookup helpers.** Added
@@ -349,7 +349,7 @@ The problem is needing them for every runtime analysis thread.
   speed (sub-second).
 - No test regressions in the existing test suite.
 - Memory usage for the populated metadata is within 2x of the
-  current `ast_map` + `class_index` combined size.
+  current `uri_classes_index` + `fqn_uri_index` combined size.
 - The diagnostic/analysis pass never calls
   `resolve_class_with_inheritance`. All class metadata is
   pre-populated and immutable during analysis.

docs/todo/eager-resolution.md

@@ -22,7 +22,7 @@ PHPantom embeds JetBrains phpstorm-stubs at compile time via
 `build.rs`. The stubs are baked into the binary as static string
 arrays and indexed by class, function, and constant name. At runtime,
 `find_or_load_class` checks the `stub_index` as a final fallback
-(Phase 3) after `ast_map`, classmap, and PSR-4. Stub files are parsed
+(Phase 3) after `uri_classes_index`, `fqn_uri_index`, and PSR-4. Stub files are parsed
 lazily on first access and cached under `phpantom-stub://` URIs.
 
 This works well for the PHP standard library but has limitations:
@@ -321,13 +321,13 @@ embedded stubs:
 
 **`find_or_load_class`:**
 
-1. Phase 1: `ast_map` (user code, already-parsed files)
-2. Phase 1.5: Composer classmap
+1. Phase 0: `fqn_class_index` (user code, already-parsed files)
+2. Phase 1: fqn_uri_index
 3. Phase 2: PSR-4
 4. **Phase 2.5 (new): External stub class index.** Checks the
    unified external stub index (populated from `.phpantom.toml`,
    Composer stubs, and IDE-provided stubs in priority order). Read
-   the file, parse and cache in `ast_map` under a
+   the file, parse and cache in `uri_classes_index` under a
    `phpantom-ext-stub://` URI.
 5. Phase 3: Embedded stubs
 

docs/todo/external-stubs.md

@@ -409,7 +409,7 @@ the last report, avoiding notification spam.
 ### Go to Implementation
 
 `find_implementors` has five phases with different totals:
-Phase 1 (ast_map), Phase 2 (class_index), Phase 3 (classmap
+Phase 0 (fqn_class_index), Phase 1 (fqn_uri_index), Phase 2 (PSR-4
 files), Phase 4 (stubs), Phase 5 (PSR-4 walk). The total for
 each phase is known before iteration begins. Report progress
 within each phase and allocate percentage ranges across phases

docs/todo/indexing.md

@@ -214,6 +214,98 @@ Each item must include:
 
 ## Outstanding items
 
-No outstanding items.
+### R1. Shadow chain resolver in `helpers.rs` 🔴
+
+`src/completion/source/helpers.rs` L625–780 contains `resolve_lhs_to_class` /
+`resolve_raw_type_from_call_chain`, a full parallel chain resolver that manually
+splits on `->` and `::` via `rfind`, handles `$this->prop`, `new Foo()`,
+`ClassName::method()`, and recursive call chains by string manipulation. This
+duplicates what `SubjectExpr::parse` + `resolve_target_classes_expr` in
+`completion/resolver.rs` already does. Also called from
+`extract_first_class_callable_return_type` (L407–470, same file).
+
+**Action:** Replace with calls through the main `SubjectExpr::parse` +
+`resolve_target_classes_expr` pipeline.
+
+**Files:** `src/completion/source/helpers.rs`
+
+### R2. Mini expression resolver in `call_resolution.rs` 🔴
+
+`src/completion/call_resolution.rs` L2528 has `resolve_expression_to_type`, a
+separate expression-to-`PhpType` resolver for conditional return type argument
+matching. Handles `SubjectExpr::PropertyChain` and `SubjectExpr::Variable`
+through different code paths than the forward walker's `resolve_rhs_expression`.
+Fewer cases, different path, will diverge as features are added.
+
+**Action:** Route through the shared `resolve_rhs_expression` /
+`resolve_expression_type` pipeline.
+
+**Files:** `src/completion/call_resolution.rs`
+
+### R3. Backward `@var` scanner in `docblock/tags.rs` 🟠
+
+`src/docblock/tags.rs` L520–620 (`find_var_raw_type_in_source`) and L1000–1100
+(`find_iterable_raw_type_in_source`) scan source lines backward with
+`lines().rev()`, manually tracking brace depth and sibling scopes via character
+counting. This reimplements scope analysis that the forward walker and
+`scope_collector/` already provide. Called from `call_resolution.rs` (L1251,
+L2793) and `array_shape.rs` (L519), making them load-bearing.
+
+**Action:** Replace with forward walker variable resolution or ensure the
+forward walker captures `@var` annotations so these backward scanners become
+unnecessary.
+
+**Files:** `src/docblock/tags.rs`, `src/completion/call_resolution.rs`,
+`src/completion/array_shape.rs`
+
+### R4. Backward callable scan in `signature_help.rs` 🟠
+
+`src/signature_help.rs` L438–470 (`extract_callable_target_from_variable`) uses
+raw `rfind` backward text scan to find `$fn = someTarget(...)` assignments,
+bypassing the forward walker which already tracks variable assignments.
+
+**Action:** Use the forward walker's assignment tracking instead of raw text
+scanning.
+
+**Files:** `src/signature_help.rs`
+
+### R5. Hover double-resolution 🟠
+
+`src/hover/mod.rs` L984–1030: `hover_variable` calls `resolve_variable_php_type`
+(which internally runs `resolve_variable_types` via the forward walker). If that
+returns `None`, it calls `resolve_variable_types` again directly. Since the first
+function already called the second internally, the second call is dead code.
+
+**Action:** Remove the redundant second call to `resolve_variable_types`.
+
+**Files:** `src/hover/mod.rs`
+
+---
+
+## Intentional overlap (reference, not actionable)
+
+These are parallel systems that exist for valid reasons. Documented here so
+they are factored into future design decisions.
+
+### `uri_classes_index` vs `fqn_class_index` vs `fqn_uri_index`
+
+Three maps storing overlapping class data:
+- `uri_classes_index`: URI → `Vec<Arc<ClassInfo>>` (needed for "all classes in this file")
+- `fqn_class_index`: FQN → `Arc<ClassInfo>` (O(1) FQN lookup)
+- `fqn_uri_index`: FQN → URI string (survives `didClose`, enables re-loading)
+
+Data is shared via `Arc`. Each serves a distinct query pattern.
+
+### PathBuf ↔ URI round-tripping
+
+The classmap scanner produces `PathBuf`, converts to URI strings for
+`fqn_uri_index`, then at lookup time parses back to `PathBuf` for file reading.
+A minor inefficiency, not a parallel system.
+
+### `find_class_in_ast_map` linear scan fallback
+
+`src/util.rs` L1436–1447: After the O(1) `fqn_class_index` lookup fails, falls
+back to linear scan of `uri_classes_index`. Covers race conditions during initial
+indexing. Legitimate safety net.
 
 

docs/todo/refactor.md

@@ -251,7 +251,7 @@ pub async fn run(options: AnalyseOptions) -> i32 {
     // read lock, then drop the lock before resolving.  Resolution may
     // call find_or_load_class which takes write locks on ast_map.
     let sorted_fqns = {
-        let ast_map = backend.ast_map.read();
+        let ast_map = backend.uri_classes_index.read();
         crate::toposort::toposort_from_ast_map(&ast_map)
     };
     // Run eager population on a large-stack thread.  `resolve_class_fully_inner`

src/analyse.rs

@@ -259,8 +259,12 @@ impl Backend {
         member_kind: &MemberKind,
     ) -> Option<u8> {
         // Find the enclosing ClassInfo from the ast_map.
-        let local_classes: Vec<Arc<ClassInfo>> =
-            self.ast_map.read().get(uri).cloned().unwrap_or_default();
+        let local_classes: Vec<Arc<ClassInfo>> = self
+            .uri_classes_index
+            .read()
+            .get(uri)
+            .cloned()
+            .unwrap_or_default();
 
         let enclosing = crate::util::find_class_at_offset(&local_classes, cursor_offset)?;