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_end_matches('\n');
68    format!("{AGENTS_BEGIN}\n{body}\n{AGENTS_END}\n")
69}
70
71#[cfg(test)]
72mod tests {
73    use super::*;
74    use crate::domain::instance_config::WritingSource;
75
76    #[test]
77    fn the_block_carries_the_markers_and_the_root() {
78        let block = render_block("docs", &WritingStyle::default());
79        assert!(block.starts_with("<!-- BEGIN spec-driven-docs docs -->\n"));
80        assert!(block.ends_with("<!-- END spec-driven-docs docs -->\n"));
81        assert!(block.contains(
82            "Read the writing style before you author or edit prose: `sdd method writing-style`."
83        ));
84        assert!(!block.contains("{docs_root}"));
85        assert!(!block.contains("{writing_style}"));
86        assert!(!block.contains("simple-english"));
87    }
88
89    #[test]
90    fn the_underscore_root_reaches_the_block() {
91        let block = render_block("_docs", &WritingStyle::default());
92        assert!(block.contains(
93            "Read the writing style before you author or edit prose: `sdd method writing-style`."
94        ));
95        assert!(block.contains("`_docs/specs/SPEC-<domain>.md`"));
96    }
97
98    #[test]
99    fn every_instruction_item_carries_the_suppression_and_nothing_else_does() {
100        for selection in [
101            WritingStyle::default(),
102            WritingStyle {
103                source: WritingSource::Project,
104                path: Some("docs/STYLE.md".to_string()),
105            },
106            WritingStyle {
107                source: WritingSource::None,
108                path: None,
109            },
110        ] {
111            let block = render_block("docs", &selection);
112            let mut items = 0;
113            for line in block.lines() {
114                if line.starts_with("- ") {
115                    items += 1;
116                    assert!(
117                        line.ends_with(&format!(". {LINE_LENGTH_SUPPRESSION}")),
118                        "{line}"
119                    );
120                } else {
121                    assert!(!line.contains(LINE_LENGTH_SUPPRESSION), "{line}");
122                }
123                assert_ne!(
124                    line.trim(),
125                    LINE_LENGTH_SUPPRESSION,
126                    "an empty suppressed line"
127                );
128            }
129            assert!(items >= 7, "{block}");
130        }
131        let routed = render_block("docs", &WritingStyle::default());
132        assert!(routed.contains(&format!(
133            "- Read the writing style before you author or edit prose: `sdd method writing-style`. {LINE_LENGTH_SUPPRESSION}\n"
134        )));
135    }
136
137    #[test]
138    fn the_route_matches_each_selection() {
139        let project = WritingStyle {
140            source: WritingSource::Project,
141            path: Some("docs/STYLE.md".to_string()),
142        };
143        assert!(
144            render_block("docs", &project).contains(
145                "Read the writing style before you author or edit prose: `docs/STYLE.md`."
146            )
147        );
148        let none = WritingStyle {
149            source: WritingSource::None,
150            path: None,
151        };
152        let block = render_block("docs", &none);
153        assert!(!block.contains("writing style"), "{block}");
154        assert!(!block.contains("{writing_style}"));
155        assert!(
156            !block.contains("\n\n<!-- END"),
157            "the removed route left a blank line:\n{block}"
158        );
159    }
160}