Skip to main content

docsrs_cli/render/
budget.rs

1//! `max_output_bytes` enforcement: UTF-8-safe truncation and hit-list shrinking.
2//!
3//! Budgeting always cuts on a structural boundary — a whole hit, or a char
4//! boundary inside markdown. Slicing raw JSON text would emit an unparseable
5//! document, which is strictly worse for an agent than an over-budget one.
6
7use super::envelope::success_envelope;
8use crate::config::Config;
9use crate::crates_io::SearchCratesData;
10use crate::docs_rs::{GetItemData, ReadmeData, SearchInCrateData};
11
12/// Truncate UTF-8 text on a char boundary; returns (text, truncated).
13pub fn truncate_output(text: &str, max_bytes: u64) -> (String, bool) {
14    if max_bytes == 0 {
15        return (String::new(), true);
16    }
17    let max = max_bytes as usize;
18    if text.len() <= max {
19        return (text.to_string(), false);
20    }
21    let mut end = max;
22    while end > 0 && !text.is_char_boundary(end) {
23        end -= 1;
24    }
25    (text[..end].to_string(), true)
26}
27
28/// Reduce `search-crates` hits until the success envelope fits `max_output_bytes`.
29///
30/// Preserves JSON parseability (never mid-string cuts). Sets `truncated=true` when
31/// any hit is dropped for budget. If even zero hits exceeds the budget, returns
32/// the zero-hit payload with `truncated=true` (agents should raise the cap).
33pub fn apply_output_budget_search_crates(
34    mut data: SearchCratesData,
35    max_bytes: u64,
36    duration_ms: u64,
37    source_url: Option<&str>,
38) -> SearchCratesData {
39    if max_bytes == 0 {
40        data.hits.clear();
41        data.truncated = true;
42        return data;
43    }
44    loop {
45        let env = success_envelope("search-crates", &data, duration_ms, source_url);
46        let len = match serde_json::to_vec(&env) {
47            Ok(buf) => buf.len() as u64,
48            Err(_) => return data,
49        };
50        if len <= max_bytes {
51            return data;
52        }
53        if data.hits.is_empty() {
54            data.truncated = true;
55            return data;
56        }
57        data.hits.pop();
58        data.truncated = true;
59    }
60}
61
62/// Reduce `search-in-crate` hits until the success envelope fits `max_output_bytes`.
63///
64/// `truncated` becomes true when budget (or a prior limit) cuts the list.
65pub fn apply_output_budget_search_in_crate(
66    mut data: SearchInCrateData,
67    max_bytes: u64,
68    duration_ms: u64,
69    source_url: Option<&str>,
70) -> SearchInCrateData {
71    if max_bytes == 0 {
72        data.hits.clear();
73        data.emitted = 0;
74        data.truncated = true;
75        return data;
76    }
77    loop {
78        let env = success_envelope("search-in-crate", &data, duration_ms, source_url);
79        let len = match serde_json::to_vec(&env) {
80            Ok(buf) => buf.len() as u64,
81            Err(_) => return data,
82        };
83        if len <= max_bytes {
84            return data;
85        }
86        if data.hits.is_empty() {
87            data.emitted = 0;
88            data.truncated = true;
89            return data;
90        }
91        data.hits.pop();
92        data.emitted = data.hits.len();
93        data.truncated = true;
94    }
95}
96
97/// Apply max_output_bytes truncation to readme payload.
98pub fn apply_truncation_to_readme(mut data: ReadmeData, cfg: &Config) -> ReadmeData {
99    let (md, trunc) = truncate_output(&data.markdown, cfg.max_output_bytes);
100    data.markdown = md;
101    data.truncated = trunc;
102    data
103}
104
105/// Apply max_output_bytes truncation to get-item payload.
106pub fn apply_truncation_to_item(mut data: GetItemData, cfg: &Config) -> GetItemData {
107    let (md, trunc) = truncate_output(&data.markdown, cfg.max_output_bytes);
108    data.markdown = md;
109    data.truncated = trunc;
110    data
111}
112
113#[cfg(test)]
114mod tests {
115    use super::*;
116    use crate::crates_io::{CrateSearchHit, SearchMeta};
117
118    #[test]
119    fn truncate_marks_flag() {
120        let (out, trunc) = truncate_output("abcdef", 3);
121        assert!(trunc);
122        assert_eq!(out, "abc");
123    }
124
125    #[test]
126    fn truncate_zero_and_utf8_boundary() {
127        let (out, trunc) = truncate_output("abc", 0);
128        assert!(trunc);
129        assert!(out.is_empty());
130        let s = "áéí"; // multi-byte
131        let (out, trunc) = truncate_output(s, 2);
132        assert!(trunc);
133        assert!(out.is_char_boundary(out.len()));
134    }
135
136    #[test]
137    fn apply_truncation_sets_flags() {
138        let cfg = Config {
139            max_output_bytes: 4,
140            ..Config::default()
141        };
142        let r = apply_truncation_to_readme(
143            ReadmeData {
144                crate_name: "c".into(),
145                version: "1".into(),
146                resolved_version: None,
147                markdown: "hello world".into(),
148                empty: false,
149                truncated: false,
150                source_url: "u".into(),
151                cache_hit: false,
152            },
153            &cfg,
154        );
155        assert!(r.truncated);
156        assert!(r.markdown.len() <= 4);
157        let i = apply_truncation_to_item(
158            GetItemData {
159                crate_name: "c".into(),
160                item_type: "fn".into(),
161                item_path: "c::f".into(),
162                item_name: "f".into(),
163                version: "1".into(),
164                resolved_version: None,
165                markdown: "abcdef".into(),
166                empty: false,
167                truncated: false,
168                source_url: "u".into(),
169                title: "t".into(),
170                cache_hit: false,
171                extraction: None,
172                anchor_family: None,
173                resolved_item_path: None,
174            },
175            &cfg,
176        );
177        assert!(i.truncated);
178        assert_eq!(i.markdown, "abcd");
179    }
180
181    #[test]
182    fn output_budget_reduces_search_hits() {
183        let mut hits = Vec::new();
184        for i in 0..20 {
185            hits.push(CrateSearchHit {
186                name: format!("crate-{i}"),
187                description: "A".repeat(80),
188                downloads: i as u64,
189                version: "1.0.0".into(),
190                documentation: Some(format!("https://docs.rs/crate-{i}")),
191                max_version: None,
192                max_stable_version: None,
193                default_version: None,
194                recent_downloads: None,
195                exact_match: None,
196                yanked: None,
197                repository: None,
198                homepage: None,
199            });
200        }
201        let data = SearchCratesData {
202            query: "crate".into(),
203            page: 1,
204            per_page: 20,
205            sort: "relevance".into(),
206            hits,
207            meta: SearchMeta {
208                total: 20,
209                next_page: None,
210                prev_page: None,
211            },
212            cache_hit: false,
213            truncated: false,
214        };
215        let budgeted = apply_output_budget_search_crates(data, 800, 1, Some("https://crates.io"));
216        assert!(budgeted.truncated);
217        assert!(budgeted.hits.len() < 20);
218        let env = success_envelope("search-crates", &budgeted, 1, Some("https://crates.io"));
219        let len = serde_json::to_vec(&env).expect("serialize").len() as u64;
220        assert!(len <= 800, "envelope len {len} > 800");
221    }
222}