Preserve generic arguments in callable param inference

Author: AJenbo

docs/CHANGELOG.md

@@ -68,11 +68,12 @@ 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.
 
-- **Scope methods on Eloquent Builder no longer produce false-positive diagnostics.** When a scope method's return type was a bare `Builder` (without generic arguments), subsequent calls in the chain lost the model type and reported scope methods as not found. Bare `Builder` return types on scope methods are now automatically wrapped as `Builder<ConcreteModel>` to preserve the chain. Additionally, unknown method diagnostics on the Eloquent Builder are suppressed when `__call` is present, since Builder dispatches scope methods and Query\Builder calls through it at runtime.
+- **Scope methods on Eloquent Builder no longer produce false-positive diagnostics.** When a scope method's return type was a bare `Builder` (without generic arguments), subsequent calls in the chain lost the model type and reported scope methods as not found. Bare `Builder` return types on scope methods are now automatically wrapped as `Builder<ConcreteModel>` to preserve the chain.
 - **Hover on closure parameters lost inferred generic arguments.** When a closure parameter had an explicit bare class type hint (e.g. `function (Builder $q)`) and the callable signature inferred the same class with generic arguments (e.g. `Builder<Article>`), hover displayed the bare class name instead of the generic version. The inferred type string is now preserved through the resolution pipeline so that hover, completion, and diagnostics all see the same type.
 - **Hover on variables assigned from chained methods lost generic parameters.** When a method returned `static`, `$this`, or `self` and the receiver carried generic parameters (e.g. `Builder<Article>`), hover on a variable assigned from the chain showed the bare class name (`Builder`) instead of the generic version. The receiver's type string is now carried through method call resolution so that self-referencing return types preserve generic parameters across chains.
 - **Hover on the `$` sign of a variable at its assignment site showed no type.** Hovering on the `$` of `$order = new Order()` displayed a bare `$order` with no type information, while hovering one character to the right on `o` worked correctly. The variable's byte offset coincided with the assignment statement's start offset, causing the resolver to skip the assignment entirely. The cursor offset is now nudged past the statement boundary so the assignment is included.
-- **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.
+- **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. Eloquent Builder's `__call` is patched from `mixed` to `static` during resolution, matching its runtime behavior (scope dispatch, macro dispatch, and Query\Builder forwarding all return the Builder instance).
+- **Callable parameter inference now preserves generic arguments from the receiver.** When a closure parameter is typed as a bare supertype (e.g. `fn(Builder $q)`) but the enclosing method's callable signature provides a more specific type via `$this` or `static` (e.g. `callable($this)`), the inferred type now carries the receiver's generic arguments. For example, calling `->when($flag, fn(Builder $q) => $q->active())` on a `Builder<Product>` chain now infers `$q` as `Builder<Product>`, so model-specific scope methods resolve correctly instead of being flagged as unknown.
 - **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.

src/completion/resolver.rs

@@ -900,19 +900,9 @@ fn resolve_call_raw_return_type(
                     }
                 }
                 // __call fallback: method not found, or virtual method
-                // without a return type.
-                if let Some(m) = merged
-                    .methods
-                    .iter()
-                    .find(|m| m.name.eq_ignore_ascii_case("__call"))
-                    && let Some(ref ret) = m.return_type
-                {
-                    return Some(ret.to_string());
-                }
-                // __call fallback: when the method is not found but the
-                // class defines __call, use its return type so that
-                // chains through dynamic calls (e.g. Builder where{Column})
-                // preserve the type.
+                // without a return type.  Use __call's return type so
+                // that chains through dynamic calls (e.g. Builder
+                // where{Column}) preserve the type.
                 if let Some(m) = merged
                     .methods
                     .iter()

src/completion/variable/closure_resolution.rs

