Handle remaning issues fround by the PHPactor tests

Author: AJenbo

docs/CHANGELOG.md

@@ -9,6 +9,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 
+- **Pipe operator (PHP 8.5).** `$input |> trim(...) |> createDate(...)` resolves through the chain, returning the last callable's return type. Completion works after assigning the pipe result to a variable.
+- **Pass-by-reference parameter type inference.** After calling a function that accepts a typed `&$var` parameter (e.g. `function foo(Baz &$bar)`), the variable acquires the parameter's type for subsequent completion.
+- **Generic `@phpstan-assert` with `class-string<T>`.** `@phpstan-assert T $value` combined with a `@template T` bound via `class-string<T>` now resolves the narrowed type from the call-site argument. For example, `Assert::assertInstanceOf(Foo::class, $obj)` narrows `$obj` to `Foo`.
+- **Interface template inheritance.** When a class implements an interface whose methods use `@template`, `@param class-string<T>`, or `@return T`, the implementing class's overridden methods now inherit the template parameters, bindings, conditional return types, and type assertions. Previously these were lost during interface merging.
 - **Invoked closure and arrow function return types.** `(fn(): Foo => new Foo())()` and `(function(): Bar { return new Bar(); })()` now resolve to the return type of the closure or arrow function. Previously these patterns produced no completions.
 - **`new $classStringVar` and `$classStringVar::method()`.** When a variable holds a class-string value (e.g. `$f = Foo::class`), `new $f` resolves to `Foo` and `$f::staticMethod()` resolves through `Foo`'s static members.
 - **`iterator_to_array()` element type.** `iterator_to_array($iter)` now resolves the element type from the iterator's generic annotation, so `$items[0]->` offers the correct completions.

docs/todo.md

@@ -25,7 +25,6 @@ with each step.
 | [Laravel](todo/laravel.md) | Model property gaps, relationship methods, type narrowing, custom builders |
 | [Blade](todo/blade.md) | Preprocessor, component support, cross-file view intelligence |
 | [Bug Fixes](todo/bugs.md) | Incorrect behaviour that should be fixed regardless of feature priority |
-| [Testing](todo/testing.md) | Ignored fixture tasks grouped by missing feature, with effort estimates |
 | [Configuration](todo/config.md) | Per-project `.phpantom.toml` file, PHP version override, diagnostic tool toggles, prompt-and-remember settings |
 | [Refactoring](todo/refactor.md) | Technical debt and cleanup tasks. Gate check between sprints: clear all items before starting the next sprint |
 

docs/todo/testing.md

@@ -15,32 +15,6 @@ within the same impact tier.
 
 ---
 
-## 1. Pipe operator (PHP 8.5)
-**Impact: High · Effort: Low**
-
-PHP 8.5 introduced the pipe operator (`|>`):
-
-```php
-$result = $input
-    |> htmlspecialchars(...)
-    |> strtoupper(...)
-    |> fn($s) => "<b>$s</b>";
-```
-
-The mago parser already produces `Expression::Pipe` nodes, and the
-closure resolution module walks into pipe sub-expressions to find
-closures. However, **no type resolution** is performed for the pipe
-result — the RHS callable's return type is never resolved, so
-`$result->` after a pipe chain produces no completions.
-
-**Fix:** In `resolve_rhs_expression`, add a `Expression::Pipe` arm
-that resolves the RHS callable (function reference, closure, or
-arrow function) and returns its return type. For first-class
-callable syntax (`htmlspecialchars(...)`), reuse the existing
-`extract_first_class_callable_return_type` logic.
-
----
-
 ## 3. Parse and resolve `($param is T ? A : B)` return types
 **Impact: High · Effort: Medium**
 
@@ -242,35 +216,6 @@ scopes, and parse the set-visibility modifier into a new
 
 ---
 
-## 7. Narrow types of `&$var` parameters after function calls
-**Impact: Medium · Effort: Medium**
-
-When a function takes a parameter by reference, the variable's type
-after the call should reflect what the function writes to it.  PHPStan
-has `FunctionParameterOutTypeExtension` for this.
-
-Key examples:
-
-| Function | Parameter | Type after call |
-|---|---|---|
-| `preg_match($pattern, $subject, &$matches)` | `$matches` | Typed array shape based on the regex |
-| `preg_match_all($pattern, $subject, &$matches)` | `$matches` | Nested typed array based on the regex |
-| `parse_str($string, &$result)` | `$result` | `array<string, string>` |
-| `sscanf($string, $format, &...$vars)` | `$vars` | Types based on format specifiers |
-
-The most impactful case is `preg_match` — PHPStan's
-`RegexArrayShapeMatcher` parses the regex pattern to produce a precise
-array shape for `$matches`, including named capture groups.  A simpler
-first step would be to just type `$matches` as `array<int|string,
-string>` when passed to `preg_match`.
-
-**Implementation:** When resolving a variable's type after a function
-call where the variable was passed by reference, look up the
-function's parameter annotations for `@param-out` tags (PHPStan/Psalm
-extension) or use a built-in map for known functions.
-
----
-
 ## 8. SPL iterator generic stubs
 **Impact: Medium · Effort: Medium**
 
