Fix class-string<T> static method dispatch and return type resolution

Author: AJenbo

docs/CHANGELOG.md

@@ -61,6 +61,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Fixed
 
+- **`class-string<T>` static method dispatch.** When a variable is typed as `class-string<Foo>` (via `@param` or `@template` bound), calling static methods on it (e.g. `$class::from()`, `$class::cases()`) now resolves the return type correctly. The `static` return type substitutes to the bound class, so `$class::from('x')->name` resolves and `foreach ($class::cases() as $item)` gives `$item` the correct type.
+- **`@var` docblock annotations no longer leak across class and method boundaries.** When the cursor was inside a nested block (foreach, if, while), a `@var` annotation for a same-named variable in a completely different class could bleed into the current scope, producing wrong type information. The backward docblock scanner now correctly detects sibling scopes regardless of nesting depth.
+
 - **PHPStan `*` wildcard in generic type arguments.** Type strings like `Relation<TRelatedModel, *, *>` now parse correctly instead of falling back to an unparsed blob. Previously, `mago-type-syntax` rejected the `*` token, causing the entire type to be treated as a single unknown class name (e.g. `Class 'Relation<TRelatedModel, *, *>|string' not found`). The `*` wildcard is now replaced with `mixed` before parsing, matching PHPStan's semantics. Member references like `Foo::*` and constant patterns like `int-mask-of<self::FOO_*>` are not affected.
 - **Closure parameter inference from function-level `@template` bindings.** Functions like `array_any`, `array_all`, and `array_find` that declare `@template` parameters bound through an array parameter and used in a `callable` parameter now infer concrete types for untyped closure arguments. For example, `array_any($this->items, fn($item) => $item->name !== '')` where `$this->items` is `array<int, Product>` now resolves `$item` as `Product`. Previously `$item` was unresolved, producing false-positive `unresolved_member_access` diagnostics. This also fixes a related issue where `@param` tags in phpstorm-stubs that omit the parameter name (e.g. `@param callable(TValue, TKey): bool` without `$callback`) failed to enrich the parameter's type hint, preventing callable parameter type extraction.
 - **Property chain arguments in template substitution.** Expressions like `$this->items` or `$obj->prop` passed as arguments to templated functions now resolve their type for template binding. Previously only bare variables (e.g. `$items`) were resolved, so `array_any($this->items, fn($x) => ...)` could not infer the element type even when the property had a fully substituted generic type.

docs/todo.md

@@ -23,7 +23,7 @@ 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      |
+
 | 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

@@ -488,30 +488,7 @@ simpler, but basic reconciliation can work with strings too).
 
 ---
 
-## T23. `class-string<T>` static method dispatch
-**Impact: Medium · Effort: Medium**
 
-When a variable is typed as `class-string<Foo>` (via `@param` or
-native type), calling static methods on it (e.g. `$class::cases()`,
-`$class::create()`) should resolve through `Foo` as the base class.
-PHPantom currently does not resolve static method calls on
-`class-string`-typed variables, so the return type is unknown and
-any chaining breaks.
-
-A specific sub-problem is the `static` return type: `UnitEnum::cases()`
-returns `static[]`. When called via `$class::cases()` where `$class`
-is `class-string<BackedEnum>`, the return type should resolve as
-`BackedEnum[]`, making `$item->name` and `$item->value` accessible
-in a `foreach`.
-
-Example from triage: `OptionList:27,30` — `$class::cases()` where
-`$class` is typed as `class-string<BackedEnum>`. Properties `name`
-and `value` on the iterated elements are unresolved.
-
-**Implementation:** in the static call resolution path, detect when
-the subject is a variable with a `class-string<T>` type. Extract `T`
-and resolve the method on that class. When the return type contains
-`static`, substitute it with `T`.
 
 ---
 

example.php

@@ -854,6 +854,29 @@ public function demo(): void
 }
 
 
