Infer closure param type for whereHas/whereDoesntHave relation chain

Author: AJenbo

docs/CHANGELOG.md

@@ -9,6 +9,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 
+- **`whereHas` / `whereDoesntHave` closure parameter from relation traversal.** The closure parameter in `whereHas`, `orWhereHas`, `whereDoesntHave`, `orWhereDoesntHave`, `withWhereHas`, and related methods is now typed as `Builder<RelatedModel>` instead of `Builder<CallingModel>`. The relation name string (first argument) is resolved by walking the model's relationship methods. Dot-notation chains like `whereHas('category.articles', fn($q) => ...)` follow each segment to the final related model. Works for static calls (`Brand::whereHas(...)`), builder instance calls (`$query->whereHas(...)`), and body-inferred relationships (no `@return` annotation). Falls back to the calling model's builder when the relation cannot be resolved.
 - **Eloquent `where{PropertyName}()` dynamic methods.** Calls like `User::whereBrandId(42)` and `$query->whereLangCode('en')` now resolve instead of producing `unknown_member` diagnostics. For each known column on an Eloquent model (from `$casts`, `$attributes`, `$fillable`/`$guarded`/`$hidden`/`$appends`, `$dates`, timestamps, and `@property` annotations), a virtual `where{StudlyCase}()` method is synthesized on both the model (as a static method) and the Builder (as an instance method). Each method accepts a `mixed` value parameter and returns `Builder<ConcreteModel>`, so chains like `Bakery::whereFlour('rye')->whereApricot(true)->get()` resolve end-to-end.
 - **Eloquent timestamp properties.** Models extending `Illuminate\Database\Eloquent\Model` now automatically get `created_at` and `updated_at` virtual properties typed as `Carbon\Carbon`. Setting `$timestamps = false` suppresses both. Overriding `CREATED_AT` or `UPDATED_AT` constants changes the column name; setting either to `null` disables that column. Explicit `$casts` entries (e.g. `'created_at' => 'immutable_datetime'`) take priority over the timestamp defaults.
 - **Eloquent `$dates` array.** Legacy models using `protected $dates = [...]` now get `Carbon\Carbon`-typed virtual properties for each listed column. Explicit `$casts` entries take priority when both define the same column.
@@ -64,6 +65,9 @@ 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.
 
+- **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.
 - **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.

docs/todo.md

