Handle @mixin generic substitution

Author: AJenbo

docs/CHANGELOG.md

@@ -10,9 +10,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Added
 
 - **Null-coalesce (`??`) type refinement.** When the left-hand side of `??` is provably non-nullable (e.g. `new Foo()`, `clone $x`, a literal), the right-hand side is recognized as dead code and the result resolves to the LHS type only. When the LHS is nullable (e.g. a `?Foo` return type), `null` is stripped from the LHS and the result is the union of the non-null LHS with the RHS.
+- **`@mixin` generic substitution.** When a class declares `@mixin Builder<TRelatedModel>`, the generic arguments are now preserved and substituted into the mixin's members. Previously, `@mixin Builder<TRelatedModel>` was stored as just `Builder` (the generic argument was stripped), so methods like `firstOrFail(): TModel` returned the raw template parameter name instead of the concrete type. This resolves through inheritance chains: `BelongsTo @extends Relation<Product>` with `Relation @mixin Builder<TRelatedModel>` now correctly substitutes `TModel` to `Product` on all Builder methods.
 
 ### Fixed
 
+- **Hover and completion type parity.** The hover type-string engine now handles pipe expressions (`|>`), closure/arrow-function literals, and generator yield-assignment (`$var = yield`) expressions, matching the completion engine. Previously these expression kinds were only handled by the completion pipeline, so hover could show a different (or missing) type for variables assigned from them.
+
 - **Guard clause narrowing across instanceof branches.** After `if ($x instanceof Y) { return; }`, subsequent `instanceof` checks on the same variable no longer incorrectly resolve to `Y`. Previously the diagnostic cache reused the narrowed type from inside the first branch for all later accesses to the same variable, producing false-positive "not found" warnings (e.g. "Property 'value' not found on class 'Stringable'" inside a `BackedEnum` branch).
 - **`instanceof self/static/parent` narrowing.** Type narrowing with `instanceof self`, `instanceof static`, and `instanceof parent` now works correctly in all contexts (assert, if-blocks, guard clauses, compound conditions). Previously these keywords were ignored because the AST parser produces dedicated node types rather than identifiers, and `parent` was not recognized as a type hint during resolution.
 - **Interface constants through multi-extends chains.** Constants defined on parent interfaces are now found when an interface extends multiple other interfaces. Previously only the first parent interface was walked for member merging, so constants like `Carbon::JANUARY` (defined on the `UnitValue` interface, sixth in `CarbonInterface`'s extends list) were reported as unknown.

docs/todo.md

@@ -19,22 +19,6 @@ within the same impact tier.
 
 # Scheduled Sprints
 
-## Sprint 3 — Generic template resolution
-
-| #   | Item                                                                                                                                       | Impact | Effort      |
-| --- | ------------------------------------------------------------------------------------------------------------------------------------------ | ------ | ----------- |
-| B1  | [Dual type-resolution engines cause hover / completion divergence](todo/bugs.md#b1-dual-type-resolution-engines-cause-hover--completion-divergence) | Medium | Medium-High |
-| T8  | [`@mixin` generic substitution and chain-level template resolution](todo/type-inference.md#t8-mixin-generic-substitution-and-chain-level-template-resolution) | High   | Medium-High |
-|     | **Release 0.6.0**                                                                                                                          |        |             |
-
-> **Why this is next:** T8 accounts for ~186 of the 325 remaining
-> diagnostics in the `shared` triage project (57%). Two sub-problems:
-> (1) `@mixin` generic arguments are stripped during extraction, so
-> `@mixin Builder<TRelatedModel>` loses the type argument; (2)
-> chain-level calls like `Collection<int, Product>::first()` don't
-> substitute `TValue` → `Product`. Fixing both would drop the
-> diagnostic count below 140.
-
 ## Sprint 4 — Refactoring toolkit
 
 | #   | Item                                                                               | Impact | Effort |

docs/todo/bugs.md

@@ -15,63 +15,5 @@ within the same impact tier.
 
 ---
 
-#### B1. Dual type-resolution engines cause hover / completion divergence
-
-| | |
-|---|---|
-| **Impact** | Medium |
-| **Effort** | Medium-High |
-
-Variable type resolution has two parallel RHS expression resolvers that
-must be kept in sync manually:
-
-1. **`resolve_rhs_expression`** in `completion/variable/rhs_resolution.rs`
-   — returns `Vec<ClassInfo>`, used by the completion pipeline.
-2. **`resolve_rhs_raw_type`** in `completion/variable/raw_type_inference.rs`
-   — returns `Option<String>`, used by hover's type-string path
-   (`resolve_variable_type_string` → step 5).
-
-Hover tries the type-string path first.  When it returns `Some(…)` the
-ClassInfo fallback never fires, so hover shows whatever the raw-type
-engine inferred — even if it is wrong.  The completion pipeline uses the
-ClassInfo engine directly and gets the correct answer.
-
-The two resolvers handle **different sets of expression types**:
-
-| Expression kind          | ClassInfo engine | Raw-type engine |
-| ------------------------ | :--------------: | :-------------: |
-| `clone`                  | ✓                | ✗               |
-| `\|>` (pipe)             | ✓                | ✗               |
-| `Closure` / arrow fn     | ✓ (→ `\Closure`) | ✗               |
-| `yield` (send type)      | ✓                | ✗               |
-| `Call` (full resolution) | ✓                | partial¹        |
-| `Access` (property)      | ✓                | partial¹        |
-| Scalar literals          | ✗                | ✓               |
-| Array literal inference  | ✗                | ✓               |
-
-¹ The raw-type engine's `_ =>` catch-all delegates to
-`extract_rhs_iterable_raw_type`, which covers some calls and accesses
-but not all.
-
-The `??` null-coalesce handling also diverges: the ClassInfo engine
-checks whether the LHS *AST node* is syntactically non-nullable (pattern
-match on `Clone`, `Literal`, etc.), while the raw-type engine checks
-whether the resolved *type string* is non-nullable.  When the raw-type
-engine cannot resolve the LHS at all (e.g. `clone $x` → `None`), it
-falls through to returning only the RHS type, which is how
-`clone $pen ?? new Marker()` shows `Marker` on hover but `Pen` on
-completion.
-
-**Possible approaches:**
-
-- **Unify into one engine** — make `resolve_rhs_expression` the single
-  source of truth and derive the type string from its result.  Hover
-  would call the ClassInfo path and format the names into a union
-  string, falling back to `resolve_variable_type_string` only for
-  scalar / generic types that ClassInfo cannot represent.  This
-  eliminates the synchronisation burden entirely.
-- **Exhaustiveness enforcement** — if keeping both engines, add a shared
-  enum of "RHS expression kinds" and a compile-time check (or test)
-  that both match arms cover the same set, so new expression types
-  cannot be added to one without the other.
+No outstanding bugs at this time.
 

docs/todo/type-inference.md

@@ -97,105 +97,6 @@ only has a native `array` type hint.
 
 ---
 
-## T8. `@mixin` generic substitution and chain-level template resolution
-**Impact: High · Effort: Medium-High**
-
-PHPantom's generics system substitutes template parameters through
-`@extends` and `@implements` chains but fails in two related
-scenarios that together account for ~180 of the ~325 remaining
-diagnostics in the `shared` triage project (iteration 4).
-
-### Problem 1: `@mixin` generic arguments are discarded
-
-`extract_mixin_tags` (docblock/tags.rs) calls `base_class_name`,
-which calls `strip_generics`. So `@mixin Builder<TRelatedModel>`
-is stored as just `"Builder"`, and the generic argument is lost.
-
-When `collect_mixin_members` (virtual_members/phpdoc.rs) later
-loads and merges Builder's methods, `TModel` in return types like
-`firstOrFail(): TModel` is never mapped to the concrete related
-model. The diagnostic reports the raw template parameter name.
-
-**Concrete example:**
-
-```php
-/**
- * @template TRelatedModel of Model
- * @template TDeclaringModel of Model
- * @mixin Builder<TRelatedModel>          ← generic arg stripped
- */
-abstract class Relation { ... }
-
-// User code:
-$product = $orderline->product()->firstOrFail();
-//         BelongsTo<Product, OrderLine> → Relation → @mixin Builder<TRelatedModel>
-//         Builder::firstOrFail() returns TModel
-//         TModel is never substituted → diagnostic: "subject type 'TModel' could not be resolved"
-```
-
-**Impact:** 38 `TModel` diagnostics + cascading anonymous chains.
-
-**Fix:** Preserve generic arguments in `@mixin` tags (store them
-alongside the mixin class name, similar to `extends_generics` /
-`implements_generics`). In `collect_mixin_members`, build a
-substitution map from the mixin class's `template_params` to the
-provided generic arguments and apply it to all merged members.
-
-### Problem 2: chain-level generic substitution not performed
-
-When a method returns a generic type like `Collection<int, Product>`,
-calling a method on that result (e.g. `->first()`) does not
-substitute the collection's template parameters into the called
-method's return type.
-
-```php
-// Collection<TKey, TValue> has first(): TValue|TFirstDefault
-$users->map(fn($u) => $u->name)->first();
-//     map() returns Collection<int, string>
-//     first() should return string|TFirstDefault → resolves to string
-//     Actually returns: TValue|TFirstDefault (unsubstituted)
-```
-
-The completion/type resolution pipeline resolves the return type of
-a chain call by:
-1. Resolving the subject to `ClassInfo` (e.g. `Collection`).
-2. Looking up the method on that class.
-3. Returning the method's `return_type` string.
-
-Step 1 produces an unparameterised `Collection` — the generic
-arguments `<int, Product>` from the previous call's return type
-are not carried forward. The method's return type `TValue` is
-never mapped to `Product`.
-
-**Impact:** 16 `TValue|TFirstDefault` + 3 `TModel|TFirstDefault`
-+ 6 other template params + ~118 cascading anonymous chain
-diagnostics.
-
-**Fix:** When the previous link in a chain returns a parameterised
-type like `Collection<int, Product>`, resolve the class (`Collection`),
-zip its `template_params` (`[TKey, TValue]`) with the provided
-arguments (`[int, Product]`), build a substitution map, and apply
-it to the called method's return type before using it as the next
-link's subject type. This is the call-site equivalent of what
-`resolve_class_with_inheritance` already does for `@extends` chains.
-
-### Combined impact
-
-| Symptom | Count | Root cause |
-|---------|-------|------------|
-| `TModel` unresolvable | 38 | Problem 1 (@mixin generics stripped) |
-| `TValue\|TFirstDefault` unresolvable | 16 | Problem 2 (chain generics not substituted) |
-| Other template params (`T`, `TValue`, `TModel\|TFirstDefault`, `TReduceReturnType`) | 14 | Mix of both |
-| Cascading anonymous chains | ~118 | Downstream of unresolved template params |
-| **Total** | **~186** | |
-
-Fixing both problems would reduce the `shared` project from 325 to
-~140 diagnostics (57% reduction), with most remaining diagnostics
-being correct reports or `unresolved_member_access` hints on
-genuinely untyped code.
-
----
-
 ## T2. File system watching for vendor and project changes
 **Impact: Medium-High · Effort: Medium**
 

example.php

@@ -2705,6 +2705,25 @@ public function demo(): void
 }
 
 
+// ── Mixin Generic Substitution ──────────────────────────────────────────────
+
+class MixinGenericDemo
+{
+    public function demo(): void
+    {
+        $line = new ScaffoldingOrderLine();
+
+        // @mixin Builder<TRelatedModel> on Relation resolves TModel → Product
+        // through: BelongsTo @extends Relation<Product> → @mixin Builder<TRelatedModel>
+        // → TRelatedModel=Product → Builder<Product> → firstOrFail(): TModel=Product
+        $line->product()->firstOrFail()->getPrice();
+
+        // Same resolution through find()
+        $line->product()->find()->getSku();
+    }
+}
+
+
 // ═══════════════════════════════════════════════════════════════════════════
 // ┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
 // ┃  SCAFFOLDING — Supporting definitions below this line.              ┃
@@ -3871,6 +3890,40 @@ class Product
     use HasFactory;
 
     public function getPrice(): float { return 0.0; }
+    public function getSku(): string { return ''; }
+}
+
+// ─── Mixin Generic Scaffolding ─────────────────────────────────────────────
+
+/**
+ * @template TModel
+ */
+class ScaffoldingMixinBuilder
+{
+    /** @return TModel */
+    public function firstOrFail(): mixed { return null; }
+    /** @return TModel */
+    public function find(): mixed { return null; }
+}
+
+/**
+ * @template TRelatedModel
+ * @mixin ScaffoldingMixinBuilder<TRelatedModel>
+ */
+class ScaffoldingMixinRelation
+{
+}
+
+/**
+ * @extends ScaffoldingMixinRelation<Product>
+ */
+class ScaffoldingMixinBelongsTo extends ScaffoldingMixinRelation
+{
+}
+
+class ScaffoldingOrderLine
+{
+    public function product(): ScaffoldingMixinBelongsTo { return new ScaffoldingMixinBelongsTo(); }
 }
 
 /** @use Indexable<int, Pen> */
@@ -5049,6 +5102,17 @@ function runDemoAssertions(): void
     $ctExt = $ctRouter->extend('redis', function () {});
     assert($ctExt instanceof ScaffoldingClosureThisRouter, 'Router::extend() must return self');
 
+    // ── @mixin generic substitution scaffolding ─────────────────────────
+    $mixinBuilder = new ScaffoldingMixinBuilder();
+    assert($mixinBuilder->firstOrFail() === null, 'ScaffoldingMixinBuilder::firstOrFail() must return mixed');
+    $mixinRelation = new ScaffoldingMixinRelation();
+    assert($mixinRelation instanceof ScaffoldingMixinRelation, 'ScaffoldingMixinRelation instantiates');
+    $mixinBelongsTo = new ScaffoldingMixinBelongsTo();
+    assert($mixinBelongsTo instanceof ScaffoldingMixinRelation, 'ScaffoldingMixinBelongsTo extends ScaffoldingMixinRelation');
+    $orderLine = new ScaffoldingOrderLine();
+    $productRel = $orderLine->product();
+    assert($productRel instanceof ScaffoldingMixinBelongsTo, 'OrderLine::product() must return ScaffoldingMixinBelongsTo');
+
     echo "All assertions passed.\n";
 }
 

