@sdd-method/author-cli 0.12.1 → 0.14.0

package/dist/lib/validate/structural-model.js

@@ -1,4 +1,4 @@
-// structural-model: the structural model and each open change's structural artifact (M-ADR 0230 §4.3, §4.4, Proposed;
+// structural-model: the structural model and each open change's structural artifact (M-ADR 0230 §4.3, §4.4;
 // docs/method/methods/guides/structural-model-format.md).
 //
 // The model (openspec/structure/<partition>.yaml), as the current view:
@@ -6,11 +6,13 @@
 //               (a platform SDD: its domains and `platform`; an application or integration SDD: its sdd_id)
 //   elements    a `structure` catalogue, its `structure` columns only, an id held once, required columns,
 //               value types and vocabularies (the catalogue metamodel's)
-//   references  resolved in the view; into a catalogue of another class, against that catalogue as built
+//   references  resolved in the view; into a catalogue of another class, against that catalogue as built, less the
+//               contracts open changes' records agree as new (lib/structure/intended.ts): those are in their change's
+//               view, its dependants' and the intended one, so a current reference to one is refused (§4.11 proof 3)
 //   hierarchies no cycle through a self-reference; natural keys unique; domain invariants naming their entity's own
 //               attributes and relationships
-//   views       each generated view under docs/structure/ missing, stale (rendered from an earlier model) or edited by
-//               hand (its body no longer matches the digest in its header)
+//   views       docs/structure/ absent where the model is admitted, and each generated view under it missing, stale
+//               (rendered from an earlier model) or edited by hand (its body no longer matches the digest in its header)
 // Each open change (openspec/changes/<change>/structure/):
 //   artifact    where the model exists, a change has partition deltas or none.yaml, never both
 //   deltas      well formed; ADDED ids new; MODIFIED and REMOVED ids held by the delta's partition; a base
@@ -29,20 +31,22 @@
 //   archived    a change archived with structural deltas and no effect record (a raw `openspec archive`): its
 //               structure is not applied, so its transition is not shipped
 //
-// Report only while M-ADR 0230 is Proposed (ENFORCED): every finding is a [WARN] and the check exits 0. Without
-// openspec/structure/ and with no change carrying a structure/ directory it reports [N/A].
+// Enforced (the release that accepts M-ADR 0230): every finding is a [FAIL] and the check
+// exits 1; with ENFORCED false it reports them as [WARN] and exits 0. Without openspec/structure/ and with no change
+// carrying a structure/ directory it reports [N/A], so an SDD without a model is unaffected.
 import { readdir, readFile } from "node:fs/promises";
 import { join } from "node:path";
 import { parseDocument } from "yaml";
 import { parseCatalogueCsv } from "../catalogue/csv-reader.js";
 import { loadCanonicalSchema } from "../catalogue/schema-loader.js";
 import { APPLIED_FILE, elementKey, loadChangeStructure, loadModel, STRUCTURE_DIR } from "../structure/model.js";
-import { agreedOrder, attribute, checkDependencies, checkOverlap, intended, viewAt } from "../structure/compose.js";
+import { agreedOrder, attribute, checkDependencies, checkOverlap, closure, intended, viewAt } from "../structure/compose.js";
 import { describeState, renderViews, VIEW_PATHS, viewState } from "../structure/render.js";
+import { Additions, CONTRACTS, readAgreement } from "../structure/intended.js";
 import { validateDeltas, validateView, viewOf } from "../structure/view.js";
 const VIEW_COUNT = Object.keys(VIEW_PATHS).length;
