@sdd-method/author-cli 0.10.0 → 0.12.0

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