@sdd-method/author-cli 0.10.0 → 0.11.0

package/dist/lib/catalogue/rubric-coverage-map.yaml

@@ -933,3 +933,21 @@ coverage:
     kind: enum
     scoring: not-applicable
     reason: closed vocabulary, not an artefact
+  feature_status:
+    kind: enum
+    scoring: not-applicable
+    reason: closed vocabulary, not an artefact
+  journey_requirement:
+    kind: edge
+    scoring: derived-edge
+    class: dependency
+    impact_flow: toward-source
+    reason: derived from end-to-end test tags or journey features' living specs
+  feature_kind:
+    kind: enum
+    scoring: not-applicable
+    reason: closed vocabulary, not an artefact
+  journey_requirement_basis:
+    kind: enum
+    scoring: not-applicable
+    reason: closed vocabulary, not an artefact

package/dist/lib/catalogue/schema-compat.js

@@ -27,7 +27,7 @@
  * M-ADR 0134 §4.6 (canonical builder + aggregator).
  */
 export const SCHEMA_COMPAT = {
-    catalogue_schema: "^4.0.0",
+    catalogue_schema: "^5.0.0",
     sdd_manifest: "^1.0.0",
     aggregation_manifest: "^1.0.0",
 };

package/dist/lib/intents/migrate.js

@@ -10,6 +10,9 @@
 //              relative path, or a blob URL whose repository is one of the SDDs);
 //   mentioned  a tracked file in an SDD that names the request id, unless the file names many request ids
 //              (an index lists requests; it is not where one went);
+//   titled     a tracked file whose title names the request id (an application's own Epic Brief): it is
+//              about that request whatever else it cites, so it counts even when it names many ids, and it
+//              weighs more than any other evidence in choosing the intent's home;
 //   commit     a commit in an SDD whose message names the id, unless its subject moves, renames, archives or
 //              marks the Ideas and Briefs themselves. When it names at most a few ids (a plan
 //              bundle delivers several), the files it changed that the SDD still owns are evidence too
@@ -17,7 +20,8 @@
 //   plan       a plan file (from --plans) that names the id. A plan says what was planned, not what shipped,
 //              so an id whose only evidence is a plan is flagged for a check that the work landed. A plan
 //              naming at most a few ids also contributes the paths it cites that an SDD owns now (planned).
-// A path that moved since it was cited or committed is followed through the SDD's git renames to where it is
+// With no evidence, an intent goes to the platform among the SDDs (the first one named when none is a
+// platform), and is flagged. A path that moved since it was cited or committed is followed through the SDD's git renames to where it is
 // now. A reviewer's decisions are given back as --home ID=<sdd-id> and --status ID=open|closed.
 // Planning state (status, priority, relations) goes to a tool-neutral work-item import file, never into the
 // intent (M-ADR 0227 §4.3, M-ADR 0035). A dry run writes the report, the import file, the citation table and
