@sdd-method/maintain-cli 0.12.0 → 0.13.1

package/dist/lib/catalogue/aggregate.js

@@ -27,6 +27,7 @@ import { SCHEMA_COMPAT } from "./schema-compat.js";
 import { loadCanonicalSchema } from "./schema-loader.js";
 import { readCatalogueCsv, parseCatalogueCsv } from "./csv-reader.js";
 import { writeCatalogue } from "./csv-writer.js";
+import { removeRetiredCatalogues } from "./retired-catalogues.js";
 import { buildLegacyContractIdMap } from "./contract-id.js";
 import { validatedPopulation, validateWithEngineToLog } from "./engine-validator.js";
 import { PLATFORM_STAMP_COLUMN, isPlatformScopedFk } from "./fk-validator.js";
@@ -615,6 +616,7 @@ export async function runCatalogueAggregate(inputs, write) {
                 `resolving; neither is worth deleting the rows over.`);
         }
     }
+    await removeRetiredCatalogues(outDir, findings, "catalogues-aggregated");
     await writeAggregationManifestJson({
         outDir,
         schemaVersion: schema.schemaVersion,

package/dist/lib/catalogue/build.js

@@ -16,6 +16,11 @@
  * still produces a valid but empty `catalogues/` directory — useful as a
  * smoke test that the infrastructure works end-to-end on any SDD repo.
  */
+import { overlayModel } from "../structure/catalogue.js";
+import { buildDataModelElements, readDataModelSources } from "./builders/data-model.js";
+import { removeRetiredCatalogues } from "./retired-catalogues.js";
+import { loadModel } from "../structure/model.js";
+import { viewOf } from "../structure/view.js";
 import { checkCapabilityServicePopulation } from "./population-checks.js";
 import { basename, join, relative, resolve } from "node:path";
 import { copyFile, mkdir, readFile, stat } from "node:fs/promises";
@@ -35,6 +40,8 @@ import { buildDataItems, buildFeatureDemand, buildIntegrationSupply } from "./bu
 import { buildEvidenceTargetRepos } from "./builders/evidence-target-repo.js";
 import { buildRepoDependencies } from "./builders/repo-dependency.js";
 import { buildRequirements } from "./builders/requirements.js";
+import { deriveAdrGoverns } from "./builders/adr-governs.js";
+import { buildContractRevisions } from "./builders/contract-revisions.js";
 import { buildJourneyRequirement } from "./builders/journey-requirement.js";
 import { buildDomains, buildProducts, buildApplicationDataPlaneBindings, buildApplicationDataPlaneDeviations, buildApplicationConformanceCoverage, buildImplementations, buildRepositories, buildServices, buildCapabilities, buildCapabilityService, buildCapabilityAdr, buildCapabilityFeature, buildCapabilityContract, buildAdrs, buildAdrSupersedes, buildFeatures, buildFeatureGroups, buildFeatureGrounding, buildCapabilitySpec, buildContracts, buildDeclaredExternalContracts, buildRepoEdges, deriveFeatureRepoFromServices, buildRepoCapabilityExemption, buildServiceCapabilityExemption, buildEvents, buildServiceEvent, buildCapabilityEvent, buildFeatureEvent, buildServiceContract, buildServiceContractConsumes, buildFeatureContract, buildDomainModels, buildCapabilityDomainModel, buildFeatureDomainModel, buildFeatureSubscriptionChannels, buildProductPlatformDependencies, buildGlossaryItems, backfillGlossaryRelations, buildGlossaryXref, buildC4Systems, buildC4Containers, buildC4Components, buildC4ExternalSystems, buildExternalSystemExemption, buildContainerDependency, reportEntryIdReferentCollisions, buildSystemExternalDependency, buildPersonaC4System, buildPersonaContainer, buildPersonas, buildQualityScores, buildScaffolds, buildScreens, buildUserJourneys, buildPersonaJourney, buildPersonaFeature, buildJourneyFeature, buildProductEdges, buildIntegrations, entitySlug, buildEntitiesFromManifest, buildEntitiesFromMermaid, buildServiceEntityFromTables, enrichEntityPersistenceKind, buildC4ContainerEntity, buildC4SystemEntity, } from "./builders/index.js";
 import { buildIntegrationComponents } from "./builders/integration-components.js";
@@ -68,7 +75,14 @@ export async function runCatalogueBuild(inputs, write) {
             `If the manifest follows a newer sdd-manifest-schema than this build, upgrade ` +
             `sdd-cli; otherwise remove or correct the key.`);
     }
-    const rowsByCatalogue = await collectRows(schema, manifest, findings, sddPath, inputs.snapshotStore);
+    const collected = await collectRows(schema, manifest, findings, sddPath, inputs.snapshotStore);
+    // 3 (then). Where the SDD has a structural model, it is the record of structure: every structure catalogue is built from
+    // its current view, and what the sources say otherwise is reported (M-ADR 0230 §4.3, Proposed).
+    const modelProblems = [];
+    const modelFiles = await loadModel(sddPath, modelProblems);
+    const rowsByCatalogue = modelFiles === null ? collected : overlayModel(schema, viewOf(modelFiles, modelProblems), collected, findings);
+    for (const p of modelProblems)
+        findings.add("convention", `${p} (M-ADR 0230, Proposed)`);
     // 3a. Normalise every keyed catalogue to PK-unique rows. Multi-source edge
     // tables (feature_service, feature_repo) can have the same fact asserted by
     // more than one walker; each walker's own seen-set only dedupes intra-walker.
@@ -118,6 +132,9 @@ export async function runCatalogueBuild(inputs, write) {
                 `resolving; neither is worth deleting the rows over.`);
         }
     }
