sherd 0.6.0

two-axis federation of SPEC.md and source over a dir DAG, for small-context local models
Documentation
use super::*;

const SAMPLE: &str = "# SPEC\n\n## \u{a7}G GOAL\nthing do thing\n\n## \u{a7}V INVARIANTS\nV1: a ! b\n";

#[test]
fn sections_split_on_headers() {
    let s = sections(SAMPLE);
    let [goal, inv] = s.as_slice() else {
        unreachable!("two sections, and the pattern says so")
    };
    assert!(goal.0.contains("GOAL"));
    assert!(inv.1.contains("V1:"));
}

#[test]
fn a_bug_naming_no_invariant_is_unreflected() {
    let s = "## \u{a7}B BUGS\nid|date|cause|fix\nB1|d|it broke|we fixed it\n";
    let u = unreflected_bugs(s);
    assert_eq!(u.len(), 1);
    assert_eq!(u.first().map(|b| b.0.clone()), Some("B1".to_string()));
}

/// `B2`: three spellings for one citation and nothing rejected any.
/// Canonical is the node PATH -- `.` for root, `src/tdd` for a node --
/// and the bare `tdd:B12` form resolved to nothing because there is no
/// `tdd/` beside the root.
#[test]
fn a_citation_carries_the_node_path_it_names() {
    assert_eq!(
        citations("V1: see `src/tdd:B12` and `.:V50`"),
        vec![
            Citation {
                owner: "src/tdd".into(),
                id: "B12".into(),
                line: 1
            },
            Citation {
                owner: ".".into(),
                id: "V50".into(),
                line: 1
            },
        ]
    );
}

/// The foreign form uses a SLASH and is not a citation into this tree:
/// `microlith/V14` names a rule in another repository, which this tree
/// cannot resolve and must never rewrite.
#[test]
fn a_foreign_rule_is_not_a_citation_here() {
    assert!(citations("V1: microlith/V14 says so").is_empty());
    assert!(citations("MEASURED: V17 held").is_empty());
    assert!(citations("no colon here at all").is_empty());
}

/// A row opens its line: `|` in a table, `:` in a statement.
#[test]
fn a_row_is_declared_by_the_line_it_opens() {
    let s = "V1: a ! b\nT3|.|do the thing|V1\nB7|2026-01-01|cause|fix\n";
    assert!(declares(s, "V1"));
    assert!(declares(s, "T3"));
    assert!(declares(s, "B7"));
    assert!(!declares(s, "V2"), "V1 must not answer for V2");
    assert!(!declares(s, "V"), "a prefix is not an id");
}

/// V8. `§C` and `§I` are bullet lists in FORMAT.md, so an id there sits
/// behind `- `. `citation_at` already accepts `C` and `I`; without this a
/// `node:C1` citation could be written and never resolve (`B4`).
#[test]
fn a_bullet_declares_the_id_it_opens_with() {
    let s = "## \u{a7}C CONSTRAINTS\n- C1: Rust only\n- plain bullet\n\
                 ## \u{a7}I INTERFACES\n- I2: `sherd check` exits 1\n";
    assert!(declares(s, "C1"));
    assert!(declares(s, "I2"));
    assert!(!declares(s, "C2"), "C1 must not answer for C2");
    assert!(!declares("- see C1: for why\n", "C3"), "prose is not a row");
    assert!(!declares("text - C1: mid-line\n", "C1"), "opens the line");
}

/// `src/fed:V9`: a `§T` row states REMAINING work. A finished one reads to
/// a machine as work to do, and rule depth loads `§T` on every descent, so
/// every chain pays for it every turn.
#[test]
fn a_finished_task_is_not_remaining_work() {
    let s = "## \u{a7}T TASKS\nid|status|task|cites\n\
                 T1|x|the thing landed|V1\nT2|.|the other thing|V2\n\
                 T3|~|half of it|V3\n";
    let done = completed_tasks(s);
    assert_eq!(done.len(), 1, "only `x` is finished");
    assert_eq!(done.first().map(|d| d.0.as_str()), Some("T1"));

    // A `§B` row that happens to start with T is not a task.
    let b = "## \u{a7}B BUGS\nid|date|cause|fix\nT9|x|not a task row|f\n";
    assert!(completed_tasks(b).is_empty(), "§T only");
}

