@sdd-method/maintain-cli 0.12.0 → 0.13.1

package/dist/lib/structure/effects.js

@@ -0,0 +1,36 @@
+// A change's structural effect, and the effect record an archive leaves (M-ADR 0230 §4.6, §4.7, Proposed). 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";
+export function effectsOf(s, current) {
+    const out = [];
+    const rev = (catalogue, id) => {
+        const e = current.get(catalogue)?.get(id);
+        return e ? revision(e.catalogue, e.id, e.columns) : undefined;
+    };
+    for (const d of s.deltas) {
+        for (const e of d.added)
+            out.push({ element: elementKey(e.catalogue, e.id), operation: "ADDED", target: revision(e.catalogue, e.id, e.columns) });
+        for (const e of d.modified) {
+            const base = rev(e.catalogue, e.id);
+            out.push({ element: elementKey(e.catalogue, e.id), operation: "MODIFIED", ...(base ? { base } : {}), target: revision(e.catalogue, e.id, e.columns) });
+        }
+        for (const r of d.removed) {
+            const base = rev(r.catalogue, r.id);
+            out.push({ element: elementKey(r.catalogue, r.id), operation: "REMOVED", ...(base ? { base } : {}) });
+        }
+    }
+    return out.sort((a, b) => a.element.localeCompare(b.element));
+}
+export function parseAppliedRecord(text) {
+    try {
+        const v = parseDocument(text).toJS();
+        if (!v || typeof v.change !== "string" || !Array.isArray(v.effects))
+            return null;
+        return { change: v.change, baseCommit: String(v.base_commit ?? ""), effects: v.effects };
+    }
+    catch {
+        return null;
+    }
+}
+//# sourceMappingURL=effects.js.map

package/dist/lib/structure/model.js

