Include virtual member references for nullable/union types

Author: AJenbo

docs/CHANGELOG.md

@@ -40,7 +40,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - **Machine-readable CLI output.** Both `analyze` and `fix` accept a `--format` flag with `table`, `github`, and `json` options. When `GITHUB_ACTIONS` is set, table output automatically includes GitHub annotations.
 - **Magic property diagnostics.** New `report-magic-properties` option under `[diagnostics]` in `.phpantom.toml`. When enabled, classes with `__get` that also have virtual properties (from `@property` docblock tags, Laravel Eloquent column inference, or other providers) will flag unknown property access instead of silently allowing it.
 - **Inline diagnostic suppression.** `// @phpantom-ignore code` on the same line or the line above suppresses the specified diagnostic. Multiple codes can be comma-separated. A bare `// @phpantom-ignore` suppresses all diagnostics on the target line.
-- **Find references and rename for PHPDoc virtual members.** `@property`, `@property-read`, `@property-write`, and `@method` declarations in docblocks are now included in find-references and rename results alongside their runtime usages. (thanks @AbyssWaIker)
+- **Find references and rename for PHPDoc virtual members.** `@property`, `@property-read`, `@property-write`, and `@method` declarations in docblocks are now included in find-references and rename results alongside their runtime usages, including when the subject has a nullable or union type (e.g. `Foo|null` from `->first()`). (thanks @AbyssWaIker)
 
 ### Changed
 

src/references/mod.rs

@@ -151,6 +151,7 @@ impl Backend {
                 // so we only return references on related classes.
                 let hierarchy =
                     self.resolve_member_access_hierarchy(uri, subject_text, *is_static, span_start);
+
                 self.find_member_references(
                     member_name,
                     *is_static,
@@ -1086,10 +1087,12 @@ impl Backend {
     ) -> Vec<String> {
         let class_loader = self.class_loader(ctx);
         let function_loader = self.function_loader(ctx);
-        let ctx = crate::subject_resolution::SubjectResolutionCtx {
+        let use_map = &ctx.use_map;
+        let namespace = &ctx.namespace;
+        let resolution_ctx = crate::subject_resolution::SubjectResolutionCtx {
             local_classes: &ctx.classes,
-            use_map: &ctx.use_map,
-            namespace: &ctx.namespace,
+            use_map,
+            namespace,
             content,
             class_loader: &class_loader,
             function_loader: &function_loader,
@@ -1099,12 +1102,25 @@ impl Backend {
             subject_text,
             is_static,
             access_offset,
-            &ctx,
+            &resolution_ctx,
         ) {
             Some(php_type) => php_type
                 .top_level_class_names()
                 .into_iter()
-                .map(|n| normalize_fqn(&n))
+                .map(|n| {
+                    let normalized = normalize_fqn(&n);
+                    // top_level_class_names() may return short names
+                    // (e.g. "BlogAuthor" instead of
+                    // "App\Models\BlogAuthor").  Resolve them through
+                    // the file's use-map and namespace so they match
+                    // the FQNs used in the hierarchy set.
+                    if normalized.contains('\\') {
+                        normalized.to_string()
+                    } else {
+                        normalize_fqn(&Self::resolve_to_fqn(&normalized, use_map, namespace))
+                            .to_string()
+                    }
+                })
                 .collect(),
             None => Vec::new(),
         }

tests/integration/references.rs

@@ -1579,3 +1579,152 @@ class Cart {
 
     assert_no_duplicates(&results, "one_file_method_refs");
 }
+
+// ─── Nullable / union type member references ────────────────────────────────
+
+/// Find references on a @property-read member via a nullable variable
+/// should include the @property-read declaration and non-nullable usages.
+#[test]
+fn member_references_nullable_type_virtual_property() {
+    let backend = create_test_backend();
+    let uri = "file:///tmp/test_refs_nullable_virtual.php";
+    let content = r#"<?php
+
+/**
+ * @property-read string $displayName
+ */
+class Author {
+    public function __get(string $name): mixed { return null; }
+
+    /** @return static|null */
+    public static function first(): ?static { return null; }
+}
+
+function test(): void {
+    $found = Author::first();
+    echo $found->displayName;
+
+    $author = new Author();
+    echo $author->displayName;
+}
+"#;
+
+    open_file(&backend, uri, content);
+
+    // Cursor on `displayName` in `$found->displayName` (line 14)
+    let results = backend
+        .find_references(uri, content, Position::new(14, 18), true)
+        .expect("should find references");
+
+    assert_no_duplicates(&results, "nullable_virtual_prop_refs");
+
+    for (i, loc) in results.iter().enumerate() {
+        eprintln!(
+            "  [{}] {}:{}:{}-{}:{}",
+            i,
+            loc.uri,
+            loc.range.start.line,
+            loc.range.start.character,
+            loc.range.end.line,
+            loc.range.end.character,
+        );
+    }
+
+    // Expect: 1 @property-read declaration + 2 accesses ($found->displayName, $author->displayName)
+    assert_eq!(
+        results.len(),
+        3,
+        "Expected 3 references (1 @property-read declaration + 2 accesses), got {}: {:#?}",
+        results.len(),
+        results
+    );
+}
+
+/// Cross-file find references on a @property-read member via a nullable
+/// variable should include the declaration and non-nullable usages from other files.
+#[test]
+fn cross_file_member_references_nullable_virtual_property() {
+    let (backend, _dir) = crate::common::create_psr4_workspace(
+        r#"{
+            "autoload": {
+                "psr-4": {
+                    "App\\": "src/"
+                }
+            }
+        }"#,
+        &[
+            (
+                "src/Author.php",
+                r#"<?php
+namespace App;
+
+/**
+ * @property-read string $displayName
+ */
+class Author {
+    public function __get(string $name): mixed { return null; }
+
+    /** @return static|null */
+    public static function first(): ?static { return null; }
+}
+"#,
+            ),
+            (
+                "src/Service.php",
+                r#"<?php
+namespace App;
+
+class Service {
+    public function test(): void {
+        $found = Author::first();
+        echo $found->displayName;
+
+        $author = new Author();
+        echo $author->displayName;
+    }
+}
+"#,
+            ),
+        ],
+    );
+
+    let author_path = _dir.path().join("src/Author.php");
+    let service_path = _dir.path().join("src/Service.php");
+
+    let author_uri = format!("file://{}", author_path.display());
+    let service_uri = format!("file://{}", service_path.display());
+
+    let author_content = std::fs::read_to_string(&author_path).unwrap();
+    let service_content = std::fs::read_to_string(&service_path).unwrap();
+
+    open_file(&backend, &author_uri, &author_content);
+    open_file(&backend, &service_uri, &service_content);
+
+    // Cursor on `displayName` in `$found->displayName` (line 6 in Service.php)
+    let results = backend
+        .find_references(&service_uri, &service_content, Position::new(6, 22), true)
+        .expect("should find references");
+
+    assert_no_duplicates(&results, "cross_file_nullable_virtual_prop_refs");
+
+    for (i, loc) in results.iter().enumerate() {
+        eprintln!(
+            "  [{}] {}:{}:{}-{}:{}",
+            i,
+            loc.uri,
+            loc.range.start.line,
+            loc.range.start.character,
+            loc.range.end.line,
+            loc.range.end.character,
+        );
+    }
+
+    // Expect: 1 @property-read declaration in Author.php + 2 accesses in Service.php
+    assert_eq!(
+        results.len(),
+        3,
+        "Expected 3 references (1 @property-read declaration + 2 accesses), got {}: {:#?}",
+        results.len(),
+        results
+    );
+}