+    // 4a. A catalogue the schema has retired leaves the SDD's own catalogues/ with its replacement's first build.
+    if (outDir === ownCatalogues)
+        await removeRetiredCatalogues(outDir, findings, "catalogues");
     // 5. Internal FK validation (external FKs logged as findings). Pass the
     // SDD profile so profile-external FKs (schema 2.23.0, e.g. an app/integration
     // capability's platform-resident domain_id per M-ADR 0136) resolve at
@@ -191,6 +208,7 @@ export async function runCatalogueBuild(inputs, write) {
         pkConflicts: dedupe.conflicts.length,
         unionedRows: dedupe.unionedRows,
         outDir,
+        findings: findings.all(),
     };
 }
 /**
@@ -1168,10 +1186,16 @@ async function collectRows(schema, manifest, findings, sddPath, snapshotStore) {
         });
         out.set("requirements", r.requirements);
         out.set("requirement_lineage", r.lineage);
-        out.set("requirement_status", r.status);
+        out.set("requirement_revisions", r.revisions);
+        out.set("requirement_assertions", r.assertions);
+        out.set("change_effects", r.effects);
         out.set("changes", r.changes);
         out.set("change_work_order", r.workOrders);
         out.set("change_work_item", r.workItems);
+        // M-ADR 0230 §4.2 (Proposed): which view each decision governs, now the store's changes are known.
+        out.set("adrs", deriveAdrGoverns(out.get("adrs") ?? [], out.get("adr_supersedes") ?? [], r.changes, findings));
+        // M-ADR 0230 §4.2 (Proposed): each contract's revisions by digest, active beside agreed.
+        out.set("contract_revisions", await buildContractRevisions({ sddPath, findings, contracts: out.get("contracts") ?? [], changes: r.changes }));
         // M-ADR 0229 §4.4 (Proposed): the requirements each journey cites, from its tagged end-to-end files or its
         // journey feature's living spec.
         out.set("journey_requirement", await buildJourneyRequirement({
@@ -1400,6 +1424,13 @@ async function collectRows(schema, manifest, findings, sddPath, snapshotStore) {
         entityRows,
     });
     out.set("entities", enrichedEntityRows);
+    // 17a. The domain models' own content (M-ADR 0230 §4.3, §4.11 proof 7, Proposed; schema 6.0.0): each entity's
+    // attributes, the relationships with both ends' cardinality and roles, and the keys as invariants, from the same
+    // parse the entities came from.
+    const dataModel = buildDataModelElements(await readDataModelSources(sddPath, domainModels.map((r) => ({ id: String(r["id"]), domainId: String(r["domain_id"]), docPath: String(r["doc_path"]) }))), enrichedEntityRows, findings);
+    out.set("entity_attributes", dataModel.entityAttributes);
+    out.set("entity_relationships", dataModel.entityRelationships);
+    out.set("domain_invariants", dataModel.domainInvariants);
     const serviceEntityRows = await buildServiceEntityFromTables({
         sddPath,
         findings,

package/dist/lib/catalogue/builders/adr-governs.js

@@ -0,0 +1,39 @@
+export function deriveAdrGoverns(adrs, supersedes, changes, findings) {
+    const changeState = (name) => {
+        const rows = changes.filter((c) => c["name"] === name);
+        if (rows.some((c) => c["status"] === "archived"))
+            return "archived";
+        if (rows.some((c) => c["status"] === "withdrawn" || c["status"] === "superseded"))
+            return "closed";
+        return rows.length > 0 ? "open" : "absent";
+    };
+    const accepted = new Map();
+    for (const a of adrs) {
+        if (!/^accepted\b/i.test(String(a["status"] ?? "")))
+            continue;
+        const change = String(a["effective_change"] ?? "");
+        if (change === "") {
+            accepted.set(String(a["id"]), "current");
+            continue;
+        }
+        const state = changeState(change);
+        if (state === "absent")
+            findings.add("convention", `${String(a["doc_path"])}: effective on archive of ${change}, which is no change in this store; the decision governs nothing until it is (M-ADR 0230 §4.2, Proposed)`);
+        accepted.set(String(a["id"]), state === "archived" ? "current" : state === "open" ? "intended" : "none");
+    }
+    const successors = new Map();
+    for (const s of supersedes) {
+        const old = String(s["superseded_adr_id"]);
+        successors.set(old, [...(successors.get(old) ?? []), String(s["superseding_adr_id"])]);
+    }
+    return adrs.map((a) => {
+        const id = String(a["id"]);
+        let governs = accepted.get(id) ?? "none";
+        if (/^superseded\b/i.test(String(a["status"] ?? ""))) {
+            const next = (successors.get(id) ?? []).map((s) => accepted.get(s) ?? "none");
+            governs = next.length > 0 && !next.includes("current") ? "current" : "none";
+        }
+        return { ...a, governs };
+    });
+}
+//# sourceMappingURL=adr-governs.js.map

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

@@ -19,6 +19,8 @@
 //   - **Date:** YYYY-MM-DD
 //   - **Supersedes:** raw text (captured into supersedes_raw for the
 //     adr_supersedes builder to parse)
+//   - **Effective:** `on acceptance` (the default) or `on archive of <change>` (M-ADR 0230 §4.2, Proposed):
+//     effective_change holds the change; governs is derived once the store's changes are known (adr-governs.ts)
 //
 // ID canonicalisation: filename stem `ADR XXXX[: Title]` → `ADR-{0-padded}`.
 // Title = the portion after the colon when present, else the file stem
@@ -80,6 +82,12 @@ export async function buildAdrs(inputs) {
         const decisionDate = extractField(text, "Date") || "";
         const supersedesRaw = extractField(text, "Supersedes") || "";
         const supersededByRaw = extractField(text, "Superseded By") || "";
+        const effectiveRaw = (extractField(text, "Effective") || "").trim();
+        const onArchive = /^on archive of\s+`?([A-Za-z0-9][A-Za-z0-9._-]*)`?\s*\.?$/i.exec(effectiveRaw);
+        if (effectiveRaw !== "" && !onArchive && !/^on acceptance\.?$/i.test(effectiveRaw)) {
+            inputs.findings.add("convention", `${relPath}: **Effective:** is "${effectiveRaw}", neither "on acceptance" nor "on archive of <change>"; read as on acceptance (M-ADR 0230 §4.2, Proposed)`);
+        }
+        const effectiveChange = onArchive?.[1] ?? "";
         if (scope === "domain" && !inputs.knownDomainIds.has(domainId)) {
             inputs.findings.add("orphan", `${relPath}: ADR is in domain "${domainId}" but no docs/domains/${domainId}/ exists`);
         }
@@ -97,6 +105,7 @@ export async function buildAdrs(inputs) {
             docPath: relPath,
             supersedesRaw,
             supersededByRaw,
+            effectiveChange,
         });
     }
     if (methodScopeSkipCount > 0) {
@@ -112,6 +121,8 @@ export async function buildAdrs(inputs) {
         superseded_by_id: "", // populated in a backfill pass after adr_supersedes builds
         inference_confidence: "",
         supersedes_raw: a.supersedesRaw,
+        effective_change: a.effectiveChange,
+        governs: "", // derived once the store's changes are known (adr-governs.ts)
         source_sdd_id: "",
     }));
     return { rows, parsed };

package/dist/lib/catalogue/builders/contract-revisions.js

@@ -0,0 +1,126 @@
+// contract_revisions: a contract version's content revisions, by digest (M-ADR 0230 §4.2, Proposed; schema 6.0.0).
+//   active      the contract file's current content (deprecated where the contract is)
+//   agreed      a revision an agreed open change agrees (agreement record 1.2.0, contracts[].agrees)
+//   retired     a revision an archived change agreed that the file no longer holds
+// An archived change that agreed the current content is the active revision's change. A compatible amendment is a
+// new revision at the same path, so an agreed revision and the active one coexist.
+//
+// A record names a contract by the file in its own repository (`file:`, or a `files:` list), which the catalogue holds
+// under the SDD's mount of that repository; so a record's file matches the contract whose spec_path ends with it, and
+// a file matching no contract, or several, is a finding and produces no row. `relies_on` and `agrees` are a digest
+// beside `file:`, or a map from each file to its digest beside `files:`. A `relies_on` that no longer matches the
+// file's content is reported: the change relies on a revision that has moved, and is re-agreed.
+import { createHash } from "node:crypto";
+import { readdir, readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { parse as parseYaml } from "yaml";
+const AGREEMENTS = join("docs", "agreements");
+const DIGEST = /^sha256:[0-9a-f]{64}$/;
+export function contentDigest(bytes) {
+    return `sha256:${createHash("sha256").update(bytes).digest("hex")}`;
+}
+const revisionId = (contract, digest) => `${contract}@${digest.slice("sha256:".length, "sha256:".length + 12)}`;
+/** Each (file, relies_on, agrees) a record's contracts list pins. */
+function pins(record, where, findings) {
+    const r = record?.agreement_record;
+    if (!Array.isArray(r?.contracts))
+        return [];
+    const out = [];
+    for (const [i, raw] of r.contracts.entries()) {
+        const c = raw;
+        if (!c)
+            continue;
+        const files = typeof c["file"] === "string" ? [c["file"]] : Array.isArray(c["files"]) ? c["files"].map(String) : [];
+        const digestFor = (key, file) => {
+            const v = c[key];
+            if (v === undefined)
+                return undefined;
+            const d = typeof v === "string" && typeof c["file"] === "string" ? v : typeof v === "object" && v !== null ? v[file] : undefined;
+            if (d === undefined)
+                return undefined;
+            if (typeof d !== "string" || !DIGEST.test(d)) {
+                findings.add("convention", `${where}: contracts[${i}].${key} for ${file} is not a sha256:<64 hex> digest`);
+                return undefined;
+            }
+            return d;
+        };
+        for (const file of files) {
+            const reliesOn = digestFor("relies_on", file);
+            const agrees = digestFor("agrees", file);
+            if (reliesOn || agrees)
+                out.push({ file, ...(reliesOn ? { reliesOn } : {}), ...(agrees ? { agrees } : {}) });
+        }
+    }
+    return out;
+}
+export async function buildContractRevisions(inputs) {
+    const { sddPath, findings } = inputs;
+    const rows = new Map();
+    const current = new Map(); // contract id -> current digest
+    for (const c of inputs.contracts) {
+        const path = String(c["spec_path"] ?? "");
+        if (path === "")
+            continue;
+        const bytes = await readFile(join(sddPath, path)).catch(() => null);
+        if (bytes === null)
+            continue;
+        const id = String(c["id"]);
+        const digest = contentDigest(bytes);
+        current.set(id, digest);
+        const rid = revisionId(id, digest);
+        rows.set(rid, { id: rid, contract_id: id, digest, state: c["status"] === "deprecated" ? "deprecated" : "active", sunset_date: "", change_id: "", source_sdd_id: "", platform_sdd_id: "" });
+    }
+    const byFile = (file) => inputs.contracts.filter((c) => String(c["spec_path"] ?? "").endsWith(`/${file}`) || c["spec_path"] === file).map((c) => String(c["id"]));
+    let names = [];
+    try {
+        names = (await readdir(join(sddPath, AGREEMENTS))).filter((n) => n.endsWith(".yaml")).sort();
+    }
+    catch {
+        names = [];
+    }
+    for (const name of names) {
+        const change = name.slice(0, -".yaml".length);
+        const where = join(AGREEMENTS, name);
+        let doc;
+        try {
+            doc = parseYaml(await readFile(join(sddPath, where), "utf8"));
+        }
+        catch {
+            continue; // the behaviour-store check reports an unparseable record
+        }
+        const changeRows = inputs.changes.filter((c) => c["name"] === change);
+        const archived = changeRows.find((c) => c["status"] === "archived");
+        const open = changeRows.find((c) => c["status"] !== "archived");
+        const state = archived ? "archived" : open?.["status"] === "agreed" ? "agreed" : "other";
+        if (state === "other")
+            continue;
+        const changeId = String((archived ?? open)["id"]);
+        for (const p of pins(doc, where, findings)) {
+            const matches = byFile(p.file);
+            if (matches.length !== 1) {
+                findings.add("convention", `${where}: contract file ${p.file} matches ${matches.length === 0 ? "no catalogued contract" : `${matches.length} catalogued contracts (${matches.join(", ")})`}; no revision row`);
+                continue;
+            }
+            const contract = matches[0];
+            const now = current.get(contract);
+            if (state === "agreed" && p.reliesOn && now && p.reliesOn !== now) {
+                findings.add("divergence", `${where}: relies on revision ${p.reliesOn.slice(0, 19)}… of ${contract}, which has moved to ${now.slice(0, 19)}…; the change relies on a revision no longer published, so it is re-agreed (M-ADR 0230 §4.2, Proposed)`);
+            }
+            if (!p.agrees)
+                continue;
+            const rid = revisionId(contract, p.agrees);
+            const existing = rows.get(rid);
+            if (p.agrees === now) {
+                if (existing && state === "archived")
+                    rows.set(rid, { ...existing, change_id: changeId });
+                continue;
+            }
+            if (state === "agreed")
+                rows.set(rid, { id: rid, contract_id: contract, digest: p.agrees, state: "agreed", sunset_date: "", change_id: changeId, source_sdd_id: "", platform_sdd_id: "" });
+            else if (!existing)
+                rows.set(rid, { id: rid, contract_id: contract, digest: p.agrees, state: "retired", sunset_date: "", change_id: changeId, source_sdd_id: "", platform_sdd_id: "" });
+        }
+    }
+    return [...rows.values()].sort((a, b) => String(a["id"]).localeCompare(String(b["id"])));
+}
+//# sourceMappingURL=contract-revisions.js.map

