feat: Return self-location at definition sites so editors can fall back

to Find References

Author: lucasacoutinho

docs/CHANGELOG.md

@@ -41,6 +41,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - **Faster startup.** Stub loading during initialization is significantly faster.
 - **More accurate generics resolution.** Type substitution and resolution for complex nested generic types is more correct, particularly for unions, intersections, array shapes, and deeply nested generic arguments.
 - **More accurate type predicates.** `NULL`, `Null`, and case variants of `null` are now handled consistently throughout type checking, matching PHP's case-insensitive treatment of type keywords.
+- **Go-to-definition at declaration sites returns the symbol's own location.** Class, member, and variable declaration names now return their own location instead of nothing, so editors that detect "definition == cursor" can automatically fall back to Find References. Contributed by @lucasacoutinho in https://github.com/AJenbo/phpantom_lsp/pull/76.
 
 ### Fixed
 

src/definition/resolve.rs

@@ -40,46 +40,9 @@ impl Backend {
         // Consult precomputed symbol map (retries one byte earlier for
         // end-of-token edge cases).
         let symbol = self.lookup_symbol_at_position(uri, content, position);
-        let result = if let Some(ref symbol) = symbol {
-            self.resolve_from_symbol(&symbol.kind, uri, content, position, symbol.start)
-        } else {
-            None
-        };
-
-        // ── Self-reference guard ────────────────────────────────────
-        // When the resolved location points back to the same file and
-        // the cursor is already within (or touching) the target range,
-        // the user is at the definition site.  Suppress the jump so
-        // that Ctrl+Click doesn't navigate to itself.
-        //
-        // Special case: zero-width (point) locations arise from
-        // `offset_to_position` and similar helpers that return the
-        // start of a construct (e.g. the `define` keyword) but the
-        // cursor may be anywhere on the same line (e.g. on the
-        // constant name inside the string argument).  For these we
-        // expand the check to the entire line.
-        if let Some(ref loc) = result
-            && let Ok(parsed_uri) = Url::parse(uri)
-            && loc.uri == parsed_uri
-        {
-            let is_point = loc.range.start == loc.range.end;
-            let within = if is_point {
-                // Zero-width target: suppress when cursor is on the same line.
-                position.line == loc.range.start.line
-            } else {
-                position.line >= loc.range.start.line
-                    && position.line <= loc.range.end.line
-                    && (position.line != loc.range.start.line
-                        || position.character >= loc.range.start.character)
-                    && (position.line != loc.range.end.line
-                        || position.character <= loc.range.end.character)
-            };
-            if within {
-                return None;
-            }
-        }
-
-        result
+        symbol
+            .as_ref()
+            .and_then(|s| self.resolve_from_symbol(&s.kind, uri, content, position, s.start))
     }
 
     /// Look up the symbol at the given byte offset in the precomputed
@@ -205,14 +168,19 @@ impl Backend {
                     // outer-scope lookup.
                     if def_kind != VarDefKind::ClosureCapture {
                         // The cursor is on a variable at its definition
-                        // site (assignment LHS, parameter, foreach
-                        // binding, catch binding, etc.).  GTD should not
-                        // trigger here — the user is already at the
-                        // definition.  Type hints next to the variable
-                        // (e.g. `Throwable` in `catch (Throwable $it)`)
-                        // are separate symbol spans that the user can
-                        // click directly.
-                        return None;
+                        // site.  Return the symbol's own location so
+                        // editors can fall back to Find References.
+                        let parsed_uri = Url::parse(uri).ok()?;
+                        let start =
+                            crate::util::offset_to_position(content, cursor_offset as usize);
+                        let end = crate::util::offset_to_position(
+                            content,
+                            cursor_offset as usize + 1 + name.len(),
+                        );
+                        return Some(Location {
+                            uri: parsed_uri,
+                            range: Range { start, end },
+                        });
                     }
                 }
 
@@ -275,11 +243,20 @@ impl Backend {
                 self.resolve_class_reference(uri, content, name, *is_fqn, cursor_offset)
             }
 
