Ignore invalid PHPDoc types

Author: AJenbo

docs/CHANGELOG.md

@@ -10,9 +10,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Added
 
 - **Semantic Tokens.** Type-aware syntax highlighting that goes beyond what a TextMate grammar can achieve. Classes, interfaces, enums, traits, methods, properties, parameters, variables, functions, constants, and template parameters all get distinct token types. Modifiers convey declaration sites, static access, readonly, deprecated, and abstract status.
-- **Inlay hints.** Parameter name and by-reference indicators appear at call sites (`textDocument/inlayHint`). Hints are suppressed when the argument already makes the parameter obvious: variable names matching the parameter, property accesses with a matching trailing identifier, string literals whose content matches, well-known single-parameter functions like `count` and `strlen`, and spread arguments. Named arguments never receive a redundant hint.
+- **Inlay hints.** Parameter name and by-reference indicators appear at call sites (`textDocument/inlayHint`). Hints are suppressed when the argument already makes the parameter obvious: variable names matching the parameter, property accesses with a matching trailing identifier, string literals whose content matches, well-known single-parameter functions like `count` and `strlen`, and spread arguments. Named arguments never receive a redundant hint. Mixed positional and named argument ordering is handled correctly.
 - **PHPStan diagnostics.** PHPStan errors appear inline as you edit, using PHPStan's editor mode (`--tmp-file` / `--instead-of`). Auto-detects `vendor/bin/phpstan` or `$PATH`. Runs in a dedicated background worker with a 2-second debounce and at most one process at a time, so native diagnostics are never blocked. Configurable via `[phpstan]` in `.phpantom.toml` (`command`, `memory-limit`, `timeout`). "Ignore PHPStan error" and "Remove unnecessary @phpstan-ignore" code actions manage inline ignore comments.
-- **Formatting.** Built-in PHP formatting via mago-formatter (PER-CS 2.0 style). Formatting works out of the box without any external tools. Projects that depend on php-cs-fixer or PHP_CodeSniffer in their `composer.json` `require-dev` automatically use those tools instead (both can run in sequence). Per-tool command overrides and disable switches in `[formatting]` in `.phpantom.toml`.
+- **Formatting.** Built-in PHP formatting via mago-formatter (PER-CS 2.0 style). Formatting works out of the box without any external tools. Projects that depend on php-cs-fixer or PHP_CodeSniffer in their `composer.json` `require-dev` automatically use those tools instead (both can run in sequence). Per-tool command overrides and disable switches in `[formatting]` in `.phpantom.toml`. External formatters run without blocking completions or other requests.
 - **Document Symbols.** The outline sidebar and breadcrumbs now show classes, interfaces, traits, enums, methods, properties, constants, and standalone functions with correct nesting, icons, visibility detail, and deprecation tags.
 - **Workspace Symbols.** "Go to Symbol in Workspace" (Ctrl+T / Cmd+T) searches across all indexed files including vendor classes. Results include namespace context and deprecation markers, sorted by relevance.
 - **Type Hierarchy.** "Show Type Hierarchy" on any class, interface, trait, or enum reveals its supertypes and subtypes with full up-and-down navigation through the inheritance tree, including cross-file resolution and transitive relationships.
@@ -24,19 +24,13 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - **Implementation error diagnostic.** Concrete classes that fail to implement all required methods from their interfaces or abstract parents are now flagged with an Error-severity diagnostic on the class name. The existing "Implement missing methods" quick-fix appears inline alongside the error. Cyclic hierarchies are handled gracefully.
 - **Argument count diagnostic.** Flags function and method calls that pass too few or too many arguments. Variadic parameters and argument unpacking are handled correctly.
 - **Change visibility.** Code action on any method, property, constant, or promoted constructor parameter offers to change its visibility (`public`, `protected`, `private`).