package/dist/lib/catalogue/builders/data-model.js

@@ -0,0 +1,316 @@
+// A domain model's content, parsed whole (M-ADR 0230 §4.3, §4.11 proof 7, Proposed; schema 6.0.0). One parser per
+// notation, shared by every reader of the file: the entities builder takes its entities from here, and this module
+// builds entity_attributes, entity_relationships and domain_invariants from the same parse.
+//
+// Mermaid ER (`data-model.mermaid.md`, every ```mermaid fence opening with erDiagram):
+//   ENTITY {                      an entity block; ENTITY { type a; type b } on one line is one too
+//     type name [PK|FK|UK|PK_FK[, ...]] ["comment"]
+//   }
+//   A <end>--<end> B : label      a relationship; each end marker || |o o| }| |{ }o o{ is one of four cardinalities;
+//                                 `..` (non-identifying) is read as `--`, and reported
+// TypeQL, in the documented subset (M-ADR 0210 §4.2, `data-model.tql`), through the fail-closed parseTypes:
+//   an entity's owned attributes (@key, @card), and each binary relation as a relationship between its two roles'
+//   players, roles kept. The subset admits no participation cardinality, so both ends are zero-or-more, and a role's
+//   own @card is a cardinality invariant on the relationship.
+// The keys become invariants: a primary key (PK, @key) is one unique invariant over its attributes, which are not
+// nullable; a UK is a unique invariant over its attribute. What a parser reads and cannot hold is an `extraction`
+// finding, never a silent skip.
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { ParseError, parseTypes } from "../../metamodel/tql-subset-parser.js";
+import { entitySlug } from "./entity-slug.js";
+const RE_MERMAID_OPEN = /^```\s*mermaid\s*$/i;
+const RE_FENCE_CLOSE = /^```\s*$/;
+const RE_COMMENT = /^\s*%%/;
+const RE_ENTITY_OPEN = /^\s*([A-Za-z_][A-Za-z0-9_]*)\s*\{\s*$/;
+const RE_ENTITY_INLINE = /^\s*([A-Za-z_][A-Za-z0-9_]*)\s*\{(.*)\}\s*$/;
+const RE_ATTRIBUTE = /^\s*([A-Za-z_][\w[\]~(),.<>-]*)\s+([A-Za-z_*][\w.-]*)\s*((?:PK_FK|PK|FK|UK)(?:\s*,\s*(?:PK_FK|PK|FK|UK))*)?\s*(?:"([^"]*)")?\s*$/;
+const RE_RELATIONSHIP = /^\s*([A-Za-z_][\w-]*)\s+(\|\||\|o|o\||\}\||\}o)(--|\.\.)(\|\||o\||\|o|\|\{|o\{)\s+([A-Za-z_][\w-]*)\s*:\s*(.+?)\s*$/;
+const RE_BARE_ENTITY = /^\s*[A-Za-z_][\w-]*\s*$/;
+const MERMAID_KEYWORDS = new Set(["erdiagram", "subgraph", "classdef", "style", "class"]);
+const END = {
+    "||": "exactly-one",
+    "|o": "zero-or-one",
+    "o|": "zero-or-one",
+    "}|": "one-or-more",
+    "|{": "one-or-more",
+    "}o": "zero-or-more",
+    "o{": "zero-or-more",
+};
+function mermaidAttribute(text) {
+    const m = RE_ATTRIBUTE.exec(text);
+    if (!m)
+        return null;
+    const keys = new Set((m[3] ?? "").split(",").map((k) => k.trim()).flatMap((k) => (k === "PK_FK" ? ["PK", "FK"] : k === "" ? [] : [k])));
+    const description = m[4] ?? "";
+    const primaryKey = keys.has("PK");
+    const nullable = primaryKey ? false : /^nullable\b/i.test(description.trim()) ? true : undefined;
+    return { name: m[2].replace(/^\*/, ""), type: m[1], primaryKey, unique: keys.has("UK"), foreignKey: keys.has("FK"), nullable, description };
+}
+/** Parse every erDiagram fence of a Mermaid data-model file. `where` locates what is reported. */
+export function parseMermaidDataModel(text, where) {
+    const lines = text.split(/\r?\n/);
+    const entities = [];
+    const relationships = [];
+    const unread = [];
+    const seen = new Set();
+    let inMermaid = false;
+    let isEr = false;
+    let firstKeywordSeen = false;
+    let open = null;
+    const close = (e) => {
+        const slug = entitySlug(e.name);
+        if (seen.has(slug))
+            return; // a later block naming the entity again: the first declaration stands
+        seen.add(slug);
+        entities.push(e);
+    };
+    for (let i = 0; i < lines.length; i++) {
+        const raw = lines[i] ?? "";
+        const at = `${where}:${i + 1}`;
+        if (!inMermaid) {
+            if (RE_MERMAID_OPEN.test(raw)) {
+                inMermaid = true;
+                isEr = false;
+                firstKeywordSeen = false;
+            }
+            continue;
+        }
+        if (RE_FENCE_CLOSE.test(raw)) {
+            inMermaid = false;
+            open = null; // a block the fence cut off is dropped, as the entities builder always has
+            continue;
+        }
+        const stripped = raw.trim();
+        if (!firstKeywordSeen && stripped !== "" && !RE_COMMENT.test(raw)) {
+            firstKeywordSeen = true;
+            isEr = stripped.toLowerCase().startsWith("erdiagram");
+            continue;
+        }
+        if (!isEr || stripped === "" || RE_COMMENT.test(raw))
+            continue;
+        if (open) {
+            if (stripped.startsWith("}")) {
+                close(open);
+                open = null;
+                continue;
+            }
+            open.columnCount++;
+            const a = mermaidAttribute(raw);
+            if (a)
+                open.attributes.push(a);
+            else
+                unread.push(`${at}: an attribute line of ${open.name} not understood: ${JSON.stringify(stripped)}`);
+            continue;
+        }
+        const rel = RE_RELATIONSHIP.exec(raw);
+        if (rel) {
+            if (rel[3] === "..")
+                unread.push(`${at}: a non-identifying relationship (..), read as identifying: ${JSON.stringify(stripped)}`);
+            relationships.push({
+                from: rel[1],
+                to: rel[5],
+                name: rel[6].replace(/^"(.*)"$/, "$1").trim(),
+                fromCardinality: END[rel[2]],
+                toCardinality: END[rel[4]],
+                fromRole: "",
+                toRole: "",
+                roleCards: [],
+            });
+            continue;
+        }
+        const inline = RE_ENTITY_INLINE.exec(raw);
+        if (inline && !MERMAID_KEYWORDS.has(inline[1].toLowerCase())) {
+            const parts = inline[2].split(";").map((p) => p.trim()).filter((p) => p !== "");
+            const attributes = [];
+            for (const p of parts) {
+                const a = mermaidAttribute(p);
+                if (a)
+                    attributes.push(a);
+                else
+                    unread.push(`${at}: an attribute of ${inline[1]} not understood: ${JSON.stringify(p)}`);
+            }
+            close({ name: inline[1], attributes, columnCount: parts.length });
+            continue;
+        }
+        const m = RE_ENTITY_OPEN.exec(raw);
+        if (m && !MERMAID_KEYWORDS.has(m[1].toLowerCase())) {
+            open = { name: m[1], attributes: [], columnCount: 0 };
+            continue;
+        }
+        if (RE_BARE_ENTITY.test(raw) && !MERMAID_KEYWORDS.has(stripped.toLowerCase())) {
+            unread.push(`${at}: an entity named without a block (${stripped}); it is catalogued only where a block declares it`);
+            continue;
+        }
+        unread.push(`${at}: a line not understood: ${JSON.stringify(stripped)}`);
+    }
+    return { entities, relationships, unread, unclosed: open?.name ?? null };
+}
+/** Parse a TypeQL data model in the documented subset. A file outside the subset is refused whole, located. */
+export function parseTypeqlDataModel(text, where) {
+    let t;
+    try {
+        t = parseTypes(text, where, { singlePlayer: false });
+    }
+    catch (e) {
+        if (e instanceof ParseError)
+            return { refused: e.message };
+        throw e;
+    }
+    const unread = [];
+    const entities = [];
+    for (const [label, d] of t.entities) {
+        const attributes = [];
+        for (const [attr, ann] of d.owns) {
+            if (ann.multi)
+                unread.push(`${where}: ${label} owns ${attr} @card(0..), a multi-valued attribute; the model holds one value per attribute`);
+            attributes.push({
+                name: attr,
+                type: t.attrs.get(attr) ?? "",
+                primaryKey: ann.key,
+                unique: false,
+                foreignKey: false,
+                // TypeDB's default for an ownership is @card(0..1)
+                nullable: ann.key || ann.required ? false : true,
+                description: "",
+            });
+        }
+        entities.push({ name: label, attributes, columnCount: attributes.length });
+    }
+    const relationships = [];
+    for (const [label, d] of t.relations) {
+        const roles = [...d.relates.keys()];
+        if (d.owns.size > 0)
+            unread.push(`${where}: relation ${label} owns attributes (${[...d.owns.keys()].join(", ")}); the model holds no attributes on a relationship`);
+        if (roles.length !== 2) {
+            unread.push(`${where}: relation ${label} relates ${roles.length} role(s); the model holds binary relationships only`);
+            continue;
+        }
+        const [a, b] = roles;
+        const playersOf = (role) => (t.playersAll.get(`${label}:${role}`) ?? []).filter((p) => {
+            if (t.entities.has(p))
+                return true;
+            unread.push(`${where}: relation ${p} plays ${label}:${role}; the model relates entities only`);
+            return false;
+        });
+        const cards = [...d.relates].flatMap(([role, ann]) => ann.required ? [`each ${label} relates exactly one ${role}`] : ann.optional ? [`each ${label} relates at most one ${role}`] : []);
+        for (const from of playersOf(a)) {
+            for (const to of playersOf(b)) {
+                relationships.push({ from, to, name: label, fromCardinality: "zero-or-more", toCardinality: "zero-or-more", fromRole: a, toRole: b, roleCards: cards });
+            }
+        }
+    }
+    return { entities, relationships, unread, unclosed: null };
+}
+/**
+ * Read and parse each domain model a domain_models row names. A missing file contributes nothing (the domain-models
+ * builder reports it); a TypeQL file outside the subset contributes nothing (the entities builder reports it).
+ */
+export async function readDataModelSources(sddPath, models) {
+    const out = [];
+    for (const m of models) {
+        const tql = m.docPath.endsWith(".tql");
+        if (!tql && !m.docPath.endsWith(".mermaid.md"))
+            continue;
+        const text = await readFile(m.docPath.startsWith("/") ? m.docPath : join(sddPath, m.docPath), "utf8").catch(() => null);
+        if (text === null)
+            continue;
+        const parsed = tql ? parseTypeqlDataModel(text, m.docPath) : parseMermaidDataModel(text, m.docPath);
+        if ("refused" in parsed)
+            continue; // the entities builder reports the refusal
+        out.push({ ...m, parsed });
+    }
+    return out;
+}
+/**
+ * The attribute, relationship and invariant rows of every parsed model, against the entities catalogue as built. An
+ * entity this build did not catalogue contributes nothing; a relationship names an entity of its own domain, else the
+ * one entity of that name in another, else it is reported.
+ */
+export function buildDataModelElements(sources, entities, findings) {
+    const attributes = [];
+    const relationships = [];
+    const invariants = [];
+    const entityIds = new Set(entities.map((e) => String(e["id"])));
+    const bySlug = new Map();
+    for (const e of entities) {
+        const id = String(e["id"]);
+        const domain = String(e["domain_id"] ?? "");
+        if (domain === "" || !id.startsWith(`${domain}-`))
+            continue;
+        const slug = id.slice(domain.length + 1);
+        bySlug.set(slug, [...(bySlug.get(slug) ?? []), id]);
+    }
+    const resolve = (domainId, name) => {
+        const own = `${domainId}-${entitySlug(name)}`;
+        if (entityIds.has(own))
+            return own;
+        const elsewhere = bySlug.get(entitySlug(name)) ?? [];
+        return elsewhere.length === 1 ? elsewhere[0] : null;
+    };
+    const seenAttr = new Set();
+    const seenRel = new Set();
+    for (const s of sources) {
+        for (const u of s.parsed.unread)
+            findings.add("extraction", u, "warn", s.docPath);
+        for (const e of s.parsed.entities) {
+            const entityId = `${s.domainId}-${entitySlug(e.name)}`;
+            if (!entityIds.has(entityId))
+                continue;
+            const pk = [];
+            for (const a of e.attributes) {
+                const id = `${entityId}__${entitySlug(a.name) || a.name.toLowerCase()}`;
+                if (seenAttr.has(id)) {
+                    findings.add("extraction", `${s.docPath}: ${e.name}.${a.name} is stated twice; the first stands`, "warn", s.docPath);
+                    continue;
+                }
+                seenAttr.add(id);
+                attributes.push({
+                    id,
+                    entity_id: entityId,
+                    name: a.name,
+                    type: a.type,
+                    nullable: a.nullable,
+                    foreign_key: a.foreignKey ? true : undefined,
+                    description: a.description,
+                });
+                if (a.primaryKey)
+                    pk.push(id);
+                if (a.unique)
+                    invariants.push({ id: `${id}__unique`, entity_id: entityId, kind: "unique", attribute_ids: id, statement: `${a.name} is unique among ${e.name} (UK)` });
+            }
+            if (pk.length > 0) {
+                const names = e.attributes.filter((a) => a.primaryKey).map((a) => a.name);
+                invariants.push({ id: `${entityId}__primary-key`, entity_id: entityId, kind: "unique", attribute_ids: pk.join(";"), statement: `${names.join(" and ")} identif${names.length === 1 ? "ies" : "y"} each ${e.name} (primary key)` });
+            }
+        }
+        for (const r of s.parsed.relationships) {
+            const from = resolve(s.domainId, r.from);
+            const to = resolve(s.domainId, r.to);
+            if (from === null || to === null) {
+                const missing = [from === null ? r.from : null, to === null ? r.to : null].filter((x) => x !== null).join(" and ");
+                findings.add("extraction", `${s.docPath}: the relationship ${r.from} ${r.name} ${r.to} names ${missing}, which no catalogued entity matches (in its domain, or once elsewhere); not catalogued`, "warn", s.docPath);
+                continue;
+            }
+            const id = `${from}__${entitySlug(r.name) || "related"}__${to}`;
+            if (seenRel.has(id)) {
+                findings.add("extraction", `${s.docPath}: the relationship ${r.from} ${r.name} ${r.to} is stated twice; the first stands`, "warn", s.docPath);
+                continue;
+            }
+            seenRel.add(id);
+            relationships.push({
+                id,
+                from_entity_id: from,
+                to_entity_id: to,
+                name: r.name,
+                from_cardinality: r.fromCardinality,
+                to_cardinality: r.toCardinality,
+                from_role: r.fromRole,
+                to_role: r.toRole,
+            });
+            r.roleCards.forEach((statement, i) => invariants.push({ id: `${id}__cardinality-${i + 1}`, entity_id: from, kind: "cardinality", relationship_id: id, statement }));
+        }
+    }
+    return { entityAttributes: attributes, entityRelationships: relationships, domainInvariants: invariants };
+}
+//# sourceMappingURL=data-model.js.map