docs: update roadmap and changelog for Laravel and performance work

Author: MingJen

docs/CHANGELOG.md

@@ -9,6 +9,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 
+- **Laravel custom Eloquent builder support.** Models using the `#[UseEloquentBuilder]` attribute now have their custom builder's methods forwarded as static methods on the model. `query()`, `newQuery()`, and `newModelQuery()` return the custom builder type with correct generic model substitution.
 - **Blade template support.** Completion, hover, go-to-definition, diagnostics, semantic tokens, and inlay hints work inside `.blade.php` files. Contributed by @MingJen in https://github.com/AJenbo/phpantom_lsp/pull/100.
 - **Blade keyword highlighting.** Blade directives, echo delimiters, PHP keywords, cast types, comments, and PHPDoc tags inside `.blade.php` files now receive semantic tokens for proper syntax coloring.
 - **Blade view directive navigation.** Go-to-definition works on view names inside Blade directives (`@include`, `@extends`, `@includeIf`, `@includeWhen`, `@includeUnless`, `@includeFirst`, `@component`, `@each`), jumping to the referenced template file.
@@ -44,6 +45,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Changed
 
+- **Improved LSP responsiveness.** File parsing (`update_ast`) and diagnostics now run in background tasks, preventing interactive requests (completion, hover) from being blocked by full-file parses during typing.
+- **Member completion caching.** Unfiltered member lists are cached per-target to speed up subsequent completions during keyword entry.
+- **Laravel startup performance.** Common Laravel builder classes are warmed in the background at startup to eliminate the first-access penalty on Eloquent completions.
 - **Find References performance and freshness.** Project-wide Find References now avoids more unnecessary file work while still returning references through aliased class and function imports, and it refreshes newly added workspace PHP files on later searches. Contributed by @MingJen in https://github.com/AJenbo/phpantom_lsp/pull/116.
 - **Incremental text sync.** The server now uses incremental document sync, receiving only changed ranges from the editor instead of the full file content on every keystroke.
 - **Replace FQCN with import.** Now replaces all occurrences of the same FQCN throughout the file in one action, not just the one under the cursor. A new "Replace all FQCNs with imports" action appears when the file contains multiple distinct FQCNs, replacing all of them at once (skipping those with import conflicts).

docs/todo.md

@@ -30,8 +30,8 @@ within the same impact tier.
 
 > **Note:** F1 (Workspace symbol search), F2 (Document symbols), A8
 > (Implement interface methods), A9 (Auto import), D1 (Unknown class
-> diagnostic), and D3 (Unknown member diagnostic) were originally
-> planned here but have already shipped.
+> diagnostic), D3 (Unknown member diagnostic), and L4 (Custom Eloquent
+> builders) were originally planned here but have already shipped.
 
 ## Sprint 6 — 1.0 release, editor plugins & type intelligence
 
@@ -151,8 +151,7 @@ unlikely to move the needle for most users.
 | S4  | Named argument awareness in active parameter                                                                                                                                | Low-Medium  | Medium      |
 | S5  | Language construct signature help and hover                                                                                                                                 | Low         | Low         |
 |     | **[Laravel](todo/laravel.md)**                                                                                                                                              |             |             |
-| L4  | Custom Eloquent builders (`HasBuilder` / `#[UseEloquentBuilder]`)                                                                                                           | Medium      | Medium      |
-| L3  | `$dates` array (deprecated)                                                                                                                                                 | Low-Medium  | Low         |
+| L3  | `$dates` array (deprecated)                                                                                                                  | Low-Medium  | Low         |
 | L6  | Factory `has*`/`for*` relationship methods                                                                                                                                  | Low-Medium  | Medium      |
 | L7  | `$pivot` property on BelongsToMany                                                                                                                                          | Medium      | Medium-High |
 | L8  | `withSum`/`withAvg`/`withMin`/`withMax` aggregate properties                                                                                                                | Low-Medium  | Medium-High |
