Support go-to-definition for @see tags in floating docblocks

Author: AJenbo

docs/CHANGELOG.md

@@ -56,6 +56,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - **Scope methods missing from completion on relationship results.** Scope methods from related models now appear in completions, not just hover.
 - **Closure and variable hover now preserves generic arguments.** Closure parameters inferred from callable signatures, variables assigned from chained methods returning `static`/`$this`/`self`, and hovering on the `$` sign of a variable at its assignment site all now show the correct generic type.
 - **Callable parameter inference preserves generic arguments from the receiver.** A closure typed as `fn(Builder $q)` inside a `Builder<Product>` chain now infers `$q` as `Builder<Product>`, so model-specific scope methods resolve correctly.
+- **`@see` tags in floating docblocks now support go-to-definition.** Docblock comments not directly attached to a class, function, or statement (e.g. inline `/** @see SupervisorOptions::$balanceCooldown */` inside array literals or after expressions) are now parsed for symbol references. Previously these were silently ignored, particularly in files without a namespace.
 - **Nullable `static` return types on inherited methods.** Methods returning `?static` or `static|null` now correctly resolve to the calling subclass across files.
 - **Template binding with nested generics.** Parameter types like `Wrapper<Collection<T>, V>` no longer break during template binding.
 - **Single generic argument on collections bound to the wrong template parameter.** `Collection<User>` now binds to the value parameter instead of the key parameter when key-like template parameters precede value parameters.

src/symbol_map/extraction.rs

@@ -91,6 +91,19 @@ pub(crate) fn extract_symbol_map(program: &Program<'_>, content: &str) -> Symbol
         extract_from_statement(stmt, &mut ctx, 0);
     }
 
+    // ── Sweep all docblock trivia for floating references ───────────
+    // Docblocks attached to classes, functions, methods, properties, and
+    // certain statements are already processed during the AST walk above.
+    // However, docblocks in other positions (e.g. inline `/** @see ... */`
+    // inside array literals or after expressions) are never visited.
+    // Scan every docblock trivia entry and extract symbols; the dedup
+    // step below removes any duplicates from already-processed docblocks.
+    for t in program.trivia.iter() {
+        if t.kind == TriviaKind::DocBlockComment {
+            let _tpl = extract_docblock_symbols(t.value, t.span.start.offset, &mut ctx.spans);
+        }
+    }
+
     // Sort by start offset for binary search.
     ctx.spans.sort_by_key(|s| s.start);
 

tests/integration/definition_members.rs

@@ -3821,3 +3821,234 @@ async fn test_goto_definition_trait_alias_original_name_when_class_overrides() {
         other => panic!("Expected Scalar location, got: {:?}", other),
     }
 }