-            SymbolKind::ClassDeclaration { .. } | SymbolKind::MemberDeclaration { .. } => {
-                // The cursor is on a class/interface/trait/enum declaration
-                // name or a method/property/constant declaration name —
-                // the user is already at the definition site.
-                None
+            SymbolKind::ClassDeclaration { name } | SymbolKind::MemberDeclaration { name, .. } => {
+                // The cursor is on a declaration name.  Return the
+                // symbol's own location so that editors can detect
+                // "definition == current position" and fall back to
+                // Find References (e.g. VS Code's
+                // editor.gotoLocation.alternativeDefinitionCommand).
+                let parsed_uri = Url::parse(uri).ok()?;
+                let start = crate::util::offset_to_position(content, cursor_offset as usize);
+                let end =
+                    crate::util::offset_to_position(content, cursor_offset as usize + name.len());
+                Some(Location {
+                    uri: parsed_uri,
+                    range: Range { start, end },
+                })
             }
 
             SymbolKind::FunctionCall { name, .. } => {

src/symbol_map/mod.rs

@@ -76,9 +76,9 @@ pub(crate) enum SymbolKind {
         is_fqn: bool,
     },
     /// Class/interface/trait/enum name at its *declaration* site
-    /// (`class Foo`, `interface Bar`, etc.).  Not navigable for
-    /// go-to-definition (the cursor is already at the definition),
-    /// but useful for document highlights and other features.
+    /// (`class Foo`, `interface Bar`, etc.).  Go-to-definition returns
+    /// the symbol's own location so editors can fall back to
+    /// Find References.  Also useful for document highlights.
     ClassDeclaration { name: String },
 
     /// Member name on the RHS of `->`, `?->`, or `::`.
@@ -120,9 +120,10 @@ pub(crate) enum SymbolKind {
 
     /// A method, property, or constant name at its *declaration* site.
     ///
-    /// Not navigable for go-to-definition or hover (the cursor is
-    /// already at the definition), but needed for find-references and
-    /// rename so that the declaration site participates in the match.
+    /// Go-to-definition returns the symbol's own location so editors
+    /// can fall back to Find References.  Also needed for
+    /// find-references and rename so that the declaration site
+    /// participates in the match.
     MemberDeclaration {
         /// The member name (e.g. `"save"`, `"name"`, `"MAX_SIZE"`).
         /// For properties this is the name WITHOUT the `$` prefix.

tests/integration/definition_members.rs

@@ -2431,9 +2431,9 @@ async fn test_goto_definition_own_method_same_short_name_as_parent() {
 // ─── GTD self-reference suppression ─────────────────────────────────────────
 
 /// Ctrl+Click on a method name at its own declaration site should return
-/// `None` rather than jumping to itself.
+/// self-location so editors can fall back to Find References.
 #[tokio::test]
-async fn test_goto_definition_method_declaration_returns_none() {
+async fn test_goto_definition_method_declaration_returns_self_location() {
     let backend = create_test_backend();
 
     let uri = Url::parse("file:///self_ref_method.php").unwrap();
@@ -2471,17 +2471,19 @@ async fn test_goto_definition_method_declaration_returns_none() {
     };
 
     let result = backend.goto_definition(params).await.unwrap();
-    assert!(
-        result.is_none(),
-        "GTD on a method name at its declaration site should return None, got: {:?}",
-        result
-    );
+    match result {
+        Some(GotoDefinitionResponse::Scalar(location)) => {
+            assert_eq!(location.uri, uri);
+            assert_eq!(location.range.start.line, 2, "should point back to line 2");
+        }
+        other => panic!("Expected self-location Scalar, got: {other:?}"),
+    }
 }
 
 /// Ctrl+Click on a class name at its own declaration site should return
-/// `None` rather than jumping to itself.
+/// self-location so editors can fall back to Find References.
 #[tokio::test]
-async fn test_goto_definition_class_declaration_returns_none() {
+async fn test_goto_definition_class_declaration_returns_self_location() {
     let backend = create_test_backend();
 
     let uri = Url::parse("file:///self_ref_class.php").unwrap();
@@ -2516,11 +2518,13 @@ async fn test_goto_definition_class_declaration_returns_none() {
     };
 
     let result = backend.goto_definition(params).await.unwrap();
-    assert!(
-        result.is_none(),
-        "GTD on a class name at its declaration site should return None, got: {:?}",
-        result
-    );
+    match result {
+        Some(GotoDefinitionResponse::Scalar(location)) => {
+            assert_eq!(location.uri, uri);
+            assert_eq!(location.range.start.line, 1, "should point back to line 1");
+        }
+        other => panic!("Expected self-location Scalar, got: {other:?}"),
+    }
 }
 
 /// Ctrl+Click on a constant name inside its own `define()` call should