@@ -24,7 +24,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 |
-| L11 | [`whereHas` closure parameter type from relation traversal](todo/laravel.md#l11-wherehas--wheredoesnthave-closure-parameter-type-from-relation-traversal) | Medium | 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 |
 | B9  | [Eloquent relationship property lookup is case-sensitive](todo/bugs.md#b9-eloquent-relationship-property-lookup-is-case-sensitive)                | Low    | Low    |
 | H10 | [`return.unusedType` — remove unused type from return union](todo/phpstan-actions.md#h10-returnunusedtype--remove-unused-type-from-return-union) | Medium | Medium |

docs/todo/bugs.md

@@ -98,3 +98,5 @@ properties on Eloquent models.
 **Impact:** 1 direct diagnostic (`FlowService:477`) plus 1 cascading
 (`FlowService:517` — compound with `Collection::reduce()` type loss).
 
+
+

docs/todo/laravel.md

@@ -428,122 +428,6 @@ hard-coding the two known classes.  A simpler approach: add
 `@method` tags to bundled stubs for the most common dynamic `with*`
 methods, or document this as a known limitation.
 
-#### L11. `whereHas` / `whereDoesntHave` closure parameter type from relation traversal
 
-**Impact: Medium · Effort: Medium**
-
-When a closure is passed to `whereHas`, `orWhereHas`,
-`whereDoesntHave`, `orWhereDoesntHave`, `withWhereHas`, or `has`
-(with a callback), the closure parameter `$query` should be typed as
-`Builder<TRelatedModel>` where `TRelatedModel` is the model at the
-end of the relation chain.
-
-Simple case (already works via builder forwarding and callable param
-inference):
-
-```php
-Brand::whereHas('orders', function ($q) {
-    $q->  // $q is Builder<Brand> — TModel substituted by builder forwarding
-});
-```
-
-This works because the scaffolding `Builder::whereHas` has
-`@param (\Closure(Builder<TModel>): mixed)|null $callback`, and
-builder forwarding substitutes `TModel` with the concrete model. The
-result is `Builder<Brand>` — correct for the receiver model but not
-for the related model.
-
-Dot-notation case (does not work):
-
-```php
-ArticleCategoryTranslation::whereHas('category.articles', function ($q) {
-    $q->  // should be Builder<Article>, currently Builder<ArticleCategoryTranslation>
-});
-```
-
-To resolve this properly, PHPantom needs to:
-
-1. Detect that `whereHas` (and related methods) is being called on a
-   model or builder.
-2. Extract the first argument (the relation name string).
-3. Walk the dot-separated relation chain: start from the calling
-   model, look up each segment as a relationship method, extract the
-   `TRelatedModel` from the relationship return type's generic args.
-4. Use the final related model as the `TRelatedModel` for the
-   closure parameter.
-
-The real Laravel `QueriesRelationships` trait declares `whereHas` as:
-
-```php
-/**
- * @template TRelatedModel of \Illuminate\Database\Eloquent\Model
- * @param  Relation<TRelatedModel, *, *>|string  $relation
- * @param  (\Closure(Builder<TRelatedModel>): mixed)|null  $callback
- * @return $this
- */
-public function whereHas($relation, ?Closure $callback = null, ...);
-```
-
-But `TRelatedModel` cannot be inferred from the string argument via
-normal template binding because there is no `::class` reference — it
-requires semantic knowledge of the model's relationship methods.
-
-### Implementation approach
-
-Add a Laravel-specific hook in `infer_callable_params_from_receiver`
-(or in `find_callable_params_on_method`) that intercepts calls to the
-known relation-existence methods. When the method is one of
-`whereHas`, `orWhereHas`, `whereDoesntHave`, `orWhereDoesntHave`,
-`withWhereHas`, or `has`:
-
-1. Resolve the receiver to a model class (or a `Builder<Model>`).
-2. Extract the string literal from the first argument.
-3. Call a new helper `resolve_relation_chain(model, "category.articles")`
-   that splits on `.` and follows each segment:
-   - Find the method on the model.
-   - Extract the `TRelated` type from its relationship return type
-     (using the existing `extract_related_type` from
-     `relationships.rs`).
-   - Load that class and continue with the next segment.
-4. Return `Builder<FinalRelatedModel>` as the inferred closure
-   parameter type, overriding the default callable param inference.
-
-The `resolve_relation_chain` helper can reuse
-`classify_relationship` and `extract_related_type` from
-`src/virtual_members/laravel/relationships.rs`, plus
-`infer_relationship_from_body` as a fallback when no `@return`
-annotation is present.
-
-### Affected methods
-
-All methods from the `QueriesRelationships` trait that accept a
-relation name and a closure callback:
-
-| Method | Callback arg position |
-|--------|-----------------------|
-| `has` | 1 (optional) |
-| `orHas` | 1 (optional) |
-| `doesntHave` | 1 (optional) |
-| `orDoesntHave` | 1 (optional) |
-| `whereHas` | 1 |
-| `orWhereHas` | 1 |
-| `withWhereHas` | 1 |
-| `whereDoesntHave` | 1 |
-| `orWhereDoesntHave` | 1 |
-| `whereRelation` | 1 (Builder in 2nd arg) |
-
-### Where to change
-
-- `src/virtual_members/laravel/relationships.rs` — add
-  `resolve_relation_chain(model, chain_str, class_loader)` helper.
-- `src/completion/variable/closure_resolution.rs` — in
-  `infer_callable_params_from_receiver` or
-  `find_callable_params_on_method`, add a check: if the method is one
-  of the known relation-existence methods and the receiver extends
-  `Model` (or is `Builder<Model>`), run `resolve_relation_chain` and
-  return `Builder<FinalModel>` instead of the raw callable param types.
-- Tests: `tests/integration/completion_laravel.rs` — test simple
-  relation, dot-notation chain, body-inferred relations, and missing
-  relation (should fall back to `Builder<Model>`).
 
 

example.php

@@ -1783,9 +1783,16 @@ public function demo(): void
             }
         });
 
-        // Eloquent whereHas — $query inferred as Builder
+        // Eloquent whereHas — $query inferred as Builder<BlogPost> (the related model)
         BlogAuthor::whereHas('posts', function ($query) {
-            $query->where('published', true); // resolves to Builder
+            $query->where('published', true); // resolves to Builder<BlogPost>
+        });
+
+        // Dot-notation relation chain: category.articles resolves through each segment
+        // BlogPost::whereHas('author.profile', fn($q) => $q->)
+        //   => $q is Builder<AuthorProfile>, not Builder<BlogPost>
+        BlogPost::whereHas('author', function ($q) {
+            $q->where('active', true);    // resolves to Builder<BlogAuthor>
         });
 
         // $this in callable param resolves to receiver, not current class