+
+// ─── @see Tag GTD in Floating Docblocks ─────────────────────────────────────
+
+#[tokio::test]
+async fn test_goto_definition_see_tag_in_array_no_namespace() {
+    // Regression: @see tags in floating docblocks (e.g. inside array
+    // literals, in files without a namespace) were not parsed because
+    // the docblock wasn't attached to any AST node.
+    let backend = create_test_backend();
+
+    let uri = Url::parse("file:///test_see_array.php").unwrap();
+    // Line 0: <?php
+    // Line 1: class SupervisorOptions {
+    // Line 2:     public int $balanceCooldown = 3;
+    // Line 3: }
+    // Line 4: $defaults = [
+    // Line 5:     'balanceCooldown' => 3, /** @see SupervisorOptions::$balanceCooldown */
+    // Line 6: ];
+    let text = concat!(
+        "<?php\n",
+        "class SupervisorOptions {\n",
+        "    public int $balanceCooldown = 3;\n",
+        "}\n",
+        "$defaults = [\n",
+        "    'balanceCooldown' => 3, /** @see SupervisorOptions::$balanceCooldown */\n",
+        "];\n",
+    );
+
+    let open_params = DidOpenTextDocumentParams {
+        text_document: TextDocumentItem {
+            uri: uri.clone(),
+            language_id: "php".to_string(),
+            version: 1,
+            text: text.to_string(),
+        },
+    };
+    backend.did_open(open_params).await;
+
+    // Click on "SupervisorOptions" in the @see tag (line 5)
+    let params = GotoDefinitionParams {
+        text_document_position_params: TextDocumentPositionParams {
+            text_document: TextDocumentIdentifier { uri: uri.clone() },
+            position: Position {
+                line: 5,
+                character: 40, // within "SupervisorOptions"
+            },
+        },
+        work_done_progress_params: WorkDoneProgressParams::default(),
+        partial_result_params: PartialResultParams::default(),
+    };
+
+    let result = backend.goto_definition(params).await.unwrap();
+    assert!(
+        result.is_some(),
+        "Should resolve @see class reference in floating docblock inside array literal"
+    );
+
+    match result.unwrap() {
+        GotoDefinitionResponse::Scalar(location) => {
+            assert_eq!(
+                location.range.start.line, 1,
+                "SupervisorOptions is defined on line 1"
+            );
+        }
+        other => panic!("Expected Scalar location, got: {:?}", other),
+    }
+
+    // Click on "$balanceCooldown" in the @see tag (line 5)
+    let params = GotoDefinitionParams {
+        text_document_position_params: TextDocumentPositionParams {
+            text_document: TextDocumentIdentifier { uri: uri.clone() },
+            position: Position {
+                line: 5,
+                character: 62, // within "$balanceCooldown"
+            },
+        },
+        work_done_progress_params: WorkDoneProgressParams::default(),
+        partial_result_params: PartialResultParams::default(),
+    };
+
+    let result = backend.goto_definition(params).await.unwrap();
+    assert!(
+        result.is_some(),
+        "Should resolve @see member reference in floating docblock inside array literal"
+    );
+
+    match result.unwrap() {
+        GotoDefinitionResponse::Scalar(location) => {
+            assert_eq!(
+                location.range.start.line, 2,
+                "$balanceCooldown property is defined on line 2"
+            );
+        }
+        other => panic!("Expected Scalar location, got: {:?}", other),
+    }
+}
+
+#[tokio::test]
+async fn test_goto_definition_see_tag_inline_in_expression() {
+    // A floating /** @see ... */ after an expression statement, not
+    // attached to any class or function.
+    let backend = create_test_backend();
+
+    let uri = Url::parse("file:///test_see_inline.php").unwrap();
+    // Line 0: <?php
+    // Line 1: class Config {
+    // Line 2:     public string $timeout = '30';
+    // Line 3: }
+    // Line 4:
+    // Line 5: $timeout = 30; /** @see Config::$timeout */
+    let text = concat!(
+        "<?php\n",
+        "class Config {\n",
+        "    public string $timeout = '30';\n",
+        "}\n",
+        "\n",
+        "$timeout = 30; /** @see Config::$timeout */\n",
+    );
+
+    let open_params = DidOpenTextDocumentParams {
+        text_document: TextDocumentItem {
+            uri: uri.clone(),
+            language_id: "php".to_string(),
+            version: 1,
+            text: text.to_string(),
+        },
+    };
+    backend.did_open(open_params).await;
+
+    // Click on "Config" in the @see tag (line 5)
+    let params = GotoDefinitionParams {
+        text_document_position_params: TextDocumentPositionParams {
+            text_document: TextDocumentIdentifier { uri: uri.clone() },
+            position: Position {
+                line: 5,
+                character: 25, // within "Config"
+            },
+        },
+        work_done_progress_params: WorkDoneProgressParams::default(),
+        partial_result_params: PartialResultParams::default(),
+    };
+
+    let result = backend.goto_definition(params).await.unwrap();
+    assert!(
+        result.is_some(),
+        "Should resolve @see class reference in trailing docblock after expression"
+    );
+
+    match result.unwrap() {
+        GotoDefinitionResponse::Scalar(location) => {
+            assert_eq!(location.range.start.line, 1, "Config is defined on line 1");
+        }
+        other => panic!("Expected Scalar location, got: {:?}", other),
+    }
+}
+
+#[tokio::test]
+async fn test_goto_definition_see_tag_cross_file_no_namespace() {
+    // @see in a file without namespace pointing to a class in another file.
+    let (backend, _dir) = create_psr4_workspace(
+        r#"{
+            "autoload": {
+                "psr-4": {
+                    "App\\": "src/"
+                }
+            }
+        }"#,
+        &[(
+            "src/Models/SupervisorOptions.php",
+            concat!(
+                "<?php\n",
+                "namespace App\\Models;\n",
+                "class SupervisorOptions {\n",
+                "    public int $balanceCooldown = 3;\n",
+                "}\n",
+            ),
+        )],
+    );
+
+    let config_uri = Url::parse("file:///config/horizon.php").unwrap();
+    let config_text = concat!(
+        "<?php\n",
+        "use App\\Models\\SupervisorOptions;\n",
+        "$defaults = [\n",
+        "    'balanceCooldown' => 3, /** @see SupervisorOptions::$balanceCooldown */\n",
+        "];\n",
+    );
+
+    let open_params = DidOpenTextDocumentParams {
+        text_document: TextDocumentItem {
+            uri: config_uri.clone(),
+            language_id: "php".to_string(),
+            version: 1,
+            text: config_text.to_string(),
+        },
+    };
+    backend.did_open(open_params).await;
+
+    // Click on "SupervisorOptions" in the @see tag (line 3)
+    let params = GotoDefinitionParams {
+        text_document_position_params: TextDocumentPositionParams {
+            text_document: TextDocumentIdentifier {
+                uri: config_uri.clone(),
+            },
+            position: Position {
+                line: 3,
+                character: 40, // within "SupervisorOptions"
+            },
+        },
+        work_done_progress_params: WorkDoneProgressParams::default(),
+        partial_result_params: PartialResultParams::default(),
+    };
+
+    let result = backend.goto_definition(params).await.unwrap();
+    assert!(
+        result.is_some(),
+        "Should resolve @see class reference cross-file from a no-namespace config file"
+    );
+
+    match result.unwrap() {
+        GotoDefinitionResponse::Scalar(location) => {
+            let path = location.uri.to_file_path().unwrap();
+            assert!(
+                path.ends_with("Models/SupervisorOptions.php"),
+                "Should point to SupervisorOptions.php, got: {:?}",
+                path
+            );
+        }
+        other => panic!("Expected Scalar location, got: {:?}", other),
+    }
+}