@@ -164,7 +163,6 @@ unlikely to move the needle for most users.
 |     | **[Performance](todo/performance.md) / [Eager Resolution](todo/eager-resolution.md)**                                                                                       |             |             |
 | ER5 | [Mago-style separated metadata](todo/eager-resolution.md#er5--mago-style-separated-metadata)                                                                                | High        | High        |
 | P14 | [Eager docblock parsing into structured fields](todo/performance.md#p14-eager-docblock-parsing-into-structured-fields)                                                      | Medium      | Medium      |
-| P9  | [`resolved_class_cache` generic-arg specialisation](todo/performance.md#p9-resolved_class_cache-generic-arg-specialisation)                                                 | Medium      | Medium      |
 | P11 | [Uncached base-resolution in `build_scope_methods_for_builder`](todo/performance.md#p11-uncached-base-resolution-in-build_scope_methods_for_builder)                        | Low-Medium  | Low         |
 | P3  | Parallel pre-filter in `find_implementors`                                                                                                                                  | Low-Medium  | Medium      |
 | P4  | `memmem` for block comment terminator search                                                                                                                                | Low         | Low         |
@@ -173,7 +171,6 @@ unlikely to move the needle for most users.
 | P7  | `diag_pending_uris` uses `Vec::contains` for dedup                                                                                                                          | Low         | Low         |
 | P8  | `find_class_in_ast_map` linear fallback scan                                                                                                                                | Low         | Low         |
 | P12 | [`find_or_load_function` Phase 1.75 serial bottleneck](todo/performance.md#p12-find_or_load_function-phase-175-serial-bottleneck)                                           | Low         | Low         |
-| P17 | [`mago-names` resolution on the parse hot path](todo/performance.md#p17-mago-names-resolution-on-the-parse-hot-path)                                                        | Medium      | Low         |
 | P18 | [Subtype result caching](todo/performance.md#p18-subtype-result-caching) (per-request HashMap for hierarchy walks)                                                          | Medium      | Low         |
 | P19 | [Arena reuse on the parse hot path](todo/performance.md#p19-arena-reuse-on-the-parse-hot-path) (thread-local `Bump::reset()` instead of `Bump::new()`)                      | Medium      | Low         |
 | P20 | [Content-hash gated resolution cache persistence](todo/performance.md#p20-content-hash-gated-resolution-cache-persistence)                                                  | Medium      | Medium      |

docs/todo/laravel.md

@@ -238,45 +238,6 @@ today and what is still missing.
 
 ---
 
-#### L4. Custom Eloquent builders (`HasBuilder` / `#[UseEloquentBuilder]`)
-
-**Impact: High · Effort: Medium**
-
-Custom builders are the recommended pattern for complex query scoping
-in modern Laravel. Without this, users get zero completions for
-builder-specific methods via static model calls.
-
-Laravel 11+ introduced the `HasBuilder` trait and
-`#[UseEloquentBuilder(UserBuilder::class)]` attribute to let models
-declare a custom builder class. When present, `User::query()` and
-all static builder-forwarded calls should resolve to the custom
-builder instead of the base `Illuminate\Database\Eloquent\Builder`.
-
-```php
-/** @extends Builder<User> */
-class UserBuilder extends Builder {
-    /** @return $this */
-    public function active(): static { ... }
-}
-
-class User extends Model {
-    /** @use HasBuilder<UserBuilder> */
-    use HasBuilder;
-}
-
-User::query()->active()->get(); // active() should resolve on UserBuilder
-```
-
-Larastan handles this via `BuilderHelper::determineBuilderName()`,
-which inspects `newEloquentBuilder()`'s return type or the
-`#[UseEloquentBuilder]` attribute to find the custom builder class.
-
-**Where to change:** In `build_builder_forwarded_methods`, before
-loading the standard `Eloquent\Builder`, check whether the model
-declares a custom builder via `@use HasBuilder<X>` in `use_generics`
-or a `newEloquentBuilder()` method with a non-default return type.
-If found, load and resolve that builder class instead.
-
 #### L5. `abort_if`/`abort_unless` type narrowing
 
 **Impact: High · Effort: Medium**

docs/todo/performance.md

@@ -190,36 +190,6 @@ window.
 
 ---
 
-## P9. `resolved_class_cache` generic-arg specialisation
-
-**Impact: Medium · Effort: Medium**
-
-The resolved-class cache is keyed by `(FQN, Vec<String>)`. Every
-distinct generic instantiation of the same class (e.g.
-`Builder<User>`, `Builder<Order>`, `Builder<Product>`) triggers a
-full `resolve_class_fully` call, even though the base resolution
-(inheritance merging, trait merging, virtual member injection) is
-identical. Only the final generic substitution differs.
-
-In a Laravel codebase with hundreds of Eloquent models, this means
-`Builder` is fully resolved hundreds of times, once per model.
-
-### Fix
-
-Cache the base-resolved class (before generic substitution)
-separately, keyed by FQN alone. When a generic instantiation is
-requested, look up the base-resolved class and apply
-`apply_substitution` on top. The substitution step is cheap
-(tree walk) compared to the full resolution (inheritance walking,
-trait merging, virtual member providers).
-
-This requires splitting `resolve_class_fully` into two stages:
-base resolution (cached by FQN) and generic specialisation (cached
-by `(FQN, Vec<String>)` as today, but with a much cheaper miss
-path).
-
----
-
 ## P11. Uncached base-resolution in `build_scope_methods_for_builder`
 
 **Impact: Low-Medium · Effort: Low**
@@ -506,48 +476,6 @@ essentially free for both eager and deferred indexing paths.
 
 ---
 
-## P17. `mago-names` resolution on the parse hot path
-
-**Impact: Medium · Effort: Low**
-
-The `mago-names` name resolver runs synchronously inside
-`update_ast_inner`, adding a full AST walk plus an owned `HashMap`
-copy on every `didChange` event. Measured regression from `6a0737a`
-("Migrate to use mago-names"):
-
-| Benchmark        | Before | After | Δ    |
-| ---------------- | ------ | ----- | ---- |
-| with_narrowing   | 12 ms  | 15 ms | +25% |
-| 5_methods_chain  | 8 ms   | 10 ms | +25% |
-| carbon_class     | 250 ms | 340 ms | +36% |
-| large_file       | 150 ms | 210 ms | +40% |
-
-The resolved names are currently consumed only by diagnostics (which
-run asynchronously) and `FileContext::resolve_name_at()`. Nothing on
-the completion hot path requires this data to be computed eagerly.
-
-### Fix
-
-Defer name resolution out of `update_ast_inner`. Options:
-
-- **Lazy resolution:** compute `OwnedResolvedNames` on first access
-  per file version, invalidate on the next `update_ast`. Moves the
-  cost off the typing hot path entirely.
-- **Diagnostic-worker resolution:** run the resolver in the
-  diagnostic worker clone of `Backend`, since diagnostics are the
-  primary consumer.
-
-### When to implement
-
-Low priority. The `mago-names` migration is complete, but the
-`use_map` is still used by several consumers. Further refactoring
-(migrating more consumers to byte-offset lookups, eventually
-removing `use_map`) will change the access patterns. Optimizing
-now would likely be reworked. Revisit once `use_map` usage is
-significantly reduced.
-
----
-
 ## P18. Subtype result caching
 
 **Impact: Medium · Effort: Low**