fix(lsp): suppress hover on comments and function body whitespace

- Collect comment spans via a lightweight second lex pass in
  CompilerApi.Analyze and expose them on SemanticResult.CommentSpans.
- HoverService.GetHoverResult returns null when the cursor falls inside
  any comment span (both leading "# ..." lines and trailing "x  # ...").
- Function/class/struct/interface/enum hover cases now only resolve the
  declaration symbol when the cursor is on the header identifier; hovers
  on indented blank lines in the body no longer bubble up to the
  FunctionDef/ClassDef returned by FindInnermostNode.
- Adds HoverServiceTests covering single-line comments, trailing comments,
  comment blocks, hover on def/class name, and blank-body-line cases.

Addresses #540 sub-fix A.

Author: antonsynd

src/Sharpy.Compiler/CompilerApi.cs

@@ -190,16 +190,65 @@ public SemanticResult Analyze(string source, CancellationToken cancellationToken
         var compiler = new Compiler(opts, _logger);
         var result = compiler.Analyze(source, "<source>", cancellationToken);
 
+        // Collect comment spans via a second lightweight lex pass with preserveTrivia.
+        // TODO(#540): This doubles lexer work per Analyze call. Consider threading
+        // preserveTrivia through the pipeline so the primary lex can emit trivia directly.
+        var commentSpans = CollectCommentSpans(source, cancellationToken);
+
         return new SemanticResult
         {
             Success = !result.Diagnostics.HasErrors,
             Diagnostics = result.Diagnostics.GetAll(),
             Ast = result.Module,
             SemanticInfo = result.SemanticInfo,
-            SymbolTable = result.SymbolTable
+            SymbolTable = result.SymbolTable,
+            CommentSpans = commentSpans
         };
     }
 
+    private IReadOnlyList<CommentSpan> CollectCommentSpans(string source, CancellationToken cancellationToken)
+    {
+        // Analyze is expected to return a (failed) result rather than throw when the
+        // caller cancels, so swallow cancellation here like the primary pipeline does.
+        if (cancellationToken.IsCancellationRequested)
+            return Array.Empty<CommentSpan>();
+        try
+        {
+            var lexer = new Lexer.Lexer(source, _logger, cancellationToken: cancellationToken, preserveTrivia: true);
+            var tokens = lexer.TokenizeAll();
+            var spans = new List<CommentSpan>();
+            var seen = new HashSet<(int, int)>();
+            foreach (var tok in tokens)
+            {
+                AppendTriviaSpans(tok.LeadingTrivia, spans, seen);
+                AppendTriviaSpans(tok.TrailingTrivia, spans, seen);
+            }
+            return spans;
+        }
+        catch
+        {
+            return Array.Empty<CommentSpan>();
+        }
+    }
+
+    private static void AppendTriviaSpans(
+        IReadOnlyList<Lexer.Trivia>? trivia,
+        List<CommentSpan> spans,
+        HashSet<(int, int)> seen)
+    {
+        if (trivia == null)
+            return;
+        foreach (var t in trivia)
+        {
+            if (t.Kind != Lexer.TriviaKind.Comment)
+                continue;
+            var key = (t.Line, t.Column);
+            if (!seen.Add(key))
+                continue;
+            spans.Add(new CommentSpan(t.Line, t.Column, t.Column + t.Text.Length));
+        }
+    }
+
     /// <summary>
     /// Analyzes a multi-file Sharpy project (Lexer → Parser → Semantic). No codegen.
     /// Runs phases 1-5 of the project compilation pipeline.

src/Sharpy.Compiler/CompilerApiTypes.cs

@@ -77,4 +77,18 @@ public sealed record SemanticResult
 
     /// <summary>The symbol table from name resolution, or null if name resolution failed.</summary>
     public SymbolTable? SymbolTable { get; init; }
+
+    /// <summary>
+    /// Source spans of comments in the analyzed file (1-based line and column).
+    /// Used by LSP hover to suppress hover inside comments. Empty when no comments
+    /// were collected (e.g., when analysis failed before lexing completed).
+    /// </summary>
+    public IReadOnlyList<CommentSpan> CommentSpans { get; init; } = Array.Empty<CommentSpan>();
 }
+
+/// <summary>
+/// A single-line comment span in 1-based line/column coordinates.
+/// <c>StartColumn</c> points at the <c>#</c> character; <c>EndColumn</c> is exclusive
+/// (one past the last character of the comment).
+/// </summary>
+public readonly record struct CommentSpan(int Line, int StartColumn, int EndColumn);