-/** Flipped when M-ADR 0230 is accepted: findings then FAIL. */
-export const ENFORCED = false;
+/** Findings FAIL (from M-ADR 0230's acceptance); false reports them only, as while M-ADR 0230 was Proposed. Also binds a change's structural deltas as agreed content in the behaviour-store check. */
+export const ENFORCED = true;
 const CHANGES_DIR = join("openspec", "changes");
 async function readText(p) {
     try {
@@ -60,19 +64,6 @@ async function subdirs(p) {
         return [];
     }
 }
-/** The change's agreement record status (docs/agreements/<change>.yaml), or `unrecorded`. */
-async function agreementStatus(repo, change) {
-    const text = await readText(join(repo, "docs", "agreements", `${change}.yaml`));
-    if (text === null)
-        return "unrecorded";
-    try {
-        const status = String(parseDocument(text).toJS()?.agreement_record?.status ?? "");
-        return ["proposed", "agreed", "withdrawn", "superseded"].find((s) => s === status) ?? "unrecorded";
-    }
-    catch {
-        return "unrecorded";
-    }
-}
 /** Names of archived changes: openspec/changes/archive/<YYYY-MM-DD>-<name>. */
 async function archivedNames(repo) {
     return new Set((await subdirs(join(repo, CHANGES_DIR, "archive"))).map((d) => d.replace(/^\d{4}-\d{2}-\d{2}-/, "")));
@@ -91,8 +82,22 @@ function builtLookup(repo) {
         const text = await readText(join(repo, "catalogues", `${catalogue}.csv`));
         cache.set(catalogue, text === null ? null : parseCatalogueCsv(text).rows);
     };
+    fn.rows = (catalogue) => cache.get(catalogue) ?? [];
     return fn;
 }
+/**
+ * The built catalogues as one view sees them. A contract an open change's record agrees as new is built from the
+ * change's own sources, so it is in no view but that change's, its dependants' and, once agreed, the intended one.
+ */
+function builtIn(built, all, mine) {
+    return (catalogue, column) => {
+        const rows = built(catalogue, column);
+        if (rows === null || catalogue !== CONTRACTS || column !== "id")
+            return rows;
+        const out = new Set([...rows].filter((id) => !all.has(id) || mine.has(id)));
+        return out;
+    };
+}
 export async function checkStructuralModel(repo, options = {}) {
     const enforced = options.enforced ?? ENFORCED;
     const problems = [];
@@ -123,6 +128,16 @@ export async function checkStructuralModel(repo, options = {}) {
     for (const c of schema.catalogues)
         if (c.sourceOfTruth !== "structure")
             await built.load(c.name);
+    const open = new Map();
+    const newContracts = new Map();
+    for (const s of structures) {
+        const agreement = await readAgreement(repo, s.change);
+        open.set(s.change, { structure: s, status: agreement.status });
+        newContracts.set(s.change, agreement.newContracts);
+    }
+    const additions = new Additions(open, newContracts, built.rows(CONTRACTS));
+    const allNew = additions.contracts(open.keys());
+    const addedBy = (catalogue, id) => additions.addedBy(catalogue, id);
     let allowed = null;
     if (profile === "platform-profile") {
         allowed = new Set(["platform", ...(view.get("domains")?.keys() ?? []), ...(built("domains", "id") ?? [])]);
@@ -143,14 +158,14 @@ export async function checkStructuralModel(repo, options = {}) {
     // The current view.
     const unresolved = new Set();
     const currentProblems = [];
-    validateView(schema, view, built, currentProblems, unresolved);
+    validateView(schema, view, builtIn(built, allNew, new Set()), currentProblems, unresolved, addedBy);
     problems.push(...currentProblems);
     const elementCount = [...view.values()].reduce((n, m) => n + m.size, 0);
     lines.push(files === null ? `model: none (${STRUCTURE_DIR}/ absent)` : `model: ${files.length} partition file(s), ${elementCount} element(s) in ${view.size} catalogue(s)`);
     if (unresolved.size > 0)
         lines.push(`references into ${[...unresolved].sort().join(", ")}: unresolved (no built catalogue)`);
-    // The generated views, against a render of the current view. An SDD that has not rendered them yet (no
-    // docs/structure/) is adopting the model, which keeps its originals until the review is complete (§6 step 1).
+    // The generated views, against a render of the current view. Where a model is admitted they are required (M-ADR
+    // 0230 §4.3): an SDD reviews an extraction before writing it (§6 step 1), so none is mid-adoption with a model.
     if (files !== null && (await subdirs(join(repo, "docs"))).includes("structure")) {
         let current = 0;
         for (const [path, rendered] of renderViews(view)) {
@@ -163,14 +178,15 @@ export async function checkStructuralModel(repo, options = {}) {
         lines.push(`generated views: ${current} of ${VIEW_COUNT} current`);
     }
     else if (files !== null) {
-        lines.push("generated views: not rendered (no docs/structure/); `sdd-cli structure render` writes them");
+        problems.push("docs/structure/: the generated views are not rendered; where a structural model is admitted they are required. `structure render` writes them (sdd-maintain or sdd-cli)");
+        lines.push(`generated views: 0 of ${VIEW_COUNT} (no docs/structure/)`);
     }
     // Open changes.
-    const addedBy = new Map();
+    const addedByChange = new Map();
     for (const s of structures)
         for (const d of s.deltas)
             for (const e of d.added)
-                addedBy.set(elementKey(e.catalogue, e.id), s.change);
+                addedByChange.set(elementKey(e.catalogue, e.id), s.change);
     const features = new Set(view.get("features")?.keys() ?? []);
     let withDeltas = 0;
     let noOps = 0;
@@ -190,7 +206,7 @@ export async function checkStructuralModel(repo, options = {}) {
         }
         if (s.noOp && s.deltas.length > 0)
             problems.push(`${s.noOp.file}: a no-op claim beside ${s.deltas.length} partition delta(s); state one or the other`);
-        const elsewhere = new Map([...addedBy].filter(([, c]) => c !== s.change));
+        const elsewhere = new Map([...addedByChange].filter(([, c]) => c !== s.change));
         validateDeltas(schema, view, s.deltas, elsewhere, problems);
         // A behaviour delta for a feature the model does not hold needs that feature added here.
         const adds = new Set(s.deltas.flatMap((d) => d.added.filter((e) => e.catalogue === "features").map((e) => e.id)));
@@ -207,9 +223,6 @@ export async function checkStructuralModel(repo, options = {}) {
     }
     lines.push(`changes: ${changes.length} open, ${withDeltas} with structural deltas, ${noOps} claiming none, ${without} without the artifact`);
     // Composition (M-ADR 0230 §4.5): the three views and the three checks.
-    const open = new Map();
-    for (const s of structures)
-        open.set(s.change, { structure: s, status: await agreementStatus(repo, s.change) });
     const archived = await archivedNames(repo);
     checkOverlap(open, problems);
     checkDependencies(open, archived, problems);
@@ -219,7 +232,7 @@ export async function checkStructuralModel(repo, options = {}) {
         if (oc.structure.deltas.length === 0)
             continue;
         const at = [];
-        validateView(schema, viewAt(view, name, open), built, at, new Set());
+        validateView(schema, viewAt(view, name, open), builtIn(built, allNew, additions.contracts(closure(name, open))), at, new Set(), addedBy);
         for (const p of at) {
             if (known.has(p))
                 continue;
@@ -231,7 +244,7 @@ export async function checkStructuralModel(repo, options = {}) {
     const agreed = agreedOrder(open);
     if (agreed.length > 0) {
         const inIntended = [];
-        validateView(schema, intended(view, open), built, inIntended, new Set());
+        validateView(schema, intended(view, open), builtIn(built, allNew, additions.contracts(agreed)), inIntended, new Set(), addedBy);
         for (const p of inIntended) {
             if (known.has(p) || atAgreed.has(p))
                 continue;
@@ -259,7 +272,7 @@ export async function checkStructuralModel(repo, options = {}) {
     if (problems.length === 0)
         return { exitCode: 0, stdout: `structural-model:\n${body}[PASS] structural-model: ok\n` };
     const tag = enforced ? "FAIL" : "WARN";
-    const tail = enforced ? `[FAIL] structural-model: ${problems.length} finding(s)\n` : `[WARN] structural-model: ${problems.length} finding(s), report only (M-ADR 0230, Proposed)\n`;
+    const tail = enforced ? `[FAIL] structural-model: ${problems.length} finding(s)\n` : `[WARN] structural-model: ${problems.length} finding(s), report only (M-ADR 0230)\n`;
     return { exitCode: enforced ? 1 : 0, stdout: `structural-model:\n${body}${problems.map((p) => `[${tag}] ${p}\n`).join("")}${tail}` };
 }
 //# sourceMappingURL=structural-model.js.map

package/dist/maintain-version.json

@@ -1,4 +1,4 @@
 {
-  "version": "0.13.1",
-  "built_against_sdd_cli": "4.0.1"
+  "version": "0.15.0",
+  "built_against_sdd_cli": "5.1.0"
 }

package/dist/verbs/change.js

@@ -0,0 +1,15 @@
+import { archiveChange } from "../lib/structure/archive.js";
+// `change archive <change>`: the method's archive operation (M-ADR 0230 §4.6). Behaviour and structure are
+// prepared in a scratch worktree, validated as a whole, and published as one commit only if the store has not moved.
+// Run it again after an interruption: it verifies an archive that already landed, and recovers a raw `openspec archive`.
+export function registerChange(program) {
+    const change = program.command("change").description("Operate on a change in the behaviour store (M-ADR 0223, M-ADR 0230)");
+    change
+        .command("archive <change>")
+        .description("Archive a judged change: its behaviour and structure published as one guarded commit (M-ADR 0230 §4.6)")
+        .option("--sdd-path <path>", "the SDD whose openspec/ is the store (default: the current directory)", ".")
+        .action(async (name, opts) => {
+        process.exitCode = await archiveChange({ sddPath: opts.sddPath, change: name, write: (s) => process.stdout.write(s) });
+    });
+}
+//# sourceMappingURL=change.js.map

package/dist/verbs/migrate-structure.js

@@ -0,0 +1,36 @@
+import { extractStructure, writeExtraction } from "../lib/structure/extract.js";
+// `migrate structure [--dry-run]`: extract an SDD's first structural model from its sources, with its report
+// (M-ADR 0230 §6 step 1). Refuses an SDD that has a model; writes no source file.
+export async function runMigrateStructure(sddPath, options, write) {
+    const x = await extractStructure(sddPath);
+    if (x.refused !== null) {
+        write(`[FAIL] migrate structure: ${x.refused}\n`);
+        return 1;
+    }
+    const total = [...x.counts.values()].reduce((a, b) => a + b, 0);
+    write(`${options.dryRun ? "would extract" : "extracted"} ${total} element(s) in ${x.counts.size} catalogue(s), ${x.files.size} partition(s); ${x.loss.length + x.extraction.length} fact(s) the model could not carry\n`);
+    if (options.dryRun) {
+        write(x.report);
+        return 0;
+    }
+    for (const p of await writeExtraction(sddPath, x))
+        write(`wrote ${p}\n`);
+    write("[INFO] migrate structure: the model is now the record of structure, and the catalogue is built from it. Keep the original sources until it is reviewed against the code; removing openspec/structure/ withdraws it\n");
+    return 0;
+}
+// Authored content, so the author's and sdd-cli's (M-ADR 0230 §6, at its acceptance). Attaches to the
+// `migrate` command its program already registers.
+export function registerMigrateStructure(program) {
+    const migrate = program.commands.find((c) => c.name() === "migrate");
+    if (!migrate)
+        throw new Error("registerMigrateStructure: register `migrate` first");
+    migrate
+        .command("structure")
+        .description("Extract the SDD's first structural model from its sources into openspec/structure/, with an extraction report; source files are untouched (M-ADR 0230)")
+        .option("--sdd-path <path>", "the SDD (default: the current directory)", ".")
+        .option("--dry-run", "write nothing; print the report", false)
+        .action(async (opts) => {
+        process.exitCode = await runMigrateStructure(opts.sddPath, { dryRun: opts.dryRun }, (s) => process.stdout.write(s));
+    });
+}
+//# sourceMappingURL=migrate-structure.js.map

package/dist/verify-version.json

@@ -1,4 +1,4 @@
 {
-  "version": "4.0.1",
-  "built_against_sdd_cli": "4.0.1"
+  "version": "5.1.0",
+  "built_against_sdd_cli": "5.1.0"
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@sdd-method/author-cli",
-  "version": "0.12.1",
-  "sddCliVersion": "4.0.1",
+  "version": "0.14.0",
+  "sddCliVersion": "5.1.0",
   "description": "Re-author one SDD's content — scaffold, plan, contracts, conformance, api-surface, snapshots, briefings, catalogue check — plus every read-only verify verb. Ships only the code those verbs reach; it cannot sync the baseline or rebuild the catalogues. Maintenance is in @sdd-method/maintain-cli, administration in @sdd-method/sdd-cli.",
   "license": "UNLICENSED",
   "type": "module",