-- **Update docblock.** Code action on a function or method whose existing docblock is out of sync with its signature. Adds missing `@param` tags, removes stale ones, reorders to match the signature, fixes contradicted types, and removes redundant `@return void`. Refinement types and unrelated tags are preserved.
+- **Update docblock.** Code action on a function or method whose existing docblock is out of sync with its signature. Adds missing `@param` tags, removes stale ones, reorders to match the signature, fixes contradicted types, and removes redundant `@return void`. Refinement types and unrelated tags are preserved. Handles `@param $name` (no type) correctly.
 - **PHPDoc block generation.** Typing `/**` above any declaration generates a docblock skeleton. Tags are only emitted when the native type hint needs enrichment. Properties and constants always get `@var`. Class-likes with templated parents or interfaces get `@extends`/`@implements` tags. Uncaught exceptions get `@throws` with auto-import. Works both via completion and on-type formatting.
 - **PHPDoc `@var` completion.** Inline `@var` above variable assignments sorts first and pre-fills the inferred type when available. Template parameters from `@template` enrich `@param`, `@return`, and `@var` type hints.
 - **File rename on class rename.** Renaming a class whose file follows PSR-4 naming now also renames the file to match. The file is only renamed when it contains a single class-like declaration and the editor supports file rename operations.
 - **`@see` and `@link` improvements.** `@see` references in docblocks now work with go-to-definition (class, member, and function forms). Hover popups show all `@link` and `@see` URLs as clickable links. Deprecation diagnostics include `@see` targets when the `@deprecated` docblock references them.
 - **Progress indicators.** Go to Implementation and Find References now show a progress indicator in the editor while scanning.
 
-### Fixed
-
-- **Double-dollar in docblock variable completion.** Typing `$` or `$va` after a type in a `@param` tag no longer produces `$$var` in editors like Helix and Neovim that do not treat `$` as a word character. Completions now replace the typed prefix in place.
-- **Closure and arrow function variable scope.** Variable name completion now correctly respects PHP scoping rules for anonymous functions and arrow functions. Parameters of a closure are visible inside its body, `use`-captured variables appear alongside them, and `$this` is available when the closure is defined in an instance method. Outer method locals that were not captured do not leak in. Arrow function parameters are now visible inside the arrow body while the enclosing scope's variables remain accessible, matching PHP's implicit capture behaviour.
-- **Namespace alias completion.** Typing a class name through a namespace alias (e.g. `OA\Re` with `use OpenApi\Attributes as OA`) now correctly suggests classes under the aliased namespace such as `OA\Response` and `OA\RequestBody`. Previously only unrelated classes matched because the alias was not expanded before prefix matching.
-
 ### Changed
 
 - **Pull diagnostics.** Diagnostics are now delivered via the LSP 3.17 pull model (`textDocument/diagnostic`) when the editor supports it. The editor requests diagnostics only for visible files, and cross-file invalidation uses `workspace/diagnostic/refresh` instead of recomputing every open tab. Clients without pull support fall back to the previous push model automatically.
@@ -47,23 +41,18 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Fixed
 
+- **Closure and arrow function variable scope.** Variable name completion now correctly respects PHP scoping rules for anonymous functions and arrow functions. Parameters of a closure are visible inside its body, `use`-captured variables appear alongside them, and `$this` is available when the closure is defined in an instance method. Outer method locals that were not captured do not leak in. Arrow function parameters are now visible inside the arrow body while the enclosing scope's variables remain accessible, matching PHP's implicit capture behaviour.
+- **Namespace alias completion.** Typing a class name through a namespace alias (e.g. `OA\Re` with `use OpenApi\Attributes as OA`) now correctly suggests classes under the aliased namespace such as `OA\Response` and `OA\RequestBody`. Previously only unrelated classes matched because the alias was not expanded before prefix matching.
 - **Virtual property merging.** Native type hints are now considered when determining virtual property specificity. Previously only docblock types were compared, causing properties with native PHP type declarations (e.g., `public string $name`) to be incorrectly overridden by less specific virtual properties.
+- **Native type override compatibility.** A docblock type only overrides a native type hint when it is a compatible refinement. For example, `class-string<Foo>` can refine `string` and `positive-int` can refine `int`, but `array<int>` no longer incorrectly overrides `string`. Previously any docblock type with generic parameters was accepted regardless of compatibility.
 - **PHPStan pseudo-type recognition.** Types like `non-positive-int`, `non-negative-int`, `non-zero-int`, `lowercase-string`, `truthy-string`, `callable-object`, and many other PHPStan pseudo-types are now recognized across the entire pipeline. Previously they could be misresolved as class names, flagged as contradictions in docblock updates, or missing from PHPDoc completion suggestions.
-- **PHPStan diagnostics.** Fixed a path matching false positive where files with similar name suffixes (e.g. `AFoo.php` vs `Foo.php`) could receive each other's PHPStan diagnostics.
-- **Update docblock action.** Docblocks containing `@param $name` with no type (e.g. `@param $name Some description`) are now parsed correctly. Previously the parameter name was consumed as the type token, causing the action to add a duplicate `@param mixed $name` tag.
 - **Rename updates imports.** Renaming a class now updates `use` statement FQNs (last segment only), preserves explicit aliases, and introduces an alias when the new name collides with an existing import in the same file. Previously, `use` statements were left unchanged, breaking the file.
 - **Trait alias go-to-definition.** Clicking a trait alias (e.g. `$this->__foo()` from `use Foo { foo as __foo; }`) now jumps to the trait method instead of the class's own same-named method.
