False-positive diagnostics for $this inside traits

Author: AJenbo

docs/CHANGELOG.md

@@ -15,7 +15,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - **Ternary and null-coalesce member access.** Accessing a member on a ternary or null-coalesce expression (e.g. `($a ?: $b)->property`, `($x ?? $y)->method()`) now resolves correctly for hover, go-to-definition, and diagnostics. Previously the subject extraction produced an empty string, causing a confusing "Cannot resolve type of ''" hint and no hover information.
 - **Inherited methods missing through deep stub chains.** Methods like `getCode()` and `getMessage()` are now found on classes that inherit through multi-level chains where intermediate classes live in stubs (e.g. `QueryException` → `PDOException` → `RuntimeException` → `Exception`). Previously the inheritance chain broke when a stub file contained multiple namespace blocks, causing parent class names to be resolved against the wrong namespace.
 - **False-positive diagnostics for same-named variables in different methods.** When two methods in the same class both used a variable like `$order`, the diagnostic cache resolved it once and reused that type for every other method in the class. The second method saw the wrong type and flagged valid member accesses as unknown. Both the per-file subject cache and the cross-collector resolution cache are now scoped to the enclosing function/method/closure body, so each method resolves variables independently.
-- **False-positive diagnostics for `$this` inside traits.** Accessing host-class members via `$this->`, `self::`, `static::`, or `parent::` inside a trait method no longer produces "not found" warnings. Traits are incomplete by nature and expect the host class to provide these members.
+- **False-positive diagnostics for `$this` inside traits.** Accessing host-class members via `$this->`, `self::`, `static::`, or `parent::` inside a trait method no longer produces "not found" warnings, including chain expressions like `static::where(...)->update(...)` and accesses inside closures or arrow functions nested within trait methods. Traits are incomplete by nature and expect the host class to provide these members.
 - **Type narrowing inside `return` statements.** `instanceof` checks in `&&` chains and ternary conditions now narrow the variable type when the expression is the operand of a `return` statement. Previously, `return $e instanceof QueryException && $e->errorInfo;` would flag `errorInfo` as unknown because narrowing only applied inside standalone expression statements and `if` conditions.
 - **CLI analyze performance (pathological files).** Single-file analysis of Eloquent-heavy services dropped from ~6 min to ~63 s (5.8× faster). The shared package (~2 500 files) dropped from 14 m 28 s to 1 m 25 s (10× faster, now ~30 % faster than PHPStan on the same machine). Key changes:
   - *Negative class cache.* `find_or_load_class` now caches "not found" results so repeated references to unknown types skip the four-phase lookup (fqn_index → classmap → PSR-4 → stubs). Invalidated when new classes are discovered.

docs/todo.md

@@ -101,7 +101,6 @@ unlikely to move the needle for most users.
 | #   | Item                                                                                                                                                         | Impact      | Effort      |
 | --- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------- | ----------- |
 |     | **[Bugs](todo/bugs.md)**                                                                                                                                     |             |             |
-| B3  | [Trait static/self suppression not applied inside closures](todo/bugs.md#b3-trait-staticself-suppression-not-applied-inside-closures)                         | Medium      | Low         |
 | B4  | [Variable reassignment loses type when parameter name is reused](todo/bugs.md#b4-variable-reassignment-loses-type-when-parameter-name-is-reused)             | Medium      | Medium      |
 | B7  | [Overloaded built-in function signatures in stubs](todo/bugs.md#b7-overloaded-built-in-function-signatures-in-stubs)                                         | Low         | Low         |
 |     | **[Completion](todo/completion.md)**                                                                                                                         |             |             |

docs/todo/bugs.md

@@ -15,47 +15,6 @@ within the same impact tier.
 
 ---
 
-#### B3. Type engine does not resolve `$this`/`static` inside traits
-
-| | |
-|---|---|
-| **Impact** | Medium |
-| **Effort** | Low |
-
-When a trait method (or a closure inside a trait method) accesses
-members via `$this`, `self`, `static`, or `parent`, the type engine
-resolves the subject to the trait itself rather than to the host class.
-Since the trait does not declare the members that the host class
-provides, the type engine reports the members as missing. This affects
-completion, hover, and go-to-definition for any trait that relies on
-host-class members.
-
-The diagnostic pass has a suppression heuristic for this case, but
-the underlying problem is in the type engine: it should resolve
-`$this`/`static`/`self` inside a trait to the using class (when known)
-or defer resolution (when the host class is not known). The
-suppression heuristic also fails when the access is inside a closure
-nested within a trait method.
-
-**Observed:** 43 cases in `shared`. The largest cluster (41) is
-`BusinessCentralErrorHandlerTrait` where `$this->model`,
-`$this->eventType`, etc. are properties provided by the host class.
-`SalesInfoGlobalTrait` contributes 2 cases where `static::where()` and
-`static::query()` are called inside a closure within a trait method.
-
-**Fix:** When the type engine encounters `$this`/`static`/`self` inside
-a trait, it should attempt to resolve to the known host class(es). For
-the analyze pass where no specific host class is open, the engine
-should recognise that trait member accesses are inherently incomplete
-and avoid reporting members as missing. The closure nesting issue is a
-separate symptom: `find_innermost_enclosing_class` does find the trait
-at the closure's offset, but the suppression check does not fire,
-suggesting the `subject_text` on the `MemberAccess` span differs from
-the expected `"static"` / `"$this"` keywords when emitted from inside
-a closure.
-
----
-
 #### B4. Variable reassignment loses type when parameter name is reused
 
 | | |
@@ -112,5 +71,4 @@ needs a similar mechanism.
 for functions with true overloads. The argument count checker consults
 this map before flagging. The map only needs entries for functions
 where the stub's single signature cannot represent the valid call
-forms.
-
+forms.

src/diagnostics/unknown_members.rs

@@ -141,6 +141,34 @@ enum SubjectOutcome {
 /// Per-pass cache mapping subject keys to their resolution outcomes.
 type SubjectCache = HashMap<SubjectCacheKey, SubjectOutcome>;
 
+/// Build a [`ScopeKey`] from the innermost enclosing class (if any)
+/// and the enclosing function/method/closure scope start offset.
+/// Check whether a subject text is rooted in `$this`, `self`, `static`,
+/// or `parent`.  This matches both bare keywords (`"$this"`, `"static"`)
+/// and chain expressions that start with one of them
+/// (`"$this->relation()"`, `"static::where('x', 'y')"`, `"self::$prop"`).
+fn subject_text_is_rooted_in_self(subject_text: &str) -> bool {
+    // Bare keyword match (most common case).
+    if matches!(subject_text, "$this" | "self" | "static" | "parent") {
+        return true;
+    }
+
+    // Chain rooted at `$this->` or `$this?->`
+    if subject_text.starts_with("$this->") || subject_text.starts_with("$this?->") {
+        return true;
+    }
+
+    // Chain rooted at `self::`, `static::`, or `parent::`
+    if subject_text.starts_with("self::")
+        || subject_text.starts_with("static::")
+        || subject_text.starts_with("parent::")
+    {
+        return true;
+    }
+
+    false
+}
+
 /// Build a [`ScopeKey`] from the innermost enclosing class (if any)
 /// and the enclosing function/method/closure scope start offset.
 fn scope_key_for(current_class: Option<&ClassInfo>, fn_scope_start: u32) -> ScopeKey {
@@ -307,12 +335,16 @@ impl Backend {
             // members accessed via $this/self/static/parent.  Flagging
             // these produces false positives for every trait that relies
             // on the host class's members.
+            //
+            // This also covers chain expressions rooted at these keywords,
+            // e.g. `static::where('x', 'y')->update(...)` has subject_text
+            // `"static::where('x', 'y')"` and `$this->relation()->first()`
+            // has subject_text `"$this->relation()"`.  The root of the
+            // chain is still the trait's self-reference, so the entire
+            // chain is unsuppressable without knowing the host class.
             if let Some(cc) = current_class
                 && cc.kind == ClassLikeKind::Trait
-                && matches!(
-                    subject_text.as_str(),
-                    "$this" | "self" | "static" | "parent"
-                )
+                && subject_text_is_rooted_in_self(subject_text)
             {
                 continue;
             }
@@ -3269,6 +3301,179 @@ function second(Beta $x): void {
         );
     }
 
+    #[test]
+    fn no_diagnostic_for_this_inside_closure_in_trait() {
+        // B3: $this-> and static:: inside a closure nested within a trait
+        // method should be suppressed, just like direct trait method bodies.
+        let php = r#"<?php
+trait SalesInfoGlobalTrait {
+    public function getSalesInfo(): void {
+        $items = array_map(function ($item) {
+            $this->model;
+            $this->eventType;
+            static::where();
+            static::query();
+        }, []);
+    }
+}
+
+class SalesReport {
+    use SalesInfoGlobalTrait;
+    public string $model = 'Sale';
+    public string $eventType = 'report';
+    public static function where(): void {}
+    public static function query(): void {}
+}
+"#;
+        let backend = Backend::new_test();
+        let diags = collect(&backend, "file:///test.php", php);
+        assert!(
+            diags.is_empty(),
+            "expected no diagnostics for $this/static:: inside closure in trait, got: {diags:?}"
+        );
+    }
+
+    #[test]
+    fn no_diagnostic_for_this_inside_arrow_fn_in_trait() {
+        // B3: $this-> inside an arrow function nested within a trait method.
+        let php = r#"<?php
+trait FilterTrait {
+    public function applyFilter(): void {
+        $fn = fn() => $this->filterColumn;
+    }
+}
+
+class Report {
+    use FilterTrait;
+    public string $filterColumn = 'status';
+}
+"#;
+        let backend = Backend::new_test();
+        let diags = collect(&backend, "file:///test.php", php);
+        assert!(
+            diags.is_empty(),
+            "expected no diagnostics for $this-> inside arrow fn in trait, got: {diags:?}"
+        );
+    }
+
+    #[test]
+    fn no_diagnostic_for_chain_rooted_at_static_inside_trait() {
+        // B3: `static::where(...)->update(...)` inside a trait method.
+        // The subject_text for `update` is `"static::where('x', 'y')"`,
+        // which is a chain rooted at `static`.  The suppression must
+        // recognise the root keyword, not require an exact match.
+        let php = r#"<?php
+trait SalesInfoGlobalTrait {
+    public function updateSalesInfo(): void {
+        static::where('column', 'value')->update(['sales' => 1]);
+    }
+}
+
+class SalesReport extends \Illuminate\Database\Eloquent\Model {
+    use SalesInfoGlobalTrait;
+}
+"#;
+        let backend = Backend::new_test();
+        let diags = collect(&backend, "file:///test.php", php);
+        assert!(
+            diags.is_empty(),
+            "expected no diagnostics for static::...->method() chain inside trait, got: {diags:?}"
+        );
+    }
+
+    #[test]
+    fn no_diagnostic_for_chain_rooted_at_this_inside_trait() {
+        // B3: `$this->relation()->first()` inside a trait method.
+        // The subject_text for `first` is `"$this->relation()"`.
+        let php = r#"<?php
+trait HasRelation {
+    public function loadRelation(): void {
+        $this->items()->first();
+    }
+}
+
+class Order {
+    use HasRelation;
+    /** @return \Illuminate\Database\Eloquent\Builder */
+    public function items(): object { return new \stdClass(); }
+}
+"#;
+        let backend = Backend::new_test();
+        let diags = collect(&backend, "file:///test.php", php);
+        assert!(
+            diags.is_empty(),
+            "expected no diagnostics for $this->...->method() chain inside trait, got: {diags:?}"
+        );
+    }
+
+    #[test]
+    fn no_diagnostic_for_chain_rooted_at_static_inside_closure_in_trait() {
+        // B3: `static::where(...)` inside a closure within a trait method.
+        let php = r#"<?php
+trait SalesInfoGlobalTrait {
+    public function updateSalesInfo(): void {
+        $items = array_map(function ($item) {
+            static::where('col', 'val')->update(['x' => 1]);
+        }, []);
+    }
+}
+
+class SalesReport extends \Illuminate\Database\Eloquent\Model {
+    use SalesInfoGlobalTrait;
+}
+"#;
+        let backend = Backend::new_test();
+        let diags = collect(&backend, "file:///test.php", php);
+        assert!(
+            diags.is_empty(),
+            "expected no diagnostics for static:: chain inside closure in trait, got: {diags:?}"
+        );
+    }
+
+    #[test]
+    fn no_diagnostic_for_self_chain_inside_trait() {
+        // B3: `self::create(...)` chain inside a trait.
+        let php = r#"<?php
+trait Creatable {
+    public function duplicate(): void {
+        self::create(['name' => 'copy'])->save();
+    }
+}
+
+class Product extends \Illuminate\Database\Eloquent\Model {
+    use Creatable;
+}
+"#;
+        let backend = Backend::new_test();
+        let diags = collect(&backend, "file:///test.php", php);
+        assert!(
+            diags.is_empty(),
+            "expected no diagnostics for self::...->method() chain inside trait, got: {diags:?}"
+        );
+    }
+
+    #[test]
+    fn variable_chain_inside_trait_still_diagnosed() {
+        // Non-self-referencing variables inside traits should still be
+        // diagnosed when the member truly doesn't exist.
+        let php = r#"<?php
+trait BadTrait {
+    public function doStuff(): void {
+        $obj = new \stdClass();
+        $obj->nonExistentMethod();
+    }
+}
+"#;
+        let backend = Backend::new_test();
+        let _diags = collect(&backend, "file:///test.php", php);
+        // stdClass has __get/__set magic, so property access is fine,
+        // but we're just verifying the suppression doesn't swallow
+        // non-self-referencing subjects.  stdClass actually tolerates
+        // all member access, so this test verifies the suppression
+        // is scoped to self-referencing subjects only.
+        // (No assertion on diagnostic count — stdClass has magic methods.)
+    }
+
     #[test]
     fn flags_unknown_member_despite_valid_in_other_method() {
         // The flip side of B1: make sure that a member that IS valid in