Skip to main content

spec_driven_docs/services/
agents_render.rs

1//! Render the managed documentation block for a root `AGENTS.md`.
2//!
3//! The block is the canonical documentation-routing section, wrapped in the
4//! `AGENTS.md` markers with the profile's documentation root substituted and
5//! the project's writing-style selection rendered as one route line, or as
6//! no line where the selection is `none`. The installer places it; this
7//! only produces the bytes. The content lives in the embedded snippet, so
8//! the block and the snippet cannot drift.
9
10use crate::domain::instance_config::WritingStyle;
11use crate::domain::marker::{AGENTS_BEGIN, AGENTS_END};
12
13/// What every rendered instruction item ends with.
14///
15/// The block's items are unwrapped prose, which `docs-format:prose-stays-unwrapped`
16/// requires and the linter's default 80-column rule refuses. The
17/// suppression is line-local, so the project's own lines around the markers
18/// stay judged. It is appended here rather than written into the snippet,
19/// which `sdd docs` serves as readable prose.
20pub const LINE_LENGTH_SUPPRESSION: &str = "<!-- markdownlint-disable-line MD013 -->";
21
22/// The list item that stands for the route in the snippet. It is a list
23/// item rather than a bare placeholder so a markdown formatter reads the
24/// snippet as the list it is.
25const ROUTE_PLACEHOLDER: &str = "- {writing_style}";
26
27/// The embedded documentation snippet, with `{docs_root}` and
28/// `{writing_style}` unresolved.
29#[must_use]
30pub fn snippet() -> &'static str {
31    crate::embedded::INSTANCE
32        .get_file("snippets/AGENTS-docs.md")
33        .and_then(include_dir::File::contents_utf8)
34        .unwrap_or_default()
35}
36
37/// The one route line the block carries for a selection, or `None` where
38/// the selection installs no route.
39#[must_use]
40pub fn route_line(selection: &WritingStyle) -> Option<String> {
41    selection
42        .route()
43        .map(|route| format!("- Read the writing style before you author or edit prose: {route}."))
44}
45
46/// The complete marked block for the given documentation root and
47/// writing-style selection, newline-terminated.
48#[must_use]
49pub fn render_block(docs_root: &str, selection: &WritingStyle) -> String {
50    let mut body = String::new();
51    for line in crate::domain::profile::render_root(snippet(), docs_root).lines() {
52        let line = if line == ROUTE_PLACEHOLDER {
53            match route_line(selection) {
54                Some(route) => route,
55                None => continue,
56            }
57        } else {
58            line.to_string()
59        };
60        body.push_str(&line);
61        if line.starts_with("- ") {
62            body.push(' ');
63            body.push_str(LINE_LENGTH_SUPPRESSION);
64        }
65        body.push('\n');
66    }
67    let body = body.trim_matches('\n');
68    // A blank line separates each marker from the body, as a Markdown
69    // formatter such as dprint writes a comment beside a heading or a list,
70    // so a formatter run leaves the placed block byte-equal to the render.
71    format!("{AGENTS_BEGIN}\n\n{body}\n\n{AGENTS_END}\n")
72}
73
74#[cfg(test)]
75mod tests {
76    use super::*;
77    use crate::domain::instance_config::WritingSource;
78
79    #[test]
80    fn the_block_carries_the_markers_and_the_root() {
81        let block = render_block("docs", &WritingStyle::default());
82        assert!(block.starts_with("<!-- BEGIN spec-driven-docs docs -->\n"));
83        assert!(block.ends_with("<!-- END spec-driven-docs docs -->\n"));
84        assert!(block.contains(
85            "Read the writing style before you author or edit prose: `sdd method writing-style`."
86        ));
87        assert!(!block.contains("{docs_root}"));
88        assert!(!block.contains("{writing_style}"));
89        assert!(!block.contains("simple-english"));
90    }
91
92    #[test]
93    fn a_blank_line_separates_each_marker_from_the_body() {
94        for selection in [
95            WritingStyle::default(),
96            WritingStyle {
97                source: WritingSource::None,
98                path: None,
99            },
100        ] {
101            let block = render_block("docs", &selection);
102            assert!(
103                block.starts_with("<!-- BEGIN spec-driven-docs docs -->\n\n## "),
104                "{block}"
105            );
106            assert!(
107                block.ends_with(" -->\n\n<!-- END spec-driven-docs docs -->\n"),
108                "{block}"
109            );
110            assert!(!block.contains("\n\n\n"), "{block}");
111        }
112    }
113
114    #[test]
115    fn the_underscore_root_reaches_the_block() {
116        let block = render_block("_docs", &WritingStyle::default());
117        assert!(block.contains(
118            "Read the writing style before you author or edit prose: `sdd method writing-style`."
119        ));
120        assert!(block.contains("`_docs/specs/SPEC-<domain>.md`"));
121    }
122
123    #[test]
124    fn every_instruction_item_carries_the_suppression_and_nothing_else_does() {
125        for selection in [
126            WritingStyle::default(),
127            WritingStyle {
128                source: WritingSource::Project,
129                path: Some("docs/STYLE.md".to_string()),
130            },
131            WritingStyle {
132                source: WritingSource::None,
133                path: None,
134            },
135        ] {
136            let block = render_block("docs", &selection);
137            let mut items = 0;
138            for line in block.lines() {
139                if line.starts_with("- ") {
140                    items += 1;
141                    assert!(
142                        line.ends_with(&format!(". {LINE_LENGTH_SUPPRESSION}")),
143                        "{line}"
144                    );
145                } else {
146                    assert!(!line.contains(LINE_LENGTH_SUPPRESSION), "{line}");
147                }
148                assert_ne!(
149                    line.trim(),
150                    LINE_LENGTH_SUPPRESSION,
151                    "an empty suppressed line"
152                );
153            }
154            assert!(items >= 7, "{block}");
155        }
156        let routed = render_block("docs", &WritingStyle::default());
157        assert!(routed.contains(&format!(
158            "- Read the writing style before you author or edit prose: `sdd method writing-style`. {LINE_LENGTH_SUPPRESSION}\n"
159        )));
160    }
161
162    #[test]
163    fn the_route_matches_each_selection() {
164        let project = WritingStyle {
165            source: WritingSource::Project,
166            path: Some("docs/STYLE.md".to_string()),
167        };
168        assert!(
169            render_block("docs", &project).contains(
170                "Read the writing style before you author or edit prose: `docs/STYLE.md`."
171            )
172        );
173        let none = WritingStyle {
174            source: WritingSource::None,
175            path: None,
176        };
177        let block = render_block("docs", &none);
178        assert!(!block.contains("writing style"), "{block}");
179        assert!(!block.contains("{writing_style}"));
180        assert!(
181            !block.contains("\n\n\n"),
182            "the removed route left a blank line:\n{block}"
183        );
184    }
185}