@sdd-method/maintain-cli 0.11.0 → 0.13.0

package/dist/lib/structure/view.js

@@ -0,0 +1,301 @@
+import { elementKey, revision } from "./model.js";
+export const STRUCTURE = "structure";
+export function catalogueOf(schema, name) {
+    return schema.catalogues.find((c) => c.name === name);
+}
+/** The model's elements as one view, reporting an id held twice. */
+export function viewOf(files, problems) {
+    const view = new Map();
+    for (const f of files) {
+        for (const e of f.elements) {
+            const byId = view.get(e.catalogue) ?? new Map();
+            const prior = byId.get(e.id);
+            if (prior) {
+                problems.push(`${e.file}: ${elementKey(e.catalogue, e.id)} is also in ${prior.file}; an element is owned by one partition, and an id is held once`);
+                continue;
+            }
+            byId.set(e.id, e);
+            view.set(e.catalogue, byId);
+        }
+    }
+    return view;
+}
+export function revisionOf(e) {
+    return revision(e.catalogue, e.id, e.columns);
+}
+function typeOk(type, v) {
+    switch (type) {
+        case "int":
+        case "integer":
+            return typeof v === "number" && Number.isInteger(v);
+        case "number":
+            return typeof v === "number";
+        case "boolean":
+            return typeof v === "boolean";
+        case "date":
+            return typeof v === "string" && /^\d{4}-\d{2}-\d{2}$/.test(v);
+        default:
+            return typeof v === "string";
+    }
+}
+/** The element's own shape against its catalogue: class, columns, required columns, types, vocabularies. */
+export function checkElementShape(schema, e, where, problems) {
+    const key = elementKey(e.catalogue, e.id);
+    const cat = catalogueOf(schema, e.catalogue);
+    if (!cat) {
+        problems.push(`${where}: ${key}: the metamodel declares no catalogue ${e.catalogue}`);
+        return;
+    }
+    if (cat.sourceOfTruth !== STRUCTURE) {
+        problems.push(`${where}: ${key}: ${e.catalogue} is of class ${cat.sourceOfTruth ?? "(none)"}, not structure; it is authored elsewhere`);
+        return;
+    }
+    for (const [col, v] of Object.entries(e.columns)) {
+        const def = cat.columns.find((c) => c.name === col);
+        if (!def) {
+            problems.push(`${where}: ${key}: ${e.catalogue} has no column ${col}`);
+            continue;
+        }
+        if (def.sourceOfTruth !== STRUCTURE) {
+            problems.push(`${where}: ${key}: ${e.catalogue}.${col} is of class ${def.sourceOfTruth ?? "(none)"}, not structure; it is never written in the model`);
+            continue;
+        }
+        if (v === "")
+            problems.push(`${where}: ${key}: ${col} is empty; omit an empty value`);
+        else if (!typeOk(def.type, v))
+            problems.push(`${where}: ${key}: ${col} must be of type ${def.type}`);
+        const en = cat.columnEnums[col];
+        if (en !== undefined && typeof v === "string" && v !== "") {
+            const values = schema.enums[en.replace(/^enums\./, "")]?.values.map((x) => x.value) ?? [];
+            if (!values.includes(v))
+                problems.push(`${where}: ${key}: ${col} ${JSON.stringify(v)} is not a value of ${en}`);
+        }
+    }
+    for (const def of cat.columns) {
+        if (def.name === cat.primaryKey || def.nullable || def.sourceOfTruth !== STRUCTURE)
+            continue;
+        if (e.columns[def.name] === undefined)
+            problems.push(`${where}: ${key}: required column ${def.name} is missing`);
+    }
+}
+function find(view, catalogue, column, value) {
+    const byId = view.get(catalogue);
+    if (!byId)
+        return undefined;
+    if (column === "id")
+        return byId.get(value);
+    for (const e of byId.values())
+        if (String(e.columns[column] ?? "") === value)
+            return e;
+    return undefined;
+}
+/** The element's references: each non-external foreign key with a value. */
+export function referencesOf(schema, e) {
+    const cat = catalogueOf(schema, e.catalogue);
+    if (!cat)
+        return [];
+    const out = [];
+    for (const fk of cat.foreignKeys) {
+        if (fk.external)
+            continue;
+        const v = e.columns[fk.column];
+        if (v === undefined || v === "")
+            continue;
+        const [target, targetColumn] = fk.references.split(".");
+        out.push({ column: fk.column, catalogue: target, targetColumn: targetColumn ?? "id", value: String(v), structural: catalogueOf(schema, target)?.sourceOfTruth === STRUCTURE });
+    }
+    return out;
+}
+/** The natural key's value for an element, or null when the catalogue declares none or the element lacks a part. */
+function naturalKey(cat, e) {
+    const nk = cat.naturalKey;
+    if (!nk || nk.length === 0)
+        return null;
+    const parts = nk.map((c) => (c === "id" ? e.id : e.columns[c]));
+    if (parts.some((p) => p === undefined || p === ""))
+        return null;
+    return parts.map(String).join("\u0000");
+}
+/**
+ * The checks a view must satisfy on its own: every element's shape, references resolved within the view (or, into a
+ * catalogue of another class, against its built rows), no cycle through a self-reference, natural keys unique, and
+ * domain invariants naming their entity's own attributes and relationships.
+ */
+export function validateView(schema, view, built, problems, unresolved) {
+    for (const [catalogue, byId] of view) {
+        const cat = catalogueOf(schema, catalogue);
+        for (const e of byId.values()) {
+            const shape = [];
+            checkElementShape(schema, e, e.file, shape);
+            problems.push(...shape);
+            if (!cat || cat.sourceOfTruth !== STRUCTURE)
+                continue;
+            for (const r of referencesOf(schema, e)) {
+                if (r.structural) {
+                    if (!find(view, r.catalogue, r.targetColumn, r.value))
+                        problems.push(`${e.file}: ${elementKey(catalogue, e.id)}: ${r.column} ${JSON.stringify(r.value)} names no ${r.catalogue} element in this view (${elementKey(r.catalogue, r.value)})`);
+                }
+                else {
+                    const rows = built(r.catalogue, r.targetColumn);
+                    if (rows === null)
+                        unresolved.add(r.catalogue);
+                    else if (!rows.has(r.value))
+                        problems.push(`${e.file}: ${elementKey(catalogue, e.id)}: ${r.column} ${JSON.stringify(r.value)} names no row of ${r.catalogue} as built`);
+                }
+            }
+        }
+        if (!cat || cat.sourceOfTruth !== STRUCTURE)
+            continue;
+        // Hierarchies through a self-reference stay acyclic.
+        for (const fk of cat.foreignKeys.filter((f) => f.references.split(".")[0] === catalogue && !f.external)) {
+            const reported = new Set();
+            for (const start of byId.values()) {
+                const path = [];
+                const onPath = new Set();
+                let cur = start;
+                while (cur && !onPath.has(cur.id)) {
+                    onPath.add(cur.id);
+                    path.push(cur.id);
+                    const next = cur.columns[fk.column];
+                    cur = next === undefined || next === "" ? undefined : byId.get(String(next));
+                }
+                if (cur && onPath.has(cur.id)) {
+                    const cycle = path.slice(path.indexOf(cur.id));
+                    const sig = [...cycle].sort().join(",");
+                    if (!reported.has(sig)) {
+                        reported.add(sig);
+                        problems.push(`${start.file}: ${catalogue}.${fk.column} forms a cycle: ${[...cycle, cur.id].map((id) => elementKey(catalogue, id)).join(" -> ")}`);
+                    }
+                }
+            }
+        }
+        // Natural keys are unique.
+        const seen = new Map();
+        for (const e of byId.values()) {
+            const k = naturalKey(cat, e);
+            if (k === null)
+                continue;
+            const prior = seen.get(k);
+            if (prior)
+                problems.push(`${e.file}: ${elementKey(catalogue, e.id)} and ${elementKey(catalogue, prior.id)} share the natural key (${cat.naturalKey.join(", ")}) ${JSON.stringify(k.split("\u0000").join(", "))}`);
+            else
+                seen.set(k, e);
+        }
+    }
+    // Domain invariants name their own entity's attributes and relationships.
+    for (const inv of view.get("domain_invariants")?.values() ?? []) {
+        const key = elementKey("domain_invariants", inv.id);
+        const entity = String(inv.columns["entity_id"] ?? "");
+        const kind = String(inv.columns["kind"] ?? "");
+        const attrs = String(inv.columns["attribute_ids"] ?? "").split(";").map((s) => s.trim()).filter(Boolean);
+        const rel = String(inv.columns["relationship_id"] ?? "");
+        if ((kind === "unique" || kind === "required") && attrs.length === 0)
+            problems.push(`${inv.file}: ${key}: a ${kind} invariant names its attributes (attribute_ids)`);
+        if (kind === "cardinality" && rel === "")
+            problems.push(`${inv.file}: ${key}: a cardinality invariant names its relationship (relationship_id)`);
+        for (const a of attrs) {
+            const at = view.get("entity_attributes")?.get(a);
+            if (!at)
+                problems.push(`${inv.file}: ${key}: attribute ${elementKey("entity_attributes", a)} is not in this view`);
+            else if (String(at.columns["entity_id"] ?? "") !== entity)
+                problems.push(`${inv.file}: ${key}: attribute ${elementKey("entity_attributes", a)} belongs to ${String(at.columns["entity_id"] ?? "")}, not ${entity}`);
+        }
+        if (rel !== "") {
+            const r = view.get("entity_relationships")?.get(rel);
+            if (r && String(r.columns["from_entity_id"] ?? "") !== entity)
+                problems.push(`${inv.file}: ${key}: relationship ${elementKey("entity_relationships", rel)} is ${String(r.columns["from_entity_id"] ?? "")}'s, not ${entity}'s`);
+        }
+    }
+}
+/**
+ * One change's deltas against the current view (M-ADR 0230 §4.4): each element's shape, ADDED ids new, MODIFIED and
+ * REMOVED ids held by the delta's partition, and a base revision for every element it modifies, removes or reads.
+ * A base revision that no longer matches the current element is reported as moved: the change is revalidated.
+ * `addedElsewhere` holds the elements other open changes add, for a reference into one of them.
+ */
+export function validateDeltas(schema, current, deltas, addedElsewhere, problems) {
+    const ownAdded = new Set();
+    const dependsOn = new Set();
+    for (const d of deltas) {
+        for (const e of d.added)
+            ownAdded.add(elementKey(e.catalogue, e.id));
+        for (const c of d.dependsOn)
+            dependsOn.add(c);
+    }
+    const seenWrite = new Map();
+    for (const d of deltas) {
+        const write = (key, op) => {
+            const prior = seenWrite.get(key);
+            if (prior)
+                problems.push(`${d.file}: ${op} ${key}, which this change also writes in ${prior}`);
+            else
+                seenWrite.set(key, `${d.file} (${op})`);
+        };
+        const needBase = (key, why) => {
+            const b = d.base.get(key);
+            if (b === undefined) {
+                problems.push(`${d.file}: no base revision for ${key}, which it ${why}`);
+                return;
+            }
+            const [catalogue, ...rest] = key.split("/");
+            const cur = current.get(catalogue)?.get(rest.join("/"));
+            if (cur && revisionOf(cur) !== b)
+                problems.push(`${d.file}: base revision of ${key} has moved since the change was written (${b.slice(0, 19)}… now ${revisionOf(cur).slice(0, 19)}…): revalidate the change`);
+        };
+        for (const e of d.added) {
+            const key = elementKey(e.catalogue, e.id);
+            checkElementShape(schema, e, `${d.file}: ADDED`, problems);
+            if (current.get(e.catalogue)?.has(e.id))
+                problems.push(`${d.file}: ADDED ${key}, which the model already holds; an added id is new`);
+            write(key, "ADDED");
+        }
+        for (const e of d.modified) {
+            const key = elementKey(e.catalogue, e.id);
+            checkElementShape(schema, e, `${d.file}: MODIFIED`, problems);
+            const cur = current.get(e.catalogue)?.get(e.id);
+            if (!cur)
+                problems.push(`${d.file}: MODIFIED ${key}, which the model does not hold`);
+            else {
+                if (cur.partition !== d.partition)
+                    problems.push(`${d.file}: MODIFIED ${key}, which partition ${cur.partition} owns, not ${d.partition}`);
+                needBase(key, "modifies");
+            }
+            write(key, "MODIFIED");
+        }
+        for (const r of d.removed) {
+            const key = elementKey(r.catalogue, r.id);
+            const cur = current.get(r.catalogue)?.get(r.id);
+            if (!cur)
+                problems.push(`${d.file}: REMOVED ${key}, which the model does not hold`);
+            else {
+                if (cur.partition !== d.partition)
+                    problems.push(`${d.file}: REMOVED ${key}, which partition ${cur.partition} owns, not ${d.partition}`);
+                needBase(key, "removes");
+            }
+            write(key, "REMOVED");
+        }
+        // Reads: every element an added or modified element references.
+        for (const e of [...d.added, ...d.modified]) {
+            for (const r of referencesOf(schema, e)) {
+                if (!r.structural)
+                    continue;
+                const target = r.targetColumn === "id" ? r.value : find(current, r.catalogue, r.targetColumn, r.value)?.id;
+                const key = elementKey(r.catalogue, target ?? r.value);
+                if (target !== undefined && current.get(r.catalogue)?.has(target)) {
+                    needBase(key, `reads (${elementKey(e.catalogue, e.id)}.${r.column})`);
+                    continue;
+                }
+                if (ownAdded.has(key))
+                    continue;
+                const by = addedElsewhere.get(key);
+                if (by !== undefined && dependsOn.has(by))
+                    continue;
+                if (by !== undefined)
+                    problems.push(`${d.file}: ${elementKey(e.catalogue, e.id)}.${r.column} names ${key}, which open change ${by} adds; declare it in depends_on`);
+                else
+                    problems.push(`${d.file}: ${elementKey(e.catalogue, e.id)}.${r.column} names ${key}, which is in neither the model nor an open change`);
+            }
+        }
+    }
+}
+//# sourceMappingURL=view.js.map

