feat(lsp): narrow hover highlight spans for definitions and return keyword

Hover highlights previously spanned the entire AST node, causing
multi-line highlighting for definitions and 'return self' highlighting
for return statements. Now definition-site hovers narrow to just the
name identifier, and return statements narrow to the 6-char keyword.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: antonsynd

src/Sharpy.Lsp.Tests/E2E/ProtocolTests.cs

@@ -901,4 +901,89 @@ await _client.WaitForNotificationAsync(
             s!["name"]?.GetValue<string>()?.Contains("animal", StringComparison.OrdinalIgnoreCase) == true);
         hasAnimal.Should().BeTrue("at least one symbol should have a name containing 'animal'");
     }
+
+    [Fact]
+    public async Task Hover_OverMethodName_RangeNarrowedToName()
+    {
+        await _client.InitializeAsync();
+
+        var uri = "file:///test_hover_narrow_method.spy";
+        // Mirrors async_with_basic.spy structure
+        var source = "class AsyncResource:\n    def __init__(self):\n        pass\n\n    async def __aenter__(self) -> AsyncResource:\n        print(\"entering\")\n        return self\n\n    async def __aexit__(self):\n        print(\"exiting\")\n\nasync def main():\n    async with AsyncResource() as r:\n        print(\"inside\")";
+        await _client.DidOpenAsync(uri, source);
+
+        // Wait for diagnostics to ensure analysis is complete
+        await _client.WaitForNotificationAsync(
+            "textDocument/publishDiagnostics",
+            TimeSpan.FromSeconds(15));
+
+        // Hover over '__aenter__' on line 4 (0-based), character 14 (0-based)
+        // Source line 5 (1-based): "    async def __aenter__(self) -> AsyncResource:"
+        // 0-based:                  0123456789012345
+        //                                         ^ col 14 = start of "__aenter__"
+        var hover = await _client.HoverAsync(uri, 4, 14);
+
+        hover.Should().NotBeNull("hover over a method name should return information");
+
+        var contents = hover!["contents"];
+        contents.Should().NotBeNull();
+        var hoverText = contents!.ToJsonString();
+        hoverText.Should().Contain("__aenter__");
+
+        // Verify the range is narrowed to just the method name, not the whole function body
+        var range = hover["range"];
+        range.Should().NotBeNull("hover should include a range");
+
+        var startLine = range!["start"]!["line"]!.GetValue<int>();
+        var startChar = range["start"]!["character"]!.GetValue<int>();
+        var endLine = range["end"]!["line"]!.GetValue<int>();
+        var endChar = range["end"]!["character"]!.GetValue<int>();
+
+        startLine.Should().Be(4, "highlight should start on the method name line");
+        endLine.Should().Be(4, "highlight should end on the same line (not span multi-line)");
+        startChar.Should().Be(14, "highlight should start at '__aenter__'");
+        endChar.Should().Be(24, "highlight should end after '__aenter__' (10 chars)");
+    }
+
+    [Fact]
+    public async Task Hover_OverReturnKeyword_RangeNarrowedToKeyword()
+    {
+        await _client.InitializeAsync();
+
+        var uri = "file:///test_hover_narrow_return.spy";
+        var source = "def greet() -> str:\n    return \"hello\"\ndef main():\n    greet()";
+        await _client.DidOpenAsync(uri, source);
+
+        // Wait for diagnostics to ensure analysis is complete
+        await _client.WaitForNotificationAsync(
+            "textDocument/publishDiagnostics",
+            TimeSpan.FromSeconds(15));
+
+        // Hover over 'return' on line 1 (0-based), character 4 (0-based)
+        // Source line 2 (1-based): "    return \"hello\""
+        // 0-based:                  01234
+        //                               ^ col 4 = start of "return"
+        var hover = await _client.HoverAsync(uri, 1, 4);
+
+        hover.Should().NotBeNull("hover over return keyword should return information");
+
+        var contents = hover!["contents"];
+        contents.Should().NotBeNull();
+        var hoverText = contents!.ToJsonString();
+        hoverText.Should().Contain("return");
+
+        // Verify the range is narrowed to just the 'return' keyword
+        var range = hover["range"];
+        range.Should().NotBeNull("hover should include a range");
+
+        var startLine = range!["start"]!["line"]!.GetValue<int>();
+        var startChar = range["start"]!["character"]!.GetValue<int>();
+        var endLine = range["end"]!["line"]!.GetValue<int>();
+        var endChar = range["end"]!["character"]!.GetValue<int>();
+
+        startLine.Should().Be(1, "highlight should start on the return line");
+        endLine.Should().Be(1, "highlight should end on the same line");
+        startChar.Should().Be(4, "highlight should start at 'return'");
+        endChar.Should().Be(10, "highlight should end after 'return' (6 chars)");
+    }
 }

src/Sharpy.Lsp.Tests/HoverServiceTests.cs

@@ -437,4 +437,65 @@ public void GetHoverResult_OverNotKeyword_NarrowsHighlightToKeyword()
         hover.HighlightColumnStart.Should().Be(9);
         hover.HighlightColumnEnd.Should().Be(12);
     }