src/code_actions/update_docblock.rs

@@ -812,13 +812,14 @@ fn normalize_type_for_comparison(t: &str) -> String {
         |rest| format!("{}|null", rest.to_lowercase()),
     );
     // Sort union components.
-    let mut parts: Vec<&str> = split_union_depth0(&t).into_iter().map(|s| s.trim()).collect();
+    let mut parts: Vec<&str> = split_union_depth0(&t)
+        .into_iter()
+        .map(|s| s.trim())
+        .collect();
     parts.sort();
     parts.join("|")
 }
 
-
-
 /// Build the updated docblock text.
 fn build_updated_docblock(
     info: &FunctionWithDocblock,

src/completion/source/throws_analysis_tests.rs

@@ -780,6 +780,7 @@ fn make_class_with_throws(name: &str, methods: Vec<(&str, Vec<&str>)>) -> Arc<Cl
         interfaces: Vec::new(),
         used_traits: Vec::new(),
         mixins: Vec::new(),
+        mixin_generics: Vec::new(),
         is_final: false,
         is_abstract: false,
         deprecation_message: None,

src/completion/variable/raw_type_inference.rs

@@ -915,6 +915,35 @@ fn resolve_rhs_raw_type<'b>(rhs: &'b Expression<'b>, ctx: &VarResolutionCtx<'_>)
             // Last resort: docblock scan (e.g. `@var` inline annotation).
             super::foreach_resolution::extract_rhs_iterable_raw_type(rhs, ctx)
         }