package/dist/lib/validate/agreement-evidence.js

@@ -0,0 +1,216 @@
+// What an agreement binds and what a verdict must show (M-ADR 0222 §4.6, M-ADR 0223 §4.4-§4.6).
+// Pure text helpers; behaviour-store.ts runs them against git.
+//
+//   agreed content   the change's proposal, deltas, Gate 0, design, tasks (checkboxes ignored), the test plan's
+//                    scenario-to-test rows (its Before and After cells ignored) and its structural deltas with their
+//                    base revisions (M-ADR 0230 §4.4, Proposed; report only until it is accepted) are what was approved. Each is compared
+//                    with its state at the record's pinned commit: the latest amendment's commit, else sdd.commit.
+//   requirement      a requirement's block in a spec: its heading to the next requirement or section heading. The
+//                    stale check compares the blocks a change targets, not the whole file.
+//   scenario kind    changed (a scenario of an ADDED requirement, or one of a MODIFIED requirement that is new or
+//                    differs from the living spec's scenario of the same title) goes red then green; carried (identical
+//                    to the living spec's) is regression and stays green.
+//   verdict line     verdict.md's own verdict: `Verdict: PASS|FAIL` or a leading `**PASS**`/`**FAIL**`.
+/** The files under a change directory that agreement binds, relative to the change directory. */
+export function boundFile(rel) {
+    return /^(proposal|design|gate-0|tasks|test-plan)\.md$/.test(rel) || /^specs\/.+\/spec\.md$/.test(rel) || structuralFile(rel);
+}
+/**
+ * A change's structural artifact (M-ADR 0230 §4.4, Proposed): a partition delta or the no-op claim, both agreed
+ * content, so a delta's base revisions are pinned with it. The effect record (structure/applied.yaml) is written by
+ * the archive, after agreement, and is not.
+ */
+export function structuralFile(rel) {
+    return /^structure\/[^/]+\.yaml$/.test(rel) && rel !== "structure/applied.yaml";
+}
+/** A bound file's content as agreement compares it: all of it, with only the fields execution fills in masked. */
+export function normaliseBound(rel, text) {
+    if (rel === "tasks.md")
+        return text.replace(/^(\s*-\s*\[)\s*[xX~]?\s*(\])/gm, "$1 $2").trimEnd();
+    if (rel === "test-plan.md")
+        return normaliseTestPlan(text);
+    return text.trimEnd();
+}
+/**
+ * The test plan as agreed. Masked, because execution fills them in: the last two cells (Before and After) of each
+ * row of the scenario table, and the whole Ledger and Mutants sections. Everything else, the stand-ins and any
+ * strategy or limitation stated, stays bound.
+ */
+export function normaliseTestPlan(text) {
+    const out = [];
+    let section = "";
+    for (const line of text.split("\n")) {
+        const h = /^##\s+(.+?)\s*$/.exec(line);
+        if (h) {
+            section = h[1].toLowerCase();
+            if (section !== "mutants")
+                out.push(line);
+            continue;
+        }
+        // The ledger and the mutants are what apply records: the mutants are written against guards that exist only once
+        // the change is applied, and the judge writes its own for any guard they miss (M-ADR 0228 §4.1, Proposed).
+        if (section === "ledger" || section === "mutants")
+            continue;
+        if (section === "" && /^\s*\|/.test(line)) {
+            const cells = line.trim().replace(/^\||\|$/g, "").split("|").map((c) => c.trim());
+            out.push(cells.slice(0, Math.max(0, cells.length - 2)).join(" | "));
+            continue;
+        }
+        out.push(line);
+    }
+    return out.join("\n").trimEnd();
+}
+/** A tasks file's repository groups (`## <n>. <repository>`) and the requirements each says it implements. */
+export function taskGroups(tasks) {
+    const out = [];
+    let current = null;
+    for (const line of tasks.split("\n")) {
+        const g = /^##\s+\d+\.\s+`?([A-Za-z0-9][A-Za-z0-9._-]*)`?\s*$/.exec(line);
+        if (g) {
+            current = { repo: g[1], implements: [] };
+            out.push(current);
+            continue;
+        }
+        if (/^##\s/.test(line)) {
+            current = null;
+            continue;
+        }
+        const m = /^\s*(?:[-*]\s+)?\**Implements:?\**:?\s*(.+)$/i.exec(line);
+        if (current && m)
+            current.implements.push(...m[1].split(",").map((x) => x.trim().replace(/^`|`$/g, "")).filter((x) => x && !/^none$/i.test(x)));
+    }
+    return out;
+}
+/** A pinned commit: 7 to 40 hex characters. */
+export function isCommit(v) {
+    return typeof v === "string" && /^[0-9a-f]{7,40}$/i.test(v);
+}
+/** a >= b, for x.y.z versions; a missing or malformed version is lowest. */
+export function versionAtLeast(a, b) {
+    const p = (v) => (v && /^\d+\.\d+\.\d+$/.test(v) ? v.split(".").map(Number) : [-1, -1, -1]);
+    const [x, y] = [p(a), p(b)];
+    for (let i = 0; i < 3; i++)
+        if (x[i] !== y[i])
+            return x[i] > y[i];
+    return true;
+}
+/** The test plan's scenario-to-test rows: every table row before `## Ledger`, as trimmed cells, with the first row (the header) and separator rows dropped. The template holds one table there; a second would be read as more rows. */
+export function testPlanMapping(text) {
+    const head = text.split(/^##\s+Ledger\b/m)[0] ?? "";
+    const rows = head.split("\n").filter((l) => /^\s*\|/.test(l)).map((l) => l.trim().replace(/^\||\|$/g, "").split("|").map((c) => c.trim()));
+    return rows.filter((r, i) => i > 0 && !r.every((c) => /^:?-{3,}:?$/.test(c) || c === ""));
+}
+/** The test plan table's header cells, lower-cased. */
+export function testPlanHeader(text) {
+    const head = text.split(/^##\s+Ledger\b/m)[0] ?? "";
+    const first = head.split("\n").find((l) => /^\s*\|/.test(l));
+    return first ? first.trim().replace(/^\||\|$/g, "").split("|").map((c) => c.trim().toLowerCase()) : [];
+}
+/** A requirement's block: `### Requirement: <name>` to the next requirement or `##` heading. Null when absent. */
+export function requirementBlock(spec, name) {
+    const lines = spec.split("\n");
+    const start = lines.findIndex((l) => new RegExp(`^###\\s+Requirement:\\s*${name.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}\\s*$`).test(l));
+    if (start < 0)
+        return null;
+    let end = lines.length;
+    for (let i = start + 1; i < lines.length; i++) {
+        if (/^###\s+Requirement:/.test(lines[i]) || /^##\s/.test(lines[i])) {
+            end = i;
+            break;
+        }
+    }
+    return lines.slice(start, end).join("\n").trimEnd();
+}
+/** Scenario title -> its block text, within one requirement block. */
+export function scenarios(block) {
+    const out = new Map();
+    let title = null;
+    let buf = [];
+    const flush = () => {
+        if (title !== null)
+            out.set(title, buf.join("\n").trim());
+    };
+    for (const line of block.split("\n")) {
+        const m = /^####\s+Scenario:\s*(.+?)\s*$/.exec(line);
+        if (m) {
+            flush();
+            title = m[1];
+            buf = [];
+            continue;
+        }
+        if (title !== null)
+            buf.push(line);
+    }
+    flush();
+    return out;
+}
+/** The section a requirement sits under in a delta: ADDED, MODIFIED, REMOVED or RENAMED. */
+export function deltaOperation(delta, name) {
+    let op = null;
+    for (const line of delta.split("\n")) {
+        const s = /^##\s+(ADDED|MODIFIED|REMOVED|RENAMED)\s+Requirements\b/.exec(line);
+        if (s)
+            op = s[1];
+        else if (/^##\s/.test(line))
+            op = null;
+        if (new RegExp(`^###\\s+Requirement:\\s*${name.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}\\s*$`).test(line))
+            return op;
+    }
+    return null;
+}
+/** changed or carried, for one scenario of a requirement in a delta, against the living spec (null when the delta has no such scenario). */
+export function scenarioKind(delta, living, requirement, scenario) {
+    const op = deltaOperation(delta, requirement);
+    const block = requirementBlock(delta, requirement);
+    if (!op || !block)
+        return null;
+    const mine = scenarios(block).get(scenario);
+    if (mine === undefined)
+        return null;
+    if (op !== "MODIFIED")
+        return "changed";
+    const theirs = living === null ? null : requirementBlock(living, requirement);
+    const before = theirs === null ? undefined : scenarios(theirs).get(scenario);
+    return before !== undefined && before === mine ? "carried" : "changed";
+}
+/** verdict.md's own verdict, or null when it states none in a form this reads. */
+export function verdictLine(text) {
+    const m = /^\s*(?:#+\s*)?Verdict:\s*\**\s*(PASS|FAIL)\b/im.exec(text) ?? /^\s*\*\*(PASS|FAIL)\*\*/m.exec(text);
+    return m?.[1] ?? null;
+}
+/** Two pins name one commit when one abbreviates the other. */
+export function sameCommit(a, b) {
+    const [x, y] = [a.toLowerCase(), b.toLowerCase()];
+    return x.length >= 7 && y.length >= 7 && (x.startsWith(y) || y.startsWith(x));
+}
+function isoDate(v) {
+    if (v instanceof Date && !Number.isNaN(v.getTime()))
+        return v.toISOString().slice(0, 10);
+    if (typeof v === "string" && /^\d{4}-\d{2}-\d{2}$/.test(v))
+        return v;
+    return null;
+}
+/**
+ * Problems with one agreement condition (M-ADR 0222 §4.6 as amended); `today` is YYYY-MM-DD. A withdrawn or
+ * superseded change has closed its obligations: its conditions are not overdue.
+ */
+export function conditionProblems(c, today, recordStatus = "agreed") {
+    const out = [];
+    for (const k of ["assumption", "owner", "how", "release_limit"]) {
+        if (typeof c[k] !== "string" || c[k].trim() === "")
+            out.push(`no ${k}`);
+    }
+    const by = isoDate(c.validate_by);
+    if (by === null)
+        out.push("validate_by is not a YYYY-MM-DD date");
+    const status = typeof c.status === "string" ? c.status : "";
+    if (!["open", "validated", "failed"].includes(status))
+        out.push(`status ${JSON.stringify(c.status)} is not open | validated | failed`);
+    if ((status === "validated" || status === "failed") && (typeof c.evidence !== "string" || c.evidence.trim() === ""))
+        out.push(`${status} without evidence`);
+    if (status === "open" && by !== null && by < today && recordStatus !== "withdrawn" && recordStatus !== "superseded")
+        out.push(`OVERDUE: open past its validate_by ${by}; validate it, extend it by a ruling, or withdraw the change`);
+    return out;
+}
+export { isoDate };
+//# sourceMappingURL=agreement-evidence.js.map