-- **Diagnostics.** Enums that implement interfaces are now checked for missing methods, matching the existing behaviour for concrete classes. Scalar member access errors now detect method-return chains where an intermediate call returns a scalar type. By-reference `@param` annotations no longer produce a false "unknown class" diagnostic.
+- **Diagnostics.** Enums that implement interfaces are now checked for missing methods, matching the existing behaviour for concrete classes. Scalar member access errors now detect method-return chains where an intermediate call returns a scalar type. By-reference `@param` annotations no longer produce a false "unknown class" diagnostic. Duplicate diagnostics from different analysis phases are now reliably collapsed into a single entry per range. Deprecated-usage checks no longer block the instant diagnostic push.
 - **Hover on empty arrays.** `[]` and `array()` literals now show `array` on hover instead of nothing.
 - **Catch clause completion.** Throwable interfaces and abstract exception classes now appear in catch clause completions. Previously only concrete, non-abstract classes were offered.
-- **Inlay hints with named arguments.** Parameter name hints now map correctly when named and positional arguments are mixed. Previously, positional arguments were matched by their index in the argument list, so `greet(city: 'NYC', 'Alice')` would label `'Alice'` as `age:` instead of `name:`.
 - **Type-hint and PHPDoc completion.** Traits are now excluded from completions in parameter types, return types, property types, and PHPDoc type tags. `@throws` continues to use Throwable-filtered completion.
 - **Position encoding.** All LSP position conversions now correctly count UTF-16 code units, matching the LSP specification. Files containing emoji or supplementary Unicode characters no longer produce incorrect positions for completions, hover, go-to-definition, references, highlights, or code actions.
-- **Deprecated-usage diagnostics.** Deprecated-usage checks no longer block the instant Phase 1 diagnostic push. They now run in Phase 2 (slow) alongside other type-resolution-dependent checks, so syntax errors and unused-import warnings appear without delay.
-- **Formatting responsiveness.** The formatting handler no longer blocks the async runtime while waiting for external tools. Completion, hover, and other requests remain responsive while php-cs-fixer or PHP_CodeSniffer runs.
-- **PHPStan stale diagnostics.** Closing a file while PHPStan is running no longer leaves stale diagnostics in the cache. Previously the PHPStan worker could finish and write results back after the cache was cleared, causing old diagnostics to reappear on the next open.
-- **Graceful shutdown.** Background workers (diagnostic, PHPStan) now stop promptly when the editor closes. Previously, a running PHPStan process could continue consuming CPU and memory for up to 60 seconds after shutdown.
-- **Diagnostic deduplication.** Duplicate diagnostics from different analysis phases (fast, slow, PHPStan) are now reliably collapsed into a single entry per range. Previously, non-adjacent duplicates could survive because the dedup pass only removed consecutive matches, and diagnostics with different wording but the same range were treated as distinct.
 
 ## [0.5.0] - 2026-03-12
 

docs/todo/bugs.md

@@ -101,5 +101,3 @@ on by default.
 - `src/config.rs` — new field + accessor + default config comment.
 - `src/diagnostics/argument_count.rs` — gate the too-many block.
 - `tests/` — update or add tests asserting the default-off behaviour.
-
----

src/code_actions/update_docblock.rs

@@ -24,6 +24,7 @@ use tower_lsp::lsp_types::*;
 use crate::Backend;
 use crate::completion::phpdoc::generation::enrichment_plain;
 use crate::completion::source::throws_analysis;
+use crate::docblock::is_compatible_refinement;
 use crate::docblock::type_strings::split_type_token;
 use crate::types::ClassInfo;
 use crate::util::offset_to_position;
@@ -728,26 +729,22 @@ fn is_type_contradiction(doc_type: &str, native_type: &str) -> bool {
         return false;
     }
 
