False-positive unknown-class warnings on PHPStan type syntax

Author: AJenbo

docs/CHANGELOG.md

@@ -39,6 +39,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - **Sequential assert narrowing.** Multiple `assert($x instanceof A); assert($x instanceof B);` statements now accumulate, showing members from both types. Previously only the last assertion's narrowing applied.
 - **`instanceof` narrowing no longer widens specific types.** `assert($zoo instanceof ZooBase)` after `$zoo = new Zoo()` (where `Zoo extends ZooBase`) no longer replaces the type with the less-specific parent. The narrower `Zoo` type is preserved because it already satisfies the check. Previously this produced false-positive "unknown member" warnings for `@property` and `@method` members declared on the child class.
 - **Arrow function parameter completion with incomplete expressions.** Typing `$foo->` inside an arrow function body (e.g. `fn(Foo $foo) => $foo->`) now resolves the parameter type even when the expression is incomplete. The parser recovery inserts a dummy token so the surrounding arrow function structure is recognized.
+- **False-positive unknown-class warnings on PHPStan type syntax.** String literals in conditional return types (`$param is "foo" ? A : B`), numeric literals, and variance annotations on generic arguments (`Collection<int, covariant array{...}>`) no longer trigger "Class not found" warnings.
 
 
 - **Project configuration.** PHPantom now reads a `.phpantom.toml` file from the project root (next to `composer.json`) for per-project settings. Currently supports `[php] version` to override the detected PHP version, and `[diagnostics] unresolved-member-access` to enable the new unresolved member access diagnostic. Run `phpantom --init` to generate a default config file with all options commented out. When the file is missing, all settings use their defaults. Parse errors are reported as a warning in the editor.

src/diagnostics/unknown_classes.rs

@@ -855,4 +855,145 @@ mod tests {
             diags.iter().map(|d| &d.message).collect::<Vec<_>>()
         );
     }