@@ -1594,16 +1594,23 @@ fn infer_callable_params_from_receiver(
 
     let params = find_callable_params_on_classes(&receiver_classes, method_name, arg_idx, ctx);
 
-    // Replace `$this` / `static` tokens with the receiver class FQN
+    // Replace `$this` / `static` tokens with the receiver's full type
     // so that `resolve_closure_params_with_inferred` resolves them
     // against the declaring class rather than the user's current class.
+    //
+    // When the receiver is a generic class whose template params have
+    // already been substituted (e.g. `Builder<Product>`), we need to
+    // reconstruct the full generic type so that the inferred callable
+    // param type carries the generic args.  Without this, `$this` on
+    // `Builder<Product>` would degrade to bare `Builder`, losing the
+    // model type and preventing scope method resolution.
     let result = if let Some(receiver) = receiver_classes.first() {
-        let receiver_fqn = receiver.fqn();
+        let receiver_type = build_receiver_self_type(receiver, ctx.class_loader);
         params
             .into_iter()
             .map(|ty| {
                 crate::php_type::PhpType::parse(&ty)
-                    .replace_self(&receiver_fqn)
+                    .replace_self_with_type(&receiver_type)
                     .to_string()
             })
             .collect()
@@ -1807,6 +1814,94 @@ fn try_relation_query_override(
 /// `Builder<Model>`, extract the model from the Builder's method return
 /// types (which contain the substituted generic arg, e.g.
 /// `Builder<Brand>` → `Brand`).
+/// Build a `PhpType` representing the receiver class for `$this`/`static`
+/// replacement in callable parameter inference.
+///
+/// For most classes this returns `PhpType::Named(fqn)`.  For classes
+/// whose template parameters have been concretely substituted (detected
+/// by scanning method return types for generic signatures), the full
+/// generic type is reconstructed.  For example, an Eloquent
+/// `Builder<Product>` receiver produces
+/// `PhpType::Generic("Illuminate\\Database\\Eloquent\\Builder", [Named("App\\Product")])`
+/// instead of a bare `PhpType::Named("Illuminate\\Database\\Eloquent\\Builder")`.
+///
+/// This preserves generic args through callable param inference so that
+/// `callable($this)` on `Builder<Product>` infers `Builder<Product>`,
+/// not bare `Builder`.
+fn build_receiver_self_type(
+    receiver: &ClassInfo,
+    _class_loader: &dyn Fn(&str) -> Option<Arc<ClassInfo>>,
+) -> PhpType {
+    let fqn = receiver.fqn();
+
+    // Only attempt reconstruction when the class declares template
+    // params — otherwise there are no generic args to recover.
+    if receiver.template_params.is_empty() {
+        return PhpType::Named(fqn);
+    }
+
+    // For Eloquent Builder, extract the model name from method return
+    // types where generic substitution has already been applied.
+    if (receiver.name == "Builder" || fqn == ELOQUENT_BUILDER_FQN)
+        && let Some(model_fqn) = extract_model_from_builder(receiver)
+    {
+        return PhpType::Generic(
+            ELOQUENT_BUILDER_FQN.to_string(),
+            vec![PhpType::Named(model_fqn)],
+        );
+    }
+
+    // General case: try to recover concrete generic args from method
+    // return types that reference the class itself with generic params.
+    // For example, if a `Collection<int, User>` has a method returning
+    // `Collection<int, User>`, we can extract `[int, User]` as the
+    // concrete args.
+    if let Some(args) = extract_generic_args_from_methods(receiver, &fqn) {
+        return PhpType::Generic(fqn, args);
+    }
+
+    // Fallback: if we have a parent class with @extends generics and
+    // only one template param, try to extract from the parent chain.
+    // This covers cases like Relation<TRelatedModel> subclasses.
+    if !receiver.extends_generics.is_empty() && receiver.template_params.len() == 1 {
+        for (_, args) in &receiver.extends_generics {
+            if let Some(first_arg) = args.first() {
+                let arg_str = first_arg.to_string();
+                // Skip raw template param names that weren't substituted.
+                if !receiver.template_params.contains(&arg_str) {
+                    return PhpType::Generic(fqn, vec![first_arg.clone()]);
+                }
+            }
+        }
+    }
+
+    PhpType::Named(fqn)
+}
+
+/// Try to extract concrete generic args from a class's own methods.
+///
+/// Scans method return types for `ClassName<Arg1, Arg2, ...>` patterns
+/// where the base name matches the class, and the args are concrete
+/// (not raw template param names).
+fn extract_generic_args_from_methods(class: &ClassInfo, class_fqn: &str) -> Option<Vec<PhpType>> {
+    let class_short = crate::util::short_name(class_fqn);
+    for method in &class.methods {
+        if let Some(PhpType::Generic(base, args)) = &method.return_type {
+            let base_short = crate::util::short_name(base);
+            if (base == class_fqn || base_short.eq_ignore_ascii_case(class_short))
+                && !args.is_empty()
+                && args.iter().all(|a| {
+                    let s = a.to_string();
+                    !class.template_params.contains(&s)
+                })
+            {
+                return Some(args.clone());
+            }
+        }
+    }
+    None
+}
+
 fn find_model_from_receivers(
     receiver_classes: &[Arc<ClassInfo>],
     class_loader: &dyn Fn(&str) -> Option<Arc<ClassInfo>>,

src/diagnostics/unknown_members.rs

@@ -59,7 +59,6 @@ use crate::Backend;
 use crate::completion::resolver::{ResolutionCtx, SubjectOutcome, resolve_subject_outcome};
 use crate::symbol_map::SymbolKind;
 use crate::types::{AccessKind, ClassInfo, ClassLikeKind};
-use crate::virtual_members::laravel::ELOQUENT_BUILDER_FQN;
 use crate::virtual_members::resolve_class_fully_cached;
 
 use super::helpers::{find_innermost_enclosing_class, make_diagnostic};
@@ -635,27 +634,6 @@ impl Backend {
                     .iter()
                     .any(|c| has_magic_method_for_access(c, is_static, true)));
 
-        // ── Suppress diagnostics on Eloquent Builder with __call ────
-        // Eloquent Builder's `__call` specifically dispatches scope
-        // methods defined on the concrete model and forwards unknown
-        // calls to Query\Builder.  When the Builder is used without
-        // generic args (e.g. a closure parameter typed as bare
-        // `Builder`), scope methods cannot be injected because the
-        // model type is unknown.  Emitting a warning for every scope
-        // call on a bare Builder creates pervasive false positives in
-        // real Laravel projects.  Suppress the diagnostic entirely
-        // when any resolved branch is an Eloquent Builder that has
-        // `__call`, since the method WILL succeed at runtime.
-        if has_magic_call
-            && resolved_classes.iter().any(|c| {
-                c.name == "Builder"
-                    && c.file_namespace.as_deref() == Some("Illuminate\\Database\\Eloquent")
-                    || c.name == ELOQUENT_BUILDER_FQN
-            })
-        {
-            return MemberCheckResult::Ok;
-        }
-
         // ── Member is unresolved on ALL branches — emit diagnostic ──
         let range = match offset_range_to_lsp_range(content, start as usize, end as usize) {
             Some(r) => r,

src/virtual_members/mod.rs

@@ -64,6 +64,7 @@ use crate::inheritance::{
 use crate::php_type::PhpType;
 use crate::types::{ClassInfo, ConstantInfo, MethodInfo, PropertyInfo};
 use crate::util::short_name;
+use crate::virtual_members::laravel::ELOQUENT_BUILDER_FQN;
 
 /// Cache key for [`ResolvedClassCache`]: fully-qualified class name
 /// paired with the concrete generic type arguments used at this
@@ -830,6 +831,20 @@ fn resolve_class_fully_inner(
         }
     }
 
+    // ── Eloquent Builder __call return type override ────────────────
+    // Laravel's `Builder::__call()` is declared as returning `mixed`,
+    // but in practice it always returns `$this`: scope dispatch,
+    // macro dispatch, and Query\Builder forwarding all return the
+    // Builder instance.  The `mixed` docblock breaks method chains
+    // because the resolver cannot recover a class type from `mixed`.
+    // Override the return type to `static` so that chains through
+    // unknown methods (e.g. scope calls on a bare `Builder` without
+    // generic args) preserve the Builder type and downstream methods
+    // like `get()`, `pluck()`, `first()` continue to resolve.
+    if fqn == ELOQUENT_BUILDER_FQN {
+        patch_eloquent_builder_call_return_type(&mut merged);
+    }
+
     // ── Cache store ─────────────────────────────────────────────────
     let result = Arc::new(merged);
     if let Some(cache) = cache {
@@ -839,6 +854,29 @@ fn resolve_class_fully_inner(
     result
 }
 
+/// Override `__call` and `__callStatic` return types on Eloquent Builder
+/// from `mixed` to `static`.
+///
+/// Builder's `__call` dispatches to scope methods (`callNamedScope`),
+/// macros, and `Query\Builder` forwarding — all of which return `$this`.
+/// The `@return mixed` docblock is a PHP limitation; the actual return
+/// type is always the Builder instance.  Patching this here means every
+/// consumer of the resolved Builder (completion, diagnostics, hover)
+/// automatically gets correct chain continuation through unknown methods.
+fn patch_eloquent_builder_call_return_type(class: &mut ClassInfo) {
+    let static_type = PhpType::Named("static".to_string());
+    for method in class.methods.make_mut().iter_mut() {
+        if (method.name == "__call" || method.name == "__callStatic")
+            && method
+                .return_type
+                .as_ref()
+                .is_some_and(|rt| rt.to_string() == "mixed")
+        {
+            method.return_type = Some(static_type.clone());
+        }
+    }
+}
+
 /// Merge resolved interface members into a class, applying `@implements`
 /// generic substitutions.
 ///