@method and @property tags are parsed once per class

Author: AJenbo

docs/ARCHITECTURE.md

@@ -625,7 +625,7 @@ Provider priority order (highest first):
 Two providers are currently registered in `default_providers()`:
 
 - **`LaravelModelProvider`** (`virtual_members/laravel.rs`): synthesizes virtual members for classes extending `Illuminate\Database\Eloquent\Model`. Produces relationship properties (methods returning `HasMany`, `HasOne`, `BelongsTo`, etc. generate a virtual property typed from the relationship's generic parameters), scope methods (both the `scopeActive` naming convention and the `#[Scope]` attribute from Laravel 11+ are supported; either style becomes `active()` as both static and instance), Builder-as-static forwarding (`User::where()->get()` resolves end-to-end), accessors (legacy `getXAttribute()` and modern `Attribute` casts), and cast properties (`$casts` array or `casts()` method entries are mapped to PHP types like `datetime` to `\Carbon\Carbon`, `boolean` to `bool`, custom cast classes to their `get()` return type). Highest priority among virtual member providers. Scope methods are also injected onto `Builder<Model>` instances via a post-generic-substitution hook in `type_hint_to_classes_depth` (see "Scope Methods on Builder Instances" below).
-- **`PHPDocProvider`** (`virtual_members/phpdoc.rs`): parses `@method`, `@property`, `@property-read`, `@property-write`, and `@mixin` tags from the class-level docblock stored in `ClassInfo.class_docblock`. Explicit `@method` / `@property` tags are not parsed eagerly during AST extraction; instead, the raw docblock string is preserved and parsed lazily when `provide` is called. For `@mixin` tags, the provider loads the referenced classes and merges their public members. Within the provider, explicit tags take precedence over mixin members. Recurses into mixin-of-mixin chains up to `MAX_MIXIN_DEPTH`.
+- **`PHPDocProvider`** (`virtual_members/phpdoc.rs`): surfaces `@method`, `@property`, `@property-read`, `@property-write`, and `@mixin` tags from the class-level docblock. Explicit `@method` / `@property` tags are parsed once during AST extraction into `ClassInfo.doc_members` (an `Arc<DocblockMembers>`, `None` when the docblock declares neither), so `provide` only reads structured data and applies the per-consumer generic substitutions. The provider collects those tags from the class itself, its used traits, its parent chain, and its implemented interfaces. For `@mixin` tags, it loads the referenced classes and merges their public members. Within the provider, explicit tags take precedence over mixin members. Recurses into mixin-of-mixin chains up to `MAX_MIXIN_DEPTH`.
 
 ### Laravel Class Patches
 

docs/CHANGELOG.md

@@ -47,6 +47,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - **Lower memory use in the cross-file reference index.** The index backing Find References and the reference-count inlay hints now keeps only the distinct files and counts each symbol actually needs, instead of one entry per matching location plus never-read position data. On large projects this removes millions of short-lived allocations and shrinks the index to a fraction of its previous size, with no change to Find References or inlay hint results.
 - **Lower memory use for method lookups.** Each resolved class's method name index is now a sorted list searched with binary search instead of a hash map, using about a third of the memory for the same lookup speed. On large Laravel projects, where the resolved-class cache holds thousands of these indexes, this measurably shrinks total memory use.
 - **Lower memory use for member access spans.** The subject text recorded for every `->`/`::` access (e.g. `$this` in `$this->save()`) no longer allocates a string when it is a plain slice of the source, which covers the vast majority of accesses in typical PHP code. It now reuses the file's own bytes instead, with an allocation only for the rarer cases (chained calls, `new` expressions) where the recorded text differs from the source.
+- **`@method` and `@property` tags are parsed once per class.** The magic members a class declares in its docblock were re-parsed from the raw comment text every time the class, or any class that inherits or mixes it in, was resolved. They are now parsed when the file is read and reused from then on, which also means the parsed types are qualified against the declaring file's imports directly instead of by rewriting the comment text. Whole-project analysis of a large Laravel codebase runs a few percent faster and uses slightly less memory, with identical results.
 - **Faster diagnostics on large projects.** Several diagnostic checks (by-reference parameter detection, the `Stringable`-to-`string` acceptance check, and `model-property<Model>` literal validation) now read a class's inheritance from the resolved-class cache instead of re-merging traits, parent classes, and generics from scratch on every call. On large Laravel projects this removed a measurable share of the diagnostic pass's CPU time, and as a side effect these checks now also see interface-declared members (e.g. a `__toString` declared only on an implemented interface).
 - **Laravel string keys are collected once instead of once per CPU core.** Checking a `route()`, `config()`, `view()`, or `__()` key needs the project's full list of valid keys, and building each list walks the project directory. The diagnostic pass runs one worker per core, so all of them used to reach the empty list at the same moment and every one repeated the same walk, leaving most cores waiting on the disk rather than analysing. Each list is now built once and shared, which roughly doubles the number of cores the diagnostic pass keeps busy and cuts whole-project analysis time by around 15% on large Laravel projects.
 - **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.
@@ -57,6 +58,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Fixed
 
+- **`@method` and `@property` tags on an implemented interface are now always applied.** A class that declared no docblock of its own missed the magic methods and properties its interfaces declared, so they did not complete, hover, or resolve, and calls to them were reported as unknown members. Tags on an interface (and on the interfaces it extends) are now picked up regardless of what the implementing class documents.
 - **Find References, Rename, and Go to Implementation no longer look stalled during startup indexing.** A search started while the background index is still parsing the workspace waits for that index to finish, since acting on a partial index would silently miss results. That wait now shows in the request's own progress bar as "Waiting for workspace index" alongside the index's live file counts, instead of sitting at "Resolving…" with no indication of what it is waiting for.
 - **Type narrowing against `@phpstan-assert`/`@psalm-assert` no longer leaks memory.** Evaluating a narrowing call such as `Assert::isInstanceOf($x, Foo::class)` or a custom function/method with the same annotations allocated a small amount of memory that was never freed. This ran on every conditional touched during completion, hover, diagnostics, and go-to-definition, so memory held by a long-running editor session grew slowly but permanently the more the project was edited. Fixed by no longer leaking the allocation.
 - **Renaming a namespace no longer corrupts group `use` statements.** Renaming a namespace segment that is imported with a group `use` (e.g. `use App\Old\{Foo, Bar};`) previously rewrote the group's shared prefix and then also spliced the new prefix into each member name, producing invalid PHP like `use App\New\{App\New\Foo, Bar};`. The member names are left untouched now, since the prefix rewrite alone already updates the whole statement correctly.

docs/todo.md

@@ -201,7 +201,6 @@ unlikely to move the needle for most users.
 | P16 | [Pre-parsed stub format (eliminate raw PHP embedding)](todo/performance.md#p16-pre-parsed-stub-format-eliminate-raw-php-embedding)                                          | High        | Medium-High |
 | P25 | [`type_mismatch_argument` / `argument_count_mismatch` slow on large single files](todo/performance.md#p25-type_mismatch_argument-argument_count_mismatch-slow-on-large-single-files) | Medium      | Medium      |
 | P22 | [Signature change re-queues slow diagnostics for every open file](todo/performance.md#p22-signature-change-re-queues-slow-diagnostics-for-every-open-file)                  | Medium-High | Medium      |
-| P14 | [Eager docblock parsing into structured fields](todo/performance.md#p14-eager-docblock-parsing-into-structured-fields)                                                      | Medium      | Medium      |
 | P27 | [`object`/`?object` call-return check re-resolves the subject a second time](todo/performance.md#p27-objectobject-call-return-check-re-resolves-the-subject-a-second-time)  | Medium      | Low         |
 | 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      |

docs/todo/performance.md

@@ -82,53 +82,6 @@ but not to this function.
 
 ---
 
-## P14. Eager docblock parsing into structured fields
-
-**Impact: Medium · Effort: Medium**
-
-> **Note.** This item needs refinement when we work on it. The
-> codebase and feature set may change significantly before then.
-
-Currently `ClassInfo::class_docblock` stores the raw docblock
-string. Consumers that need virtual members (`@method`,
-`@property`, `@property-read`, `@property-write`) re-parse the
-raw text via `PHPDocProvider`, and the inheritance merge re-parses
-it again (`reserve_method_tag_names`). Since the resolved-class
-cache landed, this fires only when a class is (re-)resolved after
-a cache miss or eviction rather than on every request, so the win
-is smaller than when this item was filed.
-
-Parse the class-level docblock once during extraction and store the
-structured results directly on ClassInfo:
-
-- A list of parsed `@method` signatures (name, parameters, return
-  type, static flag, description).
-- A list of parsed `@property` / `@property-read` /
-  `@property-write` entries (name, type, access mode, description).
-
-This has three benefits:
-
-1. **Drop the raw string.** For heavily-annotated classes (Eloquent
-   models, facades) the raw docblock can be hundreds of bytes.
-   The structured representation may be comparable in size but is
-   directly usable without re-parsing.
-
-2. **Eliminate repeated parsing.** Virtual member resolution
-   re-parses the same docblock text every time the class is
-   resolved into the resolved-class cache (and again in the
-   inheritance merge). Parsing once during extraction removes
-   this redundant work.
-
-3. **Simpler consumer code.** Consumers iterate structured fields
-   instead of calling into the docblock parser. This removes the
-   lazy-parse indirection and makes the data flow easier to follow.
-
-The same principle applies to other docblock data that is currently
-extracted from raw text at multiple read sites (descriptions, link
-URLs, see references), though those are smaller wins.
-
----
-
 ## P15. Two-phase stub index construction (eliminate `RwLock` on stub maps)
 
 **Impact: Low · Effort: Medium**
@@ -933,7 +886,9 @@ computing. What is left, re-profiled after the memo:
 - Type strings are still parsed during the diagnostic pass rather than
   at index time: `TypeTokenStream::fill_buffer_slow`, `PhpType::parse`,
   `LocalArena::alloc_slice_copy` and `parse_primary_type` together are
-  ~6.5% of Phase 2 samples. This is P14's territory.
+  ~6.5% of Phase 2 samples. Class-level `@method` / `@property` tags
+  are now parsed at extraction time; the remaining cost is method,
+  parameter and return type strings.
 - malloc/free/memmove remains diffuse. `is_scalar_name` and
   `is_keyword_type` (~2.3% between them) allocate a lowercase `String`
   per call and are reached from `base_name`, the subtype checks and the

src/code_actions/extract_interface.rs

@@ -580,6 +580,7 @@ mod tests {
             trait_precedences: vec![],
             trait_aliases: vec![],
             class_docblock: None,
+            doc_members: None,
             file_namespace: Some(Atom::from("App\\Models")),
             backed_type: None,
             attribute_targets: 0,
@@ -641,6 +642,7 @@ mod tests {
             trait_precedences: vec![],
             trait_aliases: vec![],
             class_docblock: None,
+            doc_members: None,
             file_namespace: None,
             backed_type: None,
             attribute_targets: 0,
@@ -690,6 +692,7 @@ mod tests {
             trait_precedences: vec![],
             trait_aliases: vec![],
             class_docblock: None,
+            doc_members: None,
             file_namespace: None,
             backed_type: None,
             attribute_targets: 0,

src/completion/eloquent_string.rs

@@ -735,10 +735,8 @@ fn collect_model_columns(class: &ClassInfo) -> Vec<String> {
     }
 
     // @property tags from docblock.
-    if let Some(ref doc_text) = class.class_docblock {
-        for (name, _type_str) in crate::docblock::extract_property_tags(doc_text) {
-            push(&name);
-        }
+    for (name, _type) in class.doc_properties() {
+        push(name);
     }
 
     columns

src/completion/source/throws_analysis_tests.rs

@@ -861,6 +861,7 @@ fn make_class_with_throws(name: &str, methods: Vec<(&str, Vec<&str>)>) -> Arc<Cl
         trait_precedences: Vec::new(),
         trait_aliases: Vec::new(),
         class_docblock: None,
+        doc_members: None,
         file_namespace: None,
         backed_type: None,
         attribute_targets: 0,

src/definition/member/mod.rs

@@ -35,7 +35,6 @@ use tower_lsp::lsp_types::*;
 use super::point_location;
 use crate::Backend;
 use crate::class_lookup::find_class_at_offset;
-use crate::docblock;
 use crate::text_position::position_to_offset;
 use crate::type_engine::resolver::ResolutionCtx;
 use crate::types::ResolvedType;
@@ -806,23 +805,14 @@ impl Backend {
         None
     }
 
-    /// Check if a class's deferred docblock contains `@method` or `@property`
-    /// tags that declare the given member name.
+    /// Check if a class's docblock declares `@method` or `@property` tags
+    /// for the given member name.
     ///
-    /// Returns `(has_method, has_property)`.  This is a lazy parse of the
-    /// class-level docblock that only runs when the member was not found
-    /// among real declared members.
+    /// Returns `(has_method, has_property)`.
     fn has_docblock_virtual_member(class: &ClassInfo, member_name: &str) -> (bool, bool) {
-        let doc_text = match class.class_docblock.as_deref() {
-            Some(t) if !t.is_empty() => t,
-            _ => return (false, false),
-        };
-
-        let has_method = docblock::extract_method_tags(doc_text)
-            .iter()
-            .any(|m| m.name == member_name);
-
-        let has_property = docblock::extract_property_tags(doc_text)
+        let has_method = class.doc_methods().iter().any(|m| m.name == member_name);
+        let has_property = class
+            .doc_properties()
             .iter()
             .any(|(name, _)| name == member_name);
 

src/docblock/mod.rs

@@ -72,7 +72,10 @@ pub use templates::{
 };
 
 // Virtual member tags
-pub use virtual_members::{extract_method_tags, extract_property_tags};
+pub use virtual_members::{
+    extract_method_tags, extract_method_tags_from_info, extract_property_tags,
+    extract_property_tags_from_info,
+};
 
 // Conditional return types
 pub use conditional::{extract_conditional_return_type, extract_conditional_return_type_from_info};

src/docblock/virtual_members.rs

@@ -7,11 +7,11 @@
 //!   - `@method ReturnType methodName(ParamType $param, ...)`
 //!   - `@method static ReturnType methodName(...)`
 
-use crate::atom::AtomMap;
+use crate::atom::{Atom, AtomMap, atom};
 
 use mago_docblock::document::TagKind;
 
-use super::parser::parse_docblock_for_tags;
+use super::parser::{DocblockInfo, parse_docblock_for_tags};
 use super::tags::sanitise_and_parse_docblock_type;
 use super::type_strings::split_type_token;
 use crate::php_type::PhpType;
@@ -32,11 +32,18 @@ use crate::types::{MethodInfo, ParameterInfo, Visibility};
 ///
 /// Returns a list of `(property_name, cleaned_type)` pairs.  The property
 /// name does **not** include the `$` prefix.
-pub fn extract_property_tags(docblock: &str) -> Vec<(String, Option<PhpType>)> {
+pub fn extract_property_tags(docblock: &str) -> Vec<(Atom, Option<PhpType>)> {
     let Some(info) = parse_docblock_for_tags(docblock) else {
         return Vec::new();
     };
+    extract_property_tags_from_info(&info)
+}
 
+/// [`extract_property_tags`] against an already-parsed docblock.
+///
+/// Class-level docblocks are parsed once during extraction, so the class
+/// parser reuses that [`DocblockInfo`] instead of re-parsing the text.
+pub fn extract_property_tags_from_info(info: &DocblockInfo) -> Vec<(Atom, Option<PhpType>)> {
     const PROPERTY_KINDS: &[TagKind] = &[
         TagKind::Property,
         TagKind::PropertyRead,
@@ -62,7 +69,7 @@ pub fn extract_property_tags(docblock: &str) -> Vec<(String, Option<PhpType>)> {
             if name.is_empty() {
                 continue;
             }
-            results.push((name.to_string(), None));
+            results.push((atom(name), None));
             continue;
         }
 
@@ -90,7 +97,7 @@ pub fn extract_property_tags(docblock: &str) -> Vec<(String, Option<PhpType>)> {
         } else {
             sanitise_and_parse_docblock_type(type_str)
         };
-        results.push((name.to_string(), parsed));
+        results.push((atom(name), parsed));
     }
 
     results
@@ -113,7 +120,14 @@ pub fn extract_method_tags(docblock: &str) -> Vec<MethodInfo> {
     let Some(info) = parse_docblock_for_tags(docblock) else {
         return Vec::new();
     };
+    extract_method_tags_from_info(&info)
+}
 
+/// [`extract_method_tags`] against an already-parsed docblock.
+///
+/// Class-level docblocks are parsed once during extraction, so the class
+/// parser reuses that [`DocblockInfo`] instead of re-parsing the text.
+pub fn extract_method_tags_from_info(info: &DocblockInfo) -> Vec<MethodInfo> {
     const METHOD_KINDS: &[TagKind] = &[TagKind::Method, TagKind::PsalmMethod];
 
     let mut results: Vec<MethodInfo> = Vec::new();