+
+    #[test]
+    fn no_diagnostic_for_string_literal_in_conditional_return() {
+        let backend = Backend::new_test();
+        let uri = "file:///test.php";
+        let content = concat!(
+            "<?php\n",
+            "namespace App;\n",
+            "\n",
+            "class Mapper {\n",
+            "    /**\n",
+            "     * @return ($signature is \"foo\" ? Pen : Marker)\n",
+            "     */\n",
+            "    public function map(string $signature): Pen|Marker {\n",
+            "        return new Pen();\n",
+            "    }\n",
+            "}\n",
+            "class Pen {}\n",
+            "class Marker {}\n",
+        );
+
+        let diags = collect(&backend, uri, content);
+        assert!(
+            !diags.iter().any(|d| d.message.contains("\"foo\"")),
+            "should not flag string literal '\"foo\"' as unknown class, got: {:?}",
+            diags.iter().map(|d| &d.message).collect::<Vec<_>>()
+        );
+    }
+
+    #[test]
+    fn no_diagnostic_for_single_quoted_literal_in_conditional_return() {
+        let backend = Backend::new_test();
+        let uri = "file:///test.php";
+        let content = concat!(
+            "<?php\n",
+            "namespace App;\n",
+            "\n",
+            "class Mapper {\n",
+            "    /**\n",
+            "     * @return ($sig is 'bar' ? Pen : Marker)\n",
+            "     */\n",
+            "    public function map(string $sig): Pen|Marker {\n",
+            "        return new Pen();\n",
+            "    }\n",
+            "}\n",
+            "class Pen {}\n",
+            "class Marker {}\n",
+        );
+
+        let diags = collect(&backend, uri, content);
+        assert!(
+            !diags.iter().any(|d| d.message.contains("'bar'")),
+            "should not flag single-quoted literal as unknown class, got: {:?}",
+            diags.iter().map(|d| &d.message).collect::<Vec<_>>()
+        );
+    }
+
+    #[test]
+    fn no_diagnostic_for_numeric_literal_in_conditional_return() {
+        let backend = Backend::new_test();
+        let uri = "file:///test.php";
+        let content = concat!(
+            "<?php\n",
+            "namespace App;\n",
+            "\n",
+            "class Mapper {\n",
+            "    /**\n",
+            "     * @return ($count is 0 ? EmptyList : FullList)\n",
+            "     */\n",
+            "    public function get(int $count): EmptyList|FullList {\n",
+            "        return new EmptyList();\n",
+            "    }\n",
+            "}\n",
+            "class EmptyList {}\n",
+            "class FullList {}\n",
+        );
+
+        let diags = collect(&backend, uri, content);
+        assert!(
+            !diags.iter().any(|d| d.message.contains("0")),
+            "should not flag numeric literal as unknown class, got: {:?}",
+            diags.iter().map(|d| &d.message).collect::<Vec<_>>()
+        );
+    }
+
+    #[test]
+    fn no_diagnostic_for_covariant_variance_annotation() {
+        let backend = Backend::new_test();
+        let uri = "file:///test.php";
+        let content = concat!(
+            "<?php\n",
+            "namespace App;\n",
+            "\n",
+            "class Collection {}\n",
+            "class Customer {}\n",
+            "class Contact {}\n",
+            "\n",
+            "class Repo {\n",
+            "    /**\n",
+            "     * @return Collection<int, covariant array{customer: Customer, contact: Contact|null}>\n",
+            "     */\n",
+            "    public function getAll(): Collection {\n",
+            "        return new Collection();\n",
+            "    }\n",
+            "}\n",
+        );
+
+        let diags = collect(&backend, uri, content);
+        assert!(
+            !diags.iter().any(|d| d.message.contains("covariant")),
+            "should not flag 'covariant array' as unknown class, got: {:?}",
+            diags.iter().map(|d| &d.message).collect::<Vec<_>>()
+        );
+    }
+
+    #[test]
+    fn no_diagnostic_for_contravariant_variance_annotation() {
+        let backend = Backend::new_test();
+        let uri = "file:///test.php";
+        let content = concat!(
+            "<?php\n",
+            "namespace App;\n",
+            "\n",
+            "class Handler {}\n",
+            "\n",
+            "class Processor {\n",
+            "    /**\n",
+            "     * @param Consumer<contravariant Handler> $consumer\n",
+            "     */\n",
+            "    public function run($consumer): void {}\n",
+            "}\n",
+            "class Consumer {}\n",
+        );
+
+        let diags = collect(&backend, uri, content);
+        assert!(
+            !diags.iter().any(|d| d.message.contains("contravariant")),
+            "should not flag 'contravariant Handler' as unknown class, got: {:?}",
+            diags.iter().map(|d| &d.message).collect::<Vec<_>>()
+        );
+    }
 }

src/symbol_map/docblock.rs

@@ -537,6 +537,44 @@ pub(super) fn emit_type_spans(
         return;
     }
 
+    // ── Skip string literals ────────────────────────────────────────
+    // PHPStan conditional return types allow literal strings as the
+    // condition value, e.g. `($sig is "foo" ? A : B)`.  These are not
+    // class names and must not produce ClassReference spans.
+    if (type_name.starts_with('"') && type_name.ends_with('"'))
+        || (type_name.starts_with('\'') && type_name.ends_with('\''))
+    {
+        return;
+    }
+
+    // ── Skip numeric literals ───────────────────────────────────────
+    // Literal integers/floats (e.g. `123`, `-1`, `3.14`) can appear in
+    // conditional types and const expressions.  They are not class names.
+    if type_name
+        .strip_prefix('-')
+        .unwrap_or(type_name)
+        .starts_with(|c: char| c.is_ascii_digit())
+    {
+        return;
+    }
+
+    // ── Strip PHPStan variance annotations ──────────────────────────
+    // Generic type arguments may carry a variance prefix, e.g.
+    // `Collection<int, covariant array{customer: Customer}>`.
+    // Strip the prefix and adjust the offset so the underlying type is
+    // processed correctly.
+    let (type_name, extra_offset) = if let Some(rest) = type_name.strip_prefix("covariant ") {
+        (rest, extra_offset + "covariant ".len() as u32)
+    } else if let Some(rest) = type_name.strip_prefix("contravariant ") {
+        (rest, extra_offset + "contravariant ".len() as u32)
+    } else {
+        (type_name, extra_offset)
+    };
+
+    if type_name.is_empty() {
+        return;
+    }
+
     // Handle `$this` as a self-reference (equivalent to `static`).
     if type_name == "$this" {
         let start = token_file_offset + extra_offset;