Implement bidirectional template inference from closure param types

Author: AJenbo

docs/CHANGELOG.md

@@ -17,7 +17,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - **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.
 - **`fix` CLI subcommand.** `phpantom_lsp fix` applies automated code fixes across a project, modeled after php-cs-fixer. Specify rules with `--rule unused_import` (multiple allowed) or omit to run all preferred native fixers. `--dry-run` reports what would change without writing files (exit code 2). `--with-phpstan` enables PHPStan-based fixers (not yet implemented). The first shipped rule, `unused_import`, removes all unused `use` statements project-wide, handling simple imports, group imports, and blank-line collapsing. Supports path filtering (`fix src/`) and single-file mode.
 - **Array element type extraction from property generics.** Bracket access on properties annotated with generic array types (e.g. `$this->cache[$key]->` where `cache` is `array<string, IntCollection>`, or `$this->translations[0]->` where `translations` is `Collection<int, Translation>`) now resolves the element type correctly. Previously the generic parameters were lost during property chain resolution, causing "subject type could not be resolved" on any member access after the bracket. Works for `$this->prop`, `$obj->prop`, nested chains like `$this->nested->prop[0]->`, string-literal keys, and method chains after the bracket access.
-- **Template binding from closure return types.** Methods like `Collection::reduce()` that declare a method-level `@template` parameter bound through a callable's return type now resolve correctly. When the closure or arrow function argument has a return type annotation (e.g. `fn(Decimal $carry, $item): Decimal => ...`), the return type binds the template parameter, so the method's own return type resolves to the concrete class. This works for `fn()` arrow functions, `function()` closures, and closures with `use()` clauses.
+- **Bidirectional template inference from closures.** When a method or function declares a `@template` parameter that appears in a callable's signature, the template is inferred from both the closure's return type and its parameter types. Return-type binding (e.g. `@param callable(...): T` with `fn(...): Decimal => ...` infers `T` as `Decimal`) was already supported. Parameter-type binding is new: `@param Closure(T): void` with `function(User $u): void { ... }` now infers `T` as `User` from the closure's parameter type annotation. Positional matching is supported, so `@param Closure(int, T): void` correctly picks `T` from the second parameter. When the same template appears in both the callable's return type and parameters, the return type takes priority. Works for methods, standalone functions, and constructors with `fn()` arrow functions and `function()` closures.
 - **Inherited docblock type propagation.** When a child class overrides a method from a parent class or interface without providing its own `@return` or `@param` docblock, the ancestor's richer types now flow through automatically. An interface declaring `@return list<Pen>` with a native `: array` hint propagates `list<Pen>` to any implementor that only declares `: array`. The same applies to parent class methods, parameter types (matched by position so renamed parameters still inherit), and property type hints. Descriptions and return descriptions are also inherited when the child lacks them. If the child provides its own docblock type, it is respected as an intentional override.
 - **Drupal project support.** Drupal projects are detected via `composer.json` (`drupal/core`, `drupal/core-recommended`, or `drupal/core-dev`). The web root is resolved from `extra.drupal-scaffold.locations.web-root` with a filesystem fallback. Drupal-specific directories (`core`, `modules/contrib`, `modules/custom`, `themes/contrib`, `themes/custom`, `profiles`, `sites`) are scanned with `.gitignore` bypassed so that Composer-managed code is always indexed. Drupal PHP extensions (`.module`, `.install`, `.theme`, `.profile`, `.inc`, `.engine`) are recognized as PHP source. Contributed by @syntlyx in https://github.com/AJenbo/phpantom_lsp/pull/52.
 - **`@phpstan-assert-if-true $this` narrowing.** Instance methods annotated with `@phpstan-assert-if-true` or `@phpstan-assert-if-false` targeting `$this` now narrow the receiver variable in the corresponding branch. For example, `if ($app->isTestApp())` narrows `$app` to the asserted subtype inside the then-body. Contributed by @syntlyx in https://github.com/AJenbo/phpantom_lsp/pull/52.

docs/todo.md

