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]
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}