-    // If the docblock type carries generics or callable signatures, it's
-    // likely a refinement.
-    if doc_type.contains('<') || doc_type.contains('{') || doc_type.contains('(') {
-        // Check that the base type is compatible.
-        let doc_base = base_type(doc_type).to_lowercase();
-        let native_base = base_type(native_type).to_lowercase();
-        if doc_base == native_base {
-            return false;
-        }
-        // `list<X>` refines `array`.
-        if native_base == "array" && (doc_base == "list" || doc_base == "array") {
-            return false;
-        }
-    }
-
-    // PHPStan-style type refinements like `non-empty-string`, `positive-int`,
-    // `class-string`, `literal-string`, etc. are refinements, not contradictions.
-    let doc_lower = doc_type.to_lowercase();
-    let native_lower = native_type.to_lowercase();
-    if is_refinement_of(&doc_lower, &native_lower) {
+    // Check whether the docblock type is a compatible refinement of the
+    // native type (e.g. `class-string<Foo>` refines `string`,
+    // `list<User>` refines `array`, `positive-int` refines `int`).
+    // This uses the shared refinement checker that also guards
+    // `resolve_effective_type`.
+    let native_stripped = native_type
+        .strip_prefix('\\')
+        .unwrap_or(native_type)
+        .strip_prefix('?')
+        .unwrap_or(native_type.strip_prefix('\\').unwrap_or(native_type));
+    let doc_stripped = doc_type
+        .strip_prefix('\\')
+        .unwrap_or(doc_type)
+        .strip_prefix('?')
+        .unwrap_or(doc_type.strip_prefix('\\').unwrap_or(doc_type));
+    if is_compatible_refinement(doc_stripped, &native_stripped.to_ascii_lowercase()) {
         return false;
     }
 
@@ -766,7 +763,7 @@ fn is_type_contradiction(doc_type: &str, native_type: &str) -> bool {
     if doc_bases.len() == 1 && native_bases.len() == 1 {
         let db = &doc_bases[0];
         let nb = &native_bases[0];
-        if db != nb && !is_refinement_of(db, nb) {
+        if db != nb && !is_compatible_refinement(db, nb) {
             return true;
         }
     }
@@ -788,68 +785,6 @@ fn normalize_type_for_comparison(t: &str) -> String {
     parts.join("|")
 }
 
-/// Get the base type (before `<` or `{`).
-fn base_type(t: &str) -> &str {
-    let t = t.strip_prefix('\\').unwrap_or(t);
-    let t = t.strip_prefix('?').unwrap_or(t);
-    if let Some(pos) = t.find('<') {
-        &t[..pos]
-    } else if let Some(pos) = t.find('{') {
-        &t[..pos]
-    } else {
-        t
-    }
-}
-
-/// Check if `doc_type` is a known refinement of `native_type`.
-fn is_refinement_of(doc_type: &str, native_type: &str) -> bool {
-    let refinements: &[(&str, &str)] = &[
-        ("non-empty-string", "string"),
-        ("non-falsy-string", "string"),
-        ("numeric-string", "string"),
-        ("literal-string", "string"),
-        ("class-string", "string"),
-        ("callable-string", "string"),
-        ("truthy-string", "string"),
-        ("lowercase-string", "string"),
-        ("uppercase-string", "string"),
-        ("non-empty-lowercase-string", "string"),
-        ("non-empty-uppercase-string", "string"),
-        ("non-empty-literal-string", "string"),
-        ("interface-string", "string"),
-        ("trait-string", "string"),
-        ("enum-string", "string"),
-        ("positive-int", "int"),
-        ("negative-int", "int"),
-        ("non-negative-int", "int"),
-        ("non-positive-int", "int"),
-        ("non-zero-int", "int"),
-        ("int-mask", "int"),
-        ("int-mask-of", "int"),
-        ("non-empty-array", "array"),
-        ("non-empty-list", "array"),
-        ("list", "array"),
-        ("associative-array", "array"),
-        ("callable-array", "array"),
-        ("callable-object", "object"),
-        ("closed-resource", "resource"),
-        ("open-resource", "resource"),
-    ];
-    for &(refined, base) in refinements {
-        // Handle both `doc_type` directly matching and `doc_type` having
-        // generic params (e.g. `class-string<foo>`).
-        let doc_base = if let Some(pos) = doc_type.find('<') {
-            &doc_type[..pos]
-        } else {
-            doc_type
-        };
-        if doc_base == refined && native_type == base {
-            return true;
-        }
-    }
-    false
-}
-
 /// Split a union type string into its components.
 fn split_union_types(t: &str) -> Vec<String> {
     t.split('|')

src/docblock/mod.rs

@@ -44,6 +44,7 @@ pub(crate) mod type_strings;
 // working without modification.
 
 // Core tags
+pub(crate) use tags::is_compatible_refinement;
 pub use tags::{
     extract_all_param_tags, extract_deprecation_message, extract_deprecation_with_see,
     extract_link_urls, extract_mixin_tags, extract_param_closure_this, extract_param_description,