@sdd-method/author-cli 0.13.0 → 0.14.1

package/dist/lib/structure/archive.js

@@ -0,0 +1,330 @@
+// The method's archive operation (M-ADR 0230 §4.6): behaviour and structure published as one unit.
+//   1. prepare   the full candidate in a scratch worktree at the store's current commit: OpenSpec archives the
+//                change there (behaviour), and its structural deltas are applied to the model with a record of
+//                their effect (structure/applied.yaml in the archived change)
+//   2. validate  the candidate as a whole: the change's deltas still apply (§4.5 again at archive), the model as it
+//                would stand fails nowhere the current model does not, and the behaviour-store check finds nothing
+//                wrong with the archived change (its agreed content, its verdict)
+//   3. publish   one commit, fast-forwarded onto the store only if the store has not moved since preparation; the
+//                model's generated views (docs/structure/) are rendered into it, since they are required and derived
+//                (M-ADR 0230 §4.3, at its acceptance)
+// Readers take a published commit, so they see the old state or the new. A retry is idempotent: an archived change
+// whose effect record holds at the commit that wrote it is reported as already archived. Recovery works from what
+// the store holds: an archived change with structural deltas and no effect record (a raw `openspec archive`) has its
+// deltas applied only if each element it writes is still at the revision it was written against.
+//
+// The store is the SDD's own `openspec/` in a git repository. Writes; never part of the verify-only CLI.
+import { execFile as execFileCb } from "node:child_process";
+import { mkdir, mkdtemp, readdir, readFile, rm, stat, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { dirname, join, relative } from "node:path";
+import { promisify } from "node:util";
+import { parseRequirements, resolveImplements } from "../behaviour-store/archive.js";
+import { buildRequirements } from "../catalogue/builders/requirements.js";
+import { parseCatalogueCsv } from "../catalogue/csv-reader.js";
+import { FindingsLog } from "../catalogue/findings.js";
+import { loadCanonicalSchema } from "../catalogue/schema-loader.js";
+import { checkBehaviourStore, parseAgreementRecord } from "../validate/behaviour-store.js";
+import { appliedRecord, applyToModel, effectsOf, parseAppliedRecord } from "./apply.js";
+import { APPLIED_FILE, loadChangeStructure, loadModel } from "./model.js";
+import { renderViews } from "./render.js";
+import { revisionOf, validateDeltas, validateView, viewOf } from "./view.js";
+const execFile = promisify(execFileCb);
+const CHANGES = join("openspec", "changes");
+/** Exit codes: 0 archived or already archived, 1 refused, 75 interrupted (tests). */
+export const INTERRUPTED = 75;
+async function git(cwd, ...args) {
+    return (await execFile("git", ["-C", cwd, ...args], { maxBuffer: 64 * 1024 * 1024 })).stdout.trim();
+}
+async function exists(p) {
+    return stat(p).then(() => true, () => false);
+}
+async function subdirs(p) {
+    try {
+        return (await readdir(p, { withFileTypes: true })).filter((e) => e.isDirectory()).map((e) => e.name).sort();
+    }
+    catch {
+        return [];
+    }
+}
+async function archivedDir(sddPath, change) {
+    const found = (await subdirs(join(sddPath, CHANGES, "archive"))).filter((d) => d.replace(/^\d{4}-\d{2}-\d{2}-/, "") === change);
+    return found.length > 0 ? found[found.length - 1] : null;
+}
+async function defaultOpenspecArchive(cwd, change) {
+    try {
+        const r = await execFile("openspec", ["archive", change, "--yes"], { cwd, env: { ...process.env, OPENSPEC_TELEMETRY: "0" }, maxBuffer: 16 * 1024 * 1024 });
+        return { code: 0, output: r.stdout + r.stderr };
+    }
+    catch (err) {
+        const e = err;
+        return { code: typeof e.code === "number" ? e.code : 127, output: `${e.stdout ?? ""}${e.stderr ?? ""}` };
+    }
+}
+async function defaultBehaviourFindings(sddPath, archiveDir) {
+    const r = await checkBehaviourStore(sddPath);
+    return r.stdout.split("\n").filter((l) => l.startsWith("[FAIL]") && l.includes(archiveDir));
+}
+function viewProblems(schema, view) {
+    const out = [];
+    validateView(schema, view, () => null, out, new Set());
+    return new Set(out);
+}
+/** Does the effect record hold at `commit`? Each added or modified element at its target, each removed one absent. */
+async function verifyAt(root, relSdd, commit, effects) {
+    const scratch = await mkdtemp(join(tmpdir(), "sdd-archive-verify-"));
+    try {
+        await git(root, "worktree", "add", "--detach", "-q", scratch, commit);
+        const problems = [];
+        const files = (await loadModel(join(scratch, relSdd), problems)) ?? [];
+        const view = viewOf(files, problems);
+        const bad = [];
+        for (const e of effects) {
+            const [catalogue, ...rest] = e.element.split("/");
+            const el = view.get(catalogue)?.get(rest.join("/"));
+            if (e.operation === "REMOVED") {
+                if (el)
+                    bad.push(`${e.element} is still present`);
+            }
+            else if (!el)
+                bad.push(`${e.element} is absent`);
+            else if (revisionOf(el) !== e.target)
+                bad.push(`${e.element} is at ${revisionOf(el).slice(0, 19)}…, not the recorded ${String(e.target).slice(0, 19)}…`);
+        }
+        return bad;
+    }
+    finally {
+        await git(root, "worktree", "remove", "--force", scratch).catch(() => undefined);
+        await rm(scratch, { recursive: true, force: true });
+    }
+}
+export async function archiveChange(o) {
+    const say = (s) => o.write(`${s}\n`);
+    const refuse = (s) => {
+        say(`[FAIL] change archive ${o.change}: ${s}`);
+        return 1;
+    };
+    let root;
+    try {
+        root = await git(o.sddPath, "rev-parse", "--show-toplevel");
+    }
+    catch {
+        return refuse(`${o.sddPath} is not in a git repository; the archive is published as a commit`);
+    }
+    const relSdd = relative(root, o.sddPath) || ".";
+    const schema = o.schema ?? (await loadCanonicalSchema());
+    const openDir = join(CHANGES, o.change);
+    const isOpen = await exists(join(o.sddPath, openDir));
+    const archived = await archivedDir(o.sddPath, o.change);
+    // Already archived: verify, or recover a raw archive.
+    if (!isOpen && archived !== null) {
+        const archRel = join(CHANGES, "archive", archived);
+        const problems = [];
+        const s = await loadChangeStructure(o.sddPath, join("archive", archived), problems);
+        if (problems.length > 0)
+            return refuse(`its archived structural artifact is malformed: ${problems.join("; ")}`);
+        if (s.deltas.length === 0) {
+            say(`[PASS] change archive ${o.change}: already archived (${archRel}); it carries no structural deltas`);
+            return 0;
+        }
+        const recordPath = join(o.sddPath, archRel, "structure", APPLIED_FILE);
+        const text = await readFile(recordPath, "utf8").catch(() => null);
+        if (text !== null) {
+            const rec = parseAppliedRecord(text);
+            if (rec === null)
+                return refuse(`${join(archRel, "structure", APPLIED_FILE)} is not a valid effect record`);
+            const at = await git(root, "log", "-1", "--format=%H", "--", relative(root, recordPath));
+            if (at === "")
+                return refuse(`${join(archRel, "structure", APPLIED_FILE)} is not committed; the archive was not published`);
+            const bad = await verifyAt(root, relSdd, at, rec.effects);
+            if (bad.length > 0)
+                return refuse(`its effect record does not hold at ${at.slice(0, 12)}, the commit that wrote it: ${bad.join("; ")}`);
+            say(`[PASS] change archive ${o.change}: already archived at ${at.slice(0, 12)}; its ${rec.effects.length} structural effect(s) verified there`);
+            return 0;
+        }
+        // A raw archive: the behaviour moved, the structure did not. Apply it, guarded by each written element's base.
+        return publish(o, root, relSdd, schema, s, archRel, "recover");
+    }
+    if (!isOpen)
+        return refuse(`no open change ${openDir}, and none archived`);
+    // An open change: preconditions.
+    const baseline = await exists(join(o.sddPath, openDir, "baseline-evidence.md"));
+    if (!baseline) {
+        const recFile = join("docs", "agreements", `${o.change}.yaml`);
+        const recText = await readFile(join(o.sddPath, recFile), "utf8").catch(() => null);
+        if (recText === null)
+            return refuse(`no agreement record (${recFile}); a change archives on its judge's PASS`);
+        const { record } = parseAgreementRecord(recFile, recText);
+        if (!record)
+            return refuse(`${recFile} does not parse as an agreement record`);
+        if (record.status !== "agreed")
+            return refuse(`${recFile} says status ${record.status}, not agreed`);
+        if (String(record.verdict?.result ?? "") !== "PASS")
+            return refuse(`${recFile} has no verdict.result PASS; a change archives on its judge's PASS`);
+        const left = await leftOut(o.sddPath, o.change, record.workOrders, record.noLongerImplements);
+        if (left.length > 0)
+            return refuse(left.join("\n  "));
+    }
+    const problems = [];
+    const s = await loadChangeStructure(o.sddPath, o.change, problems);
+    if (problems.length > 0)
+        return refuse(`its structural artifact is malformed: ${problems.join("; ")}`);
+    for (const dep of new Set(s.deltas.flatMap((d) => [...d.dependsOn]))) {
+        if ((await archivedDir(o.sddPath, dep)) === null)
+            return refuse(`it depends on ${dep}, which has not archived; a change archives after its dependencies`);
+    }
+    return publish(o, root, relSdd, schema, s, openDir, "archive");
+}
+/**
+ * M-ADR 0230 §4.7: when a change moves a requirement to a new revision, each repository with evidence about the
+ * current one implements the new one too, through a work order, or the record says it no longer implements it
+ * (`no_longer_implements`). Otherwise the archive would leave that repository's evidence about a revision that is no
+ * longer live, and nothing about the one that is. Reads the store as the catalogue builder does.
+ */
+async function leftOut(sddPath, change, workOrders, noLonger) {
+    // Only a change that modifies a requirement can leave a repository behind; any change can name a requirement
+    // ambiguously.
+    const delta = [];
+    let modifies = false;
+    for (const feature of await subdirs(join(sddPath, CHANGES, change, "specs"))) {
+        const text = await readFile(join(sddPath, CHANGES, change, "specs", feature, "spec.md"), "utf8").catch(() => "");
+        for (const x of parseRequirements(text)) {
+            if (x.operation === "MODIFIED")
+                modifies = true;
+            if (x.operation !== "REMOVED")
+                delta.push({ feature, name: x.name });
+        }
+    }
+    // A requirement named in a work order or under no_longer_implements: `<feature>::<name>`, or a bare name only one
+    // feature in the change has, as the record schema says. An ambiguous bare name names neither, and is refused.
+    const ambiguous = [];
+    const resolve = (entry, where) => {
+        const r = resolveImplements(delta, entry);
+        if (r.ambiguous.length > 0)
+            ambiguous.push(`${where} names "${entry}", a requirement ${r.ambiguous.length} features in the change share (${r.ambiguous.join(", ")}); qualify it as <feature>::<name>`);
+        return new Set(r.matches.map((d) => `${d.feature}::${d.name}`));
+    };
+    const implementsOf = workOrders.map((w) => ({ repo: w.repo, ids: new Set(w.implements.flatMap((i) => [...resolve(i, `the work order for ${w.repo}`)])) }));
+    const excusedOf = noLonger.map((n) => ({ repo: n.repo, ids: resolve(n.requirement, `no_longer_implements for ${n.repo}`) }));
+    if (ambiguous.length > 0)
+        return ambiguous;
+    if (!modifies)
+        return [];
+    const ids = async (catalogue) => {
+        const text = await readFile(join(sddPath, "catalogues", `${catalogue}.csv`), "utf8").catch(() => null);
+        return text === null ? null : new Set(parseCatalogueCsv(text).rows.map((r) => String(r["id"])));
+    };
+    const features = await ids("features");
+    const repos = await ids("repositories");
+    if (features === null || repos === null)
+        return ["the catalogue (catalogues/features.csv and repositories.csv) is needed to tell which repositories implement the requirements this change modifies; build it first"];
+    const r = await buildRequirements({ sddPath, findings: new FindingsLog(), knownFeatureIds: features, knownRepoIds: repos, sddId: "local" });
+    const state = new Map(r.revisions.map((x) => [String(x["id"]), String(x["state"])]));
+    const modified = r.effects
+        .filter((e) => e["change_id"] === `local::${change}` && e["element_kind"] === "requirement" && e["operation"] === "MODIFIED")
+        .map((e) => String(e["element_id"]));
+    const out = [];
+    for (const req of modified) {
+        const implementers = new Set(r.assertions.filter((a) => a["requirement_id"] === req && state.get(String(a["revision_id"])) === "current").map((a) => String(a["repo_id"])));
+        const covered = new Set(implementsOf.filter((w) => w.ids.has(req)).map((w) => w.repo));
+        const excused = new Set(excusedOf.filter((n) => n.ids.has(req)).map((n) => n.repo));
+        const missing = [...implementers].filter((repo) => !covered.has(repo) && !excused.has(repo)).sort();
+        if (missing.length > 0) {
+            out.push(`${req}: ${missing.join(", ")} ${missing.length === 1 ? "implements" : "implement"} its current revision, and no work order of this change implements the new one; add a work order for ${missing.length === 1 ? "it" : "each"}, or record it under no_longer_implements`);
+        }
+    }
+    return out;
+}
+async function publish(o, root, relSdd, schema, s, changeRel, mode) {
+    const say = (x) => o.write(`${x}\n`);
+    const refuse = (x) => {
+        say(`[FAIL] change archive ${o.change}: ${x}`);
+        return 1;
+    };
+    const storeRel = join(relSdd, "openspec");
+    const viewsRel = join(relSdd, "docs", "structure");
+    const dirty = await git(root, "status", "--porcelain", "--", storeRel, viewsRel);
+    if (dirty !== "")
+        return refuse(`the store has uncommitted changes (${dirty.split("\n").length} path(s) under ${storeRel} or ${viewsRel}); the archive is published as one commit onto a clean store`);
+    const base = await git(root, "rev-parse", "HEAD");
+    // §4.5 again, against the model as it now is.
+    const problems = [];
+    const current = viewOf((await loadModel(o.sddPath, problems)) ?? [], problems);
+    const before = viewProblems(schema, current);
+    const deltaProblems = [];
+    validateDeltas(schema, current, s.deltas, new Map(), deltaProblems);
+    if (deltaProblems.length > 0)
+        return refuse(`its structural deltas no longer apply to the model as it stands:\n  ${deltaProblems.join("\n  ")}`);
+    const effects = effectsOf(s, current);
+    const scratch = await mkdtemp(join(tmpdir(), "sdd-archive-"));
+    let added = false;
+    try {
+        await git(root, "worktree", "add", "--detach", "-q", scratch, base);
+        added = true;
+        const scratchSdd = join(scratch, relSdd);
+        // 1. Prepare.
+        let archiveRel = changeRel;
+        if (mode === "archive") {
+            const beforeDirs = new Set(await subdirs(join(scratchSdd, CHANGES, "archive")));
+            const r = await (o.openspecArchive ?? defaultOpenspecArchive)(scratchSdd, o.change);
+            if (r.code !== 0)
+                return refuse(`openspec archive failed (exit ${r.code}): ${r.output.trim().split("\n").slice(-3).join(" ")}`);
+            const fresh = (await subdirs(join(scratchSdd, CHANGES, "archive"))).filter((d) => !beforeDirs.has(d));
+            if (fresh.length !== 1)
+                return refuse(`openspec archive left ${fresh.length} new archive folder(s), not one`);
+            archiveRel = join(CHANGES, "archive", fresh[0]);
+        }
+        await applyToModel(scratchSdd, s);
+        if (s.deltas.length > 0)
+            await writeFile(join(scratchSdd, archiveRel, "structure", APPLIED_FILE), appliedRecord(o.change, base, effects), "utf8");
+        // 2. Validate the candidate as a whole.
+        const cp = [];
+        const candidate = viewOf((await loadModel(scratchSdd, cp)) ?? [], cp);
+        const after = viewProblems(schema, candidate);
+        const worse = [...cp, ...[...after].filter((p) => !before.has(p))];
+        if (worse.length > 0)
+            return refuse(`the model as it would stand fails where it did not:\n  ${worse.join("\n  ")}`);
+        if (mode === "archive") {
+            const bf = await (o.behaviourFindings ?? defaultBehaviourFindings)(scratchSdd, archiveRel.split("/").pop());
+            if (bf.length > 0)
+                return refuse(`the behaviour-store check refuses the archived change:\n  ${bf.join("\n  ")}`);
+        }
+        if (o.interrupt === "prepared")
+            return INTERRUPTED;
+        // The generated views move with the model they render, in the same commit.
+        if (s.deltas.length > 0) {
+            for (const [path, text] of renderViews(candidate)) {
+                await mkdir(dirname(join(scratchSdd, path)), { recursive: true });
+                await writeFile(join(scratchSdd, path), text, "utf8");
+            }
+        }
+        // 3. Publish: one commit, fast-forwarded only onto the commit it was prepared from.
+        const withViews = await stat(join(scratch, viewsRel)).then(() => true, () => false);
+        await git(scratch, "add", "-A", "--", storeRel, ...(withViews ? [viewsRel] : []));
+        const message = mode === "archive"
+            ? `Archive ${o.change}: its behaviour and structure (M-ADR 0230 §4.6)`
+            : `Apply the structure of archived ${o.change}, which was archived without it (M-ADR 0230 §4.6)`;
+        await git(scratch, "commit", "-q", "-m", message);
+        const commit = await git(scratch, "rev-parse", "HEAD");
+        if (o.interrupt === "committed")
+            return INTERRUPTED;
+        if ((await git(root, "rev-parse", "HEAD")) !== base)
+            return refuse(`the store moved since the candidate was prepared (from ${base.slice(0, 12)}); run it again`);
+        try {
+            await git(root, "merge", "--ff-only", "-q", commit);
+        }
+        catch (err) {
+            return refuse(`the store moved since the candidate was prepared, so nothing was published: ${err.message.split("\n")[0]}`);
+        }
+        if (o.interrupt === "published")
+            return INTERRUPTED;
+        say(`[PASS] change archive ${o.change}: ${mode === "archive" ? "archived" : "its structure applied"} in ${commit.slice(0, 12)}, ${effects.length} structural effect(s)${s.deltas.length > 0 ? `, recorded in ${join(archiveRel, "structure", APPLIED_FILE)}` : ""}`);
+        return 0;
+    }
+    finally {
+        if (added)
+            await git(root, "worktree", "remove", "--force", scratch).catch(() => undefined);
+        await rm(scratch, { recursive: true, force: true });
+    }
+}
+//# sourceMappingURL=archive.js.map

package/dist/lib/structure/catalogue.js

@@ -1,13 +1,15 @@
-// The catalogue from the structural model, and the model a built catalogue implies (M-ADR 0230 §4.3, §5.3,
-// Proposed). Where an SDD has a model, it is the record of structure, so every structure catalogue is built from it whole:
+// The catalogue from the structural model, and the model a built catalogue implies (M-ADR 0230 §4.3, §5.3).
+// Where an SDD has a model, it is the record of structure, so every structure catalogue is built from it whole:
 //   a row per element of the current view, with the model's structure columns;
 //   its other columns (every class but structure: derived, declaration, evidence, intent, execution) from the
 //   source-built row with the same id;
 //   for an element only the model holds, the derived columns the model itself settles (MODEL_DERIVED).
 // What the sources hold and the model does not, and a structure column where they disagree, is reported once per
-// catalogue. The model wins: either finding means the sources moved outside a change. Pure: no file is read or written.
+// catalogue. The model wins: either finding means the sources moved outside a change. A source row that states an
+// element as an agreed open change adds or modifies it is that change's intended element, not a disagreement: it is
+// listed apart, and catalogued once the change archives. Pure: no file is read or written.
 import { stringify } from "yaml";
-import { FORMAT_VERSION } from "./model.js";
+import { elementKey, FORMAT_VERSION } from "./model.js";
 import { STRUCTURE } from "./view.js";
 /** The view each generated file renders, for a derived path column of an element only the model holds. */
 export const VIEW_PATHS = {
@@ -44,8 +46,10 @@ function sample(ids) {
 /**
  * Replace every structure catalogue's rows with the view's. Rows of other catalogues are returned as they are. Source
  * rows sharing an id are merged first, later values filling earlier gaps, as the keyed-table dedupe would.
+ * `intended` holds the elements agreed open changes add or modify (intendedWrites); a source row agreeing with one is
+ * pushed to `intendedOut` as `<key> (<change>)` instead of being reported.
  */
-export function overlayModel(schema, view, rows, findings) {
+export function overlayModel(schema, view, rows, findings, intended = new Map(), intendedOut = []) {
     const out = new Map(rows);
     for (const cat of schema.catalogues) {
         if (cat.sourceOfTruth !== STRUCTURE)
@@ -66,6 +70,20 @@ export function overlayModel(schema, view, rows, findings) {
         const elements = view.get(cat.name) ?? new Map();
         const built = [];
         const differ = [];
+        const disagree = (from, e) => structural.filter((c) => cell(from[c]) !== "" && cell(from[c]) !== cell(e.columns[c]));
+        // The source row states the element as an agreed open change does; one stating it otherwise is reported as such.
+        const differIntended = [];
+        const asIntended = (id, from) => {
+            const w = intended.get(elementKey(cat.name, id));
+            if (w === undefined)
+                return false;
+            const cols = disagree(from, w.element);
+            if (cols.length > 0)
+                differIntended.push(`${id} (${cols.join(", ")}; ${w.change})`);
+            else
+                intendedOut.push(`${elementKey(cat.name, id)} (${w.change})`);
+            return true;
+        };
         for (const e of elements.values()) {
             const from = source.get(e.id);
             const row = {};
@@ -73,8 +91,8 @@ export function overlayModel(schema, view, rows, findings) {
                 for (const [k, v] of Object.entries(from))
                     if (!structural.includes(k))
                         row[k] = v;
-                const cols = structural.filter((c) => cell(from[c]) !== "" && cell(from[c]) !== cell(e.columns[c]));
-                if (cols.length > 0)
+                const cols = disagree(from, e);
+                if (cols.length > 0 && !asIntended(e.id, from))
                     differ.push(`${e.id} (${cols.join(", ")})`);
             }
             else {
@@ -85,12 +103,15 @@ export function overlayModel(schema, view, rows, findings) {
                 row[c] = e.columns[c];
             built.push(row);
         }
-        const missing = [...source.keys()].filter((id) => id !== "" && !elements.has(id)).sort();
+        const missing = [...source.keys()].filter((id) => id !== "" && !elements.has(id) && !asIntended(id, source.get(id))).sort();
         if (missing.length > 0) {
-            findings.add("divergence", `${cat.name}: the sources hold ${missing.length} row(s) the structural model does not (${sample(missing)}); the model is the record of structure, so they are not catalogued. Add them through a change's structural deltas, or remove them from the sources (M-ADR 0230 §4.3, Proposed)`, "warn", `catalogue:${cat.name}`);
+            findings.add("divergence", `${cat.name}: the sources hold ${missing.length} row(s) the structural model does not (${sample(missing)}); the model is the record of structure, so they are not catalogued. Add them through a change's structural deltas, or remove them from the sources (M-ADR 0230 §4.3)`, "warn", `catalogue:${cat.name}`);
+        }
+        if (differIntended.length > 0) {
+            findings.add("divergence", `${cat.name}: ${differIntended.length} source row(s) state an element an agreed open change adds or modifies, and disagree with it: ${sample(differIntended.sort())}. The change's delta is what archives; bring the source into line with it, or the delta with the source (M-ADR 0230 §4.3, §4.7)`, "warn", `catalogue:${cat.name}`);
         }
         if (differ.length > 0) {
-            findings.add("divergence", `${cat.name}: ${differ.length} element(s) where the sources and the structural model disagree, catalogued as the model states them: ${sample(differ.sort())}. A source that is a generated view is rendered again; any other is brought into line through a change (M-ADR 0230 §4.3, Proposed)`, "warn", `catalogue:${cat.name}`);
+            findings.add("divergence", `${cat.name}: ${differ.length} element(s) where the sources and the structural model disagree, catalogued as the model states them: ${sample(differ.sort())}. A source that is a generated view is rendered again; any other is brought into line through a change (M-ADR 0230 §4.3)`, "warn", `catalogue:${cat.name}`);
         }
         out.set(cat.name, built);
     }

package/dist/lib/structure/compose.js

@@ -1,4 +1,4 @@
-// Views over the structural model, and how changes compose (M-ADR 0230 §4.5, §4.7, Proposed).
+// Views over the structural model, and how changes compose (M-ADR 0230 §4.5, §4.7).
 //   current       the model as published
 //   at a change   current with that change's deltas and those of its dependency closure, dependencies first
 //   intended      current with every agreed change's deltas

package/dist/lib/structure/effects.js

@@ -1,4 +1,4 @@
-// A change's structural effect, and the effect record an archive leaves (M-ADR 0230 §4.6, §4.7, Proposed). Pure reads,
+// A change's structural effect, and the effect record an archive leaves (M-ADR 0230 §4.6, §4.7). Pure reads,
 // so the catalogue builder and the verify-only CLI can carry them; writing the record is apply.ts's.
 import { parseDocument } from "yaml";
 import { elementKey, revision } from "./model.js";

package/dist/lib/structure/extract.js

@@ -0,0 +1,123 @@
+// An SDD's first structural model, extracted from its sources (M-ADR 0230 §5.3, §6 step 1). The builders
+// already parse the sources: the diagrams, data models, service tables, configuration, traceability manifests,
+// feature trees and groundings. So extraction builds the catalogue from the sources into a scratch directory, and
+// projects the model it implies (modelFromRows). It writes the partition files and an extraction report beside
+// them, and touches no source file. From the moment openspec/structure/ exists, committed or not, the catalogue is
+// built from the model, so writing it is the admission: review the extraction against the code first, with --dry-run
+// (which writes nothing) or in a scratch copy, and keep the originals until that review is complete.
+import { execFileSync } from "node:child_process";
+import { mkdir, mkdtemp, readdir, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { runCatalogueBuild } from "../catalogue/build.js";
+import { readCatalogueCsv } from "../catalogue/csv-reader.js";
+import { loadCanonicalSchema } from "../catalogue/schema-loader.js";
+import { modelFileText, modelFromRows } from "./catalogue.js";
+import { STRUCTURE_DIR } from "./model.js";
+import { STRUCTURE } from "./view.js";
+export const REPORT_FILE = "extraction-report.md";
+/** Derived path columns of structure catalogues: the source files the elements were read from. */
+const SOURCE_PATH_COLUMNS = ["doc_path", "diagram_path", "spec_path"];
+function head(sddPath) {
+    try {
+        const sha = execFileSync("git", ["-C", sddPath, "rev-parse", "--short", "HEAD"], { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }).trim();
+        const dirty = execFileSync("git", ["-C", sddPath, "status", "--porcelain"], { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }).trim() !== "";
+        return dirty ? `${sha}, with uncommitted changes` : sha;
+    }
+    catch {
+        return "not a git repository";
+    }
+}
+function report(sddId, at, schemaVersion, x, sources, otherFindings) {
+    const lines = [
+        "# Structural model extraction",
+        "",
+        `Extracted by \`sdd-cli migrate structure\` from ${sddId}'s sources at ${at}, against catalogue schema ${schemaVersion} (M-ADR 0230).`,
+        "",
+        "**Writing this model admits it as the baseline** (M-ADR 0230 §6 step 1). From the moment `openspec/structure/` exists, committed or not, it is the record of structure: the catalogue is built from it, and the structural-model check asks every open change for its structural deltas or a `none.yaml`, and fails a change that has neither. Review it against the code before it is written (`sdd-cli migrate structure --dry-run` prints this report and writes nothing), and keep the sources listed below until that review is complete; nothing here changed them. Removing `openspec/structure/` withdraws a model written too soon. After admission, structure changes only through a change's structural deltas, and the diagrams and tables are generated by `sdd-cli structure render`.",
+        "",
+        "## Elements",
+        "",
+        "| Catalogue | Elements |",
+        "| --- | --- |",
+        ...[...x.counts].map(([c, n]) => `| ${c} | ${n} |`),
+        "",
+        `Partitions: ${[...x.files.keys()].map((p) => `\`${p}\``).join(", ") || "none"}.`,
+        "",
+        "## What the extraction could not carry",
+        "",
+    ];
+    if (x.loss.length === 0 && x.extraction.length === 0)
+        lines.push("Nothing: every structural fact the sources state that a builder reads is in the model.", "");
+    for (const l of x.loss)
+        lines.push(`- ${l}`);
+    for (const f of x.extraction)
+        lines.push(`- ${f.summary}`);
+    if (x.loss.length + x.extraction.length > 0)
+        lines.push("");
+    lines.push("Prose, and anything a builder does not read, stays in the original files only. A diagram's layout and styling are not structure, and the generated views do not reproduce them.", "", "## Sources the elements were read from", "", ...(sources.length > 0 ? sources.map((s) => `- \`${s}\``) : ["- (no element names its source file)"]), "", "## Other findings of the build", "", ...(otherFindings.size > 0 ? [...otherFindings].map(([c, n]) => `- ${c}: ${n}`) : ["- none"]), "", "These are the build's findings about the sources. They are reported by `sdd-cli catalogue build` as before, and extraction does not change them.", "");
+    return lines.join("\n");
+}
+/** Extract the model. Writes nothing; `writeExtraction` writes it. `build` is the catalogue build, replaceable in tests. */
+export async function extractStructure(sddPath, build = runCatalogueBuild) {
+    const none = { files: new Map(), counts: new Map(), loss: [], extraction: [], report: "" };
+    try {
+        await readdir(join(sddPath, STRUCTURE_DIR));
+        return { ...none, refused: `${STRUCTURE_DIR}/ already exists; an SDD's first model is extracted once, and after that structure changes through a change's structural deltas` };
+    }
+    catch {
+        // no model yet
+    }
+    const schema = await loadCanonicalSchema();
+    const scratch = await mkdtemp(join(tmpdir(), "sdd-migrate-structure-"));
+    try {
+        const built = await build({ sddPath, outDir: scratch }, () => undefined);
+        if (built.exitCode !== 0) {
+            return { ...none, refused: `the sources do not build cleanly (sdd-cli catalogue build exits ${built.exitCode}: ${built.internalFkPass ? "" : "dangling references, "}${built.pkConflicts} key conflict(s)); a model extracted from them would carry the same faults. Fix the build first` };
+        }
+        const rows = new Map();
+        for (const c of schema.catalogues) {
+            if (c.sourceOfTruth !== STRUCTURE)
+                continue;
+            rows.set(c.name, (await readCatalogueCsv(join(scratch, `${c.name}.csv`)).catch(() => ({ rows: [] }))).rows);
+        }
+        const loss = [];
+        const model = modelFromRows(schema, rows, { platform: built.profile === "platform-profile", sddId: built.sddId }, loss);
+        const files = new Map([...model].sort(([a], [b]) => a.localeCompare(b)).map(([p, els]) => [p, modelFileText(p, els)]));
+        const counts = new Map();
+        for (const els of model.values())
+            for (const [c, list] of Object.entries(els))
+                counts.set(c, (counts.get(c) ?? 0) + list.length);
+        const sortedCounts = new Map([...counts].sort(([a], [b]) => a.localeCompare(b)));
+        const sources = new Set();
+        for (const list of rows.values())
+            for (const r of list)
+                for (const col of SOURCE_PATH_COLUMNS)
+                    if (r[col])
+                        sources.add(String(r[col]));
+        const extraction = built.findings.filter((f) => f.category === "extraction");
+        const other = new Map();
+        for (const f of built.findings)
+            if (f.category !== "extraction")
+                other.set(String(f.category), (other.get(String(f.category)) ?? 0) + 1);
+        const x = { files, counts: sortedCounts, loss, extraction };
+        return { ...x, refused: null, report: report(built.sddId, head(sddPath), schema.schemaVersion, x, [...sources].sort(), new Map([...other].sort())) };
+    }
+    finally {
+        await rm(scratch, { recursive: true, force: true });
+    }
+}
+/** Write the partition files and the report under openspec/structure/. Returns the paths written. */
+export async function writeExtraction(sddPath, x) {
+    const dir = join(sddPath, STRUCTURE_DIR);
+    await mkdir(dir, { recursive: true });
+    const written = [];
+    for (const [p, text] of x.files) {
+        await writeFile(join(dir, `${p}.yaml`), text, "utf8");
+        written.push(join(STRUCTURE_DIR, `${p}.yaml`));
+    }
+    await writeFile(join(dir, REPORT_FILE), x.report, "utf8");
+    written.push(join(STRUCTURE_DIR, REPORT_FILE));
+    return written;
+}
+//# sourceMappingURL=extract.js.map