@@ -39,6 +43,8 @@ const NOT_OWN = /^(docs\/method\/|catalogues|\.sdd\/|openspec\/schemas\/|content
 const SWEEP = 25;
 /** A commit or plan naming more request ids than this is not evidence for any one of them. */
 const SHARED = 3;
+/** How much a file titled with the id weighs in choosing a home, against one for any other evidence line. */
+const TITLED_WEIGHT = 100;
 const HOUSEKEEPING = /\b(move[sd]?|moving|rename[sd]?|renaming|archive[sd]?|mark(s|ed)?|retire[sd]?|close[sd]?|complete[sd]?)\b.*\b(idea|ideas|idea-map|epic|epics|brief|briefs)\b|\b(idea|ideas|idea-map|epic|epics|brief|briefs)\b.*\b(moved|renamed|archived|marked|retired|closed|completed)\b/i;
 async function walk(dir, accept) {
     const out = [];
@@ -109,7 +115,14 @@ async function loadSdd(dir) {
     catch {
         // not a git repository
     }
-    return { dir, id, repoNames, managed: await managedPaths(dir), renames };
+    let kind = "";
+    try {
+        kind = (await readFile(join(dir, ".sdd-repo-kind"), "utf8")).trim();
+    }
+    catch {
+        // no marker
+    }
+    return { dir, id, repoNames, managed: await managedPaths(dir), renames, kind };
 }
 function readSource(path, text) {
     const doc = parseMarkdown(text);
@@ -306,6 +319,7 @@ export async function migrateIntents(opts) {
     const sdds = await Promise.all(opts.sdds.map((d) => loadSdd(resolve(d))));
     if (sdds.length === 0)
         throw new Error("name at least one SDD (--sdd)");
+    const defaultHome = sdds.find((s) => s.kind === "platform-product") ?? sdds[0];
     // 1. Sources, grouped by request id.
     const byId = new Map();
     const unrecognised = [];
@@ -332,7 +346,7 @@ export async function migrateIntents(opts) {
     const ids = new Set(byId.keys());
     const map = opts.ideaMap ? readIdeaMap(await readFile(opts.ideaMap, "utf8")) : new Map();
     // 2. Evidence.
-    const ev = new Map([...ids].map((i) => [i, { cited: [], mentioned: [], committed: [], planned: [], commits: [], plans: [] }]));
+    const ev = new Map([...ids].map((i) => [i, { cited: [], mentioned: [], titled: [], committed: [], planned: [], commits: [], plans: [] }]));
     const indexFiles = [];
     for (const [id, e] of byId) {
         const text = [e.idea, e.brief].filter(Boolean).map((f) => readFileSyncSafe(f.path)).join("\n");
@@ -357,11 +371,18 @@ export async function migrateIntents(opts) {
             const hits = [...new Set((text.match(ID_TOKEN) ?? []).filter((t) => ids.has(t)))];
             if (hits.length === 0)
                 continue;
+            // A file titled with a request id is about that request, however many others it cites.
+            const title = /^#\s+(.+)$/m.exec(text)?.[1] ?? "";
+            const titled = (title.match(ID_TOKEN) ?? []).filter((t) => ids.has(t));
+            for (const id of titled)
+                ev.get(id).titled.push({ sdd: s.id, path: rel });
             if (hits.length > opts.indexThreshold) {
                 indexFiles.push(`${s.id}: ${rel} (${hits.length} ids)`);
                 continue;
             }
             for (const id of hits) {
+                if (titled.includes(id))
+                    continue;
                 const e = ev.get(id);
                 if (!e.cited.some((c) => c.sdd === s.id && c.path === rel))
                     e.mentioned.push({ sdd: s.id, path: rel });
@@ -442,15 +463,19 @@ export async function migrateIntents(opts) {
         }
         // Mentioned and committed paths already cited are listed once, as cited.
         const has = (l, x) => l.some((c) => c.sdd === x.sdd && c.path === x.path);
-        e.mentioned = e.mentioned.filter((x) => !has(e.cited, x));
-        e.committed = e.committed.filter((x) => !has(e.cited, x) && !has(e.mentioned, x));
-        e.planned = e.planned.filter((x) => !has(e.cited, x) && !has(e.mentioned, x) && !has(e.committed, x));
+        e.titled = e.titled.filter((x) => !has(e.cited, x));
+        e.mentioned = e.mentioned.filter((x) => !has(e.cited, x) && !has(e.titled, x));
+        e.committed = e.committed.filter((x) => !has(e.cited, x) && !has(e.titled, x) && !has(e.mentioned, x));
+        e.planned = e.planned.filter((x) => !has(e.cited, x) && !has(e.titled, x) && !has(e.mentioned, x) && !has(e.committed, x));
         // Home: the SDD most of the evidence is in, unless a reviewer set it.
         const count = new Map();
         for (const x of [...e.cited, ...e.mentioned, ...e.committed, ...e.planned])
             count.set(x.sdd, (count.get(x.sdd) ?? 0) + 1);
+        // A file titled with the id outweighs the rest: an application's own Epic Brief places its request there.
+        for (const x of e.titled)
+            count.set(x.sdd, (count.get(x.sdd) ?? 0) + TITLED_WEIGHT);
         const ranked = [...count.entries()].sort((a, b) => b[1] - a[1]);
-        let home = sdds[0];
+        let home = defaultHome;
         const set = opts.homes?.get(id);
         if (set) {
             const s = sdds.find((x) => x.id === set);
@@ -466,7 +491,7 @@ export async function migrateIntents(opts) {
             if (ranked.length > 1 && ranked[0][1] === ranked[1][1])
                 flag(id, `home ambiguous: ${ranked.map(([s, n]) => `${s} ${n}`).join(", ")}`);
             home = sdds.find((s) => s.id === ranked[0][0]);
-            if (e.cited.length + e.mentioned.length + e.committed.length === 0)
+            if (e.cited.length + e.titled.length + e.mentioned.length + e.committed.length === 0)
                 flag(id, "planned paths only: check that the work landed");
         }
         const classification = (fields("Classification") || "").toLowerCase();
@@ -475,6 +500,7 @@ export async function migrateIntents(opts) {
         const path = `${dir}/${slug(primary.path, id)}`;
         const where = [
             ...e.cited.map((c) => `- \`${c.path}\` (${c.sdd}; cited)`),
+            ...e.titled.map((c) => `- \`${c.path}\` (${c.sdd}; titled)`),
             ...e.mentioned.map((c) => `- \`${c.path}\` (${c.sdd}; mentioned)`),
             ...e.committed.map((c) => `- \`${c.path}\` (${c.sdd}; committed in ${c.sha}${c.with.length ? ` with ${c.with.join(", ")}` : ""})`),
             ...e.planned.map((c) => `- \`${c.path}\` (${c.sdd}; planned in ${c.plan}${c.with.length ? ` with ${c.with.join(", ")}` : ""})`),
@@ -593,7 +619,7 @@ export async function migrateIntents(opts) {
         `Request ids: ${ids.size} (${pairs.filter((p) => p.idea && p.brief).length} with an Idea and an Epic Brief, ${pairs.filter((p) => p.idea && !p.brief).length} with an Idea only, ${pairs.filter((p) => !p.idea && p.brief).length} with a Brief only).`,
         `Work items: ${items.filter((i) => i.status === "closed").length} closed, ${items.filter((i) => i.status === "open").length} open.`,
         `Homes: ${[...homes.entries()].map(([s, n]) => `${s} ${n}`).join(", ")}.`,
-        `Evidence, ids supported by each source: cited ${supported("cited")}, mentioned ${supported("mentioned")}, committed ${supported("committed")}, planned ${supported("planned")}, commit ${supported("commits")}, plan ${supported("plans")}.`,
+        `Evidence, ids supported by each source: cited ${supported("cited")}, titled ${supported("titled")}, mentioned ${supported("mentioned")}, committed ${supported("committed")}, planned ${supported("planned")}, commit ${supported("commits")}, plan ${supported("plans")}.`,
         "",
         `## Flagged (${flags.size})`,
         "",

package/dist/lib/metamodel/tql-subset-parser.js

@@ -174,7 +174,13 @@ export function parseTypes(text, fileLabel = "catalogue-schema.tql", options = {
                     throw new ParseError(`${where}: plays needs <relation>:<role>`);
                 if (decl.plays.has(w[1]))
                     throw new ParseError(`${where}: ${lab} plays ${w[1]} twice`);
-                decl.plays.set(w[1], parseAnnotations(w.slice(2), where));
+                const ann = parseAnnotations(w.slice(2), where);
+                // A plays clause's cardinality constrains participation, which the relational projection has no place for:
+                // refused, so a constraint the model gained can never be dropped by the projection with the gate green.
+                if (ann.key || ann.required || ann.multi || ann.optional) {
+                    throw new ParseError(`${where}: ${lab} plays ${w[1]} with a cardinality annotation; participation cardinality cannot be projected onto the catalogue schema, so it is not admitted`);
+                }
+                decl.plays.set(w[1], ann);
             }
             else if (head === "relates") {
                 if (kind !== "relation")
@@ -225,6 +231,16 @@ export function parseTypes(text, fileLabel = "catalogue-schema.tql", options = {
 }
 const ROW_RE = /^insert \$m isa ([a-z][a-z0-9-]*), (.*);$/;
 const TOK_RE = /has ([a-z][a-z0-9-]*) ("(?:[^"\\]|\\.)*"|-?\d+|true|false)/y;
+function valueFamily(v) {
+    return typeof v === "boolean" ? "boolean" : typeof v === "number" ? "integer" : "string";
+}
+function attrFamily(valueType) {
+    if (valueType === undefined)
+        return undefined;
+    if (valueType === "long" || valueType === "integer")
+        return "integer";
+    return valueType;
+}
 export function parseMeta(text, fileLabel = "catalogue-schema-meta.tql", options = {}) {
     const metaTypes = options.metaTypes ?? META_TYPES;
     const rows = new Map();
@@ -268,9 +284,26 @@ export function parseMeta(text, fileLabel = "catalogue-schema-meta.tql", options
             else
                 throw new ParseError(`${where}: expected ', has ...' at offset ${i}: ${JSON.stringify(body.slice(i, i + 40))}`);
         }
+        const decl = options.types?.entities.get(typ);
+        if (options.types && !decl)
+            throw new ParseError(`${where}: meta type ${typ} is not declared in the type file`);
+        if (decl) {
+            for (const [k, vs] of acc) {
+                const own = decl.owns.get(k);
+                if (!own)
+                    throw new ParseError(`${where}: ${typ} does not own ${k}; an undeclared meta property is refused, not ignored`);
+                if (!own.multi && vs.length > 1)
+                    throw new ParseError(`${where}: ${typ}.${k} is a single value and appears ${vs.length} times; a repeated scalar is refused, not reduced to its first value`);
+                const fam = attrFamily(options.types.attrs.get(k));
+                for (const v of vs) {
+                    if (fam !== undefined && valueFamily(v) !== fam)
+                        throw new ParseError(`${where}: ${typ}.${k} holds ${JSON.stringify(v)}, but ${k} is of value type ${options.types.attrs.get(k)}`);
+                }
+            }
+        }
         const row = {};
         for (const [k, vs] of acc)
-            row[k] = LIST_KEYS.has(k) ? vs : vs[0];
+            row[k] = (decl ? decl.owns.get(k).multi : LIST_KEYS.has(k)) ? vs : vs[0];
         const list = rows.get(typ) ?? [];
         list.push(row);
         rows.set(typ, list);

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

@@ -0,0 +1,204 @@
+// 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) and the test plan's
+//                    scenario-to-test rows (its Before and After cells ignored) 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);
+}
+/** 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, the whole Ledger section, and the last two cells (Killed by and Result) of each row of
+ * the Mutants table. 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();
+            out.push(line);
+            continue;
+        }
+        if (section === "ledger")
+            continue;
+        if ((section === "" || section === "mutants") && /^\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