Skip to main content

lockdocs_core/query/
render.rs

1//! Token-budgeted answer text, citations, and shared source provenance.
2
3use super::packages::ReadyPkg;
4use crate::extract::{Entry, Kind};
5use crate::index::PackageIndex;
6use crate::{est_tokens, Eco};
7use serde_json::{json, Value};
8
9pub(super) fn provenance(ready: &[ReadyPkg]) -> Vec<Value> {
10    ready
11        .iter()
12        .map(|(idx, dep, note)| {
13            json!({
14                "package": idx.id(), "requested_version": dep.version, "source": idx.source,
15                "registry_fetched": idx.fetched, "upstream": idx.upstream_provenance, "upstream_label": idx.upstream, "note": note,
16            })
17        })
18        .collect()
19}
20
21fn lang(eco: Eco) -> &'static str {
22    match eco {
23        Eco::Npm => "ts",
24        Eco::PyPI => "python",
25        Eco::Cargo => "rust",
26        Eco::Go => "go",
27    }
28}
29
30pub(super) fn truncate(s: &str, n: usize) -> String {
31    if s.chars().count() <= n {
32        return s.to_string();
33    }
34    let t: String = s.chars().take(n).collect();
35    format!("{t}…")
36}
37
38/// One result block with its citation.
39pub fn render_entry(idx: &PackageIndex, e: &Entry, max_doc: usize) -> String {
40    let cite = format!("{} {}:{}", idx.id(), e.file, e.line);
41    if e.kind == Kind::Prose {
42        return format!("### {} — {}\n{}\n", e.name, cite, truncate(&e.doc, max_doc));
43    }
44    let mut s = format!("### {} ({}) — {}\n```{}\n{}\n```\n", e.path, e.kind.as_str(), cite, lang(idx.eco), e.sig);
45    if !e.doc.is_empty() {
46        s.push_str(&truncate(&e.doc, max_doc));
47        s.push('\n');
48    }
49    s
50}
51
52/// The first paragraph of text of a section, and the short list or code
53/// block right after it (what the section offers). Tag-only lines
54/// (`<Deprecated>`) are skipped.
55pub(super) fn lead(doc: &str) -> String {
56    let tag_only = |l: &str| l.starts_with('<') && l.ends_with('>');
57    let mut lines = doc.lines().map(str::trim_end).peekable();
58    let mut para: Vec<&str> = Vec::new();
59    for l in lines.by_ref() {
60        let t = l.trim();
61        if t.starts_with("```") || t.starts_with("~~~") {
62            return String::new();
63        }
64        if t.is_empty() || tag_only(t) {
65            if para.is_empty() {
66                continue;
67            }
68            break;
69        }
70        para.push(t);
71    }
72    let mut out = truncate(&para.join(" "), 320);
73    while lines.peek().is_some_and(|l| l.trim().is_empty()) {
74        lines.next();
75    }
76    let bullet = |l: &str| {
77        let t = l.trim_start();
78        t.starts_with("* ") || t.starts_with("- ") || t.split_once(". ").is_some_and(|(n, _)| !n.is_empty() && n.chars().all(|c| c.is_ascii_digit()))
79    };
80    if lines.peek().is_some_and(|l| bullet(l)) {
81        let mut list = String::new();
82        for l in lines.by_ref() {
83            if l.trim().is_empty() {
84                break;
85            }
86            let t = l.trim();
87            list.push_str(if bullet(l) { "\n" } else { " " });
88            list.push_str(t);
89        }
90        out.push_str(&truncate(&list, 400));
91    } else if lines.peek().is_some_and(|l| l.trim_start().starts_with("```")) {
92        let mut code = vec![lines.next().unwrap_or_default()];
93        for l in lines.by_ref() {
94            code.push(l);
95            if l.trim_start().starts_with("```") {
96                break;
97            }
98        }
99        let code = code.join("\n");
100        if code.len() <= 300 && code.matches("```").count() == 2 {
101            out.push('\n');
102            out.push_str(&code);
103        }
104    }
105    out
106}
107
108/// Leads of a prose section's page and parent section, quoted, when they
109/// say something the section does not (a deprecation notice on the page,
110/// the setup a subsection builds on).
111pub(super) fn section_context(idx: &PackageIndex, e: &Entry, scope: &std::collections::BTreeSet<usize>) -> Option<String> {
112    if e.kind != Kind::Prose {
113        return None;
114    }
115    // Keep the page and closest nonempty parent, using logical ancestry rather
116    // than heading text (which can repeat), and the same applicability filter
117    // as retrieval. A permitted child must not quote an incompatible setup.
118    let mut wanted = Vec::new();
119    if let Some(line) = e.prose_parents.first() {
120        wanted.push(*line);
121    }
122    if let Some(line) = e.prose_parents.last() {
123        if !wanted.contains(line) {
124            wanted.push(*line);
125        }
126    }
127    let mut out = String::new();
128    for line in wanted {
129        let Some(p) = scope
130            .iter()
131            .map(|&i| &idx.entries[i])
132            .find(|p| p.kind == Kind::Prose && p.file == e.file && p.line == line)
133        else {
134            continue;
135        };
136        let l = lead(&p.doc);
137        if l.len() < 20 || e.doc.contains(&l) || out.contains(&l) {
138            continue;
139        }
140        // The enclosing hit already cites this same file. Keep the ancestor
141        // line explicit without repeating its long path in the token budget.
142        for line in format!("line {}: {l}", p.line).lines() {
143            out.push_str("> ");
144            out.push_str(line);
145            out.push('\n');
146        }
147    }
148    (!out.is_empty()).then(|| out + "\n")
149}
150
151/// Token-budgeted output.
152pub(super) struct Pack {
153    pub(super) text: String,
154    budget: usize,
155    pub(super) blocks: usize,
156    full: bool,
157}
158
159impl Pack {
160    pub(super) fn new(budget: usize) -> Pack {
161        Pack {
162            text: String::new(),
163            budget,
164            blocks: 0,
165            full: false,
166        }
167    }
168    fn used(&self) -> usize {
169        est_tokens(&self.text)
170    }
171    pub(super) fn push_raw(&mut self, s: &str) {
172        self.text.push_str(s);
173    }
174    pub(super) fn prepend(&mut self, s: &str) {
175        self.text.insert_str(0, s);
176    }
177    /// Add a block if it fits; a first oversize block is trimmed to fit.
178    pub(super) fn push_block(&mut self, b: &str) -> bool {
179        if self.full {
180            return false;
181        }
182        let need = est_tokens(b) + 1;
183        let left = self.budget.saturating_sub(self.used());
184        if need <= left {
185            self.text.push('\n');
186            self.text.push_str(b);
187            self.blocks += 1;
188            return true;
189        }
190        if left > 120 {
191            // Trim to the remaining budget at a line boundary.
192            let max_chars = left * 3;
193            let mut cut = String::new();
194            for line in b.lines() {
195                if cut.len() + line.len() + 1 > max_chars {
196                    break;
197                }
198                cut.push_str(line);
199                cut.push('\n');
200            }
201            if cut.matches("```").count() % 2 == 1 {
202                cut.push_str("```\n");
203            }
204            if cut.lines().count() > 1 {
205                self.text.push('\n');
206                self.text.push_str(&cut);
207                self.text.push_str("[…truncated to fit the token budget]\n");
208                self.blocks += 1;
209            }
210        }
211        self.full = true;
212        false
213    }
214}