Prioritize @phpstan-param and @psalm-param over @param tags in docblock

param type extraction

Author: AJenbo

docs/CHANGELOG.md

@@ -28,6 +28,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - **Trait `self` return type resolution through inheritance.** When a trait method has return type `self`, calling it on a subclass now correctly resolves to the class that uses the trait (the declaring class), not the calling subclass. `static` and `$this` continue to resolve to the runtime class.
 - **`NoRewindIterator` generic resolution.** Added stub patch so `new NoRewindIterator($generator)` propagates the wrapped iterator's type parameters.
 - **Template param inference from type bounds.** When a class template parameter has a bound like `TIterator as Iterator<TKey, TValue>` and `TIterator` is resolved to a concrete generic type, the nested template params (`TKey`, `TValue`) are now inferred from the concrete type's generic arguments.
+- **`@psalm-param`/`@phpstan-param` priority over `@param`.** When a docblock contained both `@param array $x` and `@psalm-param array<TKey, T> $x`, the parameter type was resolved from whichever tag appeared first in the docblock. Now `@phpstan-param` always takes precedence over `@psalm-param`, which always takes precedence over `@param`, matching PHPStan and Psalm behaviour. This fixes generic constructor inference when stubs use paired `@param`/`@psalm-param` tags.
 - **`static` return type through first-class callables.** `self::method(...)()`, `static::method(...)()`, `parent::method(...)()`, and `$this->method(...)()` now preserve `static` in the return type when the underlying method declares `@return static`.
 - **ArrayAccess array-access assignment.** `$obj[$key] = $val` on objects implementing `ArrayAccess` no longer overwrites the variable's generic type annotation with an array type.
 - **Method-level `@template` with `key-of` bound.** When a method declares `@template K as key-of<TData>` and returns `TData[K]`, passing a string literal argument (e.g. `$config->get('name')`) now infers K from the literal and resolves the return type to the specific array shape value type.

docs/todo/bugs.md

@@ -20,23 +20,31 @@ to second-guess upstream output.
 Remaining failures have multiple root causes (the original
 multi-namespace theory was incorrect for most of them):
 
-- **Lines 16, 29, 41, 56, 68:** Generic constructor inference
-  through iterator decorators (`CachingIterator(new ArrayIterator(...))`)
-  does not propagate template parameters. Fails in single-namespace
-  files too.
-- **Line 602:** Union generic method resolution (`C<A>|C<B>` → `->get()`)
-  does not resolve per-branch template substitutions.
-- **Line 752:** `new ArrayCollection()` with no args infers
-  `ArrayCollection<array, array>` instead of `ArrayCollection<never, never>`.
-- **Line 788:** Static method call `Collection::fromClassString(A::class)`
-  does not propagate the method-level template to the return type.
-
-**Fixed:** Line 122 — `@var` docblocks with additional tags
-(e.g. `@psalm-suppress`) after the type corrupted the type string.
-Fixed in `parse_inline_var_docblock_no_var`.
+- **Lines 16, 29, 41, 56, 68:** SPL iterator stubs
+  (`CachingIterator`, `InfiniteIterator`, `LimitIterator`,
+  `CallbackFilterIterator`, `NoRewindIterator`) lack `@template`
+  annotations, so generic type propagation through iterator
+  decorator constructors is impossible with current stubs.
+- **Lines 602, 788:** Union generic method resolution and static
+  method template inference work correctly in single-namespace
+  files. The failures are caused by the multi-namespace test
+  runner not resolving short class names to FQN across namespace
+  blocks in the same file.
+
+**Fixed:**
+- Line 122 — `@var` docblocks with additional tags
+  (e.g. `@psalm-suppress`) after the type corrupted the type
+  string. Fixed in `parse_inline_var_docblock_no_var`.
+- Line 752 — `new ArrayCollection([])` inferred
+  `ArrayCollection<array, array>` instead of
+  `ArrayCollection<never, never>`. Root cause: when both `@param`
+  and `@psalm-param` existed for the same parameter,
+  `extract_param_raw_type_from_info` returned the first match in
+  document order instead of respecting `@phpstan-param` >
+  `@psalm-param` > `@param` priority.
 
 **Tests:** SKIPs in `tests/psalm_assertions/template_class_template.php`
