Skip to main content

spec_driven_docs/services/
verifier.rs

1//! Offline instance verification.
2//!
3//! Reads the manifest, compares every recorded projection to the disk, holds
4//! the managed block to its recorded hash, checks the block's `sdd` entries
5//! resolve, scans for duplicate rule IDs, and compares the instance's canon
6//! version to this binary's. Everything is local: no network, no canon
7//! checkout, no ambient tools. What gets recorded is the installer's
8//! business; this only holds the record to the disk.
9
10use camino::Utf8Path;
11
12use crate::adapters::fs::{DestinationRefusal, check_destination, sha256_file};
13use crate::domain::gate_id::GateId;
14use crate::domain::manifest::{MANIFEST_PATH, Manifest, ManifestParseError};
15use crate::domain::marker;
16use crate::domain::paths::{AGENTS_DIGEST_PATH, HOOKS_CONFIG_PATH};
17use crate::domain::version::CanonVersion;
18use crate::error::AppError;
19
20/// What a verification run reports.
21#[derive(Debug, Default)]
22pub struct VerifyReport {
23    /// Every line to print, failures and notes alike, in order.
24    pub lines: Vec<String>,
25    /// How many lines are failures.
26    pub failures: usize,
27    /// How many managed files are missing, symlinked, or byte-drifted.
28    pub managed_drift: usize,
29    /// How many adopted files await reconciliation.
30    pub adopted_drift: usize,
31}
32
33impl VerifyReport {
34    fn fail(&mut self, line: impl Into<String>) {
35        self.lines.push(line.into());
36        self.failures += 1;
37    }
38
39    fn note(&mut self, line: impl Into<String>) {
40        self.lines.push(line.into());
41    }
42}
43
44pub(crate) fn read_manifest(target: &Utf8Path) -> Result<Manifest, AppError> {
45    let path = target.join(MANIFEST_PATH);
46    if reached_through_symlink(target, Utf8Path::new(MANIFEST_PATH)) {
47        return Err(AppError::ManifestInvalid(
48            "manifest reached through a symlink".to_string(),
49        ));
50    }
51    if !path.is_file() {
52        return Err(AppError::ManifestMissing(path));
53    }
54    let text = std::fs::read_to_string(&path)?;
55    Manifest::parse(&text).map_err(|error| match error {
56        ManifestParseError::Invalid(detail) => AppError::ManifestInvalid(detail),
57        other => AppError::ManifestInvalid(other.to_string()),
58    })
59}
60
61fn check_block_entries(block: &str, report: &mut VerifyReport) {
62    let mut sdd_entries = 0usize;
63    for line in block.lines() {
64        let Some(entry) = line.trim_start().strip_prefix("entry: ") else {
65            continue;
66        };
67        let words: Vec<&str> = entry.split_whitespace().collect();
68        let Some(gate_position) = words.iter().position(|word| *word == "gate") else {
69            if words.last() == Some(&"verify") {
70                sdd_entries += 1;
71            }
72            continue;
73        };
74        sdd_entries += 1;
75        match words.get(gate_position + 1) {
76            Some(id) if id.parse::<GateId>().is_ok() => {}
77            Some(id) => report.fail(format!(
78                "FAIL managed block entry names an unknown gate: {id}"
79            )),
80            None => report.fail(format!("FAIL managed block entry names no gate: {entry}")),
81        }
82    }
83    if sdd_entries == 0 {
84        report.fail("FAIL managed block wires no sdd entry");
85    }
86}
87
88fn reached_through_symlink(target: &Utf8Path, destination: &Utf8Path) -> bool {
89    matches!(
90        check_destination(target, destination),
91        Err(DestinationRefusal::SymlinkEscape)
92    )
93}
94
95/// The declaration and the managed block must say the same thing.
96///
97/// The block is rendered from the declaration, so a difference means the
98/// project edited the declaration and nothing reached the block. That is a
99/// real disagreement between two artifacts that claim to agree, not drift in
100/// a file the project owns, so it fails and names the command that fixes it.
101///
102/// A declaration that does not parse fails once here rather than once from
103/// every always-run gate.
104fn check_declaration(target: &Utf8Path, manifest: &Manifest, report: &mut VerifyReport) {
105    let declaration = match crate::domain::instance_config::InstanceConfig::read(target) {
106        Ok(declaration) => declaration,
107        Err(error) => {
108            report.fail(format!("FAIL {error}"));
109            return;
110        }
111    };
112
113    // The documentation block carries the writing-style route the
114    // declaration selects, so a stale route is the same disagreement as a
115    // stale hook filter, and the same command repairs it.
116    let agents = target.join(crate::commands::hooks::AGENTS);
117    let agents_recorded = manifest
118        .integration_blocks
119        .iter()
120        .any(|block| block.path.as_str() == crate::commands::hooks::AGENTS);
121    if agents_recorded
122        && let Ok(host) = std::fs::read_to_string(&agents)
123        && let Some(region) = crate::domain::marker::block_region_with(
124            &host,
125            crate::domain::marker::AGENTS_BEGIN,
126            crate::domain::marker::AGENTS_END,
127        )
128    {
129        let expected = crate::services::agents_render::render_block(
130            manifest.docs_root.as_str(),
131            &declaration.writing_style,
132        );
133        if region != expected {
134            report.fail(format!(
135                "FAIL the documentation block in {} does not match the declaration; run 'sdd hooks --apply'",
136                crate::commands::hooks::AGENTS
137            ));
138        }
139    }
140
141    let config = target.join(crate::commands::hooks::CONFIG);
142    let Ok(host) = std::fs::read_to_string(&config) else {
143        return;
144    };
145    // Measure from the host stripped of its block, which is what the
146    // installer measures. With the block still in place the first item under
147    // `repos:` is the block's own, and the depth read back differs.
148    let Ok((base, _)) = crate::domain::marker::split_block(&host) else {
149        return;
150    };
151    // The indentation is the host file's, measured the same way the
152    // installer measures it. Rendering with the default would report every
153    // instance whose `repos:` items sit at another depth.
154    let Ok(indent) = crate::domain::marker::splice_indent(&base) else {
155        return;
156    };
157    let rendered = crate::services::hooks_render::render_block(
158        &crate::services::hooks_render::RenderOptions {
159            docs_root: manifest.docs_root.to_string(),
160            indent,
161            declaration,
162            ..crate::services::hooks_render::RenderOptions::default()
163        },
164    );
165    // Compare per gate rather than over the whole region. A block an older
166    // release rendered carries hooks this renderer no longer emits, and the
167    // upgrade rewrites those; what this names is the wiring a declaration
168    // edit left stale.
169    let expected = crate::services::hooks_render::selectors(&rendered);
170    let Some(region) = crate::domain::marker::block_region(&host) else {
171        return;
172    };
173    let found = crate::services::hooks_render::selectors(&region);
174    for (id, wanted) in &expected {
175        let Some(actual) = found.get(id) else {
176            continue;
177        };
178        if actual != wanted {
179            report.fail(format!(
180                "FAIL the wiring for {id} in {} does not match the declaration; run 'sdd hooks --apply'",
181                crate::commands::hooks::CONFIG
182            ));
183        }
184    }
185}
186
187/// Where the canon's own record keeps the artifacts every skill shares.
188///
189/// `sdd self-manifest` records them as managed entries at their authored
190/// paths, and no consumer landing writes anything there, so their presence
191/// is what tells the two layouts apart.
192const CANON_ONLY_ROOT: &str = "skill-shared/";
193
194/// The manifest must record every projection the profile declares — an
195/// omitted record is an owned file the verifier would silently stop
196/// holding. Applies when the instance is at this binary's version, in
197/// whichever of the two layouts the record claims.
198///
199/// The layout is read from what only the canon's self-manifest records: a
200/// managed entry under `skill-shared/`. That recognizes the ordinary canon
201/// and consumer records. It authenticates nothing, because the record is a
202/// file a user can edit, and changing the claimed layout changes which
203/// obligations this check enforces. The canon branch requires the managed
204/// projection sources, the embedded specs, the canon templates, and the
205/// pre-commit block. The consumer branch requires every declared
206/// destination and both integration blocks. Neither set contains the
207/// other, and the canon branch does not require the whole skill inventory.
208///
209/// A seed that yields, and that the record does not name, is not owed:
210/// the target root held a file of its set, so the landing did not write it.
211fn check_projection_against(
212    released: &crate::domain::projection::Declaration,
213    manifest: &Manifest,
214    present_at_root: &[String],
215    report: &mut VerifyReport,
216) {
217    if manifest.canon_version != CanonVersion::current() {
218        return;
219    }
220    let Some(declaration) = released.profile(manifest.profile) else {
221        return;
222    };
223    let managed: std::collections::BTreeSet<&str> = manifest
224        .managed_files
225        .iter()
226        .map(|entry| entry.destination.as_str())
227        .collect();
228    let adopted: std::collections::BTreeSet<&str> = manifest
229        .adopted_files
230        .iter()
231        .map(|entry| entry.destination.as_str())
232        .collect();
233
234    let self_layout = managed
235        .iter()
236        .any(|destination| destination.starts_with(CANON_ONLY_ROOT));
237
238    let mut expected: std::collections::BTreeSet<String> = std::collections::BTreeSet::new();
239    let mut missing: Vec<String> = Vec::new();
240    if self_layout {
241        for projection in declaration.managed {
242            expected.insert(projection.source.clone());
243        }
244        for file in crate::embedded::SPECS.files() {
245            if let Some(name) = file.path().as_os_str().to_str() {
246                expected.insert(format!("_docs/specs/{name}"));
247            }
248        }
249        for template in crate::domain::profile::CANON_TEMPLATES.iter() {
250            expected.insert((*template).to_string());
251        }
252        for destination in &expected {
253            if !managed.contains(destination.as_str()) && !adopted.contains(destination.as_str()) {
254                missing.push(destination.clone());
255            }
256        }
257    } else {
258        for projection in declaration.managed {
259            let destination = crate::domain::profile::resolve_destination(
260                &projection.destination,
261                manifest.docs_root,
262            );
263            if !managed.contains(destination.as_str()) {
264                missing.push(destination.to_string());
265            }
266        }
267        for projection in declaration.adopted {
268            let destination = crate::domain::profile::resolve_destination(
269                &projection.destination,
270                manifest.docs_root,
271            );
272            if adopted.contains(destination.as_str()) {
273                continue;
274            }
275            let yielded = projection.yield_set().is_some_and(|set| {
276                set.names()
277                    .any(|name| present_at_root.iter().any(|held| held == name))
278            });
279            if !yielded {
280                missing.push(destination.to_string());
281            }
282        }
283    }
284    for destination in missing {
285        report.fail(format!(
286            "FAIL manifest omits a declared projection: {destination}"
287        ));
288    }
289    // Every installed instance carries both integration blocks. The canon's
290    // own layout carries the pre-commit block, which `just hooks` renders;
291    // its root AGENTS.md is release-kit-owned and outside this projection.
292    let required: &[&str] = if self_layout {
293        &[HOOKS_CONFIG_PATH]
294    } else {
295        &[HOOKS_CONFIG_PATH, AGENTS_DIGEST_PATH]
296    };
297    for path in required {
298        if !manifest
299            .integration_blocks
300            .iter()
301            .any(|block| block.path.as_str() == *path)
302        {
303            report.fail(format!(
304                "FAIL manifest records no integration block for {path}"
305            ));
306        }
307    }
308}
309
310/// Verify an installed instance offline.
311///
312/// # Errors
313///
314/// [`AppError::ManifestMissing`] / [`AppError::ManifestInvalid`] when the
315/// record itself cannot be trusted, and I/O errors when the disk cannot be
316/// read; recorded-versus-disk differences are reported, not raised.
317pub fn verify(target: &Utf8Path) -> Result<VerifyReport, AppError> {
318    let manifest = read_manifest(target)?;
319    let released = &*crate::domain::profile::DECLARATION;
320    let mut report = VerifyReport::default();
321
322    check_declaration(target, &manifest, &mut report);
323
324    for entry in &manifest.managed_files {
325        let file = target.join(&entry.destination);
326        if reached_through_symlink(target, &entry.destination) {
327            report.managed_drift += 1;
328            report.fail(format!(
329                "FAIL managed file reached through a symlink: {}",
330                entry.destination
331            ));
332            continue;
333        }
334        if !file.is_file() {
335            report.managed_drift += 1;
336            report.fail(format!("FAIL missing managed file: {}", entry.destination));
337            continue;
338        }
339        if sha256_file(&file)? != entry.sha256 {
340            report.managed_drift += 1;
341            report.fail(format!("FAIL managed drift: {}", entry.destination));
342        }
343    }
344
345    for entry in &manifest.adopted_files {
346        let file = target.join(&entry.destination);
347        if reached_through_symlink(target, &entry.destination) {
348            report.fail(format!(
349                "FAIL adopted file reached through a symlink: {}",
350                entry.destination
351            ));
352            continue;
353        }
354        if !file.is_file() {
355            report.fail(format!("FAIL missing adopted file: {}", entry.destination));
356            continue;
357        }
358        if sha256_file(&file)? != entry.sha256 {
359            report.adopted_drift += 1;
360            report.note(format!(
361                "DRIFT adopted file requires reconciliation: {}",
362                entry.destination
363            ));
364        }
365    }
366
367    check_projection_against(
368        released,
369        &manifest,
370        &crate::services::installer::present_at_root(target),
371        &mut report,
372    );
373    check_integration(target, &manifest, &mut report)?;
374    check_specs(target, &manifest, &mut report)?;
375    check_lint_composition(target, &manifest, &mut report);
376    check_debt(target, &mut report);
377    for reconciliation in crate::services::policy::needed(target, manifest.docs_root)? {
378        report.note(reconciliation.note(manifest.docs_root));
379    }
380
381    let current = CanonVersion::current();
382    if manifest.canon_version > current {
383        report.fail(format!(
384            "FAIL sdd {current} is older than the installed canon {}; upgrade sdd",
385            manifest.canon_version
386        ));
387    } else if manifest.canon_version < current {
388        report.note(format!(
389            "note: sdd {current} is newer than the installed canon {}; run 'sdd upgrade'",
390            manifest.canon_version
391        ));
392    }
393
394    if report.failures == 0 {
395        report.note(format!(
396            "OK spec-driven-docs {} at {target}",
397            manifest.canon_version
398        ));
399    }
400    Ok(report)
401}
402
403/// Every markdownlint configuration that would replace the delivered one.
404///
405/// A `.markdownlint.*` file beside the documentation root's configuration
406/// replaces its `config`, and any configuration beneath `specs/` or
407/// `decisions/` replaces its `overrides` for that directory. Either one
408/// silently turns the heading shapes off. The repository root is allowed:
409/// a configuration there merges beneath the documentation root's, and it
410/// cannot disable the shapes. Only filenames are read, so no configuration
411/// grammar is parsed.
412///
413/// A symbolic link counts by its own name, because the linter reads a
414/// configuration through one. The scan skips a linked documentation root
415/// or subtree before reading beneath it, and [`linked_lint_scan_roots`]
416/// names it instead. The walk follows neither root nor nested links, so a
417/// linked directory is not descended and a cycle cannot hold it.
418///
419/// SATISFIES instance:the-lint-configuration-composes
420#[must_use]
421pub fn lint_configurations_that_break_composition(
422    target: &Utf8Path,
423    docs_root: crate::domain::profile::DocsRoot,
424) -> Vec<camino::Utf8PathBuf> {
425    use crate::domain::markdownlint::{LIBRARY_NAMES, discovery_names};
426
427    let root = Utf8Path::new(docs_root.as_str());
428    if reached_through_symlink(target, root) {
429        return Vec::new();
430    }
431    let mut found: Vec<camino::Utf8PathBuf> = LIBRARY_NAMES
432        .iter()
433        .map(|name| root.join(name))
434        .filter(|path| {
435            std::fs::symlink_metadata(target.join(path)).is_ok_and(|held| !held.is_dir())
436        })
437        .collect();
438    for subtree in ["specs", "decisions"] {
439        let subtree = root.join(subtree);
440        if reached_through_symlink(target, &subtree) {
441            continue;
442        }
443        for entry in walkdir::WalkDir::new(target.join(subtree))
444            .follow_links(false)
445            .follow_root_links(false)
446            .into_iter()
447            .filter_map(Result::ok)
448            .filter(|entry| !entry.file_type().is_dir())
449        {
450            let Some(name) = entry.file_name().to_str() else {
451                continue;
452            };
453            if !discovery_names().any(|known| known == name) {
454                continue;
455            }
456            if let Ok(relative) = entry.path().strip_prefix(target.as_std_path())
457                && let Some(relative) = camino::Utf8Path::from_path(relative)
458            {
459                found.push(relative.to_path_buf());
460            }
461        }
462    }
463    found.sort();
464    found
465}
466
467/// The documentation root or scan roots reached through a symbolic link.
468///
469/// The linter reads a configuration through the link, and the composition
470/// scan does not follow it, so such a directory is a place no check can see
471/// into. Naming it keeps the failure with the rule it breaks rather than
472/// leaving it to whichever ownership check happens to cover a recorded file
473/// beneath it. A linked documentation root is named alone, because both
474/// scan roots sit beneath it.
475///
476/// SATISFIES instance:the-lint-configuration-composes
477#[must_use]
478pub fn linked_lint_scan_roots(
479    target: &Utf8Path,
480    docs_root: crate::domain::profile::DocsRoot,
481) -> Vec<camino::Utf8PathBuf> {
482    let root = Utf8Path::new(docs_root.as_str());
483    if reached_through_symlink(target, root) {
484        return vec![root.to_path_buf()];
485    }
486    ["specs", "decisions"]
487        .into_iter()
488        .map(|subtree| root.join(subtree))
489        .filter(|subtree| reached_through_symlink(target, subtree))
490        .collect()
491}
492
493fn check_lint_composition(target: &Utf8Path, manifest: &Manifest, report: &mut VerifyReport) {
494    for path in linked_lint_scan_roots(target, manifest.docs_root) {
495        report.fail(format!(
496            "FAIL {path} is reached through a symlink, so no check sees the lint configuration beneath it; replace the link with the directory (instance:the-lint-configuration-composes)"
497        ));
498    }
499    for path in lint_configurations_that_break_composition(target, manifest.docs_root) {
500        report.fail(format!(
501            "FAIL {path} replaces the delivered lint configuration and turns the heading shapes off; fold it into the root .markdownlint-cli2.jsonc (instance:the-lint-configuration-composes)"
502        ));
503    }
504}
505
506/// The debt file must be readable, and it must be the only debt format.
507///
508/// A file no budget gate can read fails once here rather than once from
509/// every budget gate. The legacy list alone is a note naming its migration:
510/// it still works, and nothing about it is wrong until the day the project
511/// wants a ceiling that only shrinks.
512fn check_debt(target: &Utf8Path, report: &mut VerifyReport) {
513    use crate::domain::debt::{Debt, LEGACY_DEBT_PATH, Presence};
514    let presence = Presence::at(target);
515    if let Err(error) = Debt::read(target) {
516        report.fail(format!("FAIL {error}"));
517        return;
518    }
519    if presence.legacy {
520        report.note(format!(
521            "note: {LEGACY_DEBT_PATH} is the legacy debt list, which skips a listed chapter instead of holding it to a ceiling; run 'sdd debt migrate --apply'"
522        ));
523    }
524}
525
526/// The marker pair a host file's managed region uses.
527fn markers_for(path: &str) -> (&'static str, &'static str) {
528    if path == HOOKS_CONFIG_PATH {
529        (marker::BEGIN, marker::END)
530    } else {
531        (marker::AGENTS_BEGIN, marker::AGENTS_END)
532    }
533}
534
535fn check_integration(
536    target: &Utf8Path,
537    manifest: &Manifest,
538    report: &mut VerifyReport,
539) -> Result<(), AppError> {
540    for block in &manifest.integration_blocks {
541        let path = block.path.as_str();
542        let (begin, end) = markers_for(path);
543        let full = target.join(&block.path);
544        if reached_through_symlink(target, &block.path) {
545            report.fail(format!("FAIL {path} reached through a symlink"));
546            continue;
547        }
548        if !full.is_file() {
549            report.fail(format!("FAIL missing integration host: {path}"));
550            continue;
551        }
552        let host = std::fs::read_to_string(&full)?;
553        let begins = host.lines().filter(|line| *line == begin).count();
554        let ends = host.lines().filter(|line| *line == end).count();
555        if begins != 1 {
556            report.fail(format!("FAIL missing managed block: {path}"));
557            continue;
558        }
559        if ends != 1 {
560            report.fail(format!("FAIL malformed managed block: {path}"));
561            continue;
562        }
563        match marker::block_hash_with(&host, begin, end) {
564            Some(present) if present == block.marker_hash => {
565                if path == HOOKS_CONFIG_PATH
566                    && let Some(region) = marker::block_region_with(&host, begin, end)
567                {
568                    check_block_entries(&region, report);
569                }
570            }
571            _ => report.fail(format!("FAIL managed block tampered: {path}")),
572        }
573    }
574    Ok(())
575}
576
577/// One failure per heading that follows a spec's requirements other than
578/// `## Unenforced`, the headings the `spec-trailing-section` gate fails on.
579fn fail_trailing_sections(path: &Utf8Path, text: &str, report: &mut VerifyReport) {
580    for finding in crate::gates::spec_trailing_section::judge(path.as_str(), text) {
581        if finding.rule == crate::domain::rule_id::RuleId::SpecFollowsTheHeadingShape {
582            report.fail(format!(
583                "FAIL {}:{} {} (docs-specs:a-spec-follows-the-heading-shape)",
584                path,
585                finding.line.unwrap_or_default(),
586                finding.detail
587            ));
588        }
589    }
590}
591
592fn check_specs(
593    target: &Utf8Path,
594    manifest: &Manifest,
595    report: &mut VerifyReport,
596) -> Result<(), AppError> {
597    let specs = target.join(manifest.docs_root.as_str()).join("specs");
598    if specs.is_dir() {
599        let mut counts = std::collections::BTreeMap::new();
600        let mut names: Vec<_> = specs
601            .read_dir_utf8()?
602            .filter_map(Result::ok)
603            .map(|entry| entry.file_name().to_string())
604            .filter(|name| {
605                #[allow(
606                    clippy::case_sensitive_file_extension_comparisons,
607                    reason = "the corpus convention is lowercase"
608                )]
609                name.ends_with(".md")
610            })
611            .collect();
612        names.sort();
613        for name in names {
614            let text = std::fs::read_to_string(specs.join(&name))?;
615            for id in crate::embedded::rule_ids_in(&text) {
616                *counts.entry(id).or_insert(0usize) += 1;
617            }
618            fail_trailing_sections(
619                &camino::Utf8PathBuf::from(format!("{}/specs/{name}", manifest.docs_root.as_str())),
620                &text,
621                report,
622            );
623        }
624        let duplicated: Vec<String> = counts
625            .into_iter()
626            .filter(|(_, n)| *n > 1)
627            .map(|(id, _)| id)
628            .collect();
629        if !duplicated.is_empty() {
630            report.fail("FAIL duplicate rule ID in local specs");
631            for id in duplicated {
632                report.note(format!("### `{id}`"));
633            }
634        }
635    } else {
636        report.fail(format!(
637            "FAIL missing local specs: {}/specs",
638            manifest.docs_root
639        ));
640    }
641    Ok(())
642}
643
644#[cfg(test)]
645mod tests {
646    #![allow(
647        clippy::unwrap_used,
648        reason = "a test panics as its failure signal, not as control flow"
649    )]
650
651    use super::*;
652    use crate::candidate::{Evidence, Input, project};
653    use crate::domain::ownership::{ManagedEntry, Sha256};
654    use crate::domain::profile::{DECLARATION, ProfileId};
655
656    fn consumer(profile: ProfileId) -> Manifest {
657        project(&Input {
658            profile,
659            version: CanonVersion::current(),
660            installed_at: "2026-01-01T00:00:00Z".to_string(),
661            docs_scratch: None,
662            reserve: Vec::new(),
663            writing_style: None,
664            acquisition: None,
665            evidence: Evidence::default(),
666        })
667        .unwrap()
668        .manifest
669    }
670
671    fn failures(manifest: &Manifest) -> Vec<String> {
672        let mut report = VerifyReport::default();
673        check_projection_against(&DECLARATION, manifest, &[], &mut report);
674        report.lines
675    }
676
677    fn managed(path: &str) -> ManagedEntry {
678        ManagedEntry {
679            source: path.into(),
680            destination: path.into(),
681            sha256: Sha256::of(path.as_bytes()),
682        }
683    }
684
685    /// VERIFIES instance:the-lint-configuration-composes
686    ///
687    /// Neither a linked scan root nor its documentation-root ancestor may
688    /// expose external configurations to the composition scan.
689    #[test]
690    fn the_lint_scan_does_not_follow_its_roots_or_their_ancestors() {
691        use crate::domain::profile::DocsRoot;
692
693        for docs_root in [DocsRoot::Docs, DocsRoot::UnderscoreDocs] {
694            for boundary in ["", "specs", "decisions"] {
695                let target = tempfile::tempdir().unwrap();
696                let target = Utf8Path::from_path(target.path()).unwrap();
697                let outside = tempfile::tempdir().unwrap();
698                // A linked documentation root could expose both the direct
699                // library configuration and either recursive scan.
700                for relative in [
701                    ".markdownlint.json",
702                    "specs/.markdownlint-cli2.jsonc",
703                    "decisions/.markdownlint.yaml",
704                ] {
705                    let path = outside.path().join(relative);
706                    std::fs::create_dir_all(path.parent().unwrap()).unwrap();
707                    std::fs::write(path, "{}\n").unwrap();
708                }
709                let link = if boundary.is_empty() {
710                    target.join(docs_root.as_str())
711                } else {
712                    target.join(docs_root.as_str()).join(boundary)
713                };
714                std::fs::create_dir_all(link.parent().unwrap()).unwrap();
715                std::os::unix::fs::symlink(outside.path(), &link).unwrap();
716
717                assert!(
718                    lint_configurations_that_break_composition(target, docs_root).is_empty(),
719                    "{docs_root}/{boundary}: the scan followed a directory link"
720                );
721                let linked = if boundary.is_empty() {
722                    camino::Utf8PathBuf::from(docs_root.as_str())
723                } else {
724                    Utf8Path::new(docs_root.as_str()).join(boundary)
725                };
726                assert_eq!(linked_lint_scan_roots(target, docs_root), [linked]);
727            }
728        }
729    }
730
731    /// VERIFIES instance:the-lint-configuration-composes
732    #[test]
733    fn the_lint_scan_skips_nested_directory_links_and_cycles() {
734        use crate::domain::profile::DocsRoot;
735
736        for docs_root in [DocsRoot::Docs, DocsRoot::UnderscoreDocs] {
737            let target = tempfile::tempdir().unwrap();
738            let target = Utf8Path::from_path(target.path()).unwrap();
739            let specs = target.join(docs_root.as_str()).join("specs");
740            std::fs::create_dir_all(&specs).unwrap();
741            let outside = tempfile::tempdir().unwrap();
742            std::fs::write(outside.path().join(".markdownlint-cli2.jsonc"), "{}\n").unwrap();
743            std::os::unix::fs::symlink(outside.path(), specs.join("linked")).unwrap();
744            std::os::unix::fs::symlink(&specs, specs.join("cycle")).unwrap();
745            // Skipping linked directories must still count a configuration
746            // link by its own filename, even where its target is absent.
747            let config = specs.join(".markdownlint.yaml");
748            std::os::unix::fs::symlink(outside.path().join("absent.yaml"), &config).unwrap();
749
750            assert_eq!(
751                lint_configurations_that_break_composition(target, docs_root),
752                [config.strip_prefix(target).unwrap()]
753            );
754            // A link nested inside a scan root is not a linked scan root.
755            assert!(linked_lint_scan_roots(target, docs_root).is_empty());
756        }
757    }
758
759    /// A knowledge-base record whose managed destinations equal their
760    /// sources satisfied the old discriminator, which then demanded the
761    /// canon's specs and templates and dropped the `AGENTS.md` block.
762    #[test]
763    fn a_consumer_whose_managed_destination_equals_its_source_is_still_a_consumer() {
764        let mut manifest = consumer(ProfileId::KnowledgeBase);
765        for projection in &DECLARATION.managed {
766            if !manifest
767                .managed_files
768                .iter()
769                .any(|entry| entry.destination == projection.source.as_str())
770            {
771                manifest.managed_files.push(managed(&projection.source));
772            }
773        }
774        assert!(failures(&manifest).is_empty(), "{:?}", failures(&manifest));
775
776        let mut without_block = manifest.clone();
777        without_block
778            .integration_blocks
779            .retain(|block| block.path != AGENTS_DIGEST_PATH);
780        assert!(
781            failures(&without_block)
782                .iter()
783                .any(|line| line.contains("no integration block for AGENTS.md")),
784            "{:?}",
785            failures(&without_block)
786        );
787
788        let mut without_seed = manifest;
789        let dropped = without_seed.adopted_files.remove(1).destination;
790        assert!(
791            failures(&without_seed)
792                .iter()
793                .any(|line| line.ends_with(dropped.as_str())),
794            "{:?}",
795            failures(&without_seed)
796        );
797    }
798
799    #[test]
800    fn the_canon_record_is_read_as_the_canon() {
801        let text =
802            std::fs::read_to_string(Utf8Path::new(env!("CARGO_MANIFEST_DIR")).join(MANIFEST_PATH))
803                .unwrap();
804        let mut manifest = Manifest::parse(&text).unwrap();
805        manifest.canon_version = CanonVersion::current();
806        assert!(failures(&manifest).is_empty(), "{:?}", failures(&manifest));
807    }
808
809    #[test]
810    fn a_consumer_omitting_a_declared_seed_fails() {
811        let mut manifest = consumer(ProfileId::Codebase);
812        let dropped = manifest.adopted_files.pop().unwrap().destination;
813        let lines = failures(&manifest);
814        assert!(
815            lines.contains(&format!(
816                "FAIL manifest omits a declared projection: {dropped}"
817            )),
818            "{lines:?}"
819        );
820    }
821
822    /// The marker recognizes a layout and authenticates nothing: a record
823    /// that claims the canon layout is held to the canon's obligations, and
824    /// those do not include the `AGENTS.md` block.
825    #[test]
826    fn a_claimed_canon_layout_changes_which_obligations_are_held() {
827        let mut manifest = consumer(ProfileId::KnowledgeBase);
828        manifest
829            .integration_blocks
830            .retain(|block| block.path != AGENTS_DIGEST_PATH);
831        manifest
832            .managed_files
833            .push(managed("skill-shared/plan-gate.md"));
834        let lines = failures(&manifest);
835        assert!(
836            lines
837                .iter()
838                .any(|line| line
839                    .contains("omits a declared projection: _docs/specs/SPEC-release.md")),
840            "the canon branch owes the canon-only specs: {lines:?}"
841        );
842
843        for projection in &DECLARATION.managed {
844            manifest.managed_files.push(managed(&projection.source));
845        }
846        for file in crate::embedded::SPECS.files() {
847            let name = file.path().to_str().unwrap();
848            manifest
849                .managed_files
850                .push(managed(&format!("_docs/specs/{name}")));
851        }
852        for template in crate::domain::profile::CANON_TEMPLATES.iter() {
853            manifest.managed_files.push(managed(template));
854        }
855        let lines = failures(&manifest);
856        assert!(lines.is_empty(), "{lines:?}");
857    }
858
859    #[test]
860    fn a_yielded_seed_the_record_does_not_name_is_not_owed() {
861        let Some(yielding) = DECLARATION
862            .adopted
863            .iter()
864            .find(|projection| projection.yield_set().is_some())
865        else {
866            return;
867        };
868        let mut manifest = consumer(ProfileId::Codebase);
869        let destination =
870            crate::domain::profile::resolve_destination(&yielding.destination, manifest.docs_root);
871        manifest
872            .adopted_files
873            .retain(|entry| entry.destination != destination);
874        assert!(!failures(&manifest).is_empty());
875
876        let mut report = VerifyReport::default();
877        let cause = yielding
878            .yield_set()
879            .unwrap()
880            .names()
881            .last()
882            .unwrap()
883            .to_string();
884        check_projection_against(&DECLARATION, &manifest, &[cause], &mut report);
885        assert!(report.lines.is_empty(), "{:?}", report.lines);
886    }
887}