+// ── Class-String Parameter Static Dispatch ──────────────────────────────────
+
+class ClassStringParamDispatchDemo
+{
+    /**
+     * @param class-string<\BackedEnum> $enumClass
+     */
+    public function demo(string $enumClass): void
+    {
+        // Static method dispatch through class-string<T> parameter.
+        // $enumClass::from() returns static, resolved to BackedEnum.
+        $result = $enumClass::from('foo');
+        $result->name;                            // property from UnitEnum via BackedEnum
+
+        // Foreach over $enumClass::cases() resolves items to BackedEnum.
+        foreach ($enumClass::cases() as $item) {
+            $item->value;                         // property from BackedEnum
+            $item->name;                          // property from UnitEnum
+        }
+    }
+}
+
+
 // ── Ambiguous Variables ─────────────────────────────────────────────────────
 
 class AmbiguousVariableDemo

src/completion/variable/resolution.rs

@@ -901,6 +901,7 @@ fn resolve_variable_in_members<'b>(
                     // cases where the class declares `map(object $entity)`
                     // but the interface has `@param TEntity $entity` with
                     // `@implements Interface<Boo>` substituting `TEntity`.
+                    let mut merged_type_hint: Option<String> = None;
                     let method_name = method.name.value.to_string();
                     let merged = crate::virtual_members::resolve_class_fully_maybe_cached(
                         ctx.current_class,
@@ -933,6 +934,12 @@ fn resolve_variable_in_members<'b>(
                                 );
                                 break;
                             }
+                            // The merged type hint is richer than the
+                            // native hint (e.g. `list<Pen>` vs `array`)
+                            // but didn't resolve to a class. Remember
+                            // it so the type-string-only fallback below
+                            // uses it instead of the bare native hint.
+                            merged_type_hint = Some(hint_str);
                         }
                     }
 
@@ -944,7 +951,14 @@ fn resolve_variable_in_members<'b>(
                     // Prefer the docblock type (e.g. `class-string<BackedEnum>`)
                     // over the native type (e.g. `string`) when the
                     // docblock provides a more specific annotation.
-                    let best_type_str = raw_docblock_type.as_deref().or(type_str_for_resolution);
+                    // When the merged class provides a richer type from
+                    // parent/interface inheritance (e.g. `list<Pen>` from
+                    // a parent's `@param`), prefer that over the bare
+                    // native hint.
+                    let best_type_str = raw_docblock_type
+                        .as_deref()
+                        .or(merged_type_hint.as_deref())
+                        .or(type_str_for_resolution);
                     if let Some(ts) = best_type_str {
                         let mut parsed = PhpType::parse(ts);
 

src/completion/variable/rhs_resolution.rs

@@ -1805,7 +1805,39 @@ fn resolve_rhs_static_call(
                     ctx.cursor_offset,
                     ctx.class_loader,
                 );
-            targets.first().map(|c| c.name.clone())
+            if let Some(first) = targets.first() {
+                Some(first.name.clone())
+            } else {
+                // Fallback: resolve the variable's type and extract the
+                // inner type from `class-string<T>`.  This handles
+                // parameters typed as `@param class-string<Foo> $var`
+                // where there is no `$var = Foo::class` assignment.
+                let resolved = super::resolution::resolve_variable_types(
+                    &var_name,
+                    ctx.current_class,
+                    ctx.all_classes,
+                    ctx.content,
+                    ctx.cursor_offset,
+                    ctx.class_loader,
+                    Loaders::with_function(ctx.function_loader()),
+                );
+                resolved.iter().find_map(|rt| match &rt.type_string {
+                    PhpType::ClassString(Some(inner)) => Some(inner.to_string()),
+                    PhpType::Nullable(inner) => match inner.as_ref() {
+                        PhpType::ClassString(Some(cs_inner)) => Some(cs_inner.to_string()),
+                        _ => None,
+                    },
+                    PhpType::Union(members) => members.iter().find_map(|m| match m {
+                        PhpType::ClassString(Some(inner)) => Some(inner.to_string()),
+                        PhpType::Nullable(inner) => match inner.as_ref() {
+                            PhpType::ClassString(Some(cs_inner)) => Some(cs_inner.to_string()),
+                            _ => None,
+                        },
+                        _ => None,
+                    }),
+                    _ => None,
+                })
+            }
         }
         _ => None,
     };

src/docblock/tags.rs

