Fix multi-line @var docblock parsing with extra tags

Author: AJenbo

docs/CHANGELOG.md

@@ -17,6 +17,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - **Generic method return types from `@var` annotations.** When a variable is annotated with a generic type (e.g. `/** @var Collection<int, User> */ $items`), method calls on that variable now correctly substitute class-level template parameters into the return type. Previously, return types like `TValue` remained unsubstituted.
 - **Short class name resolution in type hints.** When resolving an unqualified class name from a property or return type annotation, the resolver now prefers the class in the same namespace as the owning type before falling back to first-match.
 - **Foreach narrowing with break in else.** When a foreach body contained an `if` with an `else { break; }` branch, the variable state from the break path was not included in the post-loop type, causing the merged type to be too narrow.
+- **`@var` docblocks with additional tags.** When a `@var` annotation shared a docblock with other tags (e.g. `@psalm-suppress`, `@deprecated`), the extra lines were included in the type string, corrupting type resolution. Multi-line `@var` docblocks now correctly extract only the type from the first line.
 - **Foreach element type from untyped arrays.** Variables bound in a `foreach` over an untyped `array` (e.g. from a function returning bare `array`) now resolve to `mixed` instead of empty, so assignments from the loop variable propagate correctly.
 - **Foreach target type after non-empty literal array.** When iterating a non-empty literal array such as `["a", "b", "c"]`, the pre-loop sentinel value of the target variable (e.g. `null` from `$tag = null`) no longer survives as a possible post-loop type.
 - **Object cast type inference.** `(object)$scalar` now resolves to `object{scalar:T}` and `(object)$array` resolves to an object shape matching the array's keys, instead of bare `stdClass`.

docs/todo/bugs.md

@@ -49,14 +49,26 @@ Remaining gaps:
 **Discovered:** SKIP audit of
 `tests/psalm_assertions/template_class_template.php`.
 