+
+    // --- Highlight narrowing: definition names ---
+
+    [Fact]
+    public void GetHoverResult_OverFunctionName_NarrowsHighlightToName()
+    {
+        var source = "class AsyncResource:\n    def __init__(self):\n        pass\n\n    async def __aenter__(self) -> AsyncResource:\n        print(\"entering\")\n        return self\n\n    async def __aexit__(self):\n        print(\"exiting\")\n\ndef main():\n    pass";
+        var result = _api.Analyze(source);
+
+        // Line 5: "    async def __aenter__(self) -> AsyncResource:"
+        // Cols:    123456789012345678
+        // '__aenter__' starts at col 15
+        var hover = _hoverService.GetHoverResult(result, 5, 15);
+
+        hover.Should().NotBeNull();
+        hover!.Markdown.Should().Contain("__aenter__");
+        // Highlight should be narrowed to just the function name, not the whole FunctionDef
+        hover.HighlightLineStart.Should().Be(5);
+        hover.HighlightColumnStart.Should().Be(15);
+        hover.HighlightLineEnd.Should().Be(5);
+        hover.HighlightColumnEnd.Should().Be(25); // "__aenter__" = 10 chars
+    }
+
+    [Fact]
+    public void GetHoverResult_OverClassName_NarrowsHighlightToName()
+    {
+        var source = "class Foo:\n    x: int = 0\n    def method(self) -> int:\n        return self.x\ndef main():\n    pass";
+        var result = _api.Analyze(source);
+
+        // Line 1: "class Foo:"
+        // 'Foo' starts at col 7
+        var hover = _hoverService.GetHoverResult(result, 1, 7);
+
+        hover.Should().NotBeNull();
+        hover!.Markdown.Should().Contain("Foo");
+        hover.HighlightLineStart.Should().Be(1);
+        hover.HighlightColumnStart.Should().Be(7);
+        hover.HighlightLineEnd.Should().Be(1);
+        hover.HighlightColumnEnd.Should().Be(10); // "Foo" = 3 chars
+    }
+
+    // --- Highlight narrowing: return keyword ---
+
+    [Fact]
+    public void GetHoverResult_OverReturnKeyword_NarrowsHighlightToKeyword()
+    {
+        var source = "def greet() -> str:\n    return \"hello\"\ndef main():\n    pass";
+        var result = _api.Analyze(source);
+
+        // Line 2: "    return \"hello\"" — 'return' starts at col 5
+        var hover = _hoverService.GetHoverResult(result, 2, 5);
+
+        hover.Should().NotBeNull();
+        hover!.Markdown.Should().Contain("return");
+        hover.Markdown.Should().Contain("str");
+        // Highlight should be narrowed to just the 'return' keyword (6 chars)
+        hover.HighlightLineStart.Should().Be(2);
+        hover.HighlightColumnStart.Should().Be(5);
+        hover.HighlightLineEnd.Should().Be(2);
+        hover.HighlightColumnEnd.Should().Be(11); // "return" = 6 chars
+    }
 }

src/Sharpy.Lsp/HoverService.cs

@@ -73,6 +73,18 @@ public sealed record HoverResult(string Markdown, Node Node)
         if (markdown == null)
             return null;
 
+        // Narrow highlight to the name span for definition-site hovers,
+        // or to the keyword token for keyword statements like 'return'.
+        var highlight = TryNarrowHighlight(node, line, col);
+        if (highlight != null)
+            return new HoverResult(markdown, node)
+            {
+                HighlightLineStart = highlight.Value.line,
+                HighlightColumnStart = highlight.Value.colStart,
+                HighlightLineEnd = highlight.Value.line,
+                HighlightColumnEnd = highlight.Value.colEnd,
+            };
+
         return new HoverResult(markdown, node);
     }
 
@@ -121,6 +133,31 @@ public sealed record HoverResult(string Markdown, Node Node)
         };
     }
 
+    /// <summary>
+    /// Narrows the hover highlight range for definition nodes (to the name identifier)
+    /// and keyword statements like <c>return</c> (to the keyword token). Returns null
+    /// when no narrowing applies.
+    /// </summary>
+    private static (int line, int colStart, int colEnd)? TryNarrowHighlight(Node node, int cursorLine, int cursorCol)
+    {
+        return node switch
+        {
+            FunctionDef f when IsOnHeaderName(cursorLine, cursorCol, f.NameLineStart, f.NameColumnStart, f.Name)
+                => (f.NameLineStart, f.NameColumnStart, f.NameColumnStart + f.Name.Length),
+            ClassDef c when IsOnHeaderName(cursorLine, cursorCol, c.NameLineStart, c.NameColumnStart, c.Name)
+                => (c.NameLineStart, c.NameColumnStart, c.NameColumnStart + c.Name.Length),
+            StructDef s when IsOnHeaderName(cursorLine, cursorCol, s.NameLineStart, s.NameColumnStart, s.Name)
+                => (s.NameLineStart, s.NameColumnStart, s.NameColumnStart + s.Name.Length),
+            InterfaceDef i when IsOnHeaderName(cursorLine, cursorCol, i.NameLineStart, i.NameColumnStart, i.Name)
+                => (i.NameLineStart, i.NameColumnStart, i.NameColumnStart + i.Name.Length),
+            EnumDef e when IsOnHeaderName(cursorLine, cursorCol, e.NameLineStart, e.NameColumnStart, e.Name)
+                => (e.NameLineStart, e.NameColumnStart, e.NameColumnStart + e.Name.Length),
+            ReturnStatement ret
+                => (ret.LineStart, ret.ColumnStart, ret.ColumnStart + 6), // "return"
+            _ => null
+        };
+    }
+
     private static bool IsInsideComment(IReadOnlyList<CommentSpan> spans, int line, int col)
     {
         if (spans == null || spans.Count == 0)