+        // ── Pipe operator (PHP 8.5): `$expr |> callable(...)` ──
+        // The result type is the return type of the callable.
+        Expression::Pipe(pipe) => {
+            if let Expression::PartialApplication(PartialApplication::Function(fpa)) = pipe.callable
+                && let Expression::Identifier(ident) = fpa.function
+                && let Some(fl) = ctx.function_loader
+                && let Some(func_info) = fl(ident.value())
+                && let Some(ref ret) = func_info.return_type
+            {
+                return Some(ret.clone());
+            }
+            None
+        }
+        // ── Closure / arrow function / first-class callable ─────────
+        // All produce a `Closure` instance at runtime.
+        Expression::PartialApplication(_)
+        | Expression::Closure(_)
+        | Expression::ArrowFunction(_) => Some("\\Closure".to_string()),
+        // ── Generator yield-assignment: `$var = yield $expr` ────────
+        // The value of a yield expression is the TSend type from the
+        // enclosing function's `@return Generator<K, V, TSend, R>`.
+        Expression::Yield(_) => {
+            if let Some(ref ret_type) = ctx.enclosing_return_type
+                && let Some(send_type) = crate::docblock::extract_generator_send_type(ret_type)
+            {
+                return Some(send_type);
+            }
+            None
+        }
         // ── Call / property access — delegate to iterable extractor,
         //    with a source-scan fallback for standalone function calls
         //    when no `function_loader` is available. ──