@sdd-method/maintain-cli 0.12.0 → 0.13.0

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

@@ -0,0 +1,265 @@
+// structural-model: the structural model and each open change's structural artifact (M-ADR 0230 §4.3, §4.4, Proposed;
+// docs/method/methods/guides/structural-model-format.md).
+//
+// The model (openspec/structure/<partition>.yaml), as the current view:
+//   files       valid YAML, schema_version, a partition matching its file name and naming one this SDD has
+//               (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
+//   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)
+// 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
+//               revision for every element modified, removed or read, still the current one; a reference into an
+//               element another open change adds names that change in depends_on
+//   no-op       contradicted by a behaviour delta for a feature the model does not hold; a structural delta
+//               must add that feature
+// Composition (§4.5; lib/structure/compose.ts), with a change agreed when its agreement record says so:
+//   overlap     two agreed changes writing one element or adding one id; a change overlapping an agreed one
+//   composed    each change's view (with its dependency closure) and the intended view (every agreed change)
+//               validated on their own; what fails there and not in current is reported against the changes
+//               that write the elements it names
+//   reads       a dependency withdrawn (record withdrawn or superseded, or neither open nor archived), an agreed
+//               change depending on one not agreed, a cycle of dependencies
+// Archived changes (§4.6):
+//   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].
+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 { describeState, renderViews, VIEW_PATHS, viewState } from "../structure/render.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;
+const CHANGES_DIR = join("openspec", "changes");
+async function readText(p) {
+    try {
+        return await readFile(p, "utf8");
+    }
+    catch {
+        return null;
+    }
+}
+async function subdirs(p) {
+    try {
+        return (await readdir(p, { withFileTypes: true })).filter((e) => e.isDirectory()).map((e) => e.name).sort();
+    }
+    catch {
+        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}-/, "")));
+}
+function builtLookup(repo) {
+    const cache = new Map();
+    const fn = ((catalogue, column) => {
+        const rows = cache.get(catalogue);
+        if (rows === undefined || rows === null)
+            return null;
+        return new Set(rows.map((r) => r[column] ?? ""));
+    });
+    fn.load = async (catalogue) => {
+        if (cache.has(catalogue))
+            return;
+        const text = await readText(join(repo, "catalogues", `${catalogue}.csv`));
+        cache.set(catalogue, text === null ? null : parseCatalogueCsv(text).rows);
+    };
+    return fn;
+}
+export async function checkStructuralModel(repo, options = {}) {
+    const enforced = options.enforced ?? ENFORCED;
+    const problems = [];
+    const lines = [];
+    const files = await loadModel(repo, problems);
+    const changes = (await subdirs(join(repo, CHANGES_DIR))).filter((c) => c !== "archive");
+    const structures = [];
+    for (const c of changes)
+        structures.push(await loadChangeStructure(repo, c, problems));
+    if (files === null && !structures.some((s) => s.present)) {
+        return { exitCode: 0, stdout: `[N/A] structural-model: no structural model (${STRUCTURE_DIR}/) and no change with structural deltas in this repository\n` };
+    }
+    const schema = options.schema ?? (await loadCanonicalSchema());
+    // Partitions this SDD has.
+    const manifest = (await readText(join(repo, ".sdd", "sdd-manifest.yaml"))) ?? "";
+    let profile = "";
+    let sddId = "";
+    try {
+        const m = parseDocument(manifest).toJS();
+        profile = String(m?.profile ?? "");
+        sddId = String(m?.sdd_id ?? "");
+    }
+    catch {
+        // the manifest check reports an unparseable manifest
+    }
+    const view = viewOf(files ?? [], problems);
+    const built = builtLookup(repo);
+    for (const c of schema.catalogues)
+        if (c.sourceOfTruth !== "structure")
+            await built.load(c.name);
+    let allowed = null;
+    if (profile === "platform-profile") {
+        allowed = new Set(["platform", ...(view.get("domains")?.keys() ?? []), ...(built("domains", "id") ?? [])]);
+    }
+    else if (sddId !== "") {
+        allowed = new Set([sddId]);
+    }
+    else {
+        lines.push("partitions: not checked (no profile or sdd_id in .sdd/sdd-manifest.yaml)");
+    }
+    const checkPartition = (partition, file) => {
+        if (allowed !== null && !allowed.has(partition)) {
+            problems.push(`${file}: partition ${partition} is not one this SDD has (${profile === "platform-profile" ? "a domain id, or platform" : `its sdd_id, ${sddId}`})`);
+        }
+    };
+    for (const f of files ?? [])
+        checkPartition(f.partition, f.file);
+    // The current view.
+    const unresolved = new Set();
+    const currentProblems = [];
+    validateView(schema, view, built, currentProblems, unresolved);
+    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).
+    if (files !== null && (await subdirs(join(repo, "docs"))).includes("structure")) {
+        let current = 0;
+        for (const [path, rendered] of renderViews(view)) {
+            const state = viewState(rendered, await readText(join(repo, path)));
+            if (state === "current")
+                current++;
+            else
+                problems.push(describeState(path, state));
+        }
+        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");
+    }
+    // Open changes.
+    const addedBy = 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);
+    const features = new Set(view.get("features")?.keys() ?? []);
+    let withDeltas = 0;
+    let noOps = 0;
+    let without = 0;
+    for (const s of structures) {
+        const dir = join(CHANGES_DIR, s.change);
+        for (const d of s.deltas)
+            checkPartition(d.partition, d.file);
+        if (s.deltas.length > 0)
+            withDeltas++;
+        if (s.noOp)
+            noOps++;
+        if (!s.present || (s.deltas.length === 0 && !s.noOp)) {
+            without++;
+            if (files !== null)
+                problems.push(`${dir}: no structural artifact; the model exists, so a change states its structural deltas or claims none (structure/none.yaml)`);
+        }
+        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));
+        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)));
+        for (const feature of await subdirs(join(repo, dir, "specs"))) {
+            if (features.has(feature) || adds.has(feature))
+                continue;
+            if (files === null && features.size === 0 && !s.present)
+                continue;
+            if (s.noOp)
+                problems.push(`${s.noOp.file}: claims no structural effect, and the change's behaviour deltas create a living spec for ${feature}, a feature the model does not hold`);
+            else
+                problems.push(`${dir}: a behaviour delta for ${feature}, a feature the model does not hold, and no structural delta adds features/${feature}`);
+        }
+    }
+    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);
+    const known = new Set(currentProblems);
+    const atAgreed = new Set();
+    for (const [name, oc] of open) {
+        if (oc.structure.deltas.length === 0)
+            continue;
+        const at = [];
+        validateView(schema, viewAt(view, name, open), built, at, new Set());
+        for (const p of at) {
+            if (known.has(p))
+                continue;
+            problems.push(`at ${name}: ${p}`);
+            if (oc.status === "agreed")
+                atAgreed.add(p);
+        }
+    }
+    const agreed = agreedOrder(open);
+    if (agreed.length > 0) {
+        const inIntended = [];
+        validateView(schema, intended(view, open), built, inIntended, new Set());
+        for (const p of inIntended) {
+            if (known.has(p) || atAgreed.has(p))
+                continue;
+            const by = attribute(p, open, agreed);
+            problems.push(`in the intended view, from ${by.length > 0 ? by.join(" with ") : "the agreed changes together"}: ${p}`);
+        }
+    }
+    // An archived change with structural deltas and no effect record: archived by a raw `openspec archive`, so its
+    // behaviour moved and its structure did not. Its structural transition is not shipped (§4.6).
+    let raw = 0;
+    for (const dir of await subdirs(join(repo, CHANGES_DIR, "archive"))) {
+        const ap = [];
+        const s = await loadChangeStructure(repo, join("archive", dir), ap);
+        if (s.deltas.length === 0)
+            continue;
+        if ((await readText(join(repo, CHANGES_DIR, "archive", dir, "structure", APPLIED_FILE))) !== null)
+            continue;
+        raw++;
+        problems.push(`${join(CHANGES_DIR, "archive", dir)}: archived with structural deltas and no effect record (structure/${APPLIED_FILE}), as a raw \`openspec archive\` leaves it; its structure is not applied, so the transition is not shipped. Run \`sdd-cli change archive ${dir.replace(/^\d{4}-\d{2}-\d{2}-/, "")}\` to apply it, guarded by its base revisions`);
+    }
+    if (raw > 0)
+        lines.push(`archived changes whose structure is not applied: ${raw}`);
+    lines.push(`views: current; at each of ${[...open.values()].filter((o) => o.structure.deltas.length > 0).length} change(s) with deltas; intended from ${agreed.length} agreed change(s)`);
+    const body = lines.map((l) => `${l}\n`).join("");
+    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`;
+    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.12.0",
-  "built_against_sdd_cli": "3.0.0"
+  "version": "0.13.0",
+  "built_against_sdd_cli": "4.0.0"
 }

package/dist/verify-version.json

@@ -1,4 +1,4 @@
 {
-  "version": "3.0.0",
-  "built_against_sdd_cli": "3.0.0"
+  "version": "4.0.0",
+  "built_against_sdd_cli": "4.0.0"
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@sdd-method/maintain-cli",
-  "version": "0.12.0",
-  "sddCliVersion": "3.0.0",
+  "version": "0.13.0",
+  "sddCliVersion": "4.0.0",
   "description": "Bring an SDD repository current and rebuild its derived model — sync, briefing, catalogue build and aggregate, pack build, context pull — plus every read-only verify verb. Ships only the code those verbs reach; it cannot author specification content. Authoring is in @sdd-method/sdd-cli.",
   "license": "UNLICENSED",
   "type": "module",