Suppress false positives for Laravel Eloquent scope methods on Builder

Author: AJenbo

docs/CHANGELOG.md

@@ -67,6 +67,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.
 
+- **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.
 - **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.

docs/todo.md

@@ -23,7 +23,6 @@ within the same impact tier.
 
 | #   | Item                                                                                                                                             | Impact | Effort |
 | --- | ------------------------------------------------------------------------------------------------------------------------------------------------ | ------ | ------ |
-| B6  | [Scope methods not found on Builder in analyzer chains](todo/bugs.md#b6-scope-methods-not-found-on-builder-in-analyzer-chains)                   | High   | Medium |
 | B7  | [PHPDoc `@param` generic array type not merged with native `array` hint](todo/bugs.md#b7-phpdoc-param-generic-array-type-not-merged-with-native-array-hint) | Low | Medium |
 | H10 | [`return.unusedType` — remove unused type from return union](todo/phpstan-actions.md#h10-returnunusedtype--remove-unused-type-from-return-union) | Medium | Medium |
 | H6  | `return.type` — update return type to match actual returns                                                                                       | Medium | Medium |

docs/todo/bugs.md

@@ -1,42 +1,5 @@
 # PHPantom — Bug Fixes
 
-## B6: Scope methods not found on Builder in analyzer chains
-
-PHPantom's completion engine correctly injects scope methods onto
-`Builder<ConcreteModel>` via `try_inject_builder_scopes` in
-`resolve_named_type`. However, the analyzer's `check_member_on_resolved_classes`
-uses `resolve_class_fully_cached` which is keyed by bare FQN without
-generic args. A prior cache entry for `Builder` (without model-specific
-scopes) is returned, and the scope method is reported as not found.
-
-The analyzer does check `base_classes` first (before the cache) to avoid
-this, but in method chains like
-`ArticleCategoryTranslation::whereHas(...)->whereLanguage(...)`, the
-intermediate `Builder<ArticleCategoryTranslation>` type produced by
-`whereHas()` may not carry the scope-injected methods in `base_classes`.
-
-Affected diagnostics (5 direct + 2 cascading):
-
-Direct `unknown_member` — scope method exists on model but not found on
-Builder:
-- `ArticleRepository:69` — `whereLanguage` (scope on
-  `ArticleCategoryTranslation`)
-- `ProductRepository:271` — `whereIsLuxury` (scope on `Product`)
-- `ProductRepository:272` — `whereIsDerma` (scope on `Product`)
-- `ProductRepository:273` — `whereIsProHairCare` (scope on `Product`)
-- `ProductRepository:369` — `whereIsLuxury` (scope on `Product`)
-
-Cascading `unresolved_member_access`:
-- `EventRepository:23` — `pluck` after broken
-  `whereIsBlackFriday()->whereIsVisible()` chain
-
-Note: `EventRepository:22` reports `whereIsVisible` not found on Builder.
-Product has `scopeIsVisibleIn` (takes a `Country` parameter) but no
-`scopeWhereIsVisible` and no `is_visible` column. This may be a genuine
-code bug in the project rather than an LSP issue.
-
-**Impact:** 5–6 direct `unknown_member` diagnostics plus 1–2 cascading.
-
 ## B7: PHPDoc `@param` generic array type not merged with native `array` hint
 
 When a method has a native type hint `array` and a PHPDoc `@param` with
@@ -68,7 +31,4 @@ to `array`. The `@param` says the array case is `list<Request>`, so
 native `array` with the docblock's `list<Request>`.
 
 **Impact:** 1 diagnostic in the shared project
-(`MobilePayConnection:76`).
-
-
-
+(`MobilePayConnection:76`).

src/diagnostics/unknown_members.rs

@@ -59,6 +59,7 @@ 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};
@@ -634,6 +635,27 @@ 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/laravel/mod.rs

@@ -382,11 +382,11 @@ fn inject_scopes_and_model_methods(
     // 1. Inject scope methods.
     let scope_methods = build_scope_methods_for_builder(model_arg, class_loader);
     for method in scope_methods {
-        if !result
+        let already_exists = result
             .methods
             .iter()
-            .any(|m| m.name == method.name && m.is_static == method.is_static)
-        {
+            .any(|m| m.name == method.name && m.is_static == method.is_static);
+        if !already_exists {
             result.methods.push(method);
         }
     }

src/virtual_members/laravel/scopes.rs

@@ -11,7 +11,9 @@ use std::sync::Arc;
 
 use crate::php_type::PhpType;
 use crate::types::{ClassInfo, MethodInfo};
+use crate::util::short_name;
 
+use super::ELOQUENT_BUILDER_FQN;
 use super::helpers::extends_eloquent_model;
 
 /// Build the default return type for scope methods that don't declare a return
@@ -138,7 +140,9 @@ pub fn build_scope_methods_for_builder(
 ) -> Vec<MethodInfo> {
     let model_class = match class_loader(model_name) {
         Some(c) => c,
-        None => return Vec::new(),
+        None => {
+            return Vec::new();
+        }
     };
 
     // Only synthesize scopes for actual Eloquent models.
@@ -153,7 +157,6 @@ pub fn build_scope_methods_for_builder(
     // Using the pre-provider resolution preserves the raw methods.
     let resolved_model =
         crate::inheritance::resolve_class_with_inheritance(&model_class, class_loader);
-
     // Build a substitution map so that `static`, `$this`, and `self`
     // in scope return types resolve to the concrete model name.
     // The default scope return type is `\...\Builder<static>` where
@@ -183,6 +186,20 @@ pub fn build_scope_methods_for_builder(
         // Apply substitutions to the return type.
         if let Some(ref mut ret) = m.return_type {
             *ret = ret.substitute(&subs);
+
+            // When a scope method declares a bare `Builder` return type
+            // (without generic args), the chain loses track of the
+            // concrete model.  Subsequent calls on the returned Builder
+            // would not find model-specific scope methods because
+            // `type_hint_to_classes_typed` only injects scopes when
+            // generic args are present.  Wrap bare Builder return types
+            // as `Builder<ModelName>` to preserve the chain.
+            if is_bare_builder_type(ret) {
+                *ret = PhpType::Generic(
+                    ELOQUENT_BUILDER_FQN.to_string(),
+                    vec![PhpType::Named(model_name.to_string())],
+                );
+            }
         }
 
         methods.push(m);
@@ -191,6 +208,19 @@ pub fn build_scope_methods_for_builder(
     methods
 }
 
+/// Check whether a `PhpType` is a bare Eloquent Builder reference
+/// without generic arguments.
+///
+/// Matches both the FQN (`Illuminate\Database\Eloquent\Builder`) and
+/// the short name (`Builder`) since scope methods in user code
+/// typically use the imported short name.
+fn is_bare_builder_type(ty: &PhpType) -> bool {
+    match ty {
+        PhpType::Named(name) => name == ELOQUENT_BUILDER_FQN || short_name(name) == "Builder",
+        _ => false,
+    }
+}
+
 #[cfg(test)]
 #[path = "scopes_tests.rs"]
 mod tests;