src/Sharpy.Lsp.Tests/HoverServiceTests.cs

@@ -282,4 +282,110 @@ public void GetHoverMarkdown_OverFunctionScopedTypeAlias_ReturnsAliasInfo()
         hover.Should().Contain("LocalAlias");
         hover.Should().Contain("str");
     }
+
+    // --- #540: hover should be suppressed on comments and function body whitespace ---
+
+    [Fact]
+    public void GetHoverMarkdown_InsideSingleLineComment_ReturnsNull()
+    {
+        var source = "# hello world comment\nx: int = 42\n";
+        var result = _api.Analyze(source);
+
+        // Cursor inside the "# hello world comment" on line 1
+        var hover = _hoverService.GetHoverMarkdown(result, 1, 5);
+
+        hover.Should().BeNull();
+    }
+
+    [Fact]
+    public void GetHoverMarkdown_InsideTrailingComment_ReturnsNull()
+    {
+        var source = "x: int = 42  # inline comment\n";
+        var result = _api.Analyze(source);
+
+        // "x: int = 42  # inline comment" — '#' is at col 14
+        var hover = _hoverService.GetHoverMarkdown(result, 1, 18);
+
+        hover.Should().BeNull();
+    }
+
+    [Fact]
+    public void GetHoverMarkdown_OverVariableBeforeTrailingComment_StillResolves()
+    {
+        var source = "x: int = 42  # inline comment\n";
+        var result = _api.Analyze(source);
+
+        // Cursor on 'x' at col 1 — not in the comment
+        var hover = _hoverService.GetHoverMarkdown(result, 1, 1);
+
+        hover.Should().NotBeNull();
+        hover.Should().Contain("int");
+    }
+
+    [Fact]
+    public void GetHoverMarkdown_InsideCommentBlockLines_ReturnsNull()
+    {
+        var source = "# line one\n# line two\n# line three\nx: int = 1\n";
+        var result = _api.Analyze(source);
+
+        var hoverL1 = _hoverService.GetHoverMarkdown(result, 1, 3);
+        var hoverL2 = _hoverService.GetHoverMarkdown(result, 2, 3);
+        var hoverL3 = _hoverService.GetHoverMarkdown(result, 3, 3);
+
+        hoverL1.Should().BeNull();
+        hoverL2.Should().BeNull();
+        hoverL3.Should().BeNull();
+    }
+
+    [Fact]
+    public void GetHoverMarkdown_OverDefKeyword_ReturnsFunctionSymbol()
+    {
+        var source = "def greet(name: str) -> str:\n    return name\n";
+        var result = _api.Analyze(source);
+
+        // 'greet' starts at col 5; hover on 'g'
+        var hover = _hoverService.GetHoverMarkdown(result, 1, 5);
+
+        hover.Should().NotBeNull();
+        hover.Should().Contain("greet");
+    }
+
+    [Fact]
+    public void GetHoverMarkdown_OnFunctionBodyBlankLine_ReturnsNull()
+    {
+        // Indented blank line inside a function body should not resolve to the function.
+        var source = "def greet() -> int:\n    \n    return 1\n";
+        var result = _api.Analyze(source);
+
+        // Line 2 is the blank-indented line. Hovering on col 3 (inside indentation)
+        // used to surface the FunctionDef because FindInnermostNode returned it.
+        var hover = _hoverService.GetHoverMarkdown(result, 2, 3);
+
+        hover.Should().BeNull();
+    }
+
+    [Fact]
+    public void GetHoverMarkdown_OverClassName_ReturnsClassSymbol()
+    {
+        var source = "class Foo:\n    x: int = 0\n";
+        var result = _api.Analyze(source);
+
+        // 'Foo' starts at col 7
+        var hover = _hoverService.GetHoverMarkdown(result, 1, 7);
+
+        hover.Should().NotBeNull();
+        hover.Should().Contain("Foo");
+    }
+
+    [Fact]
+    public void GetHoverMarkdown_OnClassBodyWhitespace_ReturnsNull()
+    {
+        var source = "class Foo:\n    \n    x: int = 0\n";
+        var result = _api.Analyze(source);
+
+        // Blank indented line 2, col 3 — should not resolve to Foo.
+        var hover = _hoverService.GetHoverMarkdown(result, 2, 3);
+
+        hover.Should().BeNull();
+    }
 }