@@ -483,43 +428,6 @@ type:
 
 ---
 
-## 20. Generic `@phpstan-assert` with `class-string<T>` parameter inference
-**Impact: Medium · Effort: Medium-High**
-
-When a function declares `@phpstan-assert T $value` with a
-`@template T` bound via a `class-string<T>` parameter, the narrowed
-type should be inferred from the class-string argument at the call
-site. For example:
-
-```php
-/**
- * @template T of object
- * @param class-string<T> $class
- * @phpstan-assert T $value
- */
-function assertInstanceOf(string $class, mixed $value): void {}
-
-assertInstanceOf(Foo::class, $x);
-$x->fooMethod(); // $x should be narrowed to Foo
-```
-
-**Discovered via:** fixture conversion (phpstan_assert_generic).
-
----
-
-## 25. `class-string<T>` on interface method not inherited
-**Impact: Medium · Effort: Medium**
-
-When an interface method uses `class-string<T>` in its return type
-and a class implements that interface, the implementing class's method
-does not inherit the generic return type. The `class-string<T>`
-pattern works on the interface directly but is lost during
-inheritance merging.
-
-**Discovered via:** fixture conversion (class_string_generic_interface).
-
----
-
 ## 28. `__invoke()` return type resolution
 **Impact: Low-Medium · Effort: Low**
 

docs/todo/type-inference.md

@@ -2140,6 +2140,48 @@ public function store(): void {}
 }
 
 
+// ── Pass-by-Reference Parameter Type ────────────────────────────────────────
+
+class PassByReferenceDemo
+{
+    public function demo(): void
+    {
+        // When a function takes a typed &$var parameter, the variable
+        // acquires that type after the call.
+        initPen($pen);
+        $pen->write();                    // $pen is now Pen
+    }
+}
+
+
+// ── Interface Template Inheritance ──────────────────────────────────────────
+
+class InterfaceTemplateDemo
+{
+    public function demo(): void
+    {
+        // When a class implements an interface with @template + class-string<T>,
+        // the implementing class inherits the template machinery.
+        $locator = new ScaffoldingEntityLocator();
+        $locator->find(Pen::class)->write();   // T resolves to Pen via class-string<T>
+    }
+}
+
+
+// ── Generic @phpstan-assert Narrowing ───────────────────────────────────────
+
+class GenericAssertNarrowingDemo
+{
+    public function demo(object $obj): void
+    {
+        // @phpstan-assert with @template + class-string<T> resolves
+        // the narrowed type from the call-site argument.
+        ScaffoldingAssert::assertInstanceOf(Pen::class, $obj);
+        $obj->write();                    // $obj narrowed to Pen
+    }
+}
+
+
 // ═══════════════════════════════════════════════════════════════════════════
 // ┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
 // ┃  SCAFFOLDING — Supporting definitions below this line.              ┃
@@ -3333,6 +3375,51 @@ public static function isNotRock(mixed $value): bool
     }
 }
 
+// ─── Pipe Operator / Pass-by-Reference / Interface Template / Generic Assert ─
+
+function createPenFromString(string $input): Pen
+{
+    return new Pen();
+}
+
+function initPen(?Pen &$pen): void
+{
+    $pen = new Pen();
+}
+
+interface ScaffoldingEntityFinder
+{
+    /**
+     * @template T
+     * @param class-string<T> $class
+     * @return T
+     */
+    public function find(string $class): object;
+}
+
+class ScaffoldingEntityLocator implements ScaffoldingEntityFinder
+{
+    public function find(string $class): object
+    {
+        return new $class();
+    }
+}
+
+class ScaffoldingAssert
+{
+    /**
+     * @template ExpectedType of object
+     * @param class-string<ExpectedType> $expected
+     * @phpstan-assert ExpectedType $actual
+     */
+    public static function assertInstanceOf(string $expected, object $actual): void
+    {
+        if (!$actual instanceof $expected) {
+            throw new \InvalidArgumentException('Type mismatch');
+        }
+    }
+}
+
 // ─── Multi-line @return & Broken Docblock Recovery ──────────────────────────
 
 /**
@@ -4247,6 +4334,21 @@ function runDemoAssertions(): void
     $children = $astNode->getChildren();
     assert(is_array($children), 'AstNode::getChildren() must return array');
 
+    // ── Pass-by-reference parameter type ────────────────────────────────
+    $refPen = null;
+    initPen($refPen);
+    assert($refPen instanceof Pen, 'initPen(&$pen) must give $pen type Pen');
+
+    // ── Interface template inheritance (class-string<T>) ────────────────
+    $locator = new ScaffoldingEntityLocator();
+    $locatorResult = $locator->find(Pen::class);
+    assert($locatorResult instanceof Pen, 'ScaffoldingEntityLocator::find(Pen::class) must return Pen');
+
+    // ── Generic @phpstan-assert narrowing ────────────────────────────────
+    $assertObj = new Pen();
+    ScaffoldingAssert::assertInstanceOf(Pen::class, $assertObj);
+    assert($assertObj instanceof Pen, 'ScaffoldingAssert::assertInstanceOf(Pen::class, $obj) must narrow to Pen');
+
     echo "All assertions passed.\n";
 }