@sdd-method/author-cli 0.0.0-stage → 0.1.0

package/dist/lib/snapshot/advance.js

@@ -0,0 +1,454 @@
+// `sdd-cli snapshot advance` — move each member's evidence pin to T1 and
+// append one history entry (delta-reverse.md §8).
+//
+// Refusals, each a failure a hand run made:
+//   - no delta.yaml for T1 (the pin advanced before the diff existed);
+//   - no `impact` recorded (step 5a not done);
+//   - a legacy `entries:` history, unless --migrate-history converts it first;
+//   - a `phase:` key or a `reverse_status` outside {classified, reversed};
+//   - a source_path with no dated baseline segment (the area is not folded);
+//   - a finding of the member still unclassified (step 5 before step 8);
+//   - a pin already at the target revision, moved by hand before the tool
+//     existed (--record-only writes the row without moving it), or at a
+//     revision that is neither the prior baseline's nor the target's.
+// `impact: none` is decided from the two MANIFESTS (same revision at T0 and
+// T1), never from the pin: a pin moved by hand already holds T1's revision, and
+// reading it would record a changed member as unchanged.
+// It checks everything before it writes anything, and it only ever APPENDS:
+// after writing it re-reads each history and asserts the prior entries are
+// unchanged and exactly one was added. Entries are never cut or rewritten —
+// for an unchanged member the T0 and T1 entries share folder name and
+// revision, so any edit keyed on those removes both.
+import { isDeepStrictEqual } from "node:util";
+import { readdir, readFile, writeFile } from "node:fs/promises";
+import { join, relative, sep } from "node:path";
+import { citesPath } from "./fold.js";
+import { parse, parseDocument, stringify } from "yaml";
+// Both writers below edit TEXT, not a re-serialised document: re-serialising
+// reflows every long string in the file, so an evidence pin would arrive with
+// unrelated churn in lines the tool had no business touching.
+import { deltaPath } from "./diff.js";
+import { loadCanonicalSchema } from "../catalogue/schema-loader.js";
+import { SnapshotError, credentialNotice, exists, isIsoDate, readManifest, splitFolder, } from "./manifest.js";
+export const REVERSE_STATUSES = ["classified", "reversed"];
+export const IMPACTS = ["none", "repo-minor", "repo-major", "product-major"];
+/**
+ * Hand-written prose in a member's evidence files that still names the prior
+ * baseline or its folder: comment lines anywhere, and non-field lines of the
+ * metadata. The tool never rewrites prose — this is a list, not a control.
+ */
+export async function staleProse(dir, priorId, priorFolder) {
+    const needles = [priorId, priorFolder].filter((x) => typeof x === "string" && x !== "");
+    if (needles.length === 0)
+        return [];
+    const out = [];
+    for (const name of ["reverse-metadata.yaml", "reverse-history.yaml"]) {
+        const file = join(dir, name);
+        if (!(await exists(file)))
+            continue;
+        const lines = (await readFile(file, "utf8")).split("\n");
+        // History ENTRIES name the prior baseline by design; only its comments are prose.
+        lines.forEach((line, i) => {
+            const prose = name === "reverse-history.yaml" ? /^\s*#/.test(line) : !/^[A-Za-z_][\w-]*:\s*\S*\s*$/.test(line) || /^notes:/.test(line);
+            // A history header describes the pin's state in words ("the T1 entry is appended
+            // when…"), so there a T0/T1 mention is enough; elsewhere it must name the baseline.
+            const header = name === "reverse-history.yaml" && /\bT[01]\b/.test(line);
+            if (prose && (header || needles.some((n) => line.includes(n))))
+                out.push(`${name}:${i + 1}`);
+        });
+    }
+    return out;
+}
+const BRANCH = /-(master|main|develop|trunk)$/;
+/**
+ * The snapshot identity of a metadata file, deriving what the folder-name
+ * convention `<repo>-<branch>@<rev>` makes certain: the revision always, the
+ * branch only when the suffix is a known branch name. What was derived is
+ * returned so the caller can say so.
+ */
+export function identityOf(metadata) {
+    const str = (v) => (v === undefined || v === null || v === "" ? undefined : String(v));
+    const folder = str(metadata.exported_folder_name);
+    const split = folder ? splitFolder(folder) : null;
+    const derived = [];
+    let rev = str(metadata.source_revision);
+    if (!rev && split) {
+        rev = split.revision;
+        derived.push("source_revision");
+    }
+    let branch = str(metadata.exported_branch);
+    if (!branch && split) {
+        branch = split.stem.match(BRANCH)?.[1];
+        if (branch)
+            derived.push("exported_branch");
+    }
+    const fields = {};
+    const missing = [];
+    for (const [k, v] of [["exported_folder_name", folder], ["exported_branch", branch], ["source_revision", rev], ["source_path", str(metadata.source_path)]]) {
+        if (v)
+            fields[k] = v;
+        else
+            missing.push(k);
+    }
+    return { fields, derived, missing };
+}
+export async function runSnapshotAdvance(inputs, write) {
+    try {
+        const plans = await advance(inputs, write);
+        write(`advanced ${plans.length} member(s) to ${inputs.to}\n`);
+        return { exitCode: 0 };
+    }
+    catch (e) {
+        if (e instanceof SnapshotError) {
+            write(`REFUSED (nothing written): ${e.message}\n`);
+            return { exitCode: 1 };
+        }
+        throw e;
+    }
+}
+async function evidenceDirs(sddPath) {
+    const out = new Map();
+    const repos = join(sddPath, "repos");
+    if (!(await exists(repos)))
+        return out;
+    for (const e of await readdir(repos, { withFileTypes: true })) {
+        if (!e.isDirectory())
+            continue;
+        const md = join(repos, e.name, "reverse-metadata.yaml");
+        if (!(await exists(md)))
+            continue;
+        const key = parse(await readFile(md, "utf8"))?.canonical_repo_key;
+        out.set(key ?? e.name, join(repos, e.name));
+    }
+    return out;
+}
+/** Convert a legacy `entries:` history. Only `phase: scan` rows convert mechanically. */
+export function migrateLegacy(legacy, metadata) {
+    const entries = (legacy.entries ?? []);
+    const other = entries.filter((e) => e.phase !== undefined && e.phase !== "scan");
+    if (other.length > 0) {
+        throw new SnapshotError(`legacy history has ${other.length} row(s) with phase other than 'scan' (${[...new Set(other.map((e) => String(e.phase)))].join(", ")}): ` +
+            "which snapshot each describes cannot be derived, so convert those by hand");
+    }
+    const id = identityOf(metadata);
+    if (id.missing.length > 0) {
+        throw new SnapshotError(`cannot migrate: reverse-metadata.yaml has no ${id.missing.join(", ")}, and the folder name does not supply it` +
+            (id.missing.includes("exported_folder_name") || id.missing.includes("source_path")
+                ? " — if the area was folded, re-point the evidence pins first (`snapshot fold --sdd-path`, or by hand)"
+                : ""));
+    }
+    return {
+        derived: id.derived,
+        canonical_repo_key: metadata.canonical_repo_key,
+        history: entries.map((e) => ({
+            ...id.fields,
+            scanned_at: e.date,
+            reverse_status: "reversed",
+            notes: `${String(e.notes ?? "").trim()} (Migrated from the legacy entries: shape — originally phase: ${String(e.phase ?? "unset")}, actor: ${String(e.actor ?? "unset")}; identity fields taken from reverse-metadata.yaml at migration${id.derived.length > 0 ? `, ${id.derived.join(" and ")} derived from the folder name` : ""}.)`.trim(),
+        })),
+    };
+}
+function checkHistory(file, h) {
+    const problems = [];
+    const hist = h.history;
+    if (!Array.isArray(hist))
+        return [`${file}: no history[] list`];
+    for (const [i, e] of hist.entries()) {
+        if (e.phase !== undefined)
+            problems.push(`${file}: history[${i}] has a 'phase' key — not a field of the convention`);
+        const s = e.reverse_status;
+        if (s !== undefined && !REVERSE_STATUSES.includes(s)) {
+            problems.push(`${file}: history[${i}].reverse_status '${String(s)}' is not one of ${REVERSE_STATUSES.join(", ")}`);
+        }
+    }
+    return problems;
+}
+/** Re-point a source_path at another baseline and folder; null if it has no dated segment. */
+export function repoint(sourcePath, newBaseline, newFolder) {
+    const parts = sourcePath.split("/");
+    const i = parts.findIndex((p) => isIsoDate(p));
+    if (i < 0)
+        return null;
+    return [...parts.slice(0, i), newBaseline, newFolder].join("/");
+}
+export async function advance(inputs, write) {
+    const { sddPath, areaRoot, to } = inputs;
+    const t1 = await readManifest(areaRoot, to);
+    const dispositions = new Set(((await loadCanonicalSchema()).enums["delta_disposition"]?.values ?? []).map((v) => v.value));
+    const dp = deltaPath(areaRoot, to);
+    if (!(await exists(dp))) {
+        throw new SnapshotError(`no ${dp}: the pin advances after the delta is recorded (run snapshot diff, then classify)`);
+    }
+    const delta = parse(await readFile(dp, "utf8"));
+    const provenance = delta.t0_provenance?.result;
+    const provenanceNote = provenance ? ` T0 provenance: ${provenance}${delta.t0_provenance?.waiver?.who ? ` (waiver: ${delta.t0_provenance.waiver.who})` : ""}.` : "";
+    if (provenance && !/^pass$/.test(provenance)) {
+        write(`T0 PROVENANCE is not a clean pass for ${delta.from_snapshot ?? "the prior baseline"}: ${provenance} — delta-reverse §3: docs are read as stale only if T0 was valid\n`);
+    }
+    const fromId = delta.from_snapshot ?? t1.prior_snapshot;
+    const t0 = fromId ? await readManifest(areaRoot, fromId) : null;
+    const t0Rev = new Map((t0?.members ?? []).map((x) => [x.canonical_repo_key, x.source_revision]));
+    const notice = credentialNotice(t1);
+    if (notice)
+        write(`${notice}\n`);
+    if (!delta.impact)
+        throw new SnapshotError(`${dp} has no impact: classify first (delta-reverse.md §5a)`);
+    const impactOk = (v) => IMPACTS.includes(v);
+    if (!impactOk(delta.impact))
+        throw new SnapshotError(`${dp}: impact '${delta.impact}' is not one of ${IMPACTS.join(", ")}`);
+    const changed = new Map((delta.members_changed ?? []).map((c) => [c.canonical_repo_key, c]));
+    const dirs = await evidenceDirs(sddPath);
+    const wanted = inputs.members ? new Set(inputs.members) : null;
+    const problems = [];
+    const plans = [];
+    for (const m of t1.members) {
+        if (wanted && !wanted.has(m.canonical_repo_key))
+            continue;
+        if (m.carried_from !== undefined)
+            continue; // carried: no new entry — the manifest records where its bytes are
+        const key = m.canonical_repo_key;
+        const dir = dirs.get(key);
+        if (!dir) {
+            problems.push(`${key}: no repos/*/reverse-metadata.yaml with this canonical_repo_key — a new member is seeded (step 7) before its pin advances`);
+            continue;
+        }
+        const hFile = join(dir, "reverse-history.yaml");
+        const mFile = join(dir, "reverse-metadata.yaml");
+        const metadataText = await readFile(mFile, "utf8");
+        const metadata = parse(metadataText);
+        let history = (await exists(hFile)) ? parse(await readFile(hFile, "utf8")) : { canonical_repo_key: key, history: [] };
+        let migrated = false;
+        if (Array.isArray(history.entries)) {
+            if (!inputs.migrateHistory) {
+                problems.push(`${hFile}: legacy entries: history — pass --migrate-history to convert it first`);
+                continue;
+            }
+            try {
+                // Legacy rows describe the snapshot the pin held when they were written. If
+                // the pin was moved to T1 by hand, that was T0 — so T0's identity, never
+                // the current pin's, or a pre-T1 scan row would claim T1's revision.
+                let source = metadata;
+                const t0m = t0?.members.find((x) => x.canonical_repo_key === key);
+                const pinnedNow = identityOf(metadata).fields.source_revision;
+                if (t0m && pinnedNow === m.source_revision && t0m.source_revision !== m.source_revision) {
+                    const t0Path = repoint(String(metadata.source_path ?? ""), t0m.carried_from ?? t0.snapshot_id, t0m.exported_folder_name);
+                    source = { ...metadata, exported_folder_name: t0m.exported_folder_name, source_revision: t0m.source_revision, exported_branch: undefined, source_path: t0Path ?? undefined };
+                    write(`${key}: pin was moved by hand, so its legacy rows take ${fromId}'s identity (${t0m.exported_folder_name})\n`);
+                }
+                const mig = migrateLegacy(history, source);
+                // A row cannot describe a baseline observed after it was written.
+                const rows = mig.history;
+                const baseline = String(rows[0]?.source_path ?? "").split("/").find((p) => isIsoDate(p));
+                const early = rows.filter((e) => baseline !== undefined && String(e.scanned_at) < baseline);
+                if (early.length > 0) {
+                    throw new SnapshotError(`${early.length} legacy row(s) dated before baseline ${baseline}, the one their identity would name — which snapshot they describe must be set by hand`);
+                }
+                const { derived, ...doc } = mig;
+                // The key the evidence dir was matched by, where the metadata does not carry one.
+                history = { ...doc, canonical_repo_key: doc.canonical_repo_key ?? key };
+                migrated = true;
+                for (const d of derived)
+                    write(`${key}: ${d} derived from folder name ${metadata.exported_folder_name}\n`);
+            }
+            catch (e) {
+                problems.push(`${hFile}: ${e.message}`);
+                continue;
+            }
+        }
+        problems.push(...checkHistory(hFile, history));
+        const hist = history.history;
+        const last = hist[hist.length - 1];
+        const scannedAt = m.observed_at ?? t1.observed_at;
+        // "Already at" means already RECORDED as reversed there. A seed row (`classified`)
+        // for the T1 folder is the start of that member's T1 work, not the end of it —
+        // skipping on it left seeded members without their reversed row.
+        if (last && last.exported_folder_name === m.exported_folder_name && last.scanned_at === scannedAt && last.reverse_status === "reversed") {
+            write(`${key}: already at ${to} — skipped\n`);
+            continue;
+        }
+        const newPath = repoint(String(metadata.source_path ?? ""), to, m.exported_folder_name);
+        if (newPath === null) {
+            problems.push(`${mFile}: source_path '${metadata.source_path}' has no dated baseline segment — fold the area first`);
+            continue;
+        }
+        const priorRev = t0Rev.get(key);
+        const pinned = identityOf(metadata).fields.source_revision;
+        let movePin = true;
+        if (priorRev === undefined) {
+            // A NEW member has no prior baseline, so its pin is never "moved by hand": step 7
+            // seeded it at T1, whatever date the seed row carries. Recorded as reversed → done;
+            // seeded only → append its reversed row (the pin is already at T1); unseeded → refuse.
+            const t1Rows = hist.filter((e) => e.exported_folder_name === m.exported_folder_name);
+            if (t1Rows.some((e) => e.reverse_status === "reversed")) {
+                write(`${key}: new member, already recorded as reversed at ${to} — skipped\n`);
+                continue;
+            }
+            if (t1Rows.length === 0) {
+                problems.push(`${key}: new member with no history row for ${m.exported_folder_name} — seed it (step 7) before its pin advances`);
+                continue;
+            }
+            movePin = false;
+        }
+        const sameRevision = priorRev !== undefined && priorRev === m.source_revision;
+        if (priorRev === undefined) {
+            // handled above: the seed put the pin at T1
+        }
+        else if (pinned === m.source_revision && !sameRevision) {
+            if (!inputs.recordOnly) {
+                problems.push(`${key}: pin is already at ${to} (${m.source_revision}), moved before this run — pass --record-only to write its history row without moving it`);
+                continue;
+            }
+            movePin = false;
+        }
+        else if (priorRev !== undefined && pinned !== undefined && pinned !== priorRev && pinned !== m.source_revision) {
+            problems.push(`${key}: pin is at ${pinned}, which is neither ${fromId} (${priorRev}) nor ${to} (${m.source_revision})`);
+            continue;
+        }
+        const impact = sameRevision ? "none" : (changed.get(key)?.impact ?? delta.impact);
+        if (!impactOk(impact))
+            problems.push(`${dp}: ${key} impact '${impact}' is not one of ${IMPACTS.join(", ")}`);
+        const mine = (delta.findings ?? []).filter((f) => f.member === key);
+        const unclassified = mine.filter((f) => f.classification === null || f.classification === undefined).map((f) => f.id);
+        if (unclassified.length > 0) {
+            problems.push(`${key}: ${unclassified.length} finding(s) not yet classified (${unclassified.join(", ")}) — classify before the pin advances (delta-reverse.md §5)`);
+            continue;
+        }
+        // A classification is one of the bound vocabulary (M-ADR 0214 §4.5), read from the
+        // schema rather than restated here: a typo is not a classification.
+        const outOfVocabulary = mine.filter((f) => !dispositions.has(String(f.classification)));
+        if (outOfVocabulary.length > 0) {
+            problems.push(`${key}: ${outOfVocabulary.map((f) => `${f.id} '${String(f.classification)}'`).join(", ")} — not a delta_disposition (${[...dispositions].join(", ")}; M-ADR 0214 §4.5)`);
+            continue;
+        }
+        const findingNotes = mine.map((f) => `${f.id} [${f.classification}]${f.summary ? `: ${f.summary}` : ""}${f.spec_impact ? ` — spec: ${f.spec_impact}` : ""}`);
+        const extra = inputs.notes?.get(key);
+        const branch = splitFolder(m.exported_folder_name)?.stem.match(BRANCH)?.[1] ?? metadata.exported_branch;
+        const entry = {
+            exported_folder_name: m.exported_folder_name,
+            ...(branch ? { exported_branch: branch } : {}),
+            source_revision: m.source_revision,
+            source_path: newPath,
+            scanned_at: scannedAt,
+            reverse_status: "reversed",
+            impact,
+            ...(sameRevision
+                ? { impact_rationale: `re-observed at the same revision (${describeReverification(m)})` }
+                : (changed.get(key)?.impact_rationale ?? delta.impact_rationale)
+                    ? { impact_rationale: changed.get(key)?.impact_rationale ?? delta.impact_rationale }
+                    : {}),
+            notes: `${priorRev === undefined ? `recorded as reversed at ${to} (new member, seeded at this baseline — it has no ${fromId} entry)` : movePin ? `advanced to ${to} from ${fromId}` : `recorded at ${to} from ${fromId} (pin moved by hand before this run)`} by sdd-cli snapshot advance.${provenanceNote}` +
+                `${extra ? ` ${extra}` : ""} Findings: ${findingNotes.length > 0 ? findingNotes.join("; ") : "none"}.`,
+        };
+        plans.push({
+            key,
+            dir,
+            history,
+            migrated,
+            metadataText,
+            entry,
+            metadata: {
+                source_path: newPath,
+                exported_folder_name: m.exported_folder_name,
+                source_revision: m.source_revision,
+                scanned_at: scannedAt,
+                ...(branch ? { exported_branch: branch } : {}),
+            },
+            movePin,
+            ...(t0?.members.find((x) => x.canonical_repo_key === key)?.exported_folder_name
+                ? { priorFolder: t0.members.find((x) => x.canonical_repo_key === key).exported_folder_name }
+                : {}),
+        });
+    }
+    if (problems.length > 0)
+        throw new SnapshotError(`${problems.length} problem(s):\n  - ${problems.join("\n  - ")}`);
+    for (const p of plans) {
+        const hFile = join(p.dir, "reverse-history.yaml");
+        const before = structuredClone(p.history.history ?? []);
+        if (p.migrated || !(await exists(hFile))) {
+            const h = { ...p.history, history: [...before, p.entry] };
+            await writeFile(hFile, stringify(h, { lineWidth: 0 }));
+        }
+        else {
+            await writeFile(hFile, appendHistoryEntry(await readFile(hFile, "utf8"), p.entry));
+        }
+        const after = parse(await readFile(hFile, "utf8")).history;
+        if (after.length !== before.length + 1 || !isDeepStrictEqual(after.slice(0, before.length), before)) {
+            throw new Error(`${hFile}: post-write check failed — prior entries changed or not exactly one appended`);
+        }
+        if (p.movePin)
+            await writeFile(join(p.dir, "reverse-metadata.yaml"), setTopLevelScalars(p.metadataText, p.metadata));
+        write(`${p.key}: ${p.migrated ? "history migrated, " : ""}${p.movePin ? "pin →" : "row recorded, pin already at"} ${p.metadata.exported_folder_name} (impact ${String(p.entry.impact)})\n`);
+        for (const s of await staleProse(p.dir, fromId, p.priorFolder))
+            write(`  prose may be stale — ${s}\n`);
+    }
+    const moved = plans.filter((p) => p.movePin && p.priorFolder).map((p) => p.priorFolder);
+    if (moved.length > 0) {
+        const cites = await citationsOf(sddPath, moved);
+        if (cites.length > 0) {
+            write(`${cites.length} line(s) elsewhere in the SDD still cite a folder whose pin just moved — review each (the tool edits only the pins):\n`);
+            for (const c of cites)
+                write(`  ${c}\n`);
+        }
+    }
+    return plans;
+}
+/**
+ * Path citations (citesPath) of the given folders anywhere in the SDD — the product
+ * map, the implementation binding, design docs — outside the members' own history
+ * files, whose entries name the prior folder by design. A list, not a control.
+ */
+export async function citationsOf(sddPath, folders) {
+    const out = [];
+    const skip = new Set([".git", "node_modules", "catalogues", "bundle-cache"]);
+    async function walk(dir) {
+        for (const e of await readdir(dir, { withFileTypes: true })) {
+            const full = join(dir, e.name);
+            const rel = relative(sddPath, full).split(sep).join("/");
+            if (e.isDirectory()) {
+                if (!skip.has(e.name) && rel !== "docs/method")
+                    await walk(full);
+            }
+            else if (e.isFile() && /\.(ya?ml|md|json)$/.test(e.name) && !/^repos\/[^/]+\/reverse-history\.yaml$/.test(rel)) {
+                (await readFile(full, "utf8")).split("\n").forEach((line, i) => {
+                    if (folders.some((f) => citesPath(line, f)))
+                        out.push(`${rel}:${i + 1}`);
+                });
+            }
+        }
+    }
+    await walk(sddPath);
+    return out;
+}
+function describeReverification(m) {
+    return m.reverification ?? `revision ${m.source_revision} unchanged`;
+}
+/** Replace (or append) top-level `key: value` lines, leaving every other byte alone. */
+export function setTopLevelScalars(text, values) {
+    let out = text;
+    for (const [k, v] of Object.entries(values)) {
+        const line = `${k}: ${stringify(v).trimEnd()}`;
+        const re = new RegExp(`^${k}:[^\\n]*$`, "m");
+        out = re.test(out) ? out.replace(re, line) : `${out.replace(/\n*$/, "\n")}${line}\n`;
+    }
+    return out;
+}
+/**
+ * Append one entry to a `history:` list that ends the file, at the list's own
+ * indentation. Falls back to a document edit when `history:` is not the last
+ * top-level key; the caller's post-write check covers both paths.
+ */
+export function appendHistoryEntry(text, entry) {
+    const lines = text.replace(/\n*$/, "").split("\n");
+    const h = lines.findIndex((l) => /^history:\s*$/.test(l));
+    const laterTopLevel = h >= 0 && lines.slice(h + 1).some((l) => /^[A-Za-z_][\w-]*:/.test(l));
+    const item = lines.slice(h + 1).find((l) => /^\s*- /.test(l));
+    if (h < 0 || laterTopLevel || item === undefined) {
+        const doc = parseDocument(text);
+        doc.addIn(["history"], doc.createNode(entry));
+        return doc.toString({ lineWidth: 0 });
+    }
+    const indent = item.match(/^(\s*)- /)[1];
+    const body = stringify([entry], { lineWidth: 0 }).trimEnd().split("\n").map((l) => indent + l).join("\n");
+    return `${lines.join("\n")}\n${body}\n`;
+}
+//# sourceMappingURL=advance.js.map

