@phpstan-assert on static methods & Variadic @param template bindings

Author: AJenbo

docs/CHANGELOG.md

@@ -11,9 +11,11 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 - **Enum case properties.** Completing on an enum case variable (`$case->`) now shows `name` (on all enums) and `value` (on backed enums) inherited from the `UnitEnum` and `BackedEnum` interfaces.
 - **`@implements` generic resolution.** When a class declares `@implements SomeInterface<ConcreteType>`, template parameters on the interface's methods and properties are now substituted with the concrete types. Works with `@template-implements` and `@phpstan-implements` aliases, multiple `@implements` annotations on the same class, parameter type substitution (not just return types), and chained resolution through parent classes (e.g. `Test2 extends Test1<int>` where `Test1` has `@implements Iterator<TKey, string>`). Foreach iteration over classes implementing generic iterable interfaces (including through intermediate interface chains like `TypedCollection extends IteratorAggregate`) now resolves value and key types correctly.
+- **`@phpstan-assert` on static methods.** Type guard annotations (`@phpstan-assert`, `@phpstan-assert-if-true`, `@phpstan-assert-if-false`) now work on static method calls like `Assert::instanceOf($value, Foo::class)`. Previously only standalone function calls triggered assertion-based narrowing.
 
 ### Fixed
 
+- **Variadic `@param` template bindings.** `@param class-string<T> ...$items` now correctly binds the template parameter. Previously the `...` prefix prevented the parameter name from being recognized, so generic return types were not substituted.
 - **`@phpstan-type` aliases in foreach.** Type aliases defined via `@phpstan-type` or `@psalm-type` now resolve correctly when the aliased type is iterated in a `foreach` loop, destructured with `list()`/`[]`, or used as a foreach key type.
 - **Mixed `->` then `::` accessor chains.** Expressions like `$obj->prop::$staticProp` and `$obj->method()::staticMethod()` now resolve through the full chain instead of losing the instance prefix.
 - **Inline `(new Foo)->method()` chaining.** Parenthesized `new` expressions used as the root of a method chain now resolve for completion. Previously only assigned `new` expressions (`$x = new Foo()`) worked.

docs/todo.md

@@ -82,7 +82,6 @@ deepens that lead and rounds out the remaining feature surface.
 
 | # | Item | Effort | Domain | Doc Link |
 |---|---|---|---|---|
