@sdd-method/maintain-cli 0.13.1 → 0.15.0

package/dist/lib/catalogue/builders/entity-archetype.js

@@ -0,0 +1,121 @@
+// Catalogue schema 7.1.0: backfill `entities.ppt_archetype` from the capability specs' `## Entity Classification`
+// tables (M-ADR 0230 §4.3, at its acceptance).
+//
+// The archetype is a structure fact. Where the SDD has a structural model the model holds it, and the capability spec
+// template drops its table, so this reads the tables only in an SDD without a model: that build is what `migrate
+// structure` carries into a first model.
+//
+// Authored cells vary: "Party (Green)", "**Thing — audit record**", "Blue/Description", "Moment", "PartyRole". A cell's
+// archetype is the first one it names, colour labels and qualifiers aside. Moment alone is moment-interval, and
+// PartyRole is a role. A cell naming more than two is a list of options, not a classification, and names none.
+// What cannot be classified is reported, once per build, never guessed.
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { collectTableLines, detectColumn, entitySlug, splitRow } from "./data-store-mapping.js";
+export const PPT_ARCHETYPES = ["party", "place", "thing", "role", "moment-interval", "description"];
+const RE_HEADING = /^## Entity Classification\b/;
+const RE_TOKEN = /\b(?:moment[\s-]*interval|moment|party[\s-]*role|party|place|thing|role|description)/g;
+const EXAMPLES = 5;
+/** The archetypes a cell names, in order, each once. */
+export function archetypesNamed(cell) {
+    const out = [];
+    for (const m of cell.toLowerCase().matchAll(RE_TOKEN)) {
+        const t = m[0].replace(/[\s-]+/g, "");
+        const a = t.startsWith("moment") ? "moment-interval" : t === "partyrole" ? "role" : t;
+        if (!out.includes(a))
+            out.push(a);
+    }
+    return out;
+}
+/** A cell's archetype: the first it names, or null when it names none or more than two. */
+export function archetypeOf(cell) {
+    const named = archetypesNamed(cell);
+    return named.length === 0 || named.length > 2 ? null : named[0];
+}
+/** The entity a row's first cell names: markup and a trailing qualifier stripped. */
+function entityName(cell) {
+    return cell
+        .replace(/\[([^\]]*)\]\([^)]*\)/g, "$1")
+        .replace(/[*`_]/g, "")
+        .split(/\s+[—–-]\s+/)[0]
+        .replace(/\s*\([^)]*\)\s*$/, "")
+        .trim();
+}
+function sample(xs) {
+    return xs.slice(0, EXAMPLES).join(", ") + (xs.length > EXAMPLES ? `, and ${xs.length - EXAMPLES} more` : "");
+}
+export async function enrichEntityArchetype(inputs) {
+    // A spec in the entity's own domain outranks one that reaches it by the cross-domain fallback; otherwise the first wins.
+    const chosen = new Map();
+    const several = [];
+    const none = [];
+    const unresolved = [];
+    const disagree = new Set();
+    const specs = [...new Map(inputs.capabilities.filter((c) => c.spec_path !== "").map((c) => [c.spec_path, c])).values()].sort((a, b) => a.spec_path.localeCompare(b.spec_path));
+    for (const cap of specs) {
+        let text;
+        try {
+            text = await readFile(join(inputs.sddPath, cap.spec_path), "utf8");
+        }
+        catch {
+            continue;
+        }
+        const lines = text.split(/\r?\n/);
+        const at = lines.findIndex((l) => RE_HEADING.test(l));
+        if (at === -1)
+            continue;
+        const table = collectTableLines(lines, at + 1);
+        if (table === null || table.length < 3)
+            continue;
+        const headers = splitRow(table[0]);
+        const col = detectColumn(headers, (h) => h.includes("archetype") || h.includes("ppt"));
+        if (col === -1)
+            continue;
+        const entityCol = Math.max(0, detectColumn(headers, (h) => h.includes("entity") || h.includes("aggregate")));
+        for (const line of table.slice(2)) {
+            const cells = splitRow(line);
+            const name = entityName(cells[entityCol] ?? "");
+            // a separator, the template's placeholder row, or a header repeated inside the table
+            if (name === "" || /^[-:]+$/.test(name) || name.startsWith("{") || name.toLowerCase() === (headers[entityCol] ?? "").toLowerCase())
+                continue;
+            const where = `${cap.spec_path}: ${name}`;
+            const cell = cells[col] ?? "";
+            const named = archetypesNamed(cell);
+            const archetype = archetypeOf(cell);
+            if (archetype === null) {
+                none.push(`${where} (${JSON.stringify(cell)})`);
+                continue;
+            }
+            if (named.length > 1)
+                several.push(`${where} (${JSON.stringify(cell)} read as ${archetype})`);
+            const slug = entitySlug(name);
+            const localId = inputs.entityIdByDomainSlug.get(`${cap.domain_id}|${slug}`);
+            const id = localId ?? inputs.entityIdBySlug.get(slug);
+            if (id === undefined) {
+                unresolved.push(where);
+                continue;
+            }
+            const mine = { archetype, spec: cap.spec_path, local: localId !== undefined };
+            const prior = chosen.get(id);
+            if (prior !== undefined && prior.archetype !== archetype) {
+                const [kept, other] = mine.local && !prior.local ? [mine, prior] : [prior, mine];
+                disagree.add(`${id} (${kept.archetype} in ${kept.spec}, catalogued; ${other.archetype} in ${other.spec})`);
+            }
+            if (prior === undefined || (mine.local && !prior.local))
+                chosen.set(id, mine);
+        }
+    }
+    const report = (n, what, items) => {
+        if (n > 0)
+            inputs.findings.add("coverage", `entities.ppt_archetype: ${n} ${what}: ${sample([...items].sort())}`);
+    };
+    report(none.length, "Entity Classification row(s) name no archetype, so none is catalogued", none);
+    report(several.length, "Entity Classification row(s) name two archetypes; the first is catalogued", several);
+    report(unresolved.length, "Entity Classification row(s) name no entity of this SDD", unresolved);
+    report(disagree.size, "entities classified differently by two specs; the entity's own domain's spec, else the first, is catalogued", disagree);
+    return inputs.entityRows.map((r) => {
+        const c = chosen.get(String(r["id"]));
+        return c === undefined || String(r["ppt_archetype"] ?? "") !== "" ? r : { ...r, ppt_archetype: c.archetype };
+    });
+}
+//# sourceMappingURL=entity-archetype.js.map

package/dist/lib/catalogue/builders/entity-merge.js

@@ -0,0 +1,90 @@
+// entities: the data-model walker's rows merged with the glossary-alignment manifest's (M-ADR 0159 §4.4).
+//
+// Field by field: a manifest value wins where it is non-empty, and the data model's value stands where the
+// manifest is silent, so source_domain_model_id and the columns= note survive a manifest entry naming the
+// same entity. Notes from both are kept.
+//
+// A platform-wide manifest entry (`_platform-wide-<slug>`, M-ADR 0159 §4.2) whose slug names exactly one
+// domain entity (`<domain>-<slug>`) IS that entity: it fills the domain entity's empty fields and emits no row
+// of its own, so one entity is one element. Its glossary term moves with it, and the entity_glossary step
+// derives the edge from the domain entity. An entry matching no domain entity, or several, stays platform-wide
+// and is reported.
+import { PLATFORM_WIDE_PK_PREFIX } from "./entities-manifest.js";
+const MANIFEST_REL_PATH = "glossary-alignment-manifest.yaml";
+function filled(v) {
+    return v !== undefined && v !== null && String(v) !== "";
+}
+function joinNotes(a, b) {
+    const parts = [];
+    for (const v of [a, b]) {
+        for (const p of String(v ?? "").split(";"))
+            if (p !== "" && !parts.includes(p))
+                parts.push(p);
+    }
+    return parts.join(";");
+}
+/** `over`'s non-empty values on top of `base`; notes from both. */
+function overlay(base, over) {
+    const out = { ...base };
+    for (const [k, v] of Object.entries(over)) {
+        if (k === "notes")
+            out[k] = joinNotes(base[k], v);
+        else if (filled(v))
+            out[k] = v;
+    }
+    return out;
+}
+/** `extra`'s values only where `base` is empty; notes from both. */
+function fillEmpty(base, extra) {
+    const out = { ...base };
+    for (const [k, v] of Object.entries(extra)) {
+        if (k === "id" || k === "name" || k === "domain_id")
+            continue;
+        if (k === "notes")
+            out[k] = joinNotes(base[k], v);
+        else if (!filled(base[k]) && filled(v))
+            out[k] = v;
+    }
+    return out;
+}
+export function mergeEntities(fromDataModels, fromManifest, findings, 
+/** The sentinel ids from a platform-wide domain hint (entities-manifest's out-set): the only ones that fold. */
+platformWideIds) {
+    const byId = new Map();
+    for (const r of fromDataModels)
+        byId.set(String(r["id"]), r);
+    for (const r of fromManifest) {
+        const id = String(r["id"]);
+        const existing = byId.get(id);
+        byId.set(id, existing ? overlay(existing, r) : r);
+    }
+    const prefix = `${PLATFORM_WIDE_PK_PREFIX}-`;
+    for (const [id, row] of [...byId]) {
+        if (!id.startsWith(prefix) || !platformWideIds.has(id))
+            continue;
+        const slug = id.slice(prefix.length);
+        const matches = [...byId.values()].filter((e) => {
+            const dom = String(e["domain_id"] ?? "");
+            return dom !== "" && String(e["id"]) === `${dom}-${slug}`;
+        });
+        if (matches.length === 1) {
+            const target = matches[0];
+            const own = String(target["glossary_term"] ?? "");
+            const theirs = String(row["glossary_term"] ?? "");
+            if (own !== "" && theirs !== "" && own !== theirs) {
+                findings.add("divergence", `${MANIFEST_REL_PATH}: platform-wide entity ${row["name"]} names glossary term ${theirs}, but ${target["id"]} ` +
+                    `already names ${own} — kept ${own}`);
+            }
+            byId.set(String(target["id"]), fillEmpty(target, row));
+            byId.delete(id);
+        }
+        else if (matches.length === 0) {
+            findings.add("coverage", `${MANIFEST_REL_PATH}: platform-wide entity ${row["name"]} names no domain entity — kept as ${id}`);
+        }
+        else {
+            findings.add("divergence", `${MANIFEST_REL_PATH}: platform-wide entity ${row["name"]} names ${matches.length} domain entities (${matches.map((m) => m["id"]).join(", ")}) — kept as ${id}; give it a domain`);
+        }
+    }
+    return [...byId.values()];
+}
+//# sourceMappingURL=entity-merge.js.map

package/dist/lib/catalogue/builders/features.js

@@ -158,7 +158,7 @@ export function featureStatus(text) {
 }
 /**
  * A feature spec's kind (schema 4.4.0): the value of its `**Kind:**` line, lower-cased, else `feature`. An
- * obligation (M-ADR 0226, Proposed) and a journey feature (M-ADR 0229 §4.2, Proposed) say so; any other value is written as given, so
+ * obligation (M-ADR 0226, Proposed) and a journey feature (M-ADR 0229 §4.2) say so; any other value is written as given, so
  * the catalogue's vocabulary gate names the spec rather than a default hiding the mistake.
  */
 export function featureKind(text) {

package/dist/lib/catalogue/builders/glossary-xref.js

@@ -27,8 +27,9 @@
 //   4. Forward-method supersedes (new).
 //        models[].entities[] with status: superseded + superseded_by
 //      One row per supersedes mapping after resolving both endpoints'
-//      glossary_term against glossary_items.csv. Orphan finding when an
-//      endpoint doesn't resolve.
+//      glossary_term against glossary_items.csv: the successor (superseded_by)
+//      is the source and supersedes the superseded term, the target. Orphan
+//      finding when an endpoint doesn't resolve.
 //
 //   5. Forward-method entity-mapping (new, writes to entity_glossary).
 //        models[].entities[] with status ∈ {aligned, matched_direct} and
@@ -40,6 +41,7 @@
 import { readFile } from "node:fs/promises";
 import { join } from "node:path";
 import { parse as parseYaml } from "yaml";
+import { NON_CANONICAL_DOMAINS } from "./entities-manifest.js";
 const MANIFEST_REL_PATH = join("docs", "platform", "reference", "glossary-alignment-manifest.yaml");
 export async function buildGlossaryXref(inputs) {
     // Profile gate per M-ADR 0158 §amendment: the manifest is platform-owned;
@@ -259,14 +261,18 @@ export async function buildGlossaryXref(inputs) {
                         inputs.findings.add("orphan", `${MANIFEST_REL_PATH}: supersedes edge can't emit — target "${supersededBy}" (→ glossary "${targetEntity?.glossaryTerm ?? "?"}") doesn't resolve to a glossary item`);
                         continue;
                     }
-                    emitXref(sourceId, targetId, "supersedes");
+                    // The successor supersedes the superseded term: `source supersedes target`, as adr_supersedes reads.
+                    emitXref(targetId, sourceId, "supersedes");
                     continue;
                 }
                 if ((status === "aligned" || status === "matched_direct") && glossaryTerm !== "") {
                     // Entity-mapping walker writes to entity_glossary.csv.
                     if (domain === "" || !inputs.knownDomainIds.has(domain)) {
-                        // Domain not in this SDD's domains.csv — likely "platform-wide"
-                        // or another scope identifier. Skip with a coverage finding.
+                        // A platform-wide entry is the domain entity its slug names (entity-merge.ts), and the entity_glossary
+                        // edge is derived from that entity after the merge; the merge reports one it cannot place. Any other
+                        // domain not in this SDD's domains.csv is skipped with a coverage finding.
+                        if (NON_CANONICAL_DOMAINS.has(domain))
+                            continue;
                         inputs.findings.add("coverage", `${MANIFEST_REL_PATH}: entity ${name} domain "${domain}" not in known domains — entity_glossary row skipped`);
                         continue;
                     }

package/dist/lib/catalogue/builders/journey-requirement.js

@@ -1,4 +1,4 @@
-// journey_requirement: the requirements a user journey cites for its steps (M-ADR 0229 §4.4, Proposed; schema 4.4.0).
+// journey_requirement: the requirements a user journey cites for its steps (M-ADR 0229 §4.4; schema 4.4.0).
 //
 // Derived, never authored, from either master (§4.2):
 //   tag       option A: the end-to-end `.feature` files under the manifest's `journeys.test_paths`. A file tagged
@@ -64,13 +64,13 @@ export async function buildJourneyRequirement(inputs) {
         for (const m of text.matchAll(REQ_TAG)) {
             const quiet = atAggregate && inputs.reportedFeatureIds.has(m[1]);
             if (!knownFeatures.has(m[1])) {
-                findings.add("external", `${where}: @req:${m[1]}/${m[2]} names a feature this catalogue does not hold; resolves at aggregation (M-ADR 0229 §4.4, Proposed)`);
+                findings.add("external", `${where}: @req:${m[1]}/${m[2]} names a feature this catalogue does not hold; resolves at aggregation (M-ADR 0229 §4.4)`);
                 continue;
             }
             const ids = bySlug.get(`${m[1]}/${m[2]}`) ?? [];
             if (ids.length !== 1) {
                 if (!quiet)
-                    findings.add("orphan", `${where}: @req:${m[1]}/${m[2]} ${ids.length === 0 ? "names no requirement of that feature" : `matches ${ids.length} requirements of that feature`}; no journey_requirement row (M-ADR 0229 §4.4, Proposed)`);
+                    findings.add("orphan", `${where}: @req:${m[1]}/${m[2]} ${ids.length === 0 ? "names no requirement of that feature" : `matches ${ids.length} requirements of that feature`}; no journey_requirement row (M-ADR 0229 §4.4)`);
                 continue;
             }
             const id = `${journeyId}__${ids[0]}`;
@@ -95,7 +95,7 @@ export async function buildJourneyRequirement(inputs) {
                 continue;
             if (journeys.length > 1) {
                 if (!atAggregate)
-                    findings.add("divergence", `${where}: tagged with ${journeys.length} journeys (${journeys.join(", ")}); one file is one journey's master (M-ADR 0229 §4.2, Proposed)`);
+                    findings.add("divergence", `${where}: tagged with ${journeys.length} journeys (${journeys.join(", ")}); one file is one journey's master (M-ADR 0229 §4.2)`);
                 continue;
             }
             const journeyId = journeys[0];
@@ -129,7 +129,7 @@ export async function buildJourneyRequirement(inputs) {
         const journeys = [...new Set([...spec.matchAll(JOURNEY_TAG)].map((m) => m[1]))];
         if (journeys.length !== 1) {
             if (!atAggregate)
-                findings.add(journeys.length === 0 ? "orphan" : "divergence", `${where}: a journey feature's living spec ${journeys.length === 0 ? "names no journey (@journey:<journey-id>)" : `names ${journeys.length} journeys`}; one journey feature masters one journey (M-ADR 0229 §4.2, Proposed)`);
+                findings.add(journeys.length === 0 ? "orphan" : "divergence", `${where}: a journey feature's living spec ${journeys.length === 0 ? "names no journey (@journey:<journey-id>)" : `names ${journeys.length} journeys`}; one journey feature masters one journey (M-ADR 0229 §4.2)`);
             continue;
         }
         const journeyId = journeys[0];

package/dist/lib/catalogue/builders/quality-scores.js

@@ -119,7 +119,7 @@ const num = (v) => {
     return null;
 };
 /**
- * The review's other assessed inputs (M-ADR 0230 §4.9, Proposed): `inputs:` as a list of paths, or of `{path}`
+ * The review's other assessed inputs (M-ADR 0230 §4.9): `inputs:` as a list of paths, or of `{path}`
  * entries, each read at the review's corpus_ref. ';'-joined; null when the review names none.
  */
 function inputPaths(v) {

package/dist/lib/catalogue/builders/requirements.js

@@ -18,7 +18,7 @@
 //   change_work_order   per (change, repository): the record's work order, agreed or completed.
 //   change_work_item    per (change, work item): the ids its proposal's `## Work Items` section lists, keyed by
 //                       the undated name so the row survives archive.
-//   requirement_revisions  one row per distinct text of a requirement (schema 6.0.0, M-ADR 0230 §4.7, Proposed): the
+//   requirement_revisions  one row per distinct text of a requirement (schema 6.0.0, M-ADR 0230 §4.7): the
 //                       living spec's is current, an agreed open change's ADDED or MODIFIED block intended, an
 //                       archived change's block the living spec no longer holds history. Identified by its digest.
 //   requirement_assertions per (revision, repository): observed from a baseline's `**Observed in:**` line;

package/dist/lib/catalogue/builders/service-contract-consumes.js

@@ -59,13 +59,13 @@ export async function buildServiceContractConsumes(inputs) {
             const mapped = inputs.legacyContractIdMap?.get(contractId);
             if (mapped !== undefined && mapped.length === 1) {
                 inputs.findings.add("inferred", `service_contract: alias target "${contractId}" (${serviceId} ← "${iface.interfaceText}") re-keyed to ` +
-                    `"${mapped[0]}" — 2.x kindless contract id migrated per the 3.0.0 map (regenerable, not drift); ` +
+                    `"${mapped[0]}" — an earlier-form contract id (2.x kindless, or a pre-7.0.0 unsplit stem) migrated per the contract-id map (regenerable, not drift); ` +
                     `update .sdd/service-contract-aliases.yaml to retire this finding`);
                 contractId = mapped[0];
             }
             else if (mapped !== undefined && mapped.length > 1) {
                 inputs.findings.add("convention", `service_contract: alias target "${contractId}" (${serviceId} ← "${iface.interfaceText}") maps to ` +
-                    `${mapped.length} contracts at 3.0.0 [${mapped.join(", ")}] — a 2.x cross-family collision; ` +
+                    `${mapped.length} current contracts [${mapped.join(", ")}] — a cross-family collision under the earlier form; ` +
                     `qualify the alias with the kind-suffixed id; edge dropped`);
                 continue;
             }

package/dist/lib/catalogue/builders/service-entity-tables.js

@@ -128,7 +128,7 @@ export async function buildServiceEntityFromTables(inputs) {
     }
     return [...rowsByPk.values()];
 }
-async function loadAliasMap(sddPath, findings) {
+export async function loadAliasMap(sddPath, findings) {
     const empty = { byDisplayLower: new Map() };
     const path = join(sddPath, ALIAS_REL_PATH);
     let text;