Skip to main content

spec_driven_docs/services/
policy.rs

1//! Which declarations an instance's own specifications do not yet
2//! authorize.
3//!
4//! A project overruling a specification it owns is exercising ownership, so
5//! nothing here fails. This reads the declarations, reads the sentinel each
6//! one needs, and reports the ones whose sentinel the local specifications
7//! lack. `sdd verify` prints each as a note, and `sdd policy reconcile`
8//! offers the correction.
9//!
10//! The correction is conservative. It seeds the owning specification where
11//! the instance lacks it, and otherwise appends the sentinel's rule block,
12//! taken from the embedded seed, to the end of the local file's
13//! Requirements section. It never rewrites a sentence the project may have
14//! edited: a rule block is self-contained, and the unique-id gate catches a
15//! collision. A file not in that shape gets a checklist and no write.
16
17use 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/// One declaration its specification does not authorize.
32#[derive(Debug, Clone, PartialEq, Eq)]
33pub struct Reconciliation {
34    /// The sentinel the specifications lack.
35    pub sentinel: &'static Sentinel,
36}
37
38impl Reconciliation {
39    /// The note `sdd verify` prints for it.
40    #[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
51/// Every rule ID the instance's own specifications define.
52///
53/// # Errors
54///
55/// I/O errors when a specification cannot be read.
56pub 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
80/// Whether the declaration a sentinel authorizes is active at the target.
81///
82/// A debt file that does not parse is not active: the verifier reports it
83/// as a failure of its own, and a note beside that failure would name a
84/// second problem where there is one.
85fn 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
100/// Every active declaration whose sentinel the local specifications lack.
101///
102/// # Errors
103///
104/// I/O errors when a specification cannot be read.
105pub 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/// What one reconciliation would do.
116#[derive(Debug, Clone, PartialEq, Eq)]
117pub enum Action {
118    /// The owning specification is absent: write the seed.
119    Seed {
120        /// Where it lands.
121        destination: Utf8PathBuf,
122        /// The seed's bytes.
123        bytes: Vec<u8>,
124    },
125    /// The owning specification is present and recognized: append the rule
126    /// block to its Requirements section.
127    Append {
128        /// The file.
129        destination: Utf8PathBuf,
130        /// The rule block, as the seed states it.
131        block: String,
132        /// The whole file after the append.
133        rewritten: String,
134    },
135    /// The owning specification is present and not in a recognized shape:
136    /// print the block and write nothing.
137    Checklist {
138        /// The file.
139        destination: Utf8PathBuf,
140        /// The rule block to add by hand.
141        block: String,
142    },
143}
144
145/// One reconciliation and what it would do.
146#[derive(Debug, Clone, PartialEq, Eq)]
147pub struct Plan {
148    /// The declaration and its sentinel.
149    pub reconciliation: Reconciliation,
150    /// The action.
151    pub action: Action,
152    /// The owning seed as rendered for the instance's root: the baseline a
153    /// record added for the destination carries.
154    pub seed: Vec<u8>,
155}
156
157/// The sentinel's rule block, from the heading to the line before the next
158/// heading, as the embedded seed states it.
159#[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/// The file with the block appended to the end of its Requirements section,
176/// or `None` where the file has no such section to append to.
177#[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
202/// Every reconciliation the target needs, with what each would do.
203///
204/// # Errors
205///
206/// I/O errors when a specification cannot be read.
207pub 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
248/// The manifest's JSON with one adopted record updated, or added where the
249/// file was absent.
250///
251/// A write that left the record behind would report the instance as drifted
252/// the moment it was made correct.
253pub(crate) fn 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
284/// One destination's bytes, the sentinel they answer, and the rendered seed
285/// the record's baseline takes.
286type Write = (Utf8PathBuf, Vec<u8>, &'static Sentinel, Vec<u8>);
287
288/// The writes a set of plans amounts to, every destination checked to stay
289/// inside the target, or the refusal that stops the whole apply.
290fn 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
330/// Put every backed-up path back, and name the ones that could not be.
331///
332/// A path whose bytes already equal its backup is left alone, so a file
333/// the failure never reached is not rewritten through the same failing
334/// primitive.
335fn 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        // Only an absent file is evidence of absence. Any other read failure
340        // says nothing about the file, so the restoration is attempted and
341        // its own result decides.
342        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        // A removal that fails for any reason other than the file already
351        // being gone is a restoration that did not happen.
352        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
366/// Carry out every plan as one transaction, and report the files written.
367///
368/// Every destination and the manifest are checked to stay inside the
369/// target before a byte lands, every existing file is backed up, each
370/// specification is written atomically and re-read to confirm it defines
371/// its sentinel, and the manifest is written last with every record moved
372/// at once. Any failure restores every path this call touched, so the
373/// operator never holds an adopted file the record does not describe, or
374/// one plan applied and another not.
375///
376/// # Errors
377///
378/// [`AppError::Refused`] for a checklist plan, a destination that leaves
379/// the target, or a rewrite that does not define its sentinel, and
380/// manifest and I/O errors when the tree cannot be read or written. The
381/// target is restored before any of these returns.
382pub 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}