@@ -24,7 +24,6 @@ within the same impact tier.
 | #   | Item                                                                                                                                             | Impact      | Effort      |
 | --- | ------------------------------------------------------------------------------------------------------------------------------------------------ | ----------- | ----------- |
 | T23 | [`class-string<T>` static method dispatch](todo/type-inference.md#t23-class-stringt-static-method-dispatch)                                     | Medium      | Medium      |
-| T21 | [Bidirectional template inference](todo/type-inference.md#t21-bidirectional-template-inference-upperlower-bounds) (closure return type → generic) | Medium      | Medium-High |
 | H10 | [`return.unusedType` — remove unused type from return union](todo/phpstan-actions.md#h10-returnunusedtype--remove-unused-type-from-return-union) | Medium      | Medium      |
 | H6  | `return.type` — update return type to match actual returns                                                                                       | Medium      | Medium      |
 |     | **Release 0.7.0**                                                                                                                                |             |             |

docs/todo/type-inference.md

@@ -515,40 +515,6 @@ and resolve the method on that class. When the return type contains
 
 ---
 
-## T21. Bidirectional template inference (upper/lower bounds)
-**Impact: Medium · Effort: Medium-High**
-
-PHPantom's template resolution only tracks one direction: matching
-template parameters against concrete types from extends clauses and
-direct argument positions. PHPStan and Psalm track both upper bounds
-(covariant positions like return types) and lower bounds (contravariant
-positions like parameter types).
-
-Key gaps:
-
-1. When `@param Closure(T): void $callback` receives a closure, `T`
-   should be inferred from the closure's parameter type
-   (contravariant).
-2. When multiple bounds exist for the same template, the most specific
-   one should win. Psalm uses `appearance_depth` to prefer direct
-   bindings over nested ones.
-3. No variance tracking. `@template-covariant T` vs `@template T`
-   affects whether `Container<Cat>` is assignable to
-   `Container<Animal>`.
-4. Template parameters not instantiated from closure return type at
-   call sites. Example: `Collection::reduce(fn(Decimal $c, ...):
-   Decimal => ..., new Decimal('0'))` — `TReduceReturnType` should
-   be inferred as `Decimal` from the callback return type, and
-   `TReduceInitial` as `Decimal` from the `$initial` argument.
-   Currently the return type of `reduce()` is unresolved.
-   (Triage: `FlowService:517`.)
-
-**Implementation:** add a `TemplateResolution` struct that accumulates
-lower and upper bounds during call-site analysis, with a `resolve()`
-method that picks the most specific bound.
-
----
-
 ## T24. `stdClass` dynamic property access
 **Impact: Low-Medium · Effort: Low**
 

example.php

@@ -573,6 +573,35 @@ function(Pen $carry, Pencil $item): Pen {
     }
 }
 
+// ── Closure Param → Template Inference (Contravariant) ─────────────────────
+
+class ClosureParamTemplateDemo
+{
+    public function demo(): void
+    {
+        // When a method declares @param Closure(T): void $cb, the template
+        // param T is inferred from the closure's *parameter* type annotation
+        // (contravariant position), not the return type.
+
+        $bus = new ScaffoldingEventBus();
+
+        // Arrow function: T inferred as Pen from fn(Pen $p)
+        $result = $bus->listen(function(Pen $p): void { $p->write(); });
+        $result->write();       // T = Pen
+        $result->color();       // completions for Pen
+
+        // Full closure: T inferred as User from function(User $u)
+        $user = $bus->listen(function(User $u): void { $u->getEmail(); });
+        $user->getName();       // T = User
+
+        // Second param position: @param Closure(int, T): void
+        $proc = new ScaffoldingBatchProcessor();
+        $item = $proc->process(function(int $i, Pencil $p): void { $p->sketch(); });
+        $item->sketch();        // T = Pencil (from position 1)
+        $item->sharpen();
+    }
+}
+
 
 // ── Trait Generic Substitution ──────────────────────────────────────────────
 
@@ -3625,6 +3654,38 @@ class ScaffoldingClosureParamInference
     public function __construct() { $this->items = new FluentCollection([new Pen('red'), new Pen('blue')]); }
 }
 
+class ScaffoldingEventBus
+{
+    /**
+     * @template T
+     * @param Closure(T): void $callback
+     * @return T
+     */
+    public function listen(Closure $callback): mixed
+    {
+        $params = (new \ReflectionFunction($callback))->getParameters();
+        $type = $params[0]->getType();
+        $class = $type ? $type->getName() : 'stdClass';
+        return (new \ReflectionClass($class))->newInstanceWithoutConstructor();
+    }
+}
+
+class ScaffoldingBatchProcessor
+{
+    /**
+     * @template T
+     * @param Closure(int, T): void $handler
+     * @return T
+     */
+    public function process(Closure $handler): mixed
+    {
+        $params = (new \ReflectionFunction($handler))->getParameters();
+        $type = $params[1]->getType();
+        $class = $type ? $type->getName() : 'stdClass';
+        return (new \ReflectionClass($class))->newInstanceWithoutConstructor();
+    }
+}
+
 class ScaffoldingTemplateCallableHolder
 {
     /** @var array<int, Pen> */
@@ -5163,6 +5224,19 @@ function runDemoAssertions(): void
     );
     assert($reduced instanceof Pen, 'reduce() with fn(): Pen must return Pen');
 
+    // ── ScaffoldingEventBus::listen() — closure param type binding ──────
+    $bus = new ScaffoldingEventBus();
+    $listened = $bus->listen(function(Pen $p): void { $p->write(); });
+    assert($listened instanceof Pen, 'listen(fn(Pen $p)) must return Pen (T inferred from closure param)');
+
+    $listenedUser = $bus->listen(function(User $u): void { $u->getEmail(); });
+    assert($listenedUser instanceof User, 'listen(function(User $u)) must return User');
+
+    // ── ScaffoldingBatchProcessor::process() — second closure param ─────
+    $proc = new ScaffoldingBatchProcessor();
+    $processed = $proc->process(function(int $i, Pencil $p): void { $p->sketch(); });
+    assert($processed instanceof Pencil, 'process(fn(int, Pencil)) must return Pencil (T from position 1)');
+
     // ── Nested generic: ServiceLocator::wrap → Box::unwrap ──────────────
     $boxed = $locator->wrap(Pen::class);
     assert($boxed instanceof Box, 'ServiceLocator::wrap() must return Box');

src/completion/call_resolution.rs

@@ -1226,6 +1226,17 @@ impl Backend {
                         subs.insert(tpl_name.clone(), PhpType::parse(&ret_type));
                     }
                 }
+                TemplateBindingMode::CallableParamType(position) => {
+                    // `@param Closure(T): void $cb` — extract the closure's
+                    // parameter type annotation at the given position.
+                    if let Some(param_type) =
+                        super::source::helpers::extract_closure_param_type_from_text(
+                            arg_text, position,
+                        )
+                    {
+                        subs.insert(tpl_name.clone(), PhpType::parse(&param_type));
+                    }
+                }
                 TemplateBindingMode::ArrayElement => {
                     if let Some(type_name) = Self::resolve_arg_text_to_type(arg_text, ctx) {
                         subs.insert(tpl_name.clone(), PhpType::parse(&type_name));