spec_driven_docs/services/
policy.rs1use std::collections::BTreeSet;
18
19use camino::Utf8Path;
20
21use camino::Utf8PathBuf;
22
23use crate::adapters::fs::write_atomic;
24use crate::domain::debt::Debt;
25use crate::domain::ownership::Sha256;
26use crate::domain::policy::{SENTINELS, Sentinel};
27use crate::domain::profile::{DocsRoot, resolve_destination};
28use crate::domain::rule_id::RuleId;
29use crate::error::AppError;
30
31#[derive(Debug, Clone, PartialEq, Eq)]
33pub struct Reconciliation {
34 pub sentinel: &'static Sentinel,
36}
37
38impl Reconciliation {
39 #[must_use]
41 pub fn note(&self, docs_root: DocsRoot) -> String {
42 format!(
43 "note: {} and no local specification defines `{}`; {} owns it; run 'sdd policy reconcile'",
44 self.sentinel.declares,
45 self.sentinel.rule,
46 crate::domain::profile::resolve_destination(&self.sentinel.destination, docs_root)
47 )
48 }
49}
50
51pub fn local_rule_ids(
57 target: &Utf8Path,
58 docs_root: DocsRoot,
59) -> Result<BTreeSet<String>, AppError> {
60 let specs = target.join(docs_root.as_str()).join("specs");
61 let mut ids = BTreeSet::new();
62 let Ok(entries) = specs.read_dir_utf8() else {
63 return Ok(ids);
64 };
65 for entry in entries.filter_map(Result::ok) {
66 let path = entry.path();
67 #[allow(
68 clippy::case_sensitive_file_extension_comparisons,
69 reason = "the corpus convention is lowercase"
70 )]
71 if !path.as_str().ends_with(".md") {
72 continue;
73 }
74 let text = std::fs::read_to_string(path)?;
75 ids.extend(crate::embedded::rule_ids_in(&text));
76 }
77 Ok(ids)
78}
79
80fn active(target: &Utf8Path, sentinel: &Sentinel) -> bool {
86 match sentinel.rule {
87 RuleId::RecordedDimensionOnlyShrinks => {
88 Debt::read(target).is_ok_and(|debt| !debt.is_empty())
89 }
90 RuleId::ProjectSelectsOneSource => {
91 crate::domain::instance_config::InstanceConfig::read(target).is_ok_and(|declaration| {
92 declaration.writing_style.source
93 != crate::domain::instance_config::WritingSource::Builtin
94 })
95 }
96 _ => false,
97 }
98}
99
100pub fn needed(target: &Utf8Path, docs_root: DocsRoot) -> Result<Vec<Reconciliation>, AppError> {
106 let defined = local_rule_ids(target, docs_root)?;
107 Ok(SENTINELS
108 .iter()
109 .filter(|sentinel| active(target, sentinel))
110 .filter(|sentinel| !defined.contains(sentinel.rule.as_str()))
111 .map(|sentinel| Reconciliation { sentinel })
112 .collect())
113}
114
115#[derive(Debug, Clone, PartialEq, Eq)]
117pub enum Action {
118 Seed {
120 destination: Utf8PathBuf,
122 bytes: Vec<u8>,
124 },
125 Append {
128 destination: Utf8PathBuf,
130 block: String,
132 rewritten: String,
134 },
135 Checklist {
138 destination: Utf8PathBuf,
140 block: String,
142 },
143}
144
145#[derive(Debug, Clone, PartialEq, Eq)]
147pub struct Plan {
148 pub reconciliation: Reconciliation,
150 pub action: Action,
152 pub seed: Vec<u8>,
155}
156
157#[must_use]
160pub fn rule_block(seed: &str, rule: RuleId) -> Option<String> {
161 let heading = format!("### `{rule}`");
162 let mut lines = seed.lines().skip_while(|line| !line.starts_with(&heading));
163 let first = lines.next()?;
164 let mut block = format!("{first}\n");
165 for line in lines {
166 if line.starts_with("### ") || line.starts_with("## ") {
167 break;
168 }
169 block.push_str(line);
170 block.push('\n');
171 }
172 Some(format!("{}\n", block.trim_end_matches('\n')))
173}
174
175#[must_use]
178pub fn append_to_requirements(text: &str, block: &str) -> Option<String> {
179 let lines: Vec<&str> = text.lines().collect();
180 let start = lines.iter().position(|line| *line == "## Requirements")?;
181 let end = lines[start + 1..]
182 .iter()
183 .position(|line| line.starts_with("## "))
184 .map_or(lines.len(), |offset| start + 1 + offset);
185 let mut out = String::new();
186 for line in &lines[..end] {
187 out.push_str(line);
188 out.push('\n');
189 }
190 let trimmed = out.trim_end_matches('\n').to_string();
191 out = format!("{trimmed}\n\n{block}");
192 if end < lines.len() {
193 out.push('\n');
194 for line in &lines[end..] {
195 out.push_str(line);
196 out.push('\n');
197 }
198 }
199 Some(out)
200}
201
202pub fn plan(target: &Utf8Path, docs_root: DocsRoot) -> Result<Vec<Plan>, AppError> {
208 let mut plans = Vec::new();
209 for reconciliation in needed(target, docs_root)? {
210 let sentinel = reconciliation.sentinel;
211 let seed = crate::candidate::rendered_seed(&sentinel.source, docs_root)?;
212 let seed_text = std::str::from_utf8(&seed).map_err(anyhow::Error::from)?;
213 let block = rule_block(seed_text, sentinel.rule).ok_or_else(|| {
214 anyhow::anyhow!("{} does not define {}", sentinel.source, sentinel.rule)
215 })?;
216 let destination = resolve_destination(&sentinel.destination, docs_root);
217 let full = target.join(&destination);
218 let action = if full.is_file() {
219 let text = std::fs::read_to_string(&full)?;
220 match append_to_requirements(&text, &block) {
221 Some(rewritten)
222 if crate::embedded::rule_ids_in(&rewritten)
223 .any(|id| id == sentinel.rule.as_str()) =>
224 {
225 Action::Append {
226 destination,
227 block,
228 rewritten,
229 }
230 }
231 _ => Action::Checklist { destination, block },
232 }
233 } else {
234 Action::Seed {
235 destination,
236 bytes: seed.clone(),
237 }
238 };
239 plans.push(Plan {
240 reconciliation,
241 action,
242 seed,
243 });
244 }
245 Ok(plans)
246}
247
248fn with_adopted_record(
254 document: &mut serde_json::Value,
255 source: &str,
256 destination: &Utf8Path,
257 bytes: &[u8],
258 baseline: &[u8],
259) -> Result<(), AppError> {
260 let digest = Sha256::of(bytes).to_string();
261 let Some(entries) = document
262 .get_mut("adopted_files")
263 .and_then(serde_json::Value::as_array_mut)
264 else {
265 return Err(AppError::ManifestInvalid(
266 "adopted_files is not an array".to_string(),
267 ));
268 };
269 let recorded = entries.iter_mut().find(|entry| {
270 entry.get("destination").and_then(serde_json::Value::as_str) == Some(destination.as_str())
271 });
272 match recorded {
273 Some(entry) => entry["sha256"] = serde_json::Value::String(digest),
274 None => entries.push(serde_json::json!({
275 "source": source,
276 "destination": destination.as_str(),
277 "sha256": digest,
278 "baseline_sha256": Sha256::of(baseline).to_string(),
279 })),
280 }
281 Ok(())
282}
283
284type Write = (Utf8PathBuf, Vec<u8>, &'static Sentinel, Vec<u8>);
287
288fn preflight(target: &Utf8Path, plans: &[Plan]) -> Result<Vec<Write>, AppError> {
291 let mut writes: Vec<Write> = Vec::new();
292 for plan in plans {
293 let sentinel = plan.reconciliation.sentinel;
294 match &plan.action {
295 Action::Seed { destination, bytes } => {
296 writes.push((
297 destination.clone(),
298 bytes.clone(),
299 sentinel,
300 plan.seed.clone(),
301 ));
302 }
303 Action::Append {
304 destination,
305 rewritten,
306 ..
307 } => writes.push((
308 destination.clone(),
309 rewritten.clone().into_bytes(),
310 sentinel,
311 plan.seed.clone(),
312 )),
313 Action::Checklist { destination, .. } => {
314 return Err(AppError::Refused(format!(
315 "{destination} is not in a shape this command rewrites; add the rule by hand"
316 )));
317 }
318 }
319 }
320 for (destination, _, _, _) in &writes {
321 crate::adapters::fs::check_destination(target, destination)
322 .map_err(|refusal| AppError::Refused(format!("{destination}: {refusal}")))?;
323 }
324 let manifest_relative = Utf8Path::new(crate::domain::manifest::MANIFEST_PATH);
325 crate::adapters::fs::check_destination(target, manifest_relative)
326 .map_err(|refusal| AppError::Refused(format!("{manifest_relative}: {refusal}")))?;
327 Ok(writes)
328}
329
330fn restore(target: &Utf8Path, backups: &[(Utf8PathBuf, Option<Vec<u8>>)]) -> Vec<Utf8PathBuf> {
336 let mut unrestored = Vec::new();
337 for (destination, previous) in backups {
338 let full = target.join(destination);
339 let current = match std::fs::read(&full) {
343 Ok(bytes) => Some(Some(bytes)),
344 Err(error) if error.kind() == std::io::ErrorKind::NotFound => Some(None),
345 Err(_) => None,
346 };
347 if current.as_ref() == Some(previous) {
348 continue;
349 }
350 let put_back = previous.as_ref().map_or_else(
353 || match std::fs::remove_file(&full) {
354 Ok(()) => true,
355 Err(error) => error.kind() == std::io::ErrorKind::NotFound,
356 },
357 |bytes| write_atomic(&full, bytes).is_ok(),
358 );
359 if !put_back {
360 unrestored.push(destination.clone());
361 }
362 }
363 unrestored
364}
365
366pub fn apply_all(target: &Utf8Path, plans: &[Plan]) -> Result<Vec<Utf8PathBuf>, AppError> {
383 let manifest_relative = Utf8Path::new(crate::domain::manifest::MANIFEST_PATH);
384 let writes = preflight(target, plans)?;
385 let manifest_text = std::fs::read_to_string(target.join(manifest_relative))?;
386 let mut document: serde_json::Value = serde_json::from_str(&manifest_text)
387 .map_err(|error| AppError::ManifestInvalid(error.to_string()))?;
388
389 let mut backups: Vec<(Utf8PathBuf, Option<Vec<u8>>)> = Vec::new();
390 let mut attempt = |backups: &mut Vec<(Utf8PathBuf, Option<Vec<u8>>)>| -> Result<(), AppError> {
391 for (destination, bytes, sentinel, seed) in &writes {
392 let full = target.join(destination);
393 let previous = if full.is_file() {
394 Some(std::fs::read(&full)?)
395 } else {
396 None
397 };
398 backups.push((destination.clone(), previous));
399 write_atomic(&full, bytes)?;
400 let written = std::fs::read_to_string(&full)?;
401 if !crate::embedded::rule_ids_in(&written).any(|id| id == sentinel.rule.as_str()) {
402 return Err(AppError::Refused(format!(
403 "{destination} did not define `{}` after the rewrite",
404 sentinel.rule
405 )));
406 }
407 with_adopted_record(&mut document, &sentinel.source, destination, bytes, seed)?;
408 }
409 backups.push((
410 manifest_relative.to_path_buf(),
411 Some(manifest_text.clone().into_bytes()),
412 ));
413 let rendered = serde_json::to_string_pretty(&document)
414 .map_err(|error| AppError::ManifestInvalid(error.to_string()))?;
415 write_atomic(
416 &target.join(manifest_relative),
417 format!("{rendered}\n").as_bytes(),
418 )?;
419 Ok(())
420 };
421 if let Err(error) = attempt(&mut backups) {
422 let unrestored = restore(target, &backups);
423 let cause = match error {
424 AppError::Refused(reason) => reason,
425 other => format!("reconciliation aborted: {other}"),
426 };
427 if unrestored.is_empty() {
428 return Err(AppError::Refused(format!(
429 "{cause}; every file is restored"
430 )));
431 }
432 let paths: Vec<&str> = unrestored.iter().map(|p| p.as_str()).collect();
433 return Err(AppError::Refused(format!(
434 "{cause}; restoration is incomplete, verify by hand: {}",
435 paths.join(" ")
436 )));
437 }
438 Ok(writes
439 .into_iter()
440 .map(|(destination, _, _, _)| destination)
441 .collect())
442}
443
444#[cfg(test)]
445mod tests {
446 use super::*;
447
448 const SPEC: &str = "# Sample\n\n## Purpose\n\nOurs.\n\n## Requirements\n\n### `sample:first` — First\n\nThe author MUST keep it.\n\n#### Scenario: One\n\n- GIVEN x\n- WHEN y\n- THEN z\n\nVerify: `true`\n\n## Unenforced\n\n| Rule | Reviewer confirms |\n| --- | --- |\n";
449
450 const BLOCK: &str = "### `sample:second` — Second\n\nThe author MUST add it.\n\n#### Scenario: Two\n\n- GIVEN a\n- WHEN b\n- THEN c\n\nVerify: `true`\n";
451
452 #[test]
453 fn the_rule_block_runs_from_its_heading_to_the_next() {
454 let seed = format!("{SPEC}\n{BLOCK}");
455 let block = rule_block(&seed, RuleId::RecordedDimensionOnlyShrinks);
456 assert!(block.is_none(), "a rule the seed lacks is not found");
457 let debt =
458 std::str::from_utf8(crate::embedded::asset("_docs/specs/SPEC-budget-debt.md").unwrap())
459 .unwrap();
460 let block = rule_block(debt, RuleId::RecordedDimensionOnlyShrinks).unwrap();
461 assert!(block.starts_with("### `budget-debt:a-recorded-dimension-only-shrinks`"));
462 assert!(block.contains("Verify:"));
463 assert!(!block.contains("debt-is-created-by-an-explicit-act"));
464 assert!(block.ends_with('\n') && !block.ends_with("\n\n"));
465 }
466
467 #[test]
468 fn the_block_is_appended_before_the_next_section_and_everything_else_survives() {
469 let out = append_to_requirements(SPEC, BLOCK).unwrap();
470 let ids: Vec<String> = crate::embedded::rule_ids_in(&out).collect();
471 assert_eq!(
472 ids,
473 vec!["sample:first".to_string(), "sample:second".to_string()]
474 );
475 assert!(out.contains("Verify: `true`\n\n### `sample:second`"));
476 assert!(out.contains("Verify: `true`\n\n## Unenforced\n"));
477 assert!(out.ends_with("| --- | --- |\n"));
478 assert!(out.starts_with("# Sample\n\n## Purpose\n\nOurs.\n"));
479 }
480
481 #[test]
482 fn a_file_whose_requirements_close_it_takes_the_block_at_the_end() {
483 let spec = SPEC.split("## Unenforced").next().unwrap();
484 let out = append_to_requirements(spec, BLOCK).unwrap();
485 assert!(out.ends_with(&format!("\n\n{BLOCK}")));
486 }
487
488 #[test]
489 fn a_file_without_a_requirements_section_is_not_rewritten() {
490 assert!(append_to_requirements("# Ours\n\nProse only.\n", BLOCK).is_none());
491 }
492}