/// `src/fed:B14`: `mth archive` moves a finished row's text and leaves a stub, so a
/// milestone still finds the row and its citations resolve (`microlith/V48`).
/// The stub carries no task text, so it is not history.
#[test]
fn an_archive_stub_is_not_history() {
    let s = "## \u{a7}T TASKS\nid|status|task|cites\n\
                 T88|x|ARCHIVED to SPEC-ARCHIVE.md|V42\n\
                 T89|x|the thing landed|V1\n";
    let done = completed_tasks(s);
    // The positive case (`src/fed:V10`): a done row with its text is flagged.
    assert_eq!(done.len(), 1, "{done:?}");
    assert_eq!(done.first().map(|d| d.0.as_str()), Some("T89"));
}

/// V11: a pack carries the PLAN. Open and started rows survive rule depth;
/// a finished row and an archive stub do not, and nothing else in `§T`, nor
/// a `§V` line that merely looks like a done row, is touched.
#[test]
fn rule_depth_keeps_only_remaining_work() {
    let s = "## \u{a7}V INVARIANTS\nV1: T9|x|is prose here\n\n\
             ## \u{a7}T TASKS\nid|status|task|cites\n\
             T1|x|the thing landed|V1\nT2|.|the other thing|V1\n\
             T3|~|half of it|V1\nT4|x|ARCHIVED to SPEC-ARCHIVE.md|V1\n\
             T5a|x|a suffixed row|V1\n";
    let r = crate::spec::rule_depth(s);
    for kept in ["id|status|task|cites", "T2|.|", "T3|~|", "V1: T9|x|"] {
        assert!(r.contains(kept), "`{kept}` must survive: {r}");
    }
    for gone in ["T1|x|", "T4|x|", "T5a|x|"] {
        assert!(!r.contains(gone), "`{gone}` is history: {r}");
    }
}

/// `src/lens:V18`: an ancestor loses its `§T` section and nothing else. The
/// section is the one whose LETTER is `T` -- a heading that merely mentions
/// `§T` keeps its rows, or an ancestor's rules vanish from the pack.
#[test]
fn without_tasks_drops_the_task_section_only() {
    let s = "## \u{a7}V INVARIANTS (see \u{a7}T)\nV1: a rule\n\n\
             ## \u{a7}T TASKS\nid|status|task|cites\nT1|.|work|V1\n\n\
             ## \u{a7}B BUGS\nB1|d|it broke|V1\n";
    assert_eq!(
        crate::spec::without_tasks(s),
        "## \u{a7}V INVARIANTS (see \u{a7}T)\nV1: a rule\n\n\
         ## \u{a7}B BUGS\nB1|d|it broke|V1\n"
    );
}

use std::path::Path;

/// The defect `B2` names, on the tree that measured it: every citation in
/// every spec of this repository resolves to a node and a row. Four files
/// cited `.:V41`, which was never written at root.
#[test]
fn every_citation_in_this_repository_resolves() {
    let root = Path::new(env!("CARGO_MANIFEST_DIR"));
    let mut dead = Vec::new();
    for node in crate::fed::discover(root) {
        let Ok(text) = std::fs::read_to_string(node.join("SPEC.md")) else {
            continue;
        };
        for c in citations(&text) {
            let target = if c.owner == "." {
                root.join("SPEC.md")
            } else {
                root.join(&c.owner).join("SPEC.md")
            };
            match std::fs::read_to_string(&target) {
                Ok(t) if declares(&t, &c.id) => {}
                _ => dead.push(format!("{}:{}", c.owner, c.id)),
            }
        }
    }
    assert!(dead.is_empty(), "citations resolving to nothing: {dead:?}");
}

#[test]
fn a_bug_citing_an_invariant_is_reflected() {
    for fix in ["now V9 catches it", "see `src/fed:V9`"] {
        let s = "## \u{a7}B BUGS\nid|date|cause|fix\nB1|d|broke|".to_string()
            + fix
            + "\n";
        assert!(
            unreflected_bugs(&s).is_empty(),
            "should be reflected: {fix}"
        );
    }
}

