feat(lsp): add hover support for for heading references

jolars · jolars · commit 3ca2b248449e · 2026-03-26T12:53:13.000+01:00
Show section preview on hover of heading references.
diff --git a/TODO.md b/TODO.md
@@ -93,7 +93,7 @@ support.
 - [ ] Reference preview - Show reference definition on hover
 - [x] Footnote preview - Show footnote content inline
 - [x] Citation preview - Show bibliography entry for citation (approximate)
-- [ ] Heading preview - Show section content or summary on hover
+- [x] Heading preview - Show section content or summary on hover
 
 ### Advanced
 
diff --git a/src/lsp/handlers/hover.rs b/src/lsp/handlers/hover.rs
@@ -12,8 +12,9 @@ use tower_lsp_server::jsonrpc::Result;
 use tower_lsp_server::ls_types::*;
 
 use crate::lsp::DocumentState;
+use crate::lsp::symbols::{SymbolTarget, resolve_symbol_target_at_offset};
 use crate::metadata::inline_reference_contains;
-use crate::syntax::{AstNode, FootnoteDefinition};
+use crate::syntax::{AstNode, Document, FootnoteDefinition, Heading};
 
 use super::super::{conversions, helpers};
 
@@ -60,10 +61,37 @@ pub(crate) async fn hover(
         crate::salsa::metadata(&*db, salsa_file, salsa_config, doc_path.clone()).clone()
     };
 
