Diagnostics: unresolved class/interface implemented, and show templates in hover

Author: AJenbo

docs/CHANGELOG.md

@@ -12,6 +12,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - **Find References.** "Find All References" locates every usage of a symbol across the project. Supports classes, interfaces, traits, enums, methods, properties, constants, functions, and variables. Variable references are scoped to the enclosing function or closure. Cross-file scanning lazily indexes user files on demand (vendor and stub files are excluded, matching PhpStorm's behaviour). The workspace walk respects `.gitignore` rules, so generated/cached directories (blade cache, Symfony `var/cache/`, `node_modules/`, etc.) are automatically skipped.
 - **`#[Deprecated]` attribute support.** PHPantom now reads the `#[Deprecated]` attribute used by phpstorm-stubs (~362 elements) in addition to docblock `@deprecated` tags. The `reason` and `since` fields appear in hover, completion strikethrough, and deprecation diagnostics. When both a docblock tag and an attribute are present, the docblock message takes priority. Works on classes, interfaces, traits, enums, methods, properties, constants, and standalone functions.
 - **Deprecation diagnostics for variable member access.** Calling a deprecated method or accessing a deprecated property through a variable (e.g. `$svc->oldMethod()`) now produces a strikethrough diagnostic. Previously only `self::`, `static::`, `$this->`, and explicit class name accesses were checked.
+- **Unknown class diagnostics.** Class references that PHPantom cannot resolve through any phase (use-map, local classes, same-namespace, class_index, classmap, PSR-4, stubs) are underlined with a warning. The diagnostic pairs with the "Import Class" code action so pressing the quick-fix shortcut on the warning offers to add the missing `use` statement in one step. Template parameters, type aliases (`@phpstan-type`, `@phpstan-import-type`), and attribute classes are excluded to avoid false positives.
 - **Document highlighting.** Placing the cursor on a symbol highlights all other occurrences in the current file. Variables are scoped to their enclosing function or closure. Assignment targets, parameters, foreach bindings, and catch variables are marked as writes; all other occurrences are reads. Class names, members, functions, and constants highlight file-wide.
 
 ### Changed
@@ -45,6 +46,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - **`(new Canvas())->easel` property access.** Parenthesized `new` expressions on the left side of `->` now resolve correctly for variable type inference.
 - **Array function resolution.** `array_pop`, `array_filter`, `array_values`, `end`, and `array_map` now resolve element types correctly when the array comes from a method call chain or property access.
 - **Hover on variable definition sites.** Hovering a parameter, foreach binding, or catch variable no longer shows a redundant popup when the type is already visible in the signature. Assignment variables still show their resolved type.
+- **Inline `@var` annotations no longer leak across scopes.** A `/** @var Type $var */` annotation in one method no longer affects hover or completion for a same-named variable in a different method or class.
+- **Docblock tag parsing in description text.** Tags like `@throws` appearing mid-sentence in docblock descriptions (e.g. `"filtered out of @throws suggestions."`) are no longer mistakenly parsed as tags. Only `@` at a valid tag position (after the `* ` line prefix) is recognized.
 
 ## [0.4.0] - 2026-03-01
 

docs/todo/diagnostics.md

@@ -11,7 +11,7 @@ within the same impact tier.
 ---
 
 ## 2. Resolution-failure diagnostics
-**Impact: Medium · Effort: Medium**
+**Impact: Medium · Effort: Medium** *(partially done — unresolved class/interface implemented)*
 
 Report diagnostics only for symbols and types that PHPantom's own engine
 failed to resolve. This is **not** a general PHP linter — we don't check
@@ -34,7 +34,7 @@ unresolved types (the code may still run fine) and **Hint** or
 
 | Diagnostic | Trigger | Severity | Example |
 |---|---|---|---|
-| Unresolved class/interface | A type hint, `extends`, `implements`, `new`, or `::` reference that `find_or_load_class` cannot resolve after all phases (ast_map → classmap → PSR-4 → stubs) | Warning | `Class 'App\Foo' not found` |
+| ✅ Unresolved class/interface | A type hint, `extends`, `implements`, `new`, or `::` reference that `find_or_load_class` cannot resolve after all phases (ast_map → classmap → PSR-4 → stubs) | Warning | `Class 'App\Foo' not found` | *Done — `diagnostics::unknown_classes` module* |
 | Unresolved function | A function call that `find_or_load_function` cannot resolve (global functions, namespaced functions, stubs) | Warning | `Function 'do_thing' not found` |
 | Unresolved member access | `->method()` or `->property` on a type we *did* resolve, but the member doesn't exist after full resolution (inheritance + virtual providers) | Warning | `Method 'frobnicate' not found on class 'App\Bar'` |
 | Unresolved type in PHPDoc | A `@return`, `@param`, `@var`, `@throws`, `@mixin`, or `@extends` tag references a class that cannot be resolved | Information | `Type 'SomeAlias' in @return could not be resolved` |

example.php

@@ -1767,6 +1767,14 @@ public function toArray(): array { return []; }
 
 
 
+// ── Diagnostic: Unknown Class ───────────────────────────────────────────────
+// `MutateArrayInsertSpec` and `Cluster` below are not imported and cannot be
+// resolved — they get a yellow "Class 'X' not found" warning underline.
+// This diagnostic fires for any ClassReference that PHPantom cannot resolve
+// through use-map, local classes, same-namespace, class_index, classmap,
+// PSR-4, or stubs.  It pairs with the "Import Class" code action: press
+// Ctrl+. (Cmd+. on Mac) on the warning to import the class in one step.
+
 // ── Code Action: Import Class ───────────────────────────────────────────────
 // Place cursor on `MutateArrayInsertSpec` and press Ctrl+. (or Cmd+. on Mac)
 // to see "Import `Couchbase\MutateArrayInsertSpec`" in the quick-fix menu.

src/code_actions/import_class.rs

@@ -11,6 +11,7 @@ use tower_lsp::lsp_types::*;
 
 use crate::Backend;
 use crate::completion::use_edit::{analyze_use_block, build_use_edit, use_import_conflicts};
+use crate::diagnostics::unknown_classes::UNKNOWN_CLASS_CODE;
 
 use crate::symbol_map::SymbolKind;
 use crate::util::short_name;
@@ -120,6 +121,23 @@ impl Backend {
                 Err(_) => continue,
             };
 
+            // Find any unknown_class diagnostics from the request context
+            // that overlap this span so we can attach them to the code
+            // action.  This lets editors show the import action as a
+            // quick-fix for the diagnostic.
+            let matching_diagnostics: Vec<Diagnostic> = params
+                .context
+                .diagnostics
+                .iter()
+                .filter(|d| {
+                    matches!(
+                        &d.code,
+                        Some(NumberOrString::String(code)) if code == UNKNOWN_CLASS_CODE
+                    )
+                })
+                .cloned()
+                .collect();
+
             for fqn in &candidates {
                 // Skip candidates that would conflict with an existing
                 // import (e.g. a different class with the same short name
@@ -142,7 +160,11 @@ impl Backend {
                 out.push(CodeActionOrCommand::CodeAction(CodeAction {
                     title,
                     kind: Some(CodeActionKind::QUICKFIX),
-                    diagnostics: None,
+                    diagnostics: if matching_diagnostics.is_empty() {
+                        None
+                    } else {
+                        Some(matching_diagnostics.clone())
+                    },
                     edit: Some(WorkspaceEdit {
                         changes: Some(changes),
                         document_changes: None,

src/diagnostics/mod.rs

@@ -8,8 +8,12 @@
 //!   strikethrough in most editors).
 //! - **Unused `use` dimming** — dim `use` declarations that are not
 //!   referenced anywhere in the file with `DiagnosticTag::Unnecessary`.
+//! - **Unknown class diagnostics** — report `ClassReference` spans that
+//!   cannot be resolved through any resolution phase (use-map, local
+//!   classes, same-namespace, class_index, classmap, PSR-4, stubs).
 
 mod deprecated;
+pub(crate) mod unknown_classes;
 mod unused_imports;
 
 use tower_lsp::lsp_types::*;
@@ -59,6 +63,9 @@ impl Backend {
         // ── Unused `use` dimming ────────────────────────────────────────
         self.collect_unused_import_diagnostics(uri_str, content, &mut diagnostics);
 
+        // ── Unknown class references ────────────────────────────────────
+        self.collect_unknown_class_diagnostics(uri_str, content, &mut diagnostics);
+
         client.publish_diagnostics(uri, diagnostics, None).await;
     }