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}
153
154/// The sentinel's rule block, from the heading to the line before the next
155/// heading, as the embedded seed states it.
156#[must_use]
157pub fn rule_block(seed: &str, rule: RuleId) -> Option<String> {
158    let heading = format!("### `{rule}`");
159    let mut lines = seed.lines().skip_while(|line| !line.starts_with(&heading));
160    let first = lines.next()?;
161    let mut block = format!("{first}\n");
162    for line in lines {
163        if line.starts_with("### ") || line.starts_with("## ") {
164            break;
165        }
166        block.push_str(line);
167        block.push('\n');
168    }
169    Some(format!("{}\n", block.trim_end_matches('\n')))
170}
171
172/// The file with the block appended to the end of its Requirements section,
173/// or `None` where the file has no such section to append to.
174#[must_use]
175pub fn append_to_requirements(text: &str, block: &str) -> Option<String> {
176    let lines: Vec<&str> = text.lines().collect();
177    let start = lines.iter().position(|line| *line == "## Requirements")?;
178    let end = lines[start + 1..]
179        .iter()
180        .position(|line| line.starts_with("## "))
181        .map_or(lines.len(), |offset| start + 1 + offset);
182    let mut out = String::new();
183    for line in &lines[..end] {
184        out.push_str(line);
185        out.push('\n');
186    }
187    let trimmed = out.trim_end_matches('\n').to_string();
188    out = format!("{trimmed}\n\n{block}");
189    if end < lines.len() {
190        out.push('\n');
191        for line in &lines[end..] {
192            out.push_str(line);
193            out.push('\n');
194        }
195    }
196    Some(out)
197}
198
199/// Every reconciliation the target needs, with what each would do.
200///
201/// # Errors
202///
203/// I/O errors when a specification cannot be read.
204pub fn plan(
205    target: &Utf8Path,
206    docs_root: DocsRoot,
207    bundle: &dyn crate::release::ReleaseBundle,
208) -> Result<Vec<Plan>, AppError> {
209    let mut plans = Vec::new();
210    for reconciliation in needed(target, docs_root)? {
211        let sentinel = reconciliation.sentinel;
212        let seed = bundle.artifact(&sentinel.source)?;
213        let seed_text = std::str::from_utf8(&seed).map_err(anyhow::Error::from)?;
214        let block = rule_block(seed_text, sentinel.rule).ok_or_else(|| {
215            anyhow::anyhow!("{} does not define {}", sentinel.source, sentinel.rule)
216        })?;
217        let destination = resolve_destination(&sentinel.destination, docs_root);
218        let full = target.join(&destination);
219        let action = if full.is_file() {
220            let text = std::fs::read_to_string(&full)?;
221            match append_to_requirements(&text, &block) {
222                Some(rewritten)
223                    if crate::embedded::rule_ids_in(&rewritten)
224                        .any(|id| id == sentinel.rule.as_str()) =>
225                {
226                    Action::Append {
227                        destination,
228                        block,
229                        rewritten,
230                    }
231                }
232                _ => Action::Checklist { destination, block },
233            }
234        } else {
235            Action::Seed {
236                destination,
237                bytes: seed.clone(),
238            }
239        };
240        plans.push(Plan {
241            reconciliation,
242            action,
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.
253fn 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);
285
286/// The writes a set of plans amounts to, every destination checked to stay
287/// inside the target, or the refusal that stops the whole apply.
288fn preflight(target: &Utf8Path, plans: &[Plan]) -> Result<Vec<Write>, AppError> {
289    let mut writes: Vec<Write> = Vec::new();
290    for plan in plans {
291        let sentinel = plan.reconciliation.sentinel;
292        match &plan.action {
293            Action::Seed { destination, bytes } => {
294                writes.push((destination.clone(), bytes.clone(), sentinel));
295            }
296            Action::Append {
297                destination,
298                rewritten,
299                ..
300            } => writes.push((
301                destination.clone(),
302                rewritten.clone().into_bytes(),
303                sentinel,
304            )),
305            Action::Checklist { destination, .. } => {
306                return Err(AppError::Refused(format!(
307                    "{destination} is not in a shape this command rewrites; add the rule by hand"
308                )));
309            }
310        }
311    }
312    for (destination, _, _) in &writes {
313        crate::adapters::fs::check_destination(target, destination)
314            .map_err(|refusal| AppError::Refused(format!("{destination}: {refusal}")))?;
315    }
316    let manifest_relative = Utf8Path::new(crate::domain::manifest::MANIFEST_PATH);
317    crate::adapters::fs::check_destination(target, manifest_relative)
318        .map_err(|refusal| AppError::Refused(format!("{manifest_relative}: {refusal}")))?;
319    Ok(writes)
320}
321
322/// Put every backed-up path back, and name the ones that could not be.
323///
324/// A path whose bytes already equal its backup is left alone, so a file
325/// the failure never reached is not rewritten through the same failing
326/// primitive.
327fn restore(target: &Utf8Path, backups: &[(Utf8PathBuf, Option<Vec<u8>>)]) -> Vec<Utf8PathBuf> {
328    let mut unrestored = Vec::new();
329    for (destination, previous) in backups {
330        let full = target.join(destination);
331        // Only an absent file is evidence of absence. Any other read failure
332        // says nothing about the file, so the restoration is attempted and
333        // its own result decides.
334        let current = match std::fs::read(&full) {
335            Ok(bytes) => Some(Some(bytes)),
336            Err(error) if error.kind() == std::io::ErrorKind::NotFound => Some(None),
337            Err(_) => None,
338        };
339        if current.as_ref() == Some(previous) {
340            continue;
341        }
342        // A removal that fails for any reason other than the file already
343        // being gone is a restoration that did not happen.
344        let put_back = previous.as_ref().map_or_else(
345            || match std::fs::remove_file(&full) {
346                Ok(()) => true,
347                Err(error) => error.kind() == std::io::ErrorKind::NotFound,
348            },
349            |bytes| write_atomic(&full, bytes).is_ok(),
350        );
351        if !put_back {
352            unrestored.push(destination.clone());
353        }
354    }
355    unrestored
356}
357
358/// Carry out every plan as one transaction, and report the files written.
359///
360/// Every destination and the manifest are checked to stay inside the
361/// target before a byte lands, every existing file is backed up, each
362/// specification is written atomically and re-read to confirm it defines
363/// its sentinel, and the manifest is written last with every record moved
364/// at once. Any failure restores every path this call touched, so the
365/// operator never holds an adopted file the record does not describe, or
366/// one plan applied and another not.
367///
368/// # Errors
369///
370/// [`AppError::Refused`] for a checklist plan, a destination that leaves
371/// the target, or a rewrite that does not define its sentinel, and
372/// manifest and I/O errors when the tree cannot be read or written. The
373/// target is restored before any of these returns.
374pub fn apply_all(
375    target: &Utf8Path,
376    plans: &[Plan],
377    bundle: &dyn crate::release::ReleaseBundle,
378) -> Result<Vec<Utf8PathBuf>, AppError> {
379    let manifest_relative = Utf8Path::new(crate::domain::manifest::MANIFEST_PATH);
380    let writes = preflight(target, plans)?;
381    let manifest_text = std::fs::read_to_string(target.join(manifest_relative))?;
382    let mut document: serde_json::Value = serde_json::from_str(&manifest_text)
383        .map_err(|error| AppError::ManifestInvalid(error.to_string()))?;
384
385    let mut backups: Vec<(Utf8PathBuf, Option<Vec<u8>>)> = Vec::new();
386    let mut attempt = |backups: &mut Vec<(Utf8PathBuf, Option<Vec<u8>>)>| -> Result<(), AppError> {
387        for (destination, bytes, sentinel) in &writes {
388            let full = target.join(destination);
389            let previous = if full.is_file() {
390                Some(std::fs::read(&full)?)
391            } else {
392                None
393            };
394            backups.push((destination.clone(), previous));
395            write_atomic(&full, bytes)?;
396            let written = std::fs::read_to_string(&full)?;
397            if !crate::embedded::rule_ids_in(&written).any(|id| id == sentinel.rule.as_str()) {
398                return Err(AppError::Refused(format!(
399                    "{destination} did not define `{}` after the rewrite",
400                    sentinel.rule
401                )));
402            }
403            let seed = bundle.artifact(&sentinel.source)?;
404            with_adopted_record(&mut document, &sentinel.source, destination, bytes, &seed)?;
405        }
406        backups.push((
407            manifest_relative.to_path_buf(),
408            Some(manifest_text.clone().into_bytes()),
409        ));
410        let rendered = serde_json::to_string_pretty(&document)
411            .map_err(|error| AppError::ManifestInvalid(error.to_string()))?;
412        write_atomic(
413            &target.join(manifest_relative),
414            format!("{rendered}\n").as_bytes(),
415        )?;
416        Ok(())
417    };
418    if let Err(error) = attempt(&mut backups) {
419        let unrestored = restore(target, &backups);
420        let cause = match error {
421            AppError::Refused(reason) => reason,
422            other => format!("reconciliation aborted: {other}"),
423        };
424        if unrestored.is_empty() {
425            return Err(AppError::Refused(format!(
426                "{cause}; every file is restored"
427            )));
428        }
429        let paths: Vec<&str> = unrestored.iter().map(|p| p.as_str()).collect();
430        return Err(AppError::Refused(format!(
431            "{cause}; restoration is incomplete, verify by hand: {}",
432            paths.join(" ")
433        )));
434    }
435    Ok(writes
436        .into_iter()
437        .map(|(destination, _, _)| destination)
438        .collect())
439}
440
441#[cfg(test)]
442mod tests {
443    use super::*;
444
445    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";
446
447    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";
448
449    #[test]
450    fn the_rule_block_runs_from_its_heading_to_the_next() {
451        let seed = format!("{SPEC}\n{BLOCK}");
452        let block = rule_block(&seed, RuleId::RecordedDimensionOnlyShrinks);
453        assert!(block.is_none(), "a rule the seed lacks is not found");
454        let debt =
455            std::str::from_utf8(crate::embedded::asset("_docs/specs/SPEC-budget-debt.md").unwrap())
456                .unwrap();
457        let block = rule_block(debt, RuleId::RecordedDimensionOnlyShrinks).unwrap();
458        assert!(block.starts_with("### `budget-debt:a-recorded-dimension-only-shrinks`"));
459        assert!(block.contains("Verify:"));
460        assert!(!block.contains("debt-is-created-by-an-explicit-act"));
461        assert!(block.ends_with('\n') && !block.ends_with("\n\n"));
462    }
463
464    #[test]
465    fn the_block_is_appended_before_the_next_section_and_everything_else_survives() {
466        let out = append_to_requirements(SPEC, BLOCK).unwrap();
467        let ids: Vec<String> = crate::embedded::rule_ids_in(&out).collect();
468        assert_eq!(
469            ids,
470            vec!["sample:first".to_string(), "sample:second".to_string()]
471        );
472        assert!(out.contains("Verify: `true`\n\n### `sample:second`"));
473        assert!(out.contains("Verify: `true`\n\n## Unenforced\n"));
474        assert!(out.ends_with("| --- | --- |\n"));
475        assert!(out.starts_with("# Sample\n\n## Purpose\n\nOurs.\n"));
476    }
477
478    #[test]
479    fn a_file_whose_requirements_close_it_takes_the_block_at_the_end() {
480        let spec = SPEC.split("## Unenforced").next().unwrap();
481        let out = append_to_requirements(spec, BLOCK).unwrap();
482        assert!(out.ends_with(&format!("\n\n{BLOCK}")));
483    }
484
485    #[test]
486    fn a_file_without_a_requirements_section_is_not_rewritten() {
487        assert!(append_to_requirements("# Ours\n\nProse only.\n", BLOCK).is_none());
488    }
489}
spec_driven_docs/services/policy.rs

spec_driven_docs/services/
policy.rs