-| 25 | Function-level `@template` generic resolution | Medium | Type Inference | [type-inference.md §2](todo/type-inference.md#2-function-level-template-generic-resolution) |
 | 26 | Inherited docblock type propagation | Medium | Type Inference | [type-inference.md §4](todo/type-inference.md#4-inherited-docblock-type-propagation) |
 | 27 | `BackedEnum::from()` / `::tryFrom()` return type refinement | Low | Completion | [completion.md §1](todo/completion.md#1-backedenumfrom--tryfrom-return-type-refinement) |
 | 28 | Pipe operator (PHP 8.5) type resolution | Low | Type Inference | [type-inference.md §1](todo/type-inference.md#1-pipe-operator-php-85) |

docs/todo/testing.md

@@ -1,11 +1,11 @@
 # PHPantom — Ignored Fixture Tasks
 
-There are **228 fixture tests** in `tests/fixtures/`. Of these, **195
-pass** and **33 are ignored** because they exercise features or bug
+There are **228 fixture tests** in `tests/fixtures/`. Of these, **207
+pass** and **21 are ignored** because they exercise features or bug
 fixes that are not yet implemented. Each ignored fixture has a
 `// ignore:` comment explaining what is missing.
 
-This document groups the 33 ignored fixtures by the underlying work
+This document groups the 21 ignored fixtures by the underlying work
 needed to un-ignore them. Tasks are ordered by the number of fixtures
 they unblock (descending), then by estimated effort. Once a task is
 complete, remove the `// ignore:` line from each fixture, verify the
@@ -23,42 +23,6 @@ php -l example.php
 
 ---
 
-## 2. Function-level `@template` generic resolution (9 fixtures)
-
-**Ref:** [type-inference.md §2](type-inference.md#2-function-level-template-generic-resolution)
-**Impact: High · Effort: Medium**
-
-`FunctionInfo` lacks `template_params` and `template_bindings` fields,
-so standalone functions and constructors with `@template` cannot infer
-generic types from call-site arguments. This blocks Laravel helpers
-(`collect()`, `tap()`, `value()`) and constructor-based inference.
-
-**Fixtures:**
-
-- [ ] `generics/constructor_params.fixture` — `new Foo($bar)` infers `T` from constructor arg
-- [ ] `generics/constructor_array_arg.fixture` — constructor with array argument infers `T`
-- [ ] `generics/constructor_generic_arg.fixture` — constructor with generic-typed argument
-- [ ] `generics/constructor_param_and_extend.fixture` — constructor inference combined with `@extends`
-- [ ] `generics/method_returns_templated_generic.fixture` — method returning `Collection<T>` where `T` is inferred from constructor
-- [ ] `generics/covariant_template.fixture` — `@template-covariant` modifier on function-level template
-- [ ] `generics/class_string_generic_union.fixture` — `class-string<T>` with variadic params
-- [ ] `generics/class_string_variadic_union.fixture` — `class-string<T>` with variadic union scenario
-- [ ] `generics/class_string_nested_return.fixture` — `class-string<T>` with nested generic return type
-
-**Implementation notes:**
-
-1. Add `template_params: Vec<String>` and
-   `template_bindings: Vec<(String, String)>` to `FunctionInfo` in
-   `types.rs`, mirroring `MethodInfo`.
-2. Populate them in `parser/functions.rs` using `extract_template_params`
-   and `extract_template_param_bindings`.
-3. At call sites in `variable/rhs_resolution.rs`, after loading
-   `FunctionInfo`, check for `template_params`. Infer concrete types
-   from arguments, build a substitution map, and apply it to the return
-   type before resolving.
-
----
-
 ## 3. Property-level narrowing (5 fixtures)
 
 **Ref:** [type-inference.md §21](type-inference.md#21-property-level-narrowing)
@@ -88,32 +52,6 @@ check the narrowing state for a matching member access path.
 
 ---
 
-## 4. `@phpstan-assert` on static method calls (3 fixtures)
-
-**Ref:** [type-inference.md §18](type-inference.md#18-phpstan-assert-on-static-method-calls)
-**Impact: Medium · Effort: Medium**
-
-Type guards declared with `@phpstan-assert`, `@phpstan-assert-if-true`,
-and `@phpstan-assert-if-false` only work on standalone function calls
-today. Static method calls like `Assert::instanceOf($value, Foo::class)`
-do not trigger narrowing.
-
-**Fixtures:**
-
-- [ ] `narrowing/phpstan_assert_static.fixture` — `Assert::isInstanceOf($x, Foo::class)` narrows `$x`
-- [ ] `narrowing/phpstan_assert_if_true.fixture` — `@phpstan-assert-if-true` on static method
-- [ ] `narrowing/phpstan_assert_if_false.fixture` — `@phpstan-assert-if-false` on static method
-
-**Implementation notes:**
-
-In the narrowing pass, when processing call expressions, check whether
-the callee is a static method call (`Foo::bar()`). If so, resolve the
-class and method, extract `@phpstan-assert*` tags from the method's
-docblock, and apply the same narrowing logic used for standalone
-functions.
-
----
-
 ## 5. Attribute context support (3 fixtures)
 
 **Ref:** [signature-help.md §4](signature-help.md#4-attribute-constructor-signature-help)
@@ -347,8 +285,5 @@ Biggest unlocks (Medium effort, many fixtures):
 
 | Task | Fixtures |
 |---|---|
-| §1 `@implements` generic resolution | 7 |
-| §2 Function-level `@template` | 9 |
 | §3 Property-level narrowing | 5 |
-| §4 `@phpstan-assert` on static methods | 3 |
 | §5 Attribute context support | 3 |

docs/todo/type-inference.md

@@ -41,107 +41,6 @@ callable syntax (`htmlspecialchars(...)`), reuse the existing
 
 ---
 
-## 2. Function-level `@template` generic resolution
-**Impact: High · Effort: Medium**
-
-`MethodInfo` has `template_params` and `template_bindings` fields that
-enable method-level generic resolution at call sites (e.g.
-`@template T` + `@param class-string<T> $class` + `@return T`).
-`FunctionInfo` has **neither** field, so standalone functions that use
-`@template` lose their generic type information entirely.
-
-The only function-level template handling today is
-`synthesize_template_conditional` in `parser/functions.rs`, which
-converts the narrow `@return T` + `@param class-string<T>` pattern
-into a `ConditionalReturnType`.  This does not cover the general case
-where template params appear inside a generic return type:
-
-```php
-/**
- * @template TKey of array-key
- * @template TValue
- * @param  array<TKey, TValue>  $value
- * @return \Illuminate\Support\Collection<TKey, TValue>
- */
-function collect($value = []) { ... }
-
-/**
- * @template TValue
- * @param  TValue  $value
- * @param  callable(TValue): TValue  $callback
- * @return TValue
- */
-function tap($value, $callback = null) { ... }
-```
-
-After `$users = collect($userArray)`, the result is an unparameterised
-`Collection` — element type information is lost, and
-`$users->first()->` produces no completions.
-
-This affects Laravel helpers (`collect`, `value`, `retry`, `tap`,
-`with`, `transform`, `data_get`), PHPStan/Psalm helper libraries, and
-any userland function using `@template`.
-
-### Implementation plan
-
-1. **Add fields to `FunctionInfo`** (in `types.rs`):
-
-   ```text
-   pub template_params: Vec<String>,
-   pub template_bindings: Vec<(String, String)>,
-   ```
-
-   Mirror the existing `MethodInfo` fields.
-
-2. **Populate during parsing** (in `parser/functions.rs`):
-
-   Extract `@template` tags via `extract_template_params` and
-   `@param`-based bindings via `extract_template_param_bindings`,
-   the same functions already used for method-level templates in
-   `parser/classes.rs`.
-
-3. **Resolve at call sites** (in `variable_resolution.rs`,
-   `resolve_rhs_function_call`):
-
-   After loading the `FunctionInfo` and before falling through to
-   `type_hint_to_classes`, check whether the function has
-   `template_params`.  If so:
-
-   a. For each template param, try to infer the concrete type from
-      the call-site arguments using `template_bindings` (positional
-      match between `$paramName` and the `ArgumentList`).  Reuse
-      the existing `resolve_rhs_expression` / `type_hint_to_classes`
-      to get the argument's type.
-
-   b. Build a substitution map `{T => ConcreteType, ...}`.
-
-   c. Apply the substitution to `return_type` via
-      `apply_substitution` before passing it to
-      `type_hint_to_classes`.
-
-   This mirrors what `apply_generic_args` does for class-level
-   templates, but applied to a function call.
-
-4. **Text-based path** (in `text_resolution.rs`):
-
-   The inline chain resolver (`resolve_raw_type_from_call_chain`)
-   also needs the same treatment for chains like
-   `collect($arr)->first()->`.  After resolving the function's
-   return type, apply template substitution before continuing the
-   chain.
-
-**Note:** The existing `synthesize_template_conditional` path for
-`@return T` + `@param class-string<T>` should be kept as-is — it
-handles the special case where the return type is the template param
-itself, which is common for container-style `resolve()`/`app()`
-functions.  The new general path handles the remaining cases.
-
-See also: `todo-laravel.md` gap 5 (`collect()` and other helper
-functions lose generic type info), which is the Laravel-specific
-manifestation of this gap.
-
----
-
 ## 3. Parse and resolve `($param is T ? A : B)` return types
 **Impact: High · Effort: Medium**
 
@@ -584,20 +483,6 @@ type:
 
 ---
 
-## 18. `@phpstan-assert` on static method calls
-**Impact: Medium · Effort: Medium**
-
-`@phpstan-assert` type guards only work on standalone function calls
-today. When the assertion is on a static method (e.g.
-`Assert::instanceOf($value, Foo::class)`), the narrowing does not
-apply to the calling scope.
-
-The same limitation applies to `@phpstan-assert-if-true` and
-`@phpstan-assert-if-false` on static method calls.
-
-**Discovered via:** fixture conversion (phpstan_assert_static).
-
----
 
 ## 19. Negated `@phpstan-assert !Type`
 **Impact: Medium · Effort: Low-Medium**

example.php

@@ -228,6 +228,34 @@ public function demo(): void
 }
 
 
+// ── Static Method Assert Narrowing ─────────────────────────────────────────
+
+class StaticAssertNarrowingDemo
+{
+    public function demo(): void
+    {
+        // @phpstan-assert on static method — unconditional narrowing
+        $unknown = getUnknownValue();
+        StaticAssert::assertRock($unknown);
+        $unknown->crush();                        // narrowed to Rock
+
+        // @phpstan-assert-if-true on static method — narrows in then-branch
+        $sample = pickRockOrBanana();
+        if (StaticAssert::isRock($sample)) {
+            $sample->crush();                     // narrowed to Rock
+        }
+
+        // @phpstan-assert-if-false on static method — narrows in else-branch
+        $maybe = pickRockOrBanana();
+        if (StaticAssert::isNotRock($maybe)) {
+            $maybe->peel();                       // narrowed to Banana
+        } else {
+            $maybe->crush();                      // narrowed to Rock
+        }
+    }
+}
+
+
 // ── Guard Clause Narrowing (Early Return / Throw) ──────────────────────────
 
 class GuardClauseDemo
@@ -363,6 +391,16 @@ public function demo(): void
         $mapped->first();                         // → Pen (T resolved from argument)
 
         $mapper->wrap(new Product())->first()->getPrice(); // new expression arg → Product
+
+        // Variadic class-string<T> → union return type
+        $locator2 = new ServiceLocator();
+        $union = $locator2->getAny(Pen::class, Marker::class);
+        $union->write();                                  // A|B from variadic class-string<T>
+        $union->highlight();
+
+        // Nested generic return: @return Box<T> with class-string<T> param
+        $boxed = $locator->wrap(Pen::class);
+        $boxed->unwrap()->write();                        // Box<T>::unwrap() → Pen
     }
 }
 
@@ -2819,6 +2857,26 @@ public function get(string $id): object
     {
         return new \stdClass();
     }
+
+    /**
+     * @template T
+     * @param class-string<T> ...$ids
+     * @return T
+     */
+    public function getAny(string ...$ids): object
+    {
+        return new \stdClass();
+    }
+
+    /**
+     * @template T
+     * @param class-string<T> $id
+     * @return Box<T>
+     */
+    public function wrap(string $id): Box
+    {
+        return new Box();
+    }
 }
 
 class Factory
@@ -3095,6 +3153,29 @@ function isNotRock(mixed $value): bool
     return !$value instanceof Rock;
 }
 
+class StaticAssert
+{
+    /** @phpstan-assert Rock $value */
+    public static function assertRock(mixed $value): void
+    {
+        if (!$value instanceof Rock) {
+            throw new \InvalidArgumentException('Expected Rock');
+        }
+    }
+
+    /** @phpstan-assert-if-true Rock $value */
+    public static function isRock(mixed $value): bool
+    {
+        return $value instanceof Rock;
+    }
+
+    /** @phpstan-assert-if-false Rock $value */
+    public static function isNotRock(mixed $value): bool
+    {
+        return !$value instanceof Rock;
+    }
+}
+
 // ─── Multi-line @return & Broken Docblock Recovery ──────────────────────────
 
 /**

src/completion/call_resolution.rs

@@ -792,7 +792,10 @@ impl Backend {
     /// - `$this` / `self` / `static` → current class name
     /// - `$this->prop` → property type
     /// - `$var` → variable type via assignment scanning
-    fn resolve_arg_text_to_type(arg_text: &str, ctx: &ResolutionCtx<'_>) -> Option<String> {
+    pub(crate) fn resolve_arg_text_to_type(
+        arg_text: &str,
+        ctx: &ResolutionCtx<'_>,
+    ) -> Option<String> {
         let trimmed = arg_text.trim();
 
         // ClassName::class → ClassName