-    let pending_footnote = {
+    let target = {
         let root = ctx.syntax_root();
+        resolve_symbol_target_at_offset(&root, offset)
+    };
+
+    if let Some(SymbolTarget::HeadingLink(label)) = target.as_ref() {
+        let doc_indices = crate::lsp::navigation::project_symbol_documents(
+            &salsa_db,
+            salsa_file,
+            salsa_config,
+            &doc_path,
+            uri,
+            &content_for_offset,
+        )
+        .await;
+
+        for doc in &doc_indices {
+            if let Some(markdown) = section_hover_markdown(doc, label) {
+                return Ok(Some(Hover {
+                    contents: HoverContents::Markup(MarkupContent {
+                        kind: MarkupKind::Markdown,
+                        value: markdown,
+                    }),
+                    range: None,
+                }));
+            }
+        }
+    }
 
-        // Find the node at this offset
+    let pending_footnote = {
+        let root = ctx.syntax_root();
         let Some(mut node) = helpers::find_node_at_offset(&root, offset) else {
             return Ok(None);
         };
@@ -157,6 +185,102 @@ pub(crate) async fn hover(
     Ok(None)
 }
 
+const HOVER_PREVIEW_MAX_CHARS: usize = 180;
+
+fn section_hover_markdown(
+    doc: &crate::lsp::navigation::IndexedDocument,
+    label: &str,
+) -> Option<String> {
+    let heading_range = first_heading_definition_range(&doc.symbol_index, label)?;
+    let tree = crate::parse(&doc.text, None);
+    let document = Document::cast(tree)?;
+
+    let blocks: Vec<_> = document.blocks().collect();
+    let heading_idx = blocks.iter().position(|node| {
+        node.kind() == crate::syntax::SyntaxKind::HEADING && node.text_range() == heading_range
+    })?;
+    let heading_node = &blocks[heading_idx];
+    let heading = Heading::cast(heading_node.clone())?;
+    let title = heading.title_or("(empty)");
+    let section_end = section_end_offset(&doc.symbol_index, heading_range, doc.text.len());
+
+    let mut preview = None;
+    for block in blocks.iter().skip(heading_idx + 1) {
+        let start: usize = block.text_range().start().into();
+        if start >= section_end {
+            break;
+        }
+        let normalized = normalize_preview_text(block.text().to_string().trim());
+        if !normalized.is_empty() {
+            preview = Some(crop_preview(&normalized, HOVER_PREVIEW_MAX_CHARS));
+            break;
+        }
+    }
+
+    let markdown = match preview {
+        Some(snippet) => format!("**Section:** {}\n\n{}", title, snippet),
+        None => format!("**Section:** {}", title),
+    };
+    Some(markdown)
+}
+
+fn first_heading_definition_range(
+    index: &crate::salsa::SymbolUsageIndex,
+    label: &str,
+) -> Option<rowan::TextRange> {
+    let mut all = Vec::new();
+    if let Some(ranges) = index.heading_explicit_definition_ranges(label) {
+        all.extend(ranges.iter().copied());
+    }
+    if let Some(ranges) = index.heading_implicit_definition_ranges(label) {
+        all.extend(ranges.iter().copied());
+    }
+    all.into_iter().min_by_key(|range| range.start())
+}
+
+fn section_end_offset(
+    index: &crate::salsa::SymbolUsageIndex,
+    heading_range: rowan::TextRange,
+    text_len: usize,
+) -> usize {
+    let Some((at, level)) = index
+        .heading_sequence()
+        .iter()
+        .enumerate()
+        .find_map(|(idx, (range, lvl))| (*range == heading_range).then_some((idx, *lvl)))
+    else {
+        return text_len;
+    };
+
+    index
+        .heading_sequence()
+        .iter()
+        .skip(at + 1)
+        .find_map(|(next_range, next_level)| (*next_level <= level).then_some(next_range.start()))
+        .map(Into::<usize>::into)
+        .unwrap_or(text_len)
+}
+
+fn normalize_preview_text(text: &str) -> String {
+    text.split_whitespace().collect::<Vec<_>>().join(" ")
+}
+
+fn crop_preview(text: &str, max_chars: usize) -> String {
+    let mut iter = text.chars();
+    let mut out = String::new();
+    for _ in 0..max_chars {
+        if let Some(ch) = iter.next() {
+            out.push(ch);
+        } else {
+            return out;
+        }
+    }
+    if iter.next().is_some() {
+        out.push_str("...");
+    }
+    out
+}
+
 /// Format a bibliography entry for hover display.
 ///
 /// Works with any bibliography format (BibTeX, CSL-JSON, CSL-YAML, RIS).
diff --git a/tests/lsp/test_hover.rs b/tests/lsp/test_hover.rs
@@ -280,3 +280,100 @@ async fn test_hover_returns_none_inside_yaml_frontmatter() {
         "Expected no hover when cursor is inside YAML frontmatter"
     );
 }
+
+#[tokio::test]
+async fn test_hover_on_heading_reference_shows_section_preview() {
+    let server = TestLspServer::new();
+    let content = "# Intro {#intro}\n\nFirst paragraph in intro section.\n\n## Next\n\nTail.\n\nSee [go](#intro).\n";
+    server
+        .open_document("file:///test.md", content, "markdown")
+        .await;
+
+    let hover = server
+        .hover(
+            "file:///test.md",
+            8,  // See [go](#intro).
+            10, // Inside intro anchor text
+        )
+        .await;
+
+    let Some(h) = hover else {
+        panic!("Expected hover content for heading reference");
+    };
+    let content = match h.contents {
+        HoverContents::Markup(markup) => markup.value,
+        _ => panic!("Expected markdown hover content"),
+    };
+    assert!(content.contains("Section"));
+    assert!(content.contains("Intro"));
+    assert!(content.contains("First paragraph in intro section."));
+}
+
+#[tokio::test]
+async fn test_hover_on_heading_declaration_returns_none() {
+    let server = TestLspServer::new();
+    let content = "# Intro {#intro}\n\nBody.\n\nSee [go](#intro).\n";
+    server
+        .open_document("file:///test.md", content, "markdown")
+        .await;
+
+    let hover = server.hover("file:///test.md", 0, 3).await;
+    assert!(
+        hover.is_none(),
+        "Heading declaration should not produce section preview hover"
+    );
+}
+
+#[tokio::test]
+async fn test_hover_on_heading_reference_with_empty_section_shows_title_only() {
+    let server = TestLspServer::new();
+    let content = "# Intro {#intro}\n\n## Next\n\nSee [go](#intro).\n";
+    server
+        .open_document("file:///test.md", content, "markdown")
+        .await;
+
+    let hover = server
+        .hover(
+            "file:///test.md",
+            4, // See [go](#intro).
+            10,
+        )
+        .await;
+
+    let Some(h) = hover else {
+        panic!("Expected hover content for heading reference");
+    };
+    let content = match h.contents {
+        HoverContents::Markup(markup) => markup.value,
+        _ => panic!("Expected markdown hover content"),
+    };
+    assert!(content.contains("Section"));
+    assert!(content.contains("Intro"));
+    assert!(!content.contains("..."));
+}
+
+#[tokio::test]
+async fn test_hover_on_heading_reference_crops_preview() {
+    let server = TestLspServer::new();
+    let long_body = "Lorem ipsum dolor sit amet, consectetur adipiscing elit. ".repeat(8);
+    let content = format!(
+        "# Intro {{#intro}}\n\n{}\n\n## Next\n\nSee [go](#intro).\n",
+        long_body
+    );
+    server
+        .open_document("file:///test.md", &content, "markdown")
+        .await;
+
+    let hover = server.hover("file:///test.md", 6, 10).await;
+    let Some(h) = hover else {
+        panic!("Expected hover content for heading reference");
+    };
+    let content = match h.contents {
+        HoverContents::Markup(markup) => markup.value,
+        _ => panic!("Expected markdown hover content"),
+    };
+    assert!(
+        content.ends_with("..."),
+        "Expected cropped preview to end with ellipsis"
+    );
+}
