Skip to main content

docsrs_cli/render/
markdown.rs

1//! Human-readable Markdown rendering for each command payload.
2//!
3//! Used when stdout is a TTY or `--format markdown|text` forces the human path.
4//! Agents receive the JSON envelope instead (see [`super::envelope`]).
5
6use crate::config::{HOST_DOCS_RS, SCHEME_HTTPS};
7use crate::crates_io::SearchCratesData;
8use crate::docs_rs::{GetItemData, ReadmeData, SearchInCrateData};
9
10/// Human Markdown for search-crates.
11pub fn render_search_markdown(data: &SearchCratesData) -> String {
12    let mut out = format!(
13        "# Crate Search Results for \"{}\" (page {})\n\n",
14        data.query, data.page
15    );
16    if data.hits.is_empty() {
17        out.push_str("No crates found.\n");
18        return out;
19    }
20    for h in &data.hits {
21        out.push_str(&format!("## {} ({})\n\n", h.name, h.version));
22        out.push_str(&format!("**Description:** {}\n\n", h.description));
23        out.push_str(&format!("**Downloads:** {}\n\n", h.downloads));
24        let docs = h
25            .documentation
26            .clone()
27            .filter(|s| !s.is_empty())
28            .unwrap_or_else(|| format!("{SCHEME_HTTPS}://{HOST_DOCS_RS}/{}", h.name));
29        out.push_str(&format!("**Documentation:** {docs}\n\n---\n\n"));
30    }
31    out
32}
33
34/// Human Markdown for readme.
35pub fn render_readme_markdown(data: &ReadmeData) -> String {
36    let mut out = format!("# {} Documentation\n\n", data.crate_name);
37    if data.empty {
38        out.push_str("No documentation content found.\n");
39    } else {
40        out.push_str(&data.markdown);
41        out.push('\n');
42    }
43    out
44}
45
46/// Human Markdown for get-item.
47pub fn render_item_markdown(data: &GetItemData) -> String {
48    let mut out = format!("# {}\n\n", data.title);
49    out.push_str(&format!("**Documentation URL:** {}\n\n", data.source_url));
50    if data.empty {
51        out.push_str("No documentation content found.\n");
52    } else {
53        out.push_str(&data.markdown);
54        out.push('\n');
55    }
56    out
57}
58
59/// Human Markdown for search-in-crate.
60pub fn render_search_in_crate_markdown(data: &SearchInCrateData) -> String {
61    // Borrow query text — no String clone for the heading.
62    let term = if data.query.is_empty() {
63        "all items"
64    } else {
65        data.query.as_str()
66    };
67    let mut out = format!(
68        "# Search Results for \"{}\" in {}\n\nFound {} items (emitted {})\n\n",
69        term, data.crate_name, data.total, data.emitted
70    );
71    if data.hits.is_empty() {
72        out.push_str("No matching items found.\n");
73        return out;
74    }
75    for h in &data.hits {
76        out.push_str(&format!("## {} ({})\n\n", h.name, h.kind));
77        out.push_str(&format!("**Link:** {}\n\n---\n\n", h.url));
78    }
79    out
80}
81
82#[cfg(test)]
83mod tests {
84    use super::*;
85    use crate::crates_io::{CrateSearchHit, SearchMeta};
86
87    #[test]
88    fn empty_search_markdown() {
89        let data = SearchCratesData {
90            query: "z".into(),
91            page: 1,
92            per_page: 10,
93            sort: "relevance".into(),
94            hits: vec![],
95            meta: SearchMeta {
96                total: 0,
97                next_page: None,
98                prev_page: None,
99            },
100            cache_hit: false,
101            truncated: false,
102        };
103        let md = render_search_markdown(&data);
104        assert!(md.contains("No crates found"));
105    }
106
107    #[test]
108    fn empty_readme_and_item() {
109        let r = ReadmeData {
110            crate_name: "c".into(),
111            version: "latest".into(),
112            resolved_version: None,
113            markdown: String::new(),
114            empty: true,
115            truncated: false,
116            source_url: "u".into(),
117            cache_hit: false,
118        };
119        assert!(render_readme_markdown(&r).contains("No documentation"));
120        let i = GetItemData {
121            crate_name: "c".into(),
122            item_type: "fn".into(),
123            item_path: "c::f".into(),
124            item_name: "f".into(),
125            version: "latest".into(),
126            resolved_version: None,
127            markdown: String::new(),
128            empty: true,
129            truncated: false,
130            source_url: "u".into(),
131            title: "c::f (fn)".into(),
132            cache_hit: false,
133            extraction: None,
134            anchor_family: None,
135            resolved_item_path: None,
136        };
137        assert!(render_item_markdown(&i).contains("No documentation"));
138    }
139
140    #[test]
141    fn empty_search_in_crate_markdown() {
142        let data = SearchInCrateData {
143            crate_name: "c".into(),
144            query: String::new(),
145            version: "1".into(),
146            item_type: None,
147            match_mode: "prefix".into(),
148            total: 0,
149            emitted: 0,
150            hits: vec![],
151            truncated: false,
152            source_url: "u".into(),
153            cache_hit: false,
154        };
155        let md = render_search_in_crate_markdown(&data);
156        assert!(md.contains("all items"));
157        assert!(md.contains("No matching items"));
158    }
159
160    #[test]
161    fn search_docs_fallback_docs_rs_url() {
162        let data = SearchCratesData {
163            query: "x".into(),
164            page: 1,
165            per_page: 10,
166            sort: "relevance".into(),
167            hits: vec![CrateSearchHit {
168                name: "foo".into(),
169                description: "d".into(),
170                downloads: 1,
171                version: "1.0.0".into(),
172                documentation: None,
173                max_version: None,
174                max_stable_version: None,
175                default_version: None,
176                recent_downloads: None,
177                exact_match: None,
178                yanked: None,
179                repository: None,
180                homepage: None,
181            }],
182            meta: SearchMeta {
183                total: 1,
184                next_page: None,
185                prev_page: None,
186            },
187            cache_hit: false,
188            truncated: false,
189        };
190        let md = render_search_markdown(&data);
191        assert!(md.contains("https://docs.rs/foo"));
192        assert!(!md.contains("N/A"));
193    }
194}