src/Sharpy.Lsp/HoverService.cs

@@ -46,6 +46,10 @@ public sealed record HoverResult(string Markdown, Node Node);
         if (analysis.Ast == null || analysis.SemanticQuery == null)
             return null;
 
+        // Suppress hover when the cursor is inside a comment.
+        if (IsInsideComment(analysis.CommentSpans, line, col))
+            return null;
+
         var node = _api.FindNodeAtPosition(analysis.Ast, line, col);
         if (node == null)
             return null;
@@ -57,6 +61,18 @@ public sealed record HoverResult(string Markdown, Node Node);
         return new HoverResult(markdown, node);
     }
 
+    private static bool IsInsideComment(IReadOnlyList<CommentSpan> spans, int line, int col)
+    {
+        if (spans == null || spans.Count == 0)
+            return false;
+        foreach (var span in spans)
+        {
+            if (span.Line == line && col >= span.StartColumn && col < span.EndColumn)
+                return true;
+        }
+        return false;
+    }
+
     internal string? GetHoverMarkdownForNode(Node node, SemanticResult analysis, int line, int col)
     {
         var query = analysis.SemanticQuery!;
@@ -178,6 +194,13 @@ public sealed record HoverResult(string Markdown, Node Node);
                             ? query.GetTypeAnnotation(param.Type) : null, className);
                     }
 
+                    // Only resolve to the function symbol when the cursor is on the
+                    // header identifier — not in the body whitespace or elsewhere.
+                    if (line != funcDef.NameLineStart ||
+                        col < funcDef.NameColumnStart ||
+                        col >= funcDef.NameColumnStart + funcDef.Name.Length)
+                        break;
+
                     // Hover on function name — try global scope first, then class scope
                     var funcSymbol = analysis.SymbolTable?.LookupFunction(funcDef.Name);
                     if (funcSymbol != null)
@@ -199,6 +222,9 @@ public sealed record HoverResult(string Markdown, Node Node);
                             return baseHover;
                     }
 
+                    if (!IsOnHeaderName(line, col, classDef.NameLineStart, classDef.NameColumnStart, classDef.Name))
+                        break;
+
                     var typeSymbol = analysis.SymbolTable?.LookupType(classDef.Name);
                     if (typeSymbol != null)
                         return SymbolFormatter.FormatSymbolWithDocs(typeSymbol);
@@ -207,6 +233,9 @@ public sealed record HoverResult(string Markdown, Node Node);
 
             case StructDef structDef:
                 {
+                    if (!IsOnHeaderName(line, col, structDef.NameLineStart, structDef.NameColumnStart, structDef.Name))
+                        break;
+
                     var typeSymbol = analysis.SymbolTable?.LookupType(structDef.Name);
                     if (typeSymbol != null)
                         return SymbolFormatter.FormatSymbolWithDocs(typeSymbol);
@@ -215,6 +244,9 @@ public sealed record HoverResult(string Markdown, Node Node);
 
             case InterfaceDef interfaceDef:
                 {
+                    if (!IsOnHeaderName(line, col, interfaceDef.NameLineStart, interfaceDef.NameColumnStart, interfaceDef.Name))
+                        break;
+
                     var typeSymbol = analysis.SymbolTable?.LookupType(interfaceDef.Name);
                     if (typeSymbol != null)
                         return SymbolFormatter.FormatSymbolWithDocs(typeSymbol);
@@ -223,6 +255,9 @@ public sealed record HoverResult(string Markdown, Node Node);
 
             case EnumDef enumDef:
                 {
+                    if (!IsOnHeaderName(line, col, enumDef.NameLineStart, enumDef.NameColumnStart, enumDef.Name))
+                        break;
+
                     var typeSymbol = analysis.SymbolTable?.LookupType(enumDef.Name);
                     if (typeSymbol != null)
                         return SymbolFormatter.FormatSymbolWithDocs(typeSymbol);
@@ -552,6 +587,11 @@ private static string FormatFunctionTypeName(Compiler.Parser.Ast.FunctionType fu
         return $"({paramTypes}) -> {returnType}";
     }
 
+    private static bool IsOnHeaderName(int line, int col, int nameLine, int nameCol, string name)
+    {
+        return line == nameLine && col >= nameCol && col < nameCol + name.Length;
+    }
+
     internal static bool IsPositionInRange(int line, int col, int startLine, int startCol, int endLine, int endCol)
     {
         if (line < startLine || line > endLine)