package/dist/lib/snapshot/diff.js

@@ -0,0 +1,190 @@
+// `sdd-cli snapshot diff` — the member and file delta between two baselines,
+// written as delta.yaml's skeleton (delta-reverse.md §4 and §6).
+//
+// Members are classified from the two MANIFESTS, never the folder trees: a
+// carried member is absent from T1's tree and present in the set, and a tree
+// diff calls it removed. A prior member that T1's manifest neither lists nor
+// records in members_removed is refused — the manifest is incomplete.
+//
+// Findings are one per changed member × evidence class, at `status: proposed`,
+// with classification / spec_impact / targets left for judgement. Once any
+// finding carries judgement, diff refuses to rewrite the file.
+import { readFile, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { parse, stringify } from "yaml";
+import { SnapshotError, diffTrees, exists, hashTree, memberBytesDir, readManifest, } from "./manifest.js";
+/**
+ * A deliberately coarse, documented path classifier. It groups files so each
+ * finding is reviewable; it does not decide what a change means (that is
+ * classification, which is judgement). First match wins.
+ */
+export const EVIDENCE_CLASSES = [
+    ["contracts", /\.(avsc|proto|graphql|wsdl|xsd)$|(^|\/)(openapi|swagger|asyncapi)[^/]*\.(ya?ml|json)$/i],
+    ["tests", /(^|\/)(test|tests|__tests__|spec|it|e2e)\/|\.(test|spec)\.[a-z]+$|Tests?\.[a-z]+$/i],
+    ["infrastructure", /\.(tf|tfvars|bicep)$|(^|\/)(helm|charts|k8s|kubernetes|deploy|deployment|terraform)\//i],
+    ["build", /(^|\/)(pom\.xml|build\.gradle(\.kts)?|settings\.gradle(\.kts)?|package\.json|package-lock\.json|yarn\.lock|pnpm-lock\.yaml|go\.mod|go\.sum|Cargo\.toml|Dockerfile[^/]*|Makefile|\.csproj|.*\.sln)$|(^|\/)\.(github|gitlab-ci|circleci)|Jenkinsfile$|bitbucket-pipelines\.yml$/i],
+    ["configuration", /\.(ya?ml|properties|json|toml|ini|conf|env|config)$/i],
+    ["documentation", /\.(md|adoc|rst|txt)$/i],
+    ["source", /./],
+];
+export function evidenceClass(path) {
+    for (const [name, re] of EVIDENCE_CLASSES)
+        if (re.test(path))
+            return name;
+    return "source";
+}
+/** The prior baseline's provenance as `snapshot verify` recorded it, or an explicit "not verified". */
+export async function provenanceOf(areaRoot, id) {
+    const p = join(areaRoot, id, "provenance.yaml");
+    if (!(await exists(p)))
+        return { result: "not verified — run `sdd-cli snapshot verify` on this baseline (delta-reverse §3)" };
+    const r = (parse(await readFile(p, "utf8")) ?? {});
+    return { result: String(r.result ?? "unknown"), ...(r.verified_at ? { verified_at: String(r.verified_at) } : {}), ...(r.waiver ? { waiver: r.waiver } : {}) };
+}
+export function deltaPath(areaRoot, id) {
+    return join(areaRoot, id, "delta.yaml");
+}
+/** Findings that already carry judgement — the reason diff will not rewrite. */
+export function judgedFindings(existing) {
+    const findings = existing?.findings;
+    if (!Array.isArray(findings))
+        return [];
+    return findings.flatMap((f, i) => {
+        const x = f;
+        const judged = (x.status !== undefined && x.status !== "proposed") ||
+            (x.classification !== undefined && x.classification !== null) ||
+            (x.spec_impact !== undefined && x.spec_impact !== null);
+        return judged ? [String(x.id ?? `findings[${i}]`)] : [];
+    });
+}
+export async function runSnapshotDiff(inputs, write) {
+    try {
+        const d = await snapshotDiff(inputs);
+        write(`${d.from_snapshot} → ${d.to_snapshot}: ${d.members_changed.length} changed, ${d.members_unchanged} unchanged, ` +
+            `${d.members_added.length} added, ${d.members_removed.length} removed, ${d.members_carried.length} carried; ` +
+            `${d.findings.length} finding(s) at status proposed → ${deltaPath(inputs.areaRoot, inputs.to)}\n`);
+        return { exitCode: 0 };
+    }
+    catch (e) {
+        if (e instanceof SnapshotError) {
+            write(`REFUSED: ${e.message}\n`);
+            return { exitCode: 1 };
+        }
+        throw e;
+    }
+}
+export async function snapshotDiff(inputs) {
+    const { areaRoot, to } = inputs;
+    const t1 = await readManifest(areaRoot, to);
+    const fromId = inputs.from ?? t1.prior_snapshot;
+    if (!fromId)
+        throw new SnapshotError(`${to} has no prior_snapshot; pass --from`);
+    const t0 = await readManifest(areaRoot, fromId);
+    const out = deltaPath(areaRoot, to);
+    if (await exists(out)) {
+        const existing = parse(await readFile(out, "utf8"));
+        const judged = judgedFindings(existing);
+        if (Array.isArray(existing?.stale_scores) && existing.stale_scores.length > 0)
+            judged.push("stale_scores");
+        if (judged.length > 0) {
+            throw new SnapshotError(`${out} already holds judgement on ${judged.length} finding(s) (${judged.slice(0, 5).join(", ")}${judged.length > 5 ? ", …" : ""}) — diff will not overwrite it`);
+        }
+    }
+    const delta = await computeDelta(areaRoot, t0, t1);
+    const header = "# Snapshot delta -- reverse/workflows/delta-reverse.md §6. Skeleton written by `sdd-cli snapshot diff`;\n" +
+        "# classification, spec_impact and targets are judgement (steps 5-6). Once any is set, diff will not rewrite this file.\n";
+    await writeFile(out, header + stringify(delta, { lineWidth: 0 }));
+    return delta;
+}
+export async function computeDelta(areaRoot, t0, t1) {
+    const t0ByKey = new Map(t0.members.map((m) => [m.canonical_repo_key, m]));
+    const t1Keys = new Set(t1.members.map((m) => m.canonical_repo_key));
+    const removedKeys = new Set((t1.members_removed ?? []).map((r) => r.canonical_repo_key));
+    const unaccounted = t0.members.filter((m) => !t1Keys.has(m.canonical_repo_key) && !removedKeys.has(m.canonical_repo_key));
+    if (unaccounted.length > 0) {
+        throw new SnapshotError(`${t1.snapshot_id}'s manifest does not account for ${unaccounted.map((m) => m.canonical_repo_key).join(", ")} from ${t0.snapshot_id} — ` +
+            "each must be a member (carried or re-observed) or in members_removed[]");
+    }
+    const delta = {
+        implementation: t1.implementation,
+        from_snapshot: t0.snapshot_id,
+        to_snapshot: t1.snapshot_id,
+        members_changed: [],
+        members_added: [],
+        members_removed: (t1.members_removed ?? []).map((r) => ({ canonical_repo_key: r.canonical_repo_key, last_revision: r.last_revision, reason: r.reason })),
+        members_carried: [],
+        members_unchanged: 0,
+        disposition: null,
+        impact: null,
+        t0_provenance: await provenanceOf(areaRoot, t0.snapshot_id),
+        stale_scores: [],
+        findings: [],
+        open_questions: [],
+    };
+    for (const m of t1.members) {
+        const p = t0ByKey.get(m.canonical_repo_key);
+        if (!p) {
+            delta.members_added.push({ canonical_repo_key: m.canonical_repo_key, to_revision: m.source_revision });
+            // A new member gets the full seeding sequence, not a delta — but what the
+            // seeding writes must still trace to a finding, so it gets one.
+            delta.findings.push(memberFinding(m.canonical_repo_key, "member-added", `new member at ${m.source_revision}: seed it (full sequence), then target what it grounds`));
+            continue;
+        }
+        if (m.carried_from !== undefined) {
+            delta.members_carried.push({ canonical_repo_key: m.canonical_repo_key, carried_from: m.carried_from, carried_reason: m.carried_reason ?? "" });
+            delta.members_unchanged++;
+            continue;
+        }
+        if (p.source_revision === m.source_revision) {
+            delta.members_unchanged++;
+            continue;
+        }
+        const files = diffTrees(await hashTree(memberBytesDir(areaRoot, t0, p)), await hashTree(memberBytesDir(areaRoot, t1, m)));
+        delta.members_changed.push({
+            canonical_repo_key: m.canonical_repo_key,
+            from_revision: p.source_revision,
+            to_revision: m.source_revision,
+            files: { added: files.added.length, removed: files.removed.length, modified: files.modified.length },
+        });
+        const byClass = new Map();
+        for (const kind of ["added", "removed", "modified"]) {
+            for (const f of files[kind]) {
+                const c = evidenceClass(f);
+                if (!byClass.has(c))
+                    byClass.set(c, { added: [], removed: [], modified: [] });
+                byClass.get(c)[kind].push(f);
+            }
+        }
+        for (const [c, fs] of [...byClass].sort(([a], [b]) => a.localeCompare(b))) {
+            delta.findings.push({
+                id: `${m.canonical_repo_key}.${c}`,
+                member: m.canonical_repo_key,
+                evidence_class: c,
+                status: "proposed",
+                classification: null,
+                spec_impact: null,
+                summary: `${fs.added.length} added, ${fs.removed.length} removed, ${fs.modified.length} modified ${c} file(s)`,
+                files: fs,
+                targets: [],
+            });
+        }
+    }
+    for (const r of t1.members_removed ?? []) {
+        delta.findings.push(memberFinding(r.canonical_repo_key, "member-removed", `left the set (${r.reason}); a removed member is not a removed capability until you have checked where the capability went`));
+    }
+    return delta;
+}
+function memberFinding(member, kind, summary) {
+    return {
+        id: `${member}.${kind}`,
+        member,
+        evidence_class: kind,
+        status: "proposed",
+        classification: null,
+        spec_impact: null,
+        summary,
+        files: { added: [], removed: [], modified: [] },
+        targets: [],
+    };
+}
+//# sourceMappingURL=diff.js.map