Add performance to roadmap

Author: AJenbo

docs/todo.md

@@ -28,6 +28,7 @@ with each step.
 | [Configuration](todo/config.md) | Per-project `.phpantom.toml` file, PHP version override, diagnostic tool toggles, prompt-and-remember settings |
 | [Refactoring](todo/refactor.md) | Technical debt and cleanup tasks. Gate check between sprints: clear all items before starting the next sprint |
 | [Indexing](todo/indexing.md) | Self-generated classmap, staleness detection, parallel file processing, full background indexing, disk cache |
+| [Performance](todo/performance.md) | FQN index, `Arc<ClassInfo>`, `RwLock`, inheritance dedup, file content cloning, type substitution optimisation |
 
 ---
 
@@ -56,6 +57,49 @@ requirement to a performance tip instead of a prerequisite.
 
 ---
 
+## Sprint 2.5 — Performance foundations
+
+These structural fixes reduce latency and contention on the hot paths
+that every LSP request exercises. They are sequenced here, before
+refactoring and feature sprints, because later work amplifies the
+underlying costs:
+
+- **Parallel file processing** (indexing.md Phase 3) adds concurrent
+  readers. Without `RwLock`, parallelism is defeated by lock
+  contention.
+- **Full background indexing** (indexing.md Phase 5) puts thousands of
+  files into `ast_map`. Without the FQN index, every class lookup
+  becomes an O(thousands) scan. Without `Arc<ClassInfo>`, every lookup
+  deep-clones a large struct.
+- **Sprint 6 Laravel generics** (`collect()`, custom builders) increase
+  the depth of generic substitution chains. Without the `HashSet` dedup
+  and substitution early-exit, Eloquent models pay O(N²) per resolution.
+
+Fixing these first means every subsequent sprint benefits automatically.
+
+| # | Item | Effort | Domain | Doc Link |
+|---|---|---|---|---|
+| 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) |
+| 83 | `RwLock` for read-heavy maps | Low | Performance | [performance.md §3](todo/performance.md#3-rwlock-for-read-heavy-maps) |
+| 84 | `HashSet` dedup in inheritance merging | Low | Performance | [performance.md §4](todo/performance.md#4-hashset-dedup-in-inheritance-merging) |
+| 85 | `Arc<String>` for file content in `open_files` | Low | Performance | [performance.md §5](todo/performance.md#5-arcstring-for-file-content-in-open_files) |
+| 86 | `Arc<SymbolMap>` to avoid snapshot cloning | Low | Performance | [performance.md §6](todo/performance.md#6-arcsymbolmap-to-avoid-snapshot-cloning) |
+| 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) |
+
+Item 89 (incremental text sync) is in the backlog because the parser
+requires a full re-parse regardless, limiting the benefit to IPC
+bandwidth savings on large files.
+
+**After Sprint 2.5:** Every resolution path is O(1) lookup instead of
+O(N) scan. Concurrent reads no longer block each other. Inheritance
+merging is O(N) instead of O(N²). File content and symbol maps are
+shared by reference instead of deep-cloned. The codebase is ready for
+parallel file processing and full background indexing without
+performance regressions.
+
+---
+
 ## Sprint 3 — Refactoring
 
 Extract Function is the remaining refactoring pillar. Inline Variable,
@@ -116,7 +160,7 @@ deepens that lead and rounds out the remaining feature surface.
 | 39 | Simplify with null coalescing / null-safe operator (code action) | Medium | Code Actions | [actions.md §2](todo/actions.md#2-simplify-with-null-coalescing--null-safe-operator) |
 | 40 | Inlay hints (`textDocument/inlayHint`) | Medium | LSP Features | [lsp-features.md §9](todo/lsp-features.md#9-inlay-hints-textdocumentinlayhint) |
 
-**After Sprint 6:** PHPantom has a complete, polished LSP feature set.
+**After Sprint 5:** PHPantom has a complete, polished LSP feature set.
 Users moving to Zed/Neovim/Helix lose nothing on the intelligence side
 and gain 1000× faster startup. The remaining gaps are Blade and
 formatting (not our domain).
@@ -152,7 +196,7 @@ the Laravel-specific manifestation is a small incremental step. Item 51
 (Type Hierarchy) depends on the go-to-implementation infrastructure and
 should be scheduled after that work is stable. Item 56 (partial result
 streaming) addresses outbound latency for large result sets. See also
-item 73 (incremental text sync) in the backlog, which addresses the
+item 89 (incremental text sync) in the backlog, which addresses the
 complementary inbound direction.
 
 ---
@@ -206,8 +250,13 @@ eventually but don't move the needle.
 | # | Item | Effort | Domain | Doc Link |
 |---|---|---|---|---|
 | 72 | Switch → match conversion | Medium | Code Actions | [actions.md §4](todo/actions.md#4-switch--match-conversion) |
-| 73 | Incremental text sync | Medium | LSP Features | [lsp-features.md §17](todo/lsp-features.md#17-incremental-text-sync) |
+| 89 | Incremental text sync | Medium | Performance | [performance.md §8](todo/performance.md#8-incremental-text-sync) |
 
+### Performance long-tail
+
+| # | Item | Effort | Domain | Doc Link |
+|---|---|---|---|---|
+| 90 | Type AST for `apply_substitution` (full refactor) | High | Performance | [performance.md §7](todo/performance.md#7-recursive-string-substitution-in-apply_substitution) |
 
 ---
 
@@ -242,5 +291,4 @@ Blade is a multi-phase project tracked in [todo/blade.md](todo/blade.md).
 | Phase 1 | Blade-to-PHP preprocessor | Module skeleton, directive translation, source map, LSP wiring |
 | Phase 2 | Component support | Template/component discovery, `<x-component>` parsing, `@props`/`@aware`, name completion |
 | Phase 3 | Cross-file view intelligence | View name GTD, signature merging for `@extends`, component→template variable typing |
-| Phase 4 | Blade directive completion | Directive name completion with snippet insertion |
-
+| Phase 4 | Blade directive completion | Directive name completion with snippet insertion |

docs/todo/indexing.md

@@ -194,6 +194,24 @@ happens rarely (a few times per day at most).
 go-to-implementation, self-scan, diagnostics) by processing files in
 parallel with priority awareness.
 
+**Prerequisites (from [performance.md](performance.md)):**
+
+- **§3 `RwLock` for read-heavy maps.** Parallel `spawn_blocking` tasks
+  need concurrent read access to `ast_map`, `symbol_maps`, `use_map`,
+  and `namespace_map`. With `Mutex`, every reader serializes against
+  every other reader, defeating the purpose of parallelism regardless
+  of how clever the priority scheduling is. `RwLock` lets all readers
+  proceed concurrently; only writes (which happen on `did_change` and
+  on-demand file loading) take an exclusive lock.
+- **§5 `Arc<String>` for file content.** Parallel tasks that need file
+  content should share references rather than each cloning the full
+  string out of `open_files`.
+- **§6 `Arc<SymbolMap>` to avoid snapshot cloning.** Find References
+  snapshots all user-file symbol maps before scanning. With owned
+  `SymbolMap` values, this deep-clones hundreds of maps. With
+  `Arc<SymbolMap>`, the snapshot is cheap and the lock is released
+  immediately.
+
 ### Why not rayon?
 
 `rayon` is the obvious choice for "process N files in parallel" and
@@ -289,6 +307,28 @@ is a nice-to-have, not a requirement.
 enabling workspace symbols, fast find-references without on-demand
 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).
+- **§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
+  reference-count increment. This is the difference between full
+  indexing using ~200 MB vs. ~500 MB for a large project.
+- **§3 `RwLock`.** The second pass writes to `ast_map` at Low priority
+  while High-priority LSP requests read from it. `Mutex` would force
+  every completion/hover request to wait for the current background
+  parse to finish its map insertion. `RwLock` lets reads proceed
+  concurrently with other reads; only the brief write window blocks.
+- **§4 `HashSet` dedup.** Full indexing means every class resolution
+  pulls from a fully populated inheritance tree. Eloquent models with
+  150+ inherited methods across 8+ levels hit the O(N²) dedup path
+  on every resolution. The `HashSet` fix brings this to O(N).
+
 ### Trigger
 
 When `strategy = "full"` is set in `.phpantom.toml`.
@@ -343,7 +383,13 @@ Currently we store `ClassInfo`, `FunctionInfo`, and `SymbolMap`
 structs that are not as lean as they could be. For a 21K-file
 codebase, full indexing will use meaningful RAM. This is acceptable
 because it's an opt-in mode, but we should profile and trim struct
-sizes over time. The aim is to stay under 512MB for a full project.
+sizes over time. The aim is to stay under 512 MB for a full project.
+
+The performance prerequisites above (§2 `Arc<ClassInfo>`, §5
+`Arc<String>`, §6 `Arc<SymbolMap>`) directly reduce memory usage by
+sharing data across the ast_map, caches, and snapshot copies instead
+of deep-cloning each. These should be measured before and after to
+validate the 512 MB target.
 
 ### Workspace symbols
 

docs/todo/lsp-features.md

@@ -525,6 +525,11 @@ acceptable.
 ## 17. Incremental text sync
 **Impact: Low-Medium · Effort: Medium**
 
+> **Cross-reference:** This item is also tracked as
+> [performance.md §8](performance.md#8-incremental-text-sync) and
+> roadmap item 89. The canonical spec lives here; the performance
+> document includes it for completeness.
+
 PHPantom uses `TextDocumentSyncKind::FULL`, meaning every
 `textDocument/didChange` notification sends the entire file content.
 Switching to `TextDocumentSyncKind::INCREMENTAL` means the client sends