-(lines 16, 29, 41, 56, 68, 602, 752, 788).
+(lines 16, 29, 41, 56, 68, 602, 788).
 
 
 
@@ -64,11 +72,10 @@ tests that may now pass. Run
 `cargo nextest run --test assert_type_runner --no-fail-fast` with
 the SKIP removed to verify.
 
-Remaining SKIPs (12) are:
-- `template_class_template.php` (8) — B14 multi-namespace and
-  genuine type engine gaps (union generic method resolution,
-  generic constructor inference with `never`, static method
-  generic inference)
+Remaining SKIPs (11) are:
+- `template_class_template.php` (7) — B14: SPL stubs lack
+  @template annotations (5), multi-namespace test runner
+  limitation (2)
 - `magic_method_annotation.php` (3) — B14 cross-namespace
   resolution in single-file test runner
 - `mixin_annotation.php` (1) — `IteratorIterator` not in fixture

src/docblock/tags.rs

@@ -598,21 +598,30 @@ pub fn extract_param_raw_type(docblock: &str, var_name: &str) -> Option<PhpType>
 
 /// Like [`extract_param_raw_type`], but operates on a pre-parsed [`DocblockInfo`].
 pub fn extract_param_raw_type_from_info(info: &DocblockInfo, var_name: &str) -> Option<PhpType> {
-    for tag in info.tags_by_kinds(&[TagKind::PhpstanParam, TagKind::PsalmParam, TagKind::Param]) {
-        let desc = tag.description.trim();
-        if desc.is_empty() {
-            continue;
-        }
-
-        // Extract the full type token (respects `<…>` nesting).
-        let (type_token, remainder) = split_type_token(desc);
+    // Check tags in priority order: @phpstan-param > @psalm-param > @param.
+    // When both `@param` and `@psalm-param` exist for the same parameter,
+    // the more specific variant must win.  Because `tags_by_kinds` yields
+    // tags in document order, iterating all kinds at once would return
+    // whichever appears first in the docblock.  Instead, check each
+    // priority level separately so that `@phpstan-param` always beats
+    // `@psalm-param` which always beats `@param`.
+    for kind in &[TagKind::PhpstanParam, TagKind::PsalmParam, TagKind::Param] {
+        for tag in info.tags_by_kind(*kind) {
+            let desc = tag.description.trim();
+            if desc.is_empty() {
+                continue;
+            }
 
-        // The next token should be the parameter name.
-        // Handle `...$name` (variadic) by stripping the leading `...`.
-        if let Some(name) = remainder.split_whitespace().next() {
-            let name = name.strip_prefix("...").unwrap_or(name);
-            if name == var_name {
-                return sanitise_and_parse_docblock_type(type_token);
+            // Extract the full type token (respects `<…>` nesting).
+            let (type_token, remainder) = split_type_token(desc);
+
+            // The next token should be the parameter name.
+            // Handle `...$name` (variadic) by stripping the leading `...`.
+            if let Some(name) = remainder.split_whitespace().next() {
+                let name = name.strip_prefix("...").unwrap_or(name);
+                if name == var_name {
+                    return sanitise_and_parse_docblock_type(type_token);
+                }
             }
         }
     }
@@ -640,26 +649,31 @@ pub fn extract_all_param_tags(docblock: &str) -> Vec<(String, PhpType)> {
 /// Like [`extract_all_param_tags`], but operates on a pre-parsed [`DocblockInfo`].
 pub fn extract_all_param_tags_from_info(info: &DocblockInfo) -> Vec<(String, PhpType)> {
     let mut results = Vec::new();
+    let mut seen_params = std::collections::HashSet::new();
 
-    // Only match `@param` and `@phpstan-param`, not compound tags like
-    // `@param-closure-this` (those have their own TagKind).
-    for tag in info.tags_by_kinds(&[TagKind::PhpstanParam, TagKind::PsalmParam, TagKind::Param]) {
-        let desc = tag.description.trim();
-        if desc.is_empty() {
-            continue;
-        }
-
-        // Extract the full type token (respects `<…>` nesting).
-        let (type_token, remainder) = split_type_token(desc);
+    // Iterate in priority order: @phpstan-param > @psalm-param > @param.
+    // When both `@param` and `@psalm-param` exist for the same parameter,
+    // the more specific variant wins.
+    for kind in &[TagKind::PhpstanParam, TagKind::PsalmParam, TagKind::Param] {
+        for tag in info.tags_by_kind(*kind) {
+            let desc = tag.description.trim();
+            if desc.is_empty() {
+                continue;
+            }
 
-        // The next token should be the parameter name.
-        // Handle `...$name` (variadic) by stripping the leading `...`.
-        if let Some(name) = remainder.split_whitespace().next() {
-            let name = name.strip_prefix("...").unwrap_or(name);
-            if name.starts_with('$')
-                && let Some(parsed) = sanitise_and_parse_docblock_type(type_token)
-            {
-                results.push((name.to_string(), parsed));
+            // Extract the full type token (respects `<…>` nesting).
+            let (type_token, remainder) = split_type_token(desc);
+
+            // The next token should be the parameter name.
+            // Handle `...$name` (variadic) by stripping the leading `...`.
+            if let Some(name) = remainder.split_whitespace().next() {
+                let name = name.strip_prefix("...").unwrap_or(name);
+                if name.starts_with('$')
+                    && seen_params.insert(name.to_string())
+                    && let Some(parsed) = sanitise_and_parse_docblock_type(type_token)
+                {
+                    results.push((name.to_string(), parsed));
+                }
             }
         }
     }

tests/psalm_assertions/template_class_template.php

@@ -13,7 +13,7 @@
     $key = $decoratorIterator->key();
     $value = $decoratorIterator->current();
 
-    assertType('null|string', $value); // SKIP generic iterator constructor inference
+    assertType('null|string', $value); // SKIP SPL stubs lack @template annotations
     assertType('bool', $next);
 }
 
@@ -26,7 +26,7 @@
     $key = $decoratorIterator->key();
     $value = $decoratorIterator->current();
 
-    assertType('null|string', $value); // SKIP generic iterator constructor inference
+    assertType('null|string', $value); // SKIP SPL stubs lack @template annotations
 }
 
 // Test: limitIterator
@@ -38,7 +38,7 @@
     $key = $decoratorIterator->key();
     $value = $decoratorIterator->current();
 
-    assertType('null|string', $value); // SKIP generic iterator constructor inference
+    assertType('null|string', $value); // SKIP SPL stubs lack @template annotations
 }
 
 // Test: callbackFilterIterator
@@ -53,7 +53,7 @@ static function (string $value): bool {return "a" === $value;}
     $key = $decoratorIterator->key();
     $value = $decoratorIterator->current();
 
-    assertType('null|string', $value); // SKIP generic iterator constructor inference
+    assertType('null|string', $value); // SKIP SPL stubs lack @template annotations
 }
 
 // Test: noRewindIterator
@@ -65,9 +65,10 @@ static function (string $value): bool {return "a" === $value;}
     $key = $decoratorIterator->key();
     $value = $decoratorIterator->current();
 
-    assertType('null|string', $value); // SKIP generic iterator constructor inference
+    assertType('null|string', $value); // SKIP SPL stubs lack @template annotations
 }
 
+
 // Test: classTemplate
 namespace PsalmTest_template_class_template_6 {
     class A {}
@@ -599,7 +600,7 @@ public function get() {
     $a_or_b = $random_collection->get();
 
     assertType('C<A>|C<B>', $random_collection);
-    assertType('A|B', $a_or_b); // SKIP union generic method resolution
+    assertType('A|B', $a_or_b); // SKIP multi-namespace test runner limitation (works in real code)
 }
 
 // Test: templatedGet
@@ -749,7 +750,7 @@ public function add($key, $t) : void {
         }
     }
 
-    assertType('ArrayCollection<never, never>', $a); // SKIP generic constructor inference (never)
+    assertType('ArrayCollection<never, never>', $a);
 }
 
 // Test: unionClassStringInferenceAndDefaultEmptyArray
@@ -785,7 +786,7 @@ public static function fromClassString(string $classString, array $elements = []
         }
     }
 
-    assertType('Collection<A>', $packages); // SKIP static method call generic inference
+    assertType('Collection<A>', $packages); // SKIP multi-namespace test runner limitation (works in real code)
 }
 
 // Test: newWithoutInferredTemplate