-Remaining failures are all caused by the multi-namespace
-infrastructure limitation: `FileContext.namespace` stores only the
-first namespace, so the class loader resolves bare names (e.g.
-`Foo`, `Collection`) against the wrong namespace when the same
-short name appears in multiple namespace blocks within one file.
+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`.
 
 **Tests:** SKIPs in `tests/psalm_assertions/template_class_template.php`
-(lines 16, 29, 41, 56, 68, 122, 602, 752, 788).
+(lines 16, 29, 41, 56, 68, 602, 752, 788).
 
 
 

src/completion/variable/forward_walk.rs

@@ -3966,6 +3966,13 @@ fn parse_inline_var_docblock_no_var(doc_text: &str, _ctx: &ForwardWalkCtx<'_>) -
         .or_else(|| inner.strip_prefix("* @var"))?;
     let inner = inner.trim();
 
+    // For multi-line docblocks, only take the type from the first line.
+    // Additional lines may contain other tags like @psalm-suppress that
+    // would corrupt the type string.
+    let inner = inner.lines().next().unwrap_or(inner).trim();
+    // Strip trailing `*` that may remain from `* @var Type  *` formatting.
+    let inner = inner.trim_end_matches('*').trim();
+
     // If there's a `$` it has a variable name — not the no-var form.
     if inner.contains('$') {
         return None;

tests/integration/hover.rs

@@ -2,7 +2,8 @@
 
 use crate::common::{
     create_psr4_workspace, create_test_backend, create_test_backend_with_closure_stub,
-    create_test_backend_with_function_stubs, create_test_backend_with_stdclass_stub,
+    create_test_backend_with_full_stubs, create_test_backend_with_function_stubs,
+    create_test_backend_with_stdclass_stub,
 };
 use phpantom_lsp::Backend;
 use tower_lsp::lsp_types::*;
@@ -11127,3 +11128,72 @@ $result = $a;
         text
     );
 }
+
+#[test]
+fn hover_multi_namespace_template_foo_collision() {
+    // Regression: when `@var Foo<A>` is followed by extra tags
+    // (e.g. `@psalm-suppress`) in the docblock, the type parser
+    // would include the extra lines in the type string, breaking
+    // resolution. This test verifies the fix works with multiple
+    // namespace blocks and Foo collisions across them.
+    let backend = create_test_backend_with_full_stubs();
+    let uri = "file:///test.php";
+    let content = r#"<?php
+namespace NS6 {
+    class A {}
+
+    /**
+     * @template T as object
+     */
+    class Foo {
+        /** @var class-string<T> */
+        public $T;
+        /**
+         * @param class-string<T> $T
+         */
+        public function __construct(string $T) {
+            $this->T = $T;
+        }
+        /**
+         * @return T
+         */
+        public function bar() {
+            $t = $this->T;
+            return new $t();
+        }
+    }
+
+    /**
+     * @var Foo<A>
+     * @psalm-suppress ArgumentTypeCoercion
+     */
+    $afoo = new Foo('A');
+    $afoo_bar = $afoo->bar();
+}
+namespace NS7 {
+    /**
+     * @template T as object
+     */
+    class Foo {
+        /** @var T */
+        public $item;
+    }
+}
+"#;
+    let target_line = content
+        .lines()
+        .enumerate()
+        .find(|(_, l)| l.contains("$afoo_bar = $afoo->bar()"))
+        .map(|(i, _)| i as u32)
+        .unwrap();
+    let line_text = content.lines().nth(target_line as usize).unwrap();
+    let col = line_text.find("$afoo_bar").unwrap() as u32;
+    let hover = hover_at(&backend, uri, content, target_line, col + 1)
+        .expect("expected hover on $afoo_bar");
+    let text = hover_text(&hover);
+    assert!(
+        text.contains("A"),
+        "$afoo_bar should resolve to A via Foo<A>::bar(), got: {}",
+        text
+    );
+}

tests/psalm_assertions/template_class_template.php

@@ -13,7 +13,7 @@
     $key = $decoratorIterator->key();
     $value = $decoratorIterator->current();
 
-    assertType('null|string', $value); // SKIP multi-namespace class resolution
+    assertType('null|string', $value); // SKIP generic iterator constructor inference
     assertType('bool', $next);
 }
 
@@ -26,7 +26,7 @@
     $key = $decoratorIterator->key();
     $value = $decoratorIterator->current();
 
-    assertType('null|string', $value); // SKIP multi-namespace class resolution
+    assertType('null|string', $value); // SKIP generic iterator constructor inference
 }
 
 // Test: limitIterator
@@ -38,7 +38,7 @@
     $key = $decoratorIterator->key();
     $value = $decoratorIterator->current();
 
-    assertType('null|string', $value); // SKIP multi-namespace class resolution
+    assertType('null|string', $value); // SKIP generic iterator constructor inference
 }
 
 // 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 multi-namespace class resolution
+    assertType('null|string', $value); // SKIP generic iterator constructor inference
 }
 
 // Test: noRewindIterator
@@ -65,7 +65,7 @@ static function (string $value): bool {return "a" === $value;}
     $key = $decoratorIterator->key();
     $value = $decoratorIterator->current();
 
-    assertType('null|string', $value); // SKIP multi-namespace class resolution
+    assertType('null|string', $value); // SKIP generic iterator constructor inference
 }
 
 // Test: classTemplate
@@ -119,7 +119,7 @@ public function bar() {
     $cfoo_bar = $cfoo->bar();
 
     assertType('Foo<A>', $afoo);
-    assertType('A', $afoo_bar); // SKIP multi-namespace class resolution (Foo collision with ns6)
+    assertType('A', $afoo_bar); 
     assertType('Foo<B>', $bfoo);
     assertType('B', $bfoo_bar);
     assertType('Foo<C>', $cfoo);
@@ -599,7 +599,7 @@ public function get() {
     $a_or_b = $random_collection->get();
 
     assertType('C<A>|C<B>', $random_collection);
-    assertType('A|B', $a_or_b); // SKIP multi-namespace class resolution (C collision)
+    assertType('A|B', $a_or_b); // SKIP union generic method resolution
 }
 
 // Test: templatedGet
@@ -749,7 +749,7 @@ public function add($key, $t) : void {
         }
     }
 
-    assertType('ArrayCollection<never, never>', $a); // SKIP multi-namespace class resolution (ArrayCollection collision)
+    assertType('ArrayCollection<never, never>', $a); // SKIP generic constructor inference (never)
 }
 
 // Test: unionClassStringInferenceAndDefaultEmptyArray
@@ -785,7 +785,7 @@ public static function fromClassString(string $classString, array $elements = []
         }
     }
 
-    assertType('Collection<A>', $packages); // SKIP multi-namespace class resolution (Collection collision)
+    assertType('Collection<A>', $packages); // SKIP static method call generic inference
 }
 
 // Test: newWithoutInferredTemplate