@@ -0,0 +1,212 @@
+// The structural model and a change's structural deltas (M-ADR 0230 §4.3, §4.4, Proposed). Pure reads, so the
+// verify-only CLI can carry them. The format is docs/method/methods/guides/structural-model-format.md:
+//   openspec/structure/<partition>.yaml                    the model, one file per partition
+//   openspec/changes/<change>/structure/<partition>.yaml   a change's delta for that partition
+//   openspec/changes/<change>/structure/none.yaml          a change's typed claim of no structural effect
+// An element is a catalogue row of a `structure` catalogue, keyed by its immutable id. Its revision is the
+// SHA-256 of its canonical JSON, so two readers agree on it without agreeing on anything else.
+import { createHash } from "node:crypto";
+import { readdir, readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { parseDocument } from "yaml";
+export const STRUCTURE_DIR = join("openspec", "structure");
+export const NO_OP_FILE = "none.yaml";
+/** An archived change's record of its structural effect, beside its deltas (M-ADR 0230 §4.6). */
+export const APPLIED_FILE = "applied.yaml";
+/** Partition names a file name would confuse with the no-op claim or the effect record. */
+export const RESERVED_PARTITIONS = new Set(["none", "applied"]);
+export const FORMAT_VERSION = "1.0.0";
+/** `sha256:<hex>` of the element's canonical JSON: {catalogue, columns (sorted), id}, no whitespace, UTF-8. */
+export function revision(catalogue, id, columns) {
+    const sorted = {};
+    for (const k of Object.keys(columns).sort())
+        sorted[k] = columns[k];
+    const canonical = JSON.stringify({ catalogue, columns: sorted, id });
+    return `sha256:${createHash("sha256").update(canonical, "utf8").digest("hex")}`;
+}
+export function elementKey(catalogue, id) {
+    return `${catalogue}/${id}`;
+}
+async function readText(p) {
+    try {
+        return await readFile(p, "utf8");
+    }
+    catch {
+        return null;
+    }
+}
+async function yamlFiles(dir) {
+    try {
+        return (await readdir(dir, { withFileTypes: true }))
+            .filter((e) => e.isFile() && e.name.endsWith(".yaml"))
+            .map((e) => e.name)
+            .sort();
+    }
+    catch {
+        return null;
+    }
+}
+function parseYamlMap(text, where, problems) {
+    const doc = parseDocument(text);
+    if (doc.errors.length > 0) {
+        problems.push(`${where}: not valid YAML (${doc.errors[0].message.split("\n")[0]})`);
+        return null;
+    }
+    const v = doc.toJS();
+    if (v === null || typeof v !== "object" || Array.isArray(v)) {
+        problems.push(`${where}: not a YAML mapping`);
+        return null;
+    }
+    return v;
+}
+function checkVersion(m, where, problems) {
+    if (m["schema_version"] === undefined) {
+        problems.push(`${where}: no schema_version`);
+        return false;
+    }
+    if (String(m["schema_version"]) !== FORMAT_VERSION) {
+        problems.push(`${where}: schema_version ${JSON.stringify(String(m["schema_version"]))} is not ${FORMAT_VERSION}, the format this CLI reads`);
+        return false;
+    }
+    return true;
+}
+/** Elements under a `<catalogue>: [ {id, ...} ]` map. */
+function readElements(block, where, partition, file, problems) {
+    const out = [];
+    if (block === undefined || block === null)
+        return out;
+    if (typeof block !== "object" || Array.isArray(block)) {
+        problems.push(`${where}: must map catalogue names to lists of elements`);
+        return out;
+    }
+    for (const [catalogue, list] of Object.entries(block)) {
+        if (!Array.isArray(list)) {
+            problems.push(`${where}.${catalogue}: must be a list of elements`);
+            continue;
+        }
+        list.forEach((raw, i) => {
+            const at = `${where}.${catalogue}[${i}]`;
+            if (raw === null || typeof raw !== "object" || Array.isArray(raw)) {
+                problems.push(`${at}: an element must be a mapping`);
+                return;
+            }
+            const r = raw;
+            const id = r["id"];
+            if (typeof id !== "string" || id === "") {
+                problems.push(`${at}: no id`);
+                return;
+            }
+            const columns = {};
+            for (const [k, v] of Object.entries(r)) {
+                if (k === "id")
+                    continue;
+                if (typeof v === "string" || typeof v === "number" || typeof v === "boolean")
+                    columns[k] = v;
+                else
+                    problems.push(`${at} (${id}).${k}: a value must be a string, number or boolean`);
+            }
+            out.push({ catalogue, id, columns, partition, file });
+        });
+    }
+    return out;
+}
+/** The model, or null when the SDD has no openspec/structure/ directory. */
+export async function loadModel(repo, problems) {
+    const names = await yamlFiles(join(repo, STRUCTURE_DIR));
+    if (names === null)
+        return null;
+    const files = [];
+    for (const name of names) {
+        const file = join(STRUCTURE_DIR, name);
+        const m = parseYamlMap((await readText(join(repo, file))) ?? "", file, problems);
+        if (m === null || !checkVersion(m, file, problems))
+            continue;
+        const partition = name.slice(0, -".yaml".length);
+        if (RESERVED_PARTITIONS.has(partition)) {
+            problems.push(`${file}: ${partition} is a reserved name, not a partition`);
+            continue;
+        }
+        if (m["partition"] !== partition) {
+            problems.push(`${file}: partition ${JSON.stringify(m["partition"] ?? null)} does not match the file name (${partition})`);
+            continue;
+        }
+        for (const k of Object.keys(m))
+            if (!["schema_version", "partition", "elements"].includes(k))
+                problems.push(`${file}: unknown key ${k}`);
+        files.push({ partition, file, elements: readElements(m["elements"], `${file}: elements`, partition, file, problems) });
+    }
+    return files;
+}
+/** A change's structural artifact. */
+export async function loadChangeStructure(repo, change, problems) {
+    const dir = join("openspec", "changes", change, "structure");
+    const names = await yamlFiles(join(repo, dir));
+    if (names === null)
+        return { change, deltas: [], noOp: null, present: false };
+    const deltas = [];
+    let noOp = null;
+    for (const name of names) {
+        if (name === APPLIED_FILE)
+            continue;
+        const file = join(dir, name);
+        const m = parseYamlMap((await readText(join(repo, file))) ?? "", file, problems);
+        if (m === null || !checkVersion(m, file, problems))
+            continue;
+        if (name === NO_OP_FILE) {
+            const reason = typeof m["reason"] === "string" ? m["reason"].trim() : "";
+            if (m["no_structural_effect"] !== true)
+                problems.push(`${file}: a no-op claim states no_structural_effect: true`);
+            else if (reason === "")
+                problems.push(`${file}: a no-op claim states its reason`);
+            else
+                noOp = { file, reason };
+            continue;
+        }
+        const partition = name.slice(0, -".yaml".length);
+        if (m["partition"] !== partition) {
+            problems.push(`${file}: partition ${JSON.stringify(m["partition"] ?? null)} does not match the file name (${partition})`);
+            continue;
+        }
+        const dependsOn = m["depends_on"] ?? [];
+        if (!Array.isArray(dependsOn) || dependsOn.some((d) => typeof d !== "string"))
+            problems.push(`${file}: depends_on must be a list of change names`);
+        const base = new Map();
+        const rawBase = m["base"] ?? {};
+        if (typeof rawBase !== "object" || rawBase === null || Array.isArray(rawBase))
+            problems.push(`${file}: base must map <catalogue>/<id> to a revision`);
+        else {
+            for (const [k, v] of Object.entries(rawBase)) {
+                if (typeof v !== "string" || !/^sha256:[0-9a-f]{64}$/.test(v))
+                    problems.push(`${file}: base ${k} is not a revision (sha256:<64 hex digits>)`);
+                else
+                    base.set(k, v);
+            }
+        }
+        const removed = [];
+        for (const r of readElements(m["REMOVED"], `${file}: REMOVED`, partition, file, problems)) {
+            const reason = r.columns["reason"];
+            if (typeof reason !== "string" || reason.trim() === "")
+                problems.push(`${file}: REMOVED ${elementKey(r.catalogue, r.id)} gives no reason`);
+            const extra = Object.keys(r.columns).filter((k) => k !== "reason");
+            if (extra.length > 0)
+                problems.push(`${file}: REMOVED ${elementKey(r.catalogue, r.id)} states ${extra.join(", ")}; a removal gives its id and a reason only`);
+            removed.push({ catalogue: r.catalogue, id: r.id, reason: typeof reason === "string" ? reason : "" });
+        }
+        for (const k of Object.keys(m)) {
+            if (!["schema_version", "partition", "depends_on", "ADDED", "MODIFIED", "REMOVED", "base"].includes(k))
+                problems.push(`${file}: unknown key ${k}`);
+        }
+        deltas.push({
+            change,
+            partition,
+            file,
+            dependsOn: Array.isArray(dependsOn) ? dependsOn.map(String) : [],
+            added: readElements(m["ADDED"], `${file}: ADDED`, partition, file, problems),
+            modified: readElements(m["MODIFIED"], `${file}: MODIFIED`, partition, file, problems),
+            removed,
+            base,
+        });
+    }
+    return { change, deltas, noOp, present: true };
+}
+//# sourceMappingURL=model.js.map

package/dist/lib/structure/render.js

@@ -0,0 +1,242 @@
+// The generated views of the structural model (M-ADR 0230 §4.3, Proposed): projections, never edited. Each file is
+// rendered from the current view alone, in id order, so the same model renders the same bytes. Its first line names
+// the generator and the digest of the body below it, which tells three states apart:
+//   missing      the file is absent
+//   stale        the body matches its header but not a render of the model: the model moved; render again
+//   hand-edited  the body no longer matches its header: someone edited a generated view
+// Pure: the verb reads and writes the files.
+import { createHash } from "node:crypto";
+import { VIEW_PATHS } from "./catalogue.js";
+export { VIEW_PATHS };
+const HEADER = /^<!-- Generated by sdd-cli structure render from openspec\/structure\/ \(M-ADR 0230\)\. Do not edit: change the model through a change's structural deltas\. body (sha256:[0-9a-f]{64}) -->\n/;
+const digest = (s) => `sha256:${createHash("sha256").update(s, "utf8").digest("hex")}`;
+function withHeader(body) {
+    return `<!-- Generated by sdd-cli structure render from openspec/structure/ (M-ADR 0230). Do not edit: change the model through a change's structural deltas. body ${digest(body)} -->\n${body}`;
+}
+const elements = (view, catalogue) => [...(view.get(catalogue)?.values() ?? [])].sort((a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
+const col = (e, c) => (e.columns[c] === undefined ? "" : String(e.columns[c]));
+const nameOf = (e) => col(e, "name") || e.id;
+/** A string inside a Mermaid quoted argument: one line, no double quote. */
+const q = (s) => s.replace(/\s+/g, " ").replace(/"/g, "'").trim();
+/** A cell of a Markdown table. */
+const td = (s) => s.replace(/\s+/g, " ").replace(/\|/g, "\\|").trim();
+/** Mermaid aliases for ids, which may hold characters an alias cannot; a clash after cleaning takes a suffix. */
+function aliases() {
+    const taken = new Map();
+    const used = new Set();
+    return (id) => {
+        const known = taken.get(id);
+        if (known)
+            return known;
+        const base = id.replace(/[^A-Za-z0-9_]/g, "_").replace(/^(?=[0-9])/, "_") || "_";
+        let alias = base;
+        for (let n = 2; used.has(alias); n++)
+            alias = `${base}_${n}`;
+        used.add(alias);
+        taken.set(id, alias);
+        return alias;
+    };
+}
+function c4Context(view) {
+    const a = aliases();
+    const links = elements(view, "persona_c4system");
+    const personas = new Set(links.map((l) => col(l, "persona_id")));
+    const lines = ["# System context", "", "```mermaid", "C4Context", "  title System context"];
+    for (const p of elements(view, "personas"))
+        if (personas.has(p.id))
+            lines.push(`  Person(${a(p.id)}, "${q(nameOf(p))}", "${q(col(p, "role"))}")`);
+    for (const s of elements(view, "c4_systems"))
+        lines.push(`  System(${a(s.id)}, "${q(nameOf(s))}", "${q(col(s, "description"))}")`);
+    for (const x of elements(view, "c4_external_systems"))
+        lines.push(`  System_Ext(${a(x.id)}, "${q(nameOf(x))}", "${q(col(x, "description"))}")`);
+    for (const l of links)
+        lines.push(`  Rel(${a(col(l, "persona_id"))}, ${a(col(l, "c4_system_id"))}, "${q(col(l, "interaction"))}")`);
+    for (const l of elements(view, "system_external_dependency"))
+        lines.push(`  Rel(${a(col(l, "c4_system_id"))}, ${a(col(l, "external_system_id"))}, "${q(col(l, "interaction"))}")`);
+    lines.push("```", "");
+    return lines.join("\n");
+}
+function c4Containers(view) {
+    const containers = elements(view, "c4_containers");
+    const systemOf = new Map(containers.map((c) => [c.id, col(c, "system_id")]));
+    const deps = elements(view, "container_dependency");
+    const lines = ["# Containers", ""];
+    for (const s of elements(view, "c4_systems")) {
+        const a = aliases();
+        const inside = containers.filter((c) => col(c, "system_id") === s.id);
+        lines.push(`## ${nameOf(s)} (\`${s.id}\`)`, "", "```mermaid", "C4Container", `  title Containers of ${q(nameOf(s))}`, `  System_Boundary(${a(s.id)}, "${q(nameOf(s))}") {`);
+        for (const c of inside)
+            lines.push(`    Container(${a(c.id)}, "${q(nameOf(c))}", "${q(col(c, "technology"))}", "${q(col(c, "description"))}")`);
+        lines.push("  }");
+        const outbound = deps.filter((d) => systemOf.get(col(d, "from_container_id")) === s.id);
+        const outside = [...new Set(outbound.map((d) => col(d, "to_container_id")).filter((t) => systemOf.get(t) !== s.id))].sort();
+        for (const t of outside) {
+            const c = view.get("c4_containers")?.get(t);
+            lines.push(`  Container_Ext(${a(t)}, "${q(c ? nameOf(c) : t)}", "${q(c ? col(c, "technology") : "")}", "")`);
+        }
+        for (const d of outbound)
+            lines.push(`  Rel(${a(col(d, "from_container_id"))}, ${a(col(d, "to_container_id"))}, "${q(col(d, "interaction"))}")`);
+        lines.push("```", "");
+    }
+    return lines.join("\n");
+}
+function services(view) {
+    const lines = [
+        "# Services",
+        "",
+        "| Service | Name | Domain | Primary repository | Runtime | Language | Component type | Status |",
+        "| --- | --- | --- | --- | --- | --- | --- | --- |",
+    ];
+    for (const s of elements(view, "services")) {
+        const cells = [`\`${s.id}\``, nameOf(s), col(s, "domain_id"), col(s, "primary_repo_id"), col(s, "runtime_type"), col(s, "language"), col(s, "component_type"), col(s, "status")];
+        lines.push(`| ${cells.map(td).join(" | ")} |`);
+    }
+    lines.push("");
+    return lines.join("\n");
+}
+function featureTree(view) {
+    const caps = elements(view, "capabilities");
+    const groups = elements(view, "feature_groups");
+    const features = elements(view, "features");
+    const linked = new Map();
+    for (const l of elements(view, "capability_feature")) {
+        const set = linked.get(col(l, "capability_id")) ?? new Set();
+        set.add(col(l, "feature_id"));
+        linked.set(col(l, "capability_id"), set);
+    }
+    const placed = new Set();
+    const lines = ["# Feature tree", ""];
+    const feature = (f, depth) => {
+        placed.add(f.id);
+        const facts = [col(f, "kind"), col(f, "status")].filter((x) => x !== "").join(", ");
+        lines.push(`${"  ".repeat(depth)}- ${td(nameOf(f))} (\`${f.id}\`)${facts ? `: ${facts}` : ""}`);
+        for (const c of features)
+            if (col(c, "parent_feature_id") === f.id && !placed.has(c.id))
+                feature(c, depth + 1);
+    };
+    const group = (g, depth) => {
+        lines.push(`${"  ".repeat(depth)}- **${td(nameOf(g))}** (\`${g.id}\`)`);
+        for (const c of groups)
+            if (col(c, "parent_group_id") === g.id)
+                group(c, depth + 1);
+        for (const f of features)
+            if (col(f, "parent_group_id") === g.id && col(f, "parent_feature_id") === "" && !placed.has(f.id))
+                feature(f, depth + 1);
+    };
+    const isRoot = (f) => col(f, "parent_group_id") === "" && col(f, "parent_feature_id") === "";
+    const capability = (c, depth) => {
+        lines.push(`${"#".repeat(Math.min(depth + 2, 6))} ${nameOf(c)} (\`${c.id}\`)`, "");
+        const before = lines.length;
+        for (const g of groups)
+            if (col(g, "capability_id") === c.id && col(g, "parent_group_id") === "")
+                group(g, 0);
+        for (const f of features)
+            if (isRoot(f) && !placed.has(f.id) && (col(f, "capability_id") === c.id || linked.get(c.id)?.has(f.id)))
+                feature(f, 0);
+        if (lines.length > before)
+            lines.push("");
+        for (const child of caps)
+            if (col(child, "parent_capability_id") === c.id)
+                capability(child, depth + 1);
+    };
+    for (const c of caps)
+        if (col(c, "parent_capability_id") === "" || !view.get("capabilities")?.has(col(c, "parent_capability_id")))
+            capability(c, 0);
+    const rest = features.filter((f) => !placed.has(f.id));
+    const loose = groups.filter((g) => col(g, "capability_id") === "" && col(g, "parent_group_id") === "");
+    if (loose.length > 0 || rest.length > 0) {
+        lines.push("## Not under a capability", "");
+        for (const g of loose)
+            group(g, 0);
+        for (const f of features)
+            if (!placed.has(f.id) && isRoot(f))
+                feature(f, 0);
+        for (const f of features)
+            if (!placed.has(f.id))
+                feature(f, 0);
+        lines.push("");
+    }
+    return lines.join("\n");
+}
+/** Mermaid's end markers for relationship_end_cardinality, written at the from end and at the to end. */
+const FROM_END = { "exactly-one": "||", "zero-or-one": "|o", "one-or-more": "}|", "zero-or-more": "}o" };
+const TO_END = { "exactly-one": "||", "zero-or-one": "o|", "one-or-more": "|{", "zero-or-more": "o{" };
+function dataModel(view) {
+    const entities = elements(view, "entities");
+    const attributes = elements(view, "entity_attributes");
+    const relationships = elements(view, "entity_relationships");
+    const invariants = elements(view, "domain_invariants");
+    const word = (s) => s.replace(/[^A-Za-z0-9_]/g, "_") || "_";
+    const sections = elements(view, "domains").map((d) => [`${nameOf(d)} (\`${d.id}\`)`, entities.filter((e) => col(e, "domain_id") === d.id)]);
+    const domains = new Set(view.get("domains")?.keys() ?? []);
+    sections.push(["Entities without a domain", entities.filter((e) => !domains.has(col(e, "domain_id")))]);
+    const lines = ["# Data model", ""];
+    for (const [title, members] of sections) {
+        if (members.length === 0)
+            continue;
+        const a = aliases();
+        const ids = new Set(members.map((e) => e.id));
+        lines.push(`## ${title}`, "", "```mermaid", "erDiagram");
+        for (const e of members) {
+            const attrs = attributes.filter((x) => col(x, "entity_id") === e.id);
+            if (attrs.length === 0) {
+                lines.push(`  ${a(e.id)}["${q(nameOf(e))}"]`);
+                continue;
+            }
+            lines.push(`  ${a(e.id)}["${q(nameOf(e))}"] {`);
+            for (const x of attrs)
+                lines.push(`    ${word(col(x, "type"))} ${word(col(x, "name"))}`);
+            lines.push("  }");
+        }
+        for (const r of relationships) {
+            if (!ids.has(col(r, "from_entity_id")))
+                continue;
+            const ends = `${FROM_END[col(r, "from_cardinality")] ?? "}o"}--${TO_END[col(r, "to_cardinality")] ?? "o{"}`;
+            lines.push(`  ${a(col(r, "from_entity_id"))} ${ends} ${a(col(r, "to_entity_id"))} : "${q(nameOf(r))}"`);
+        }
+        lines.push("```", "");
+        const rules = invariants.filter((i) => ids.has(col(i, "entity_id")));
+        if (rules.length > 0) {
+            lines.push("Invariants:", "");
+            for (const i of rules)
+                lines.push(`- \`${i.id}\` (${col(i, "kind")}) on \`${col(i, "entity_id")}\`: ${td(col(i, "statement"))}`);
+            lines.push("");
+        }
+    }
+    return lines.join("\n");
+}
+/** Every generated view of the current view, by path relative to the SDD. */
+export function renderViews(view) {
+    return new Map([
+        [VIEW_PATHS.c4Context, withHeader(c4Context(view))],
+        [VIEW_PATHS.c4Containers, withHeader(c4Containers(view))],
+        [VIEW_PATHS.services, withHeader(services(view))],
+        [VIEW_PATHS.featureTree, withHeader(featureTree(view))],
+        [VIEW_PATHS.dataModel, withHeader(dataModel(view))],
+    ]);
+}
+/** A view file's state against its render. `text` is the file's content, or null when it is absent. */
+export function viewState(rendered, text) {
+    if (text === null)
+        return "missing";
+    if (text === rendered)
+        return "current";
+    const m = HEADER.exec(text);
+    if (m === null || digest(text.slice(m[0].length)) !== m[1])
+        return "hand-edited";
+    return "stale";
+}
+/** One line per view that is not current. */
+export function describeState(path, state) {
+    switch (state) {
+        case "missing":
+            return `${path}: missing; run \`sdd-cli structure render\``;
+        case "stale":
+            return `${path}: stale, rendered from an earlier model; run \`sdd-cli structure render\``;
+        case "hand-edited":
+            return `${path}: edited by hand since it was generated; a generated view is never edited. Make the change in the model, through a change's structural deltas, and render again`;
+        default:
+            return `${path}: current`;
+    }
+}
+//# sourceMappingURL=render.js.map