Skip to main content

dsl_knowledge/
render.rs

1//! Markdown renderer for knowledge-base entries.
2//!
3//! Produces the body shown in cmp documentation popovers and LSP hover.
4//! Structure:
5//!
6//!   header  : `# {label}` plus an italic kind tag (Keyword / Function / Type)
7//!   block   : signature (functions only) in a fenced sql block
8//!   body    : one-line description
9//!   example : fenced sql block with a worked example
10//!   footer  : link to the canonical Postgres docs
11
12use crate::entry::{Entry, Kind};
13
14pub fn render_markdown(entry: &Entry) -> String {
15  // Use blank lines (`\n\n`) between sections so CommonMark / nvim
16  // markdown floats render each as its own paragraph instead of one
17  // collapsed block. Order: heading, kind tag, signature, body
18  // paragraph(s), example, docs link.
19  let mut sections: Vec<String> = Vec::new();
20
21  // Heading: `# label` followed by an italic kind tag on its own line.
22  sections.push(format!("# {}\n\n_{}_", entry.label, kind_label(entry.kind)));
23
24  if let Some(sig) = entry.signature {
25    sections.push(format!("```sql\n{}\n```", sig.trim_end()));
26  }
27
28  if !entry.doc.is_empty() {
29    // Preserve any internal blank lines the entry author wrote --
30    // they signal paragraph breaks in long descriptions. Wrap each
31    // paragraph at ~72 chars so the hover float stays narrow.
32    sections.push(wrap_paragraphs(entry.doc.trim_end(), 72));
33  }
34
35  if !entry.example.is_empty() {
36    sections.push(format!("**Example**\n\n```sql\n{}\n```", entry.example.trim_end()));
37  }
38
39  if !entry.url.is_empty() {
40    sections.push(format!("[Postgres docs]({})", entry.url));
41  }
42
43  // Join with a blank line so markdown sees real paragraph breaks.
44  let mut out = sections.join("\n\n");
45  out.push('\n');
46  out
47}
48
49fn kind_label(kind: Kind) -> &'static str {
50  match kind {
51    Kind::Keyword => "Keyword",
52    Kind::Function => "Function",
53    Kind::Type => "Type",
54  }
55}
56
57/// Greedy word-wrap each paragraph at `width` columns. Preserves blank
58/// lines (paragraph separators), leaves fenced code blocks
59/// (triple-backtick) and indented lines untouched.
60pub fn wrap_paragraphs(text: &str, width: usize) -> String {
61  let mut out = String::with_capacity(text.len() + 16);
62  let mut in_fence = false;
63  let mut first_line = true;
64  for line in text.split('\n') {
65    if !first_line {
66      out.push('\n');
67    }
68    first_line = false;
69    let trimmed = line.trim_start();
70    if trimmed.starts_with("```") {
71      in_fence = !in_fence;
72      out.push_str(line);
73      continue;
74    }
75    // Don't wrap: inside code fence, indented lines, markdown list
76    // items (let the renderer handle nested wrapping), blank lines.
77    if in_fence
78      || line.starts_with("    ")
79      || line.starts_with('\t')
80      || line.starts_with('|')
81      || line.starts_with('-')
82      || line.starts_with('*')
83      || line.starts_with('>')
84      || line.trim().is_empty()
85    {
86      out.push_str(line);
87      continue;
88    }
89    out.push_str(&wrap_one(line, width));
90  }
91  out
92}
93
94fn wrap_one(line: &str, width: usize) -> String {
95  let mut out = String::with_capacity(line.len() + 8);
96  let mut col = 0usize;
97  let mut first = true;
98  for word in line.split_whitespace() {
99    let w = word.chars().count();
100    if first {
101      out.push_str(word);
102      col = w;
103      first = false;
104      continue;
105    }
106    if col + 1 + w > width {
107      out.push('\n');
108      out.push_str(word);
109      col = w;
110    } else {
111      out.push(' ');
112      out.push_str(word);
113      col += 1 + w;
114    }
115  }
116  out
117}