Add PHPStan * wildcard support in generic type positions

Author: AJenbo

docs/CHANGELOG.md

@@ -56,6 +56,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Fixed
 
+- **PHPStan `*` wildcard in generic type arguments.** Type strings like `Relation<TRelatedModel, *, *>` now parse correctly instead of falling back to an unparsed blob. Previously, `mago-type-syntax` rejected the `*` token, causing the entire type to be treated as a single unknown class name (e.g. `Class 'Relation<TRelatedModel, *, *>|string' not found`). The `*` wildcard is now replaced with `mixed` before parsing, matching PHPStan's semantics. Member references like `Foo::*` and constant patterns like `int-mask-of<self::FOO_*>` are not affected.
 - **Closure parameter inference from function-level `@template` bindings.** Functions like `array_any`, `array_all`, and `array_find` that declare `@template` parameters bound through an array parameter and used in a `callable` parameter now infer concrete types for untyped closure arguments. For example, `array_any($this->items, fn($item) => $item->name !== '')` where `$this->items` is `array<int, Product>` now resolves `$item` as `Product`. Previously `$item` was unresolved, producing false-positive `unresolved_member_access` diagnostics. This also fixes a related issue where `@param` tags in phpstorm-stubs that omit the parameter name (e.g. `@param callable(TValue, TKey): bool` without `$callback`) failed to enrich the parameter's type hint, preventing callable parameter type extraction.
 - **Property chain arguments in template substitution.** Expressions like `$this->items` or `$obj->prop` passed as arguments to templated functions now resolve their type for template binding. Previously only bare variables (e.g. `$items`) were resolved, so `array_any($this->items, fn($x) => ...)` could not infer the element type even when the property had a fully substituted generic type.
 - **Variable reassignment inside `try` blocks now tracked by the analyzer.** When a variable was reassigned to a different type inside a `try` block, subsequent accesses within the same block still resolved against the original type, producing false-positive `unknown_member` diagnostics. The same applied to `catch` and `finally` blocks. Assignments preceding the cursor within the same block are now treated as sequential.

docs/todo.md

@@ -24,6 +24,7 @@ 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 |
 | B8  | [Variadic parameter element type lost in `foreach`](todo/bugs.md#b8-variadic-parameter-element-type-lost-in-foreach)                             | Low    | Low    |
 | B9  | [Eloquent relationship property lookup is case-sensitive](todo/bugs.md#b9-eloquent-relationship-property-lookup-is-case-sensitive)                | Low    | Low    |

docs/todo/bugs.md

@@ -129,3 +129,4 @@ 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,5 +428,122 @@ 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>`).
 
 

src/diagnostics/unknown_classes.rs

@@ -982,4 +982,37 @@ mod tests {
             diags.iter().map(|d| &d.message).collect::<Vec<_>>()
         );
     }
+
+    #[test]
+    fn no_false_positive_for_star_wildcard_in_generic() {
+        // PHPStan `*` wildcards in generic positions (e.g.
+        // `Relation<TRelatedModel, *, *>`) must not cause the entire
+        // type string to be reported as an unknown class.
+        let backend = Backend::new_test();
+        let uri = "file:///test.php";
+        let content = concat!(
+            "<?php\n",
+            "namespace App;\n",
+            "\n",
+            "class Relation {}\n",
+            "\n",
+            "class Foo {\n",
+            "    /**\n",
+            "     * @param Relation<string, *, *>|string \\$relation\n",
+            "     * @return void\n",
+            "     */\n",
+            "    public function bar($relation): void {}\n",
+            "}\n",
+        );
+
+        let diags = collect(&backend, uri, content);
+        // The `Relation` class is defined locally — no diagnostic expected.
+        // Before the fix, the entire `Relation<string, *, *>|string` was
+        // emitted as a single ClassReference and flagged as unknown.
+        assert!(
+            diags.is_empty(),
+            "Star wildcards in generic positions must not cause false unknown_class diagnostics, got: {:?}",
+            diags.iter().map(|d| &d.message).collect::<Vec<_>>()
+        );
+    }
 }