spec_driven_docs/services/
agents_render.rs1use crate::domain::instance_config::WritingStyle;
11use crate::domain::marker::{AGENTS_BEGIN, AGENTS_END};
12
13pub const LINE_LENGTH_SUPPRESSION: &str = "<!-- markdownlint-disable-line MD013 -->";
21
22const ROUTE_PLACEHOLDER: &str = "- {writing_style}";
26
27#[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#[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#[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 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}