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    /// VERIFIES docs-format:author-instructions-stay-within-budget
93    ///
94    /// The block sdd writes fits the cap the gate holds every managed
95    /// block to, so this release fails here rather than at a project's
96    /// commit. A release that needs more lines moves text into `sdd docs`.
97    #[test]
98    fn the_rendered_block_fits_the_managed_block_cap() {
99        for root in ["docs", "_docs"] {
100            for selection in [
101                WritingStyle::default(),
102                WritingStyle {
103                    source: WritingSource::None,
104                    path: None,
105                },
106            ] {
107                let block = render_block(root, &selection);
108                let lines = block.lines().count();
109                assert!(
110                    lines <= crate::gates::agents_digest_size::BLOCK_CAP,
111                    "{lines} lines:\n{block}"
112                );
113                assert!(
114                    crate::gates::agents_digest_size::split(&block)
115                        .broken
116                        .is_none(),
117                    "{block}"
118                );
119            }
120        }
121    }
122
123    #[test]
124    fn a_blank_line_separates_each_marker_from_the_body() {
125        for selection in [
126            WritingStyle::default(),
127            WritingStyle {
128                source: WritingSource::None,
129                path: None,
130            },
131        ] {
132            let block = render_block("docs", &selection);
133            assert!(
134                block.starts_with("<!-- BEGIN spec-driven-docs docs -->\n\n## "),
135                "{block}"
136            );
137            assert!(
138                block.ends_with(" -->\n\n<!-- END spec-driven-docs docs -->\n"),
139                "{block}"
140            );
141            assert!(!block.contains("\n\n\n"), "{block}");
142        }
143    }
144
145    #[test]
146    fn the_underscore_root_reaches_the_block() {
147        let block = render_block("_docs", &WritingStyle::default());
148        assert!(block.contains(
149            "Read the writing style before you author or edit prose: `sdd method writing-style`."
150        ));
151        assert!(block.contains("`_docs/specs/SPEC-<domain>.md`"));
152    }
153
154    #[test]
155    fn every_instruction_item_carries_the_suppression_and_nothing_else_does() {
156        for selection in [
157            WritingStyle::default(),
158            WritingStyle {
159                source: WritingSource::Project,
160                path: Some("docs/STYLE.md".to_string()),
161            },
162            WritingStyle {
163                source: WritingSource::None,
164                path: None,
165            },
166        ] {
167            let block = render_block("docs", &selection);
168            let mut items = 0;
169            for line in block.lines() {
170                if line.starts_with("- ") {
171                    items += 1;
172                    assert!(
173                        line.ends_with(&format!(". {LINE_LENGTH_SUPPRESSION}")),
174                        "{line}"
175                    );
176                } else {
177                    assert!(!line.contains(LINE_LENGTH_SUPPRESSION), "{line}");
178                }
179                assert_ne!(
180                    line.trim(),
181                    LINE_LENGTH_SUPPRESSION,
182                    "an empty suppressed line"
183                );
184            }
185            assert!(items >= 7, "{block}");
186        }
187        let routed = render_block("docs", &WritingStyle::default());
188        assert!(routed.contains(&format!(
189            "- Read the writing style before you author or edit prose: `sdd method writing-style`. {LINE_LENGTH_SUPPRESSION}\n"
190        )));
191    }
192
193    #[test]
194    fn the_route_matches_each_selection() {
195        let project = WritingStyle {
196            source: WritingSource::Project,
197            path: Some("docs/STYLE.md".to_string()),
198        };
199        assert!(
200            render_block("docs", &project).contains(
201                "Read the writing style before you author or edit prose: `docs/STYLE.md`."
202            )
203        );
204        let none = WritingStyle {
205            source: WritingSource::None,
206            path: None,
207        };
208        let block = render_block("docs", &none);
209        assert!(!block.contains("writing style"), "{block}");
210        assert!(!block.contains("{writing_style}"));
211        assert!(
212            !block.contains("\n\n\n"),
213            "the removed route left a blank line:\n{block}"
214        );
215    }
216}