#[test]
fn only_the_bugs_section_is_read() {
    let s = "## \u{a7}T TASKS\nid|status|task|cites\nB1|.|not a bug row|-\n";
    assert!(unreflected_bugs(s).is_empty(), "a §T row is not a §B row");
}

/// V5. B1 imported through microlith's inner `violation` module -- which
/// the dep later made `pub(crate)`, turning a green HEAD red with no commit
/// here. Only the root re-exports are the contract, so the shape to forbid
/// is any path BELOW the crate, not the one symbol that happened to move.
/// The check reads text, so it fails on a mention in prose too: write the
/// module name, not a path a reader could copy.
#[test]
fn microlith_is_reached_only_through_its_root() {
    // Built at runtime: a literal here would match itself.
    let deep = "microlith".to_string() + "::";
    let mut offenders = Vec::new();
    let mut stack =
        vec![std::path::Path::new(env!("CARGO_MANIFEST_DIR")).join("src")];
    while let Some(dir) = stack.pop() {
        let Ok(entries) = std::fs::read_dir(&dir) else {
            continue;
        };
        for e in entries.flatten() {
            let p = e.path();
            if p.is_dir() {
                stack.push(p);
            } else if p.extension().is_some_and(|x| x == "rs") {
                let Ok(text) = std::fs::read_to_string(&p) else {
                    continue;
                };
                for (n, line) in text.lines().enumerate() {
                    let Some(rest) = line.split_once(&deep).map(|(_, r)| r)
                    else {
                        continue;
                    };
                    let ident: String = rest
                        .chars()
                        .take_while(|c| c.is_alphanumeric() || *c == '_')
                        .collect();
                    if rest[ident.len()..].starts_with("::") {
                        offenders.push(format!(
                            "{}:{}: {ident}",
                            p.display(),
                            n + 1
                        ));
                    }
                }
            }
        }
    }
    assert!(
        offenders.is_empty(),
        "V5: reach microlith through its root re-exports, not {offenders:?}"
    );
}

#[test]
fn fmt_is_lossless_and_idempotent() {
    // `fmt` is the write half of the spec binding and had no test at all.
    // Idempotence is the property that matters: a formatter whose second
    // pass differs from its first turns every `sherd` run into a diff, and
    // the gate would then fail on a tree nobody edited.
    let once = fmt(SAMPLE).unwrap_or_default();
    assert!(!once.is_empty(), "a valid spec formats to something");
    let twice = fmt(&once).unwrap_or_default();
    assert_eq!(once, twice, "formatting twice must change nothing");
}

#[test]
fn check_runs_against_microlith() {
    // Not asserting a specific verdict -- asserting the binding works and
    // returns microlith's own Violation type.
    let _: Vec<Violation> = check(SAMPLE);
}

/// `.:V44`: a vertical split is lossless BY REFERENCE -- every `§V` id in
/// `SPEC.md` has a row in `SPEC.why.md`, even if that row is only `-`. A
/// missing row is rationale that went nowhere; an orphan row is rationale
/// for a rule that no longer exists.
#[test]
fn why_gaps_names_missing_and_orphan_rows() {
    let spec = "## \u{a7}V INVARIANTS\n\nV1: one\nV2: two\nV3: three\n\n\
                ## \u{a7}T TASKS\n\nid|status|task|cites\nT1|.|x|-\n";
    let why = "V1|because\nV3|-\nV9|a rule that left\n";
    assert_eq!(
        why_gaps(spec, why),
        (vec!["V2".to_string()], vec!["V9".to_string()])
    );
}

/// A `§T` or `§B` id is not a rule and needs no why row; an explicit `-` is
/// a complete answer.
#[test]
fn why_gaps_is_clean_when_every_rule_is_answered() {
    let spec = "## \u{a7}V INVARIANTS\n\nV1: one\nV2: two\n\n\
                ## \u{a7}B BUGS\n\nid|date|cause|fix\nB1|2026-01-01|x|y\n";
    assert_eq!(why_gaps(spec, "V1|-\nV2|measured\n"), (vec![], vec![]));
}