Preserve method chain type through __call fallback

Author: AJenbo

docs/CHANGELOG.md

@@ -52,6 +52,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - **Diagnostics now work for vendor files open in the editor.** Projects using `--prefer-source` or monorepo setups where libraries are edited from the `vendor/` directory no longer have diagnostics suppressed. Previously all vendor files were unconditionally skipped, hiding syntax errors, deprecation warnings, and all other diagnostics. The `analyze` command also accepts vendor paths as explicit overrides (e.g. `phpantom_lsp analyze vendor/some-package/src/`).
 - **Full-line diagnostic suppression no longer requires a code mapping.** Full-line diagnostics (from tools like PHPStan that only report line numbers) are now suppressed whenever any precise diagnostic exists on the same line, regardless of error codes. Previously suppression relied on a hand-maintained mapping between error codes from different tools, which was incomplete and allowed redundant full-line underlines to obscure the precise location of the issue.
 
+- **Method chains through `__call` no longer lose the return type.** When a class defines `__call` and an unrecognized method is called (e.g. dynamic `whereColumn()` on an Eloquent Builder), the return type of `__call` is now used as a fallback. If `__call` returns `$this`, `static`, or `self`, the chain type is preserved so subsequent calls continue resolving. Previously the type was lost at the first dynamic call, breaking every link after it.
 - **Null narrowing from `!== null` checks in conditions.** When a null-initialized variable was guarded by `$var !== null` in an `if` or `while` condition, the variable still showed `null` in its type inside the condition's `&&` operands and inside the then-body. The `!== null` check (and `!is_null()`, bare truthy guards) now narrows away `null` both for subsequent `&&` operands and inside the corresponding body block. Chained conditions like `$a !== null && $b !== null && $a->method()` narrow all checked variables. Conditions wrapped inside ternary expressions and return statements are also handled.
 - **Variables assigned inside `if`/`while` conditions now resolve in the body.** `if ($admin = AdminUser::first())` and `while ($row = nextRow())` now register the assignment so the variable has a type inside the loop or branch body. Assignments wrapped in comparisons like `if (($conn = getConn()) !== null)` are also recognized.
 - **Fluent chains only flag the first broken link.** In a chain like `$m->callHome()->callMom()->callDad()` where `callHome` does not exist, only `callHome` is flagged. Previously every subsequent link received its own "cannot verify" warning, burying the root cause in noise. Separate statements on the same variable (`$m->callHome(); $m->callMom();`) still flag independently. Scalar member access chains (`$user->getAge()->value->deep`) flag only the first scalar break. Null-safe, static, and mixed-operator chains are all handled.

docs/todo.md