@@ -514,10 +514,14 @@ pub fn find_var_raw_type_in_source(
         min_depth = min_depth.min(brace_depth);
 
         // Once we have exited our containing scope (min_depth < 0) and
-        // re-entered a block at depth >= 0, we are inside a sibling
-        // scope (e.g. a different method in the same class).  From that
-        // point on every annotation belongs to a foreign scope.
-        if min_depth < 0 && brace_depth >= 0 {
+        // re-entered a block close to that level, we are inside a
+        // sibling scope (e.g. a different method in the same class).
+        // From that point on every annotation belongs to a foreign
+        // scope.  The threshold is `min_depth + 1` rather than `>= 0`
+        // because the cursor may be inside a nested block (foreach,
+        // if, etc.) whose extra depth prevents brace_depth from ever
+        // reaching 0 when traversing sibling classes.
+        if min_depth < 0 && brace_depth > min_depth {
             seen_sibling_scope = true;
         }
         if seen_sibling_scope {
@@ -966,10 +970,19 @@ pub fn find_iterable_raw_type_in_source(
         min_depth = min_depth.min(brace_depth);
 
         // Once we have exited our containing scope (min_depth < 0) and
-        // re-entered a block at depth >= 0, we are inside a sibling
-        // scope (e.g. a different method in the same class).  From that
-        // point on every annotation belongs to a foreign scope.
-        if min_depth < 0 && brace_depth >= 0 {
+        // re-entered a block close to that level, we are inside a
+        // sibling scope (e.g. a different method in the same class).
+        // From that point on every annotation belongs to a foreign
+        // scope.
+        //
+        // The threshold is `min_depth + 1` rather than `>= 0` because
+        // the cursor may be inside a nested block (foreach, if, etc.)
+        // that adds extra depth.  When starting inside a foreach in a
+        // class method, min_depth reaches -3 (foreach { + method { +
+        // class {), so a sibling method body at depth -1 would never
+        // reach 0.  Using `min_depth + 1` catches the first rise back
+        // toward our exit point.
+        if min_depth < 0 && brace_depth > min_depth {
             seen_sibling_scope = true;
         }
         if seen_sibling_scope {
@@ -1890,4 +1903,190 @@ mod tests {
         let doc = "/**\n * @deprecated Use foo() instead.\n * @see NewClass\n * @return int\n */";
         assert_eq!(extract_removed_version(doc), None);
     }
+
+    // ── find_var_raw_type_in_source — scope isolation ───────────────
+
+    #[test]
+    fn var_docblock_does_not_leak_across_sibling_methods() {
+        // A `@var` in one class method must not be visible in another.
+        let src = concat!(
+            "<?php\n",
+            "class A {\n",
+            "    public function first(): void {\n",
+            "        /** @var object{title: string} $item */\n",
+            "        $item = foo();\n",
+            "    }\n",
+            "}\n",
+            "class B {\n",
+            "    public function second(): void {\n",
+            "        $item->\n", // cursor here
+            "    }\n",
+            "}\n",
+        );
+        let cursor = src.find("$item->").unwrap();
+        let result = find_var_raw_type_in_source(src, cursor, "$item");
+        assert_eq!(
+            result, None,
+            "@var from A::first() must not leak into B::second()"
+        );
+    }
+
+    #[test]
+    fn var_docblock_does_not_leak_across_sibling_methods_same_class() {
+        let src = concat!(
+            "<?php\n",
+            "class Demo {\n",
+            "    public function first(): void {\n",
+            "        /** @var Pen $item */\n",
+            "        $item = foo();\n",
+            "    }\n",
+            "    public function second(): void {\n",
+            "        $item->\n",
+            "    }\n",
+            "}\n",
+        );
+        let cursor = src.find("$item->").unwrap();
+        let result = find_var_raw_type_in_source(src, cursor, "$item");
+        assert_eq!(
+            result, None,
+            "@var from first() must not leak into second()"
+        );
+    }
+
+    #[test]
+    fn var_docblock_does_not_leak_when_cursor_inside_nested_block() {
+        // The original bug: when the cursor is inside a foreach (or if,
+        // while, etc.), the extra nesting depth prevented the sibling
+        // scope detection from firing, allowing @var from a method in a
+        // completely different class to leak through.
+        let src = concat!(
+            "<?php\n",
+            "class ObjectShapeDemo {\n",
+            "    public function demo(): void {\n",
+            "        /** @var object{title: string, score: float} $item */\n",
+            "        $item = getUnknownValue();\n",
+            "    }\n",
+            "}\n",
+            "class Other {\n",
+            "    public function demo(): void {\n",
+            "        foreach ($things as $item) {\n",
+            "            $item->\n",
+            "        }\n",
+            "    }\n",
+            "}\n",
+        );
+        let cursor = src.find("$item->").unwrap();
+        let result = find_var_raw_type_in_source(src, cursor, "$item");
+        assert_eq!(
+            result, None,
+            "@var from ObjectShapeDemo must not leak into Other when cursor is inside foreach"
+        );
+    }
+
+    #[test]
+    fn var_docblock_found_in_own_scope() {
+        let src = concat!(
+            "<?php\n",
+            "class Demo {\n",
+            "    public function demo(): void {\n",
+            "        /** @var Pen $item */\n",
+            "        $item = foo();\n",
+            "        $item->\n",
+            "    }\n",
+            "}\n",
+        );
+        let cursor = src.find("$item->").unwrap();
+        let result = find_var_raw_type_in_source(src, cursor, "$item");
+        assert_eq!(result, Some("Pen".to_string()));
+    }
+
+    #[test]
+    fn var_docblock_found_inside_nested_block_in_own_scope() {
+        let src = concat!(
+            "<?php\n",
+            "class Demo {\n",
+            "    public function demo(): void {\n",
+            "        /** @var Pen $item */\n",
+            "        $item = foo();\n",
+            "        if (true) {\n",
+            "            $item->\n",
+            "        }\n",
+            "    }\n",
+            "}\n",
+        );
+        let cursor = src.find("$item->").unwrap();
+        let result = find_var_raw_type_in_source(src, cursor, "$item");
+        assert_eq!(result, Some("Pen".to_string()));
+    }
+
+    // ── find_iterable_raw_type_in_source — scope isolation ──────────
+
+    #[test]
+    fn iterable_docblock_does_not_leak_across_sibling_classes_nested() {
+        // Same bug scenario for find_iterable_raw_type_in_source:
+        // @var in a sibling class method leaks when cursor is nested.
+        let src = concat!(
+            "<?php\n",
+            "class A {\n",
+            "    public function demo(): void {\n",
+            "        /** @var object{title: string} $item */\n",
+            "        $item = foo();\n",
+            "    }\n",
+            "}\n",
+            "class B {\n",
+            "    public function demo(): void {\n",
+            "        foreach ($things as $x) {\n",
+            "            $item->\n",
+            "        }\n",
+            "    }\n",
+            "}\n",
+        );
+        let cursor = src.find("$item->").unwrap();
+        let result = find_iterable_raw_type_in_source(src, cursor, "$item");
+        assert_eq!(
+            result, None,
+            "@var from A::demo() must not leak into B::demo() foreach body"
+        );
+    }
+
+    #[test]
+    fn iterable_param_found_in_own_method_from_nested_block() {
+        // @param in the enclosing method's docblock must still be found
+        // even when the cursor is inside a nested block.
+        let src = concat!(
+            "<?php\n",
+            "class Demo {\n",
+            "    /**\n",
+            "     * @param list<Pen> $items\n",
+            "     */\n",
+            "    public function demo(array $items): void {\n",
+            "        foreach ($items as $x) {\n",
+            "            // cursor\n",
+            "        }\n",
+            "    }\n",
+            "}\n",
+        );
+        let cursor = src.find("// cursor").unwrap();
+        let result = find_iterable_raw_type_in_source(src, cursor, "$items");
+        assert_eq!(result, Some("list<Pen>".to_string()));
+    }
+
+    #[test]
+    fn iterable_var_found_in_own_scope_nested() {
+        let src = concat!(
+            "<?php\n",
+            "class Demo {\n",
+            "    public function demo(): void {\n",
+            "        /** @var list<Pen> $items */\n",
+            "        $items = foo();\n",
+            "        foreach ($items as $x) {\n",
+            "            // cursor\n",
+            "        }\n",
+            "    }\n",
+            "}\n",
+        );
+        let cursor = src.find("// cursor").unwrap();
+        let result = find_iterable_raw_type_in_source(src, cursor, "$items");
+        assert_eq!(result, Some("list<Pen>".to_string()));
+    }
 }

tests/fixture_runner.rs

@@ -22,6 +22,7 @@ static UNIT_ENUM_STUB: &str = "\
 <?php
 interface UnitEnum
 {
+    /** @return static[] */
     public static function cases(): array;
     public readonly string $name;
 }