@@ -24,7 +24,6 @@ within the same impact tier.
 | #   | Item                                                                                                                                       | Impact | Effort     |
 | --- | ------------------------------------------------------------------------------------------------------------------------------------------ | ------ | ---------- |
 | T18 | [Method-level template parameter resolution at call sites](todo/type-inference.md#t18-method-level-template-parameter-resolution-at-call-sites) | Medium | Medium     |
-| B21 | [Builder `__call` return type drops chain type for dynamic `where{Column}` calls](todo/bugs.md#b21-builder-__call-return-type-drops-chain-type-for-dynamic-wherecolumn-calls) | Medium | Medium     |
 | H17 | [`missingType.iterableValue` — add `@return` with inferred element type](todo/phpstan-actions.md#h17-missingtype-iterablevalue-return-type--add-return-with-iterable-type) | Medium | High       |
 | H10 | [`return.unusedType` — remove unused type from return union](todo/phpstan-actions.md#h10-returnunusedtype--remove-unused-type-from-return-union) | Medium | Medium     |
 | L12 | [`App::make` / `App::makeWith` class-string return type dispatch](todo/laravel.md#l12-appmake--appmakewith-class-string-return-type-dispatch) | Medium | Low        |

docs/todo/bugs.md

@@ -1,50 +1 @@
-# PHPantom — Bug Fixes
-
-#### B21. Builder `__call` return type drops chain type for dynamic `where{Column}` calls
-
-| | |
-|---|---|
-| **Impact** | Medium |
-| **Effort** | Medium |
-
-Eloquent's `Builder::__call()` intercepts calls like `whereColumnName()`
-and forwards them to `where('column_name', ...)`. PHPantom correctly
-suppresses the "unknown member" diagnostic because `Builder` has `__call`,
-but the return type of the magic call is lost. This breaks every
-subsequent link in the chain.
-
-**Reproducer:**
-
-```php
-// SubcategoryView has scopeWhereLanguage but NOT scopeWhereSubcategoryId.
-// whereSubcategoryId() is a dynamic where{Column} via Builder::__call.
-$view = SubcategoryView::whereLanguage($lang)
-    ->whereSubcategoryId($id)   // accepted (Builder has __call), but return type lost
-    ->first();                  // diagnostic: "subject type could not be resolved"
-```
-
-**Expected:** When `__call` is invoked on an Eloquent `Builder<TModel>`,
-the return type should be `Builder<TModel>` (i.e. `$this`), preserving
-the generic parameter so the chain continues resolving.
-
-**Root cause:** `has_magic_method_for_access` in `unknown_members.rs`
-correctly detects `__call` and suppresses the diagnostic, but the
-call-resolution pipeline in `call_resolution.rs` does not attempt to
-derive a return type from `__call`. For Eloquent builders specifically,
-any unrecognised instance method call should return `$this` (the
-builder), since nearly all `Builder` methods are fluent.
-
-**Where to fix:**
-- `src/completion/call_resolution.rs` — when resolving a method call
-  that is not found on the class but the class has `__call`, check
-  whether the class is an Eloquent `Builder` (or extends one). If so,
-  return `$this` / the builder type as the call's return type instead
-  of giving up.
-- Alternatively, add a fallback in `resolve_method_return_types_with_args`
-  that checks for `__call` and uses its declared return type (or `$this`
-  for known builder classes).
-
-**Impact in shared codebase:** ~5 diagnostics (direct chain breaks after
-dynamic `where{Column}` calls, plus downstream cascading failures).
-
-**Discovered in:** analyze-triage iteration 10.
+# PHPantom — Bug Fixes

src/completion/call_resolution.rs

@@ -61,6 +61,11 @@ pub(super) struct MethodReturnCtx<'a> {
     /// appears), as opposed to the class that owns the method being called.
     /// Used to resolve `self`/`static`/`parent` in conditional return types.
     pub calling_class_name: Option<&'a str>,
+    /// Whether the call is a static method call (`Class::method()`).
+    ///
+    /// When `true`, the magic-method fallback checks `__callStatic`
+    /// instead of `__call`.
+    pub is_static: bool,
 }
 
 /// Build a [`VarClassStringResolver`] closure from a [`ResolutionCtx`].
@@ -409,6 +414,7 @@ impl Backend {
                         var_resolver: Some(&var_resolver),
                         cache: ctx.resolved_class_cache,
                         calling_class_name: ctx.current_class.map(|c| c.name.as_str()),
+                        is_static: false,
                     };
                     results.extend(Self::resolve_method_return_types_with_args(
                         owner,
@@ -444,6 +450,7 @@ impl Backend {
                         var_resolver: Some(&var_resolver),
                         cache: ctx.resolved_class_cache,
                         calling_class_name: ctx.current_class.map(|c| c.name.as_str()),
+                        is_static: true,
                     };
                     return Self::resolve_method_return_types_with_args(
                         owner,
@@ -841,6 +848,15 @@ impl Backend {
             vec![]
         };
 
+        // Determine which magic method handles unknown calls for this
+        // access kind: `__call` for instance calls, `__callStatic` for
+        // static calls.
+        let magic_name = if mr_ctx.is_static {
+            "__callStatic"
+        } else {
+            "__call"
+        };
+
         // First check the class itself
         if let Some(method) = class_info.methods.iter().find(|m| m.name == method_name) {
             let result = resolve_method(method);
@@ -859,13 +875,263 @@ impl Backend {
             class_loader,
             mr_ctx.cache,
         );
+
+        // Look up the magic method once; used for both validation and
+        // fallback below.
+        let magic_method = merged
+            .methods
+            .iter()
+            .find(|m| m.name.eq_ignore_ascii_case(magic_name));
+
         if let Some(method) = merged.methods.iter().find(|m| m.name == method_name) {
-            return resolve_method(method);
+            if method.is_virtual {
+                // ── Virtual method (from @method, @mixin, etc.) ─────
+                // At runtime these are dispatched through __call /
+                // __callStatic.  Validate the virtual method's return
+                // type against the magic method's native return type
+                // the same way we validate a concrete implementation
+                // against an interface: the virtual type can only
+                // *narrow* the native constraint, not contradict it.
+                if let Some(ref virtual_ret) = method.return_type {
+                    if let Some(magic) = magic_method {
+                        if let Some(ref native_ret) = magic.native_return_type {
+                            // The magic method has a native PHP type
+                            // hint.  Check whether the virtual
+                            // method's declared type is a valid
+                            // narrowing of that native constraint.
+                            if is_valid_virtual_narrowing(
+                                virtual_ret,
+                                native_ret,
+                                class_info,
+                                all_classes,
+                                class_loader,
+                            ) {
+                                // Valid narrowing — trust the virtual
+                                // method's declared type.
+                                let result = resolve_method(method);
+                                if !result.is_empty() {
+                                    return result;
+                                }
+                            }
+                            // Invalid narrowing (lie) or the virtual
+                            // type failed to resolve.  Fall through
+                            // to the magic-method fallback below,
+                            // which will use __call's own return type.
+                        } else {
+                            // Magic method has no native type hint —
+                            // trust the virtual method's declared type.
+                            let result = resolve_method(method);
+                            if !result.is_empty() {
+                                return result;
+                            }
+                        }
+                    } else {
+                        // No magic method at all — trust the virtual
+                        // method's declared type unconditionally.
+                        let result = resolve_method(method);
+                        if !result.is_empty() {
+                            return result;
+                        }
+                    }
+                }
+                // Virtual method with no return type (or whose type
+                // was rejected by the validation above).  Fall through
+                // to the magic-method fallback below.
+            } else {
+                // ── Real method ─────────────────────────────────────
+                // Real methods are invoked directly at runtime, never
+                // through __call.  Use whatever resolve_method
+                // returns, even if empty.
+                return resolve_method(method);
+            }
+        }
+
+        // ── Magic-method fallback ───────────────────────────────
+        // Either the method was not found at all, or it was a virtual
+        // method whose return type was absent or rejected by the
+        // native-type validation.  Use the magic method's effective
+        // return type (docblock-overridden if available, otherwise
+        // native).  When the magic method returns `$this`/`static`/
+        // `self`, this preserves the chain type (e.g. Builder<User>
+        // stays Builder<User> through dynamic `where{Column}` calls).
+        // When it returns `mixed`, no classes resolve and the caller
+        // gets an empty vec — the same as before this fallback.
+        if let Some(magic) = magic_method {
+            let result = resolve_method(magic);
+            if !result.is_empty() {
+                return result;
+            }
         }
 
         vec![]
     }
+}
+
+// ─── Virtual method narrowing ───────────────────────────────────────────────
+
+/// Check whether a virtual method's return type is a valid narrowing of a
+/// magic method's (`__call` / `__callStatic`) native return type.
+///
+/// At runtime, calls to virtual methods (from `@method` tags, `@mixin`
+/// members, etc.) are dispatched through the magic method.  The magic
+/// method's native PHP type hint is the runtime truth: the virtual
+/// method's declared type can only *narrow* it (provide a more specific
+/// subtype), not contradict it.
+///
+/// Returns `true` when the virtual type should be trusted, `false` when
+/// it should be rejected in favour of the magic method's type.
+///
+/// # Examples
+///
+/// | `__call` native | `@method` type | Result |
+/// |-----------------|----------------|--------|
+/// | `mixed`         | `Frog`         | ✓ (anything narrows mixed) |
+/// | `object`        | `Frog`         | ✓ (any class narrows object) |
+/// | `static`        | `ChildClass`   | ✓ if ChildClass extends the owner |
+/// | `Animal`        | `Dog`          | ✓ if Dog extends Animal |
+/// | `Cement`        | `Frog`         | ✗ (unrelated classes) |
+/// | `static`        | `Frog`         | ✗ if Frog does not extend the owner |
+/// | `int`           | `string`       | ✗ (incompatible scalars) |
+fn is_valid_virtual_narrowing(
+    virtual_type: &PhpType,
+    native_type: &PhpType,
+    owner_class: &ClassInfo,
+    all_classes: &[Arc<ClassInfo>],
+    class_loader: &dyn Fn(&str) -> Option<Arc<ClassInfo>>,
+) -> bool {
+    let native_str = native_type.to_string();
+    let native_lower = native_str.to_ascii_lowercase();
+
+    // `mixed` and `void` impose no constraint — any type is valid.
+    if matches!(native_lower.as_str(), "mixed" | "void") {
+        return true;
+    }
+
+    // `object` — any class type is a valid narrowing.
+    if native_lower == "object" {
+        // Only reject if the virtual type is a non-object scalar.
+        return !virtual_type.is_scalar();
+    }
+
+    // Self-like types (`static`, `self`, `$this`) resolve to the owner
+    // class at runtime.  The virtual type must be the owner class itself
+    // or a subclass of it.
+    if is_self_like_type(native_type) {
+        return is_type_subclass_of(virtual_type, &owner_class.name, all_classes, class_loader);
+    }
+
+    // Both are concrete types.  For scalar-to-scalar, delegate to the
+    // existing `should_override_type` check which handles compatible
+    // refinements (e.g. `string` → `class-string<T>`).
+    if native_type.is_scalar() {
+        let virtual_str = virtual_type.to_string();
+        return crate::docblock::should_override_type(&virtual_str, &native_str);
+    }
+
+    // Native is a class type — the virtual type must be the same class
+    // or a subclass.
+    is_type_subclass_of(virtual_type, &native_str, all_classes, class_loader)
+}
+
+/// Check whether `candidate_type` is the same class as `ancestor_name` or
+/// a subclass of it, by walking the parent chain.
+///
+/// Returns `true` when:
+/// - The candidate type's base name matches `ancestor_name` (case-insensitive).
+/// - The candidate class's parent chain includes `ancestor_name`.
+/// - The candidate class cannot be resolved (benefit of the doubt).
+fn is_type_subclass_of(
+    candidate_type: &PhpType,
+    ancestor_name: &str,
+    all_classes: &[Arc<ClassInfo>],
+    class_loader: &dyn Fn(&str) -> Option<Arc<ClassInfo>>,
+) -> bool {
+    let candidate_str = candidate_type.to_string();
+
+    // Strip leading backslash and generic parameters for name comparison.
+    let candidate_base = candidate_str
+        .strip_prefix('\\')
+        .unwrap_or(&candidate_str)
+        .split('<')
+        .next()
+        .unwrap_or(&candidate_str);
+    let ancestor_base = ancestor_name
+        .strip_prefix('\\')
+        .unwrap_or(ancestor_name)
+        .split('<')
+        .next()
+        .unwrap_or(ancestor_name);
+
+    // Same class (case-insensitive, ignoring namespace prefix differences).
+    if candidate_base.eq_ignore_ascii_case(ancestor_base) {
+        return true;
+    }
+    // Also check short-name match (e.g. "Dog" vs "App\\Models\\Dog").
+    let candidate_short = crate::util::short_name(candidate_base);
+    let ancestor_short = crate::util::short_name(ancestor_base);
+    if candidate_short.eq_ignore_ascii_case(ancestor_short) {
+        return true;
+    }
 
+    // Try to load the candidate class and walk its parent chain.
+    let candidate_class = find_class_by_name(all_classes, candidate_base)
+        .cloned()
+        .or_else(|| class_loader(candidate_base));
+
+    let Some(cls) = candidate_class else {
+        // Cannot resolve the candidate class — give benefit of the
+        // doubt and trust the @method tag.
+        return true;
+    };
+
+    // Walk the parent chain up to a reasonable depth.
+    let mut current_parent = cls.parent_class.clone();
+    let mut depth = 0u32;
+    while let Some(ref parent_name) = current_parent {
+        depth += 1;
+        if depth > 20 {
+            break;
+        }
+        let parent_base = parent_name
+            .strip_prefix('\\')
+            .unwrap_or(parent_name)
+            .split('<')
+            .next()
+            .unwrap_or(parent_name);
+        if parent_base.eq_ignore_ascii_case(ancestor_base)
+            || crate::util::short_name(parent_base).eq_ignore_ascii_case(ancestor_short)
+        {
+            return true;
+        }
+        // Also check implemented interfaces on the parent.
+        let parent_class = find_class_by_name(all_classes, parent_base)
+            .cloned()
+            .or_else(|| class_loader(parent_base));
+        match parent_class {
+            Some(p) => current_parent = p.parent_class.clone(),
+            None => break,
+        }
+    }
+
+    // Also check the candidate's own implemented interfaces.
+    for iface in &cls.interfaces {
+        let iface_base = iface
+            .strip_prefix('\\')
+            .unwrap_or(iface)
+            .split('<')
+            .next()
+            .unwrap_or(iface);
+        if iface_base.eq_ignore_ascii_case(ancestor_base)
+            || crate::util::short_name(iface_base).eq_ignore_ascii_case(ancestor_short)
+        {
+            return true;
+        }
+    }
+
+    false
+}
+
+impl Backend {
     /// Build a template substitution map for a method-level `@template` call.
     ///
     /// Finds the method on the class (or inherited), checks for template