@sdd-method/author-cli 0.0.0-stage → 0.1.0

package/dist/lib/catalogue/builders/c4-components.js

@@ -0,0 +1,229 @@
+// C4 L3 components discoverer — emits `c4_components.csv` rows from
+// C4-PlantUML-style mermaid in:
+//   - docs/domains/<slug>/architecture/diagrams/c4-l3-*.mermaid.md
+//   - docs/platform/diagrams/c4-l3-*.mermaid.md
+//   - docs/c4-l3-*.mermaid.md (per-product, application/integration SDDs)
+//
+// Mirrors c4-containers.ts at one level down. Source convention per
+// `coordination/c4-l3-walker-and-path-convention-coordination.md`
+// (sdd-method-gov, 2026-05-29). The walker is granularity-agnostic — both
+// per-container files (one `Container_Boundary` block per file) and
+// per-domain rollup files (multiple `Container_Boundary` blocks per file)
+// produce identical row output. Adopters pick the file shape that suits
+// their authoring workflow.
+//
+// Shape rules:
+//   Container_Boundary(local_id, "Container Display Name") {
+//     Component(component_id, "Component Name", "tech", "description")
+//     Component(...)
+//   }
+//
+// container_id resolution: the walker slugifies the Container_Boundary's
+// display name and matches against `c4_containers.id` rows that end in
+// `-{slug}` within this SDD's system. Unmatched containers fire
+// `[finding] orphan` and the contained Components are skipped.
+//
+// service_id is denormalised from the resolved container's service_id —
+// populated when the parent container represents a runtime service,
+// empty otherwise.
+//
+// Row id shape: `{container_id}-{component-slug}` per schema 2.15.0
+// description.
+import { readdir, readFile } from "node:fs/promises";
+import { join, sep } from "node:path";
+const L3_PREFIX = "c4-l3-";
+const L3_SUFFIX = ".mermaid.md";
+// Boundary opener — only Container_Boundary at L3. System_Boundary is L2's domain.
+const BOUNDARY_OPEN_RE = /^Container_Boundary\s*\(\s*\w+\s*,\s*"([^"]+)"\s*\)\s*\{/;
+// C4-PlantUML component entries inside Container_Boundary blocks.
+const COMPONENT_RE = /Component\s*\(\s*(\w+)\s*,\s*"([^"]+)"\s*(?:,\s*"([^"]*)")?\s*(?:,\s*"([^"]*)")?\s*\)/;
+export async function buildC4Components(inputs) {
+    // No containers → nothing to attach components to. Skip silently; the
+    // L2 walker would have logged the absence.
+    if (inputs.c4ContainerRows.length === 0)
+        return [];
+    // Index containers by suffix-after-system-prefix for slug-of-name matching.
+    // c4_containers.id shape per c4-containers.ts:93 is `{systemId}-{slug}`.
+    // The suffix-match lets us resolve `Container_Boundary(_, "Asset Twin")`
+    // (slug = "asset-twin") to `{anything}-asset-twin`.
+    const containerBySuffix = new Map();
+    for (const row of inputs.c4ContainerRows) {
+        const id = String(row["id"] ?? "");
+        if (id === "")
+            continue;
+        // The full id IS the suffix in the trivial case; also index by the
+        // trailing `-<slug>` portion in case the system prefix varies.
+        containerBySuffix.set(id, row);
+        const dash = id.lastIndexOf("-");
+        if (dash > 0) {
+            const tail = id.slice(dash + 1);
+            // Only add tail-indexing when it's unique enough to be useful.
+            // (Multiple containers with the same tail across systems is the
+            // ambiguous case; we keep the first-seen and rely on orphan-finding
+            // for the others.)
+            if (!containerBySuffix.has(tail))
+                containerBySuffix.set(tail, row);
+        }
+    }
+    const files = await collectL3Files(inputs.sddPath);
+    const rows = [];
+    const seen = new Set();
+    for (const file of files) {
+        const content = await readFile(file.absPath, "utf-8");
+        for (const block of parseContainerBoundaries(content)) {
+            const boundarySlug = slugify(block.displayName);
+            const containerRow = resolveContainer(boundarySlug, containerBySuffix);
+            if (containerRow === undefined) {
+                inputs.findings.add("orphan", `c4_components: ${file.relPath}: Container_Boundary "${block.displayName}" doesn't resolve to a c4_containers row — ${block.components.length} component(s) skipped`);
+                continue;
+            }
+            const containerId = String(containerRow["id"]);
+            const denormalisedServiceId = String(containerRow["service_id"] ?? "");
+            for (const c of block.components) {
+                const componentSlug = slugify(c.name);
+                if (componentSlug === "")
+                    continue;
+                const id = `${containerId}-${componentSlug}`;
+                if (seen.has(id))
+                    continue;
+                seen.add(id);
+                rows.push({
+                    id,
+                    name: c.name,
+                    container_id: containerId,
+                    service_id: denormalisedServiceId,
+                    path: "",
+                    responsibility: c.description,
+                    source_sdd_id: "",
+                });
+            }
+        }
+    }
+    rows.sort((a, b) => String(a["id"]).localeCompare(String(b["id"])));
+    return rows;
+}
+function resolveContainer(slug, containerBySuffix) {
+    if (slug === "")
+        return undefined;
+    // Try the trailing-segment index first (the common case where slug is the
+    // tail of `{systemId}-{slug}`); fall back to scanning all rows for any
+    // id ending in `-{slug}`.
+    const tailHit = containerBySuffix.get(slug);
+    if (tailHit !== undefined)
+        return tailHit;
+    for (const [_, row] of containerBySuffix) {
+        if (String(row["id"]).endsWith(`-${slug}`))
+            return row;
+    }
+    return undefined;
+}
+async function collectL3Files(sddPath) {
+    const out = [];
+    // 1. Per-domain L3 files: docs/domains/<dom>/architecture/diagrams/c4-l3-*.mermaid.md
+    const domainsDir = join(sddPath, "docs", "domains");
+    let domainEntries;
+    try {
+        domainEntries = (await readdir(domainsDir, { withFileTypes: true }))
+            .filter((e) => e.isDirectory())
+            .map((e) => ({ name: e.name }));
+    }
+    catch (err) {
+        if (err.code !== "ENOENT")
+            throw err;
+        domainEntries = [];
+    }
+    for (const entry of domainEntries.sort((a, b) => a.name.localeCompare(b.name))) {
+        const diagramsDir = join(sddPath, "docs", "domains", entry.name, "architecture", "diagrams");
+        const files = await listMatching(diagramsDir, L3_PREFIX, L3_SUFFIX);
+        for (const filename of files.sort()) {
+            const abs = join(diagramsDir, filename);
+            out.push({
+                absPath: abs,
+                relPath: join("docs", "domains", entry.name, "architecture", "diagrams", filename)
+                    .split(sep)
+                    .join("/"),
+            });
+        }
+    }
+    // 2. Platform-wide L3: docs/platform/diagrams/c4-l3-*.mermaid.md
+    const platformDir = join(sddPath, "docs", "platform", "diagrams");
+    const platformFiles = await listMatching(platformDir, L3_PREFIX, L3_SUFFIX);
+    for (const filename of platformFiles.sort()) {
+        const abs = join(platformDir, filename);
+        out.push({
+            absPath: abs,
+            relPath: join("docs", "platform", "diagrams", filename).split(sep).join("/"),
+        });
+    }
+    // 3. Per-product L3 (application-product / integration-product SDDs).
+    const productDir = join(sddPath, "docs");
+    const productFiles = await listMatching(productDir, L3_PREFIX, L3_SUFFIX);
+    for (const filename of productFiles.sort()) {
+        const abs = join(productDir, filename);
+        out.push({
+            absPath: abs,
+            relPath: join("docs", filename).split(sep).join("/"),
+        });
+    }
+    return out;
+}
+async function listMatching(dir, prefix, suffix) {
+    try {
+        const entries = await readdir(dir, { withFileTypes: true });
+        return entries
+            .filter((e) => e.isFile() && e.name.startsWith(prefix) && e.name.endsWith(suffix))
+            .map((e) => e.name);
+    }
+    catch (err) {
+        if (err.code === "ENOENT")
+            return [];
+        throw err;
+    }
+}
+function parseContainerBoundaries(content) {
+    const out = [];
+    const lines = content.split(/\r?\n/);
+    let i = 0;
+    while (i < lines.length) {
+        const line = (lines[i] ?? "").trim();
+        const open = BOUNDARY_OPEN_RE.exec(line);
+        if (!open) {
+            i++;
+            continue;
+        }
+        const displayName = open[1] ?? "";
+        const components = [];
+        i++;
+        let depth = 1; // we just saw `{`
+        while (i < lines.length && depth > 0) {
+            const inner = (lines[i] ?? "").trim();
+            if (inner.endsWith("{"))
+                depth++;
+            else if (inner === "}") {
+                depth--;
+                i++;
+                continue;
+            }
+            const m = COMPONENT_RE.exec(inner);
+            if (m) {
+                components.push({
+                    entryId: m[1] ?? "",
+                    name: m[2] ?? "",
+                    technology: m[3] ?? "",
+                    description: m[4] ?? "",
+                });
+            }
+            i++;
+        }
+        out.push({ displayName, components });
+    }
+    return out;
+}
+function slugify(s) {
+    return s
+        .toLowerCase()
+        .replace(/\s*\([^)]+\)/g, "")
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-+|-+$/g, "");
+}
+//# sourceMappingURL=c4-components.js.map

package/dist/lib/catalogue/builders/c4-containers.js

@@ -0,0 +1,240 @@
+// C4 L2 containers discoverer — emits `c4_containers.csv` rows from
+// C4-PlantUML-style mermaid in:
+//   - docs/domains/<slug>/architecture/diagrams/c4-l2-container.mermaid.md
+//   - docs/platform/diagrams/c4-l2-container.mermaid.md
+//   - docs/c4-l2-container.mermaid.md (per-product, application/integration SDDs)
+//
+// Per schema 2.0.0:
+//   - system_id (required FK to c4_systems.id) — for single-system
+//     ecosystems we use {sddId}-system. Multi-system support (parsing a
+//     `**System:** <id>` metadata line) is a future hook.
+//   - domain_id (nullable, denormalised) derived from the L2 file path:
+//     docs/domains/<slug>/... → <slug>; platform-wide L2 → empty.
+//   - service_id (optional) — opportunistic match on the C4 entry's id
+//     or a slug of its display name to a known service id.
+//
+// We only consider entries inside System_Boundary or Container_Boundary
+// blocks — mirrors the python reference and excludes Person/System_Ext
+// declarations that decorate the diagram.
+//
+// Dedupe is by row id; first-seen wins (a container appearing in
+// multiple L2 files becomes one row).
+import { readdir, readFile, stat } from "node:fs/promises";
+import { join, sep } from "node:path";
+const L2_BASENAME = "c4-l2-container.mermaid.md";
+// Boundary opener: `System_Boundary(id, "name") {` or `Container_Boundary(...)`.
+const BOUNDARY_OPEN_RE = /^(System_Boundary|Container_Boundary)\s*\(\s*\w+/;
+// C4-PlantUML container entries inside boundaries. Per ADR 0155 the
+// canonical c4_container_type is Application | Data Store only:
+//   Container(id, "name", "tech", "desc")       → Application
+//   ContainerDb(id, "name", "tech", "desc")     → Data Store
+//   ContainerQueue(id, "name", "tech", "desc")  → Data Store (a running
+//                                                  broker/queue is a
+//                                                  container, not "infra")
+// `Container_Ext` is intentionally NOT matched here — external containers
+// are catalogued as `c4_external_systems` rows by the c4-external-systems
+// builder, never as internal container rows.
+const ENTRY_RE = /(Container|ContainerDb|ContainerQueue)\s*\(\s*(\w+)\s*,\s*"([^"]+)"\s*(?:,\s*"([^"]*)")?\s*(?:,\s*"([^"]*)")?\s*\)/;
+const TYPE_BY_KIND = {
+    Container: "Application",
+    ContainerDb: "Data Store",
+    ContainerQueue: "Data Store",
+};
+export async function buildC4Containers(inputs) {
+    const systemId = inputs.manifest.c4SystemId ?? `${inputs.manifest.sddId}-system`;
+    if (!inputs.knownSystemIds.has(systemId)) {
+        // No system row, so no FK target for container rows. Never silent when
+        // that drops authored content, and never on the strength of a sibling
+        // builder's log (M-ADR 0133 §4.2c no-silent-drop): if L2 diagrams
+        // exist, THIS builder says it is dropping them.
+        const orphanedL2 = await collectL2Files(inputs.sddPath);
+        if (orphanedL2.length > 0) {
+            inputs.findings.add("coverage", `c4_containers: no c4_systems row '${systemId}' to own containers; ` +
+                `${orphanedL2.length} L2 diagram file(s) present but not catalogued`);
+        }
+        return [];
+    }
+    const files = await collectL2Files(inputs.sddPath);
+    const rows = [];
+    const seen = new Set();
+    const rowById = new Map();
+    for (const file of files) {
+        const content = await readFile(file.absPath, "utf-8");
+        for (const entry of parseBoundaryEntries(content)) {
+            const slug = slugify(entry.name);
+            if (slug === "")
+                continue;
+            const id = `${systemId}-${slug}`;
+            if (!inputs.containerIdByEntryIdOut?.has(entry.entryId)) {
+                inputs.containerIdByEntryIdOut?.set(entry.entryId, id);
+            }
+            if (!inputs.containerNameByEntryIdOut?.has(entry.entryId)) {
+                inputs.containerNameByEntryIdOut?.set(entry.entryId, entry.name);
+            }
+            if (!inputs.containerTechByEntryIdOut?.has(entry.entryId) && entry.technology !== "") {
+                inputs.containerTechByEntryIdOut?.set(entry.entryId, entry.technology);
+            }
+            const collapsed = rowById.get(id);
+            if (collapsed !== undefined) {
+                // F21: dedup-by-id is first-seen and was SILENT — two containers
+                // sharing a display name collapse into one row, and every edge
+                // referencing either binds to the merge. When their technology
+                // strings flatly contradict, that is two different things wearing
+                // one name, and the collapse is the loudest available signal.
+                if (techContradicts(String(collapsed["technology"] ?? ""), entry.technology)) {
+                    inputs.findings.add("convention", `c4_containers: two containers share the display name "${entry.name}" with contradictory ` +
+                        `technologies ("${String(collapsed["technology"])}" vs "${entry.technology}") — collapsed ` +
+                        `into one row "${id}" — either different referents wearing one name (rename one) ` +
+                        `or a misused technology field on a shared reference (correct it) (F21)`);
+                }
+                continue;
+            }
+            seen.add(id);
+            const serviceId = inputs.knownServiceIds.has(entry.entryId)
+                ? entry.entryId
+                : inputs.knownServiceIds.has(slug)
+                    ? slug
+                    : "";
+            const domainId = file.domainId !== "" && inputs.knownDomainIds.has(file.domainId)
+                ? file.domainId
+                : "";
+            if (file.domainId !== "" && domainId === "") {
+                inputs.findings.add("orphan", `c4_containers: L2 file at ${file.relPath} references unknown domain "${file.domainId}" — domain_id left empty`);
+            }
+            const row = {
+                id,
+                name: entry.name,
+                system_id: systemId,
+                domain_id: domainId,
+                service_id: serviceId,
+                type: TYPE_BY_KIND[entry.kind] ?? "",
+                technology: entry.technology,
+                description: entry.description,
+                source_sdd_id: "",
+            };
+            rowById.set(id, row);
+            rows.push(row);
+        }
+    }
+    rows.sort((a, b) => String(a["id"]).localeCompare(String(b["id"])));
+    return rows;
+}
+async function collectL2Files(sddPath) {
+    const out = [];
+    // 1. Per-domain L2 files.
+    const domainsDir = join(sddPath, "docs", "domains");
+    let domainEntries;
+    try {
+        domainEntries = (await readdir(domainsDir, { withFileTypes: true }))
+            .filter((e) => e.isDirectory())
+            .map((e) => ({ name: e.name }));
+    }
+    catch (err) {
+        if (err.code !== "ENOENT")
+            throw err;
+        domainEntries = [];
+    }
+    for (const entry of domainEntries.sort((a, b) => a.name.localeCompare(b.name))) {
+        const rel = join("docs", "domains", entry.name, "architecture", "diagrams", L2_BASENAME);
+        const abs = join(sddPath, rel);
+        if (await isFile(abs)) {
+            out.push({
+                absPath: abs,
+                relPath: rel.split(sep).join("/"),
+                domainId: entry.name,
+            });
+        }
+    }
+    // 2. Platform-wide L2.
+    const platformRel = join("docs", "platform", "diagrams", L2_BASENAME);
+    const platformAbs = join(sddPath, platformRel);
+    if (await isFile(platformAbs)) {
+        out.push({
+            absPath: platformAbs,
+            relPath: platformRel.split(sep).join("/"),
+            domainId: "",
+        });
+    }
+    // 3. Per-product L2 (application-product / integration-product SDDs).
+    // Lives at the SDD docs/ root; the system is the SDD itself (one
+    // c4_systems row per SDD), so the boundary in the L2 is the product
+    // boundary. domain_id is left empty — federated app/integration
+    // products do not have a primary domain per ADR 0136.
+    const productRel = join("docs", L2_BASENAME);
+    const productAbs = join(sddPath, productRel);
+    if (await isFile(productAbs)) {
+        out.push({
+            absPath: productAbs,
+            relPath: productRel.split(sep).join("/"),
+            domainId: "",
+        });
+    }
+    return out;
+}
+async function isFile(path) {
+    try {
+        const s = await stat(path);
+        return s.isFile();
+    }
+    catch (err) {
+        if (err.code === "ENOENT")
+            return false;
+        throw err;
+    }
+}
+function parseBoundaryEntries(content) {
+    const out = [];
+    const stack = [];
+    for (const raw of content.split(/\r?\n/)) {
+        const line = raw.trim();
+        if (BOUNDARY_OPEN_RE.test(line) && line.includes("{")) {
+            stack.push("boundary");
+            continue;
+        }
+        if (line === "}" && stack.length > 0) {
+            stack.pop();
+            continue;
+        }
+        if (stack.length === 0)
+            continue;
+        const m = ENTRY_RE.exec(line);
+        if (!m)
+            continue;
+        out.push({
+            kind: m[1] ?? "",
+            entryId: m[2] ?? "",
+            name: m[3] ?? "",
+            technology: m[4] ?? "",
+            description: m[5] ?? "",
+        });
+    }
+    return out;
+}
+function slugify(s) {
+    return s
+        .toLowerCase()
+        .replace(/\s*\([^)]+\)/g, "")
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-+|-+$/g, "");
+}
+/**
+ * F21: two technology strings flatly contradict when both are present and
+ * share no token — ".NET 6 (in Linton)" vs "Java" needs no NLP. Absent or
+ * overlapping strings are NOT a contradiction (silence, not a guess).
+ */
+export function techContradicts(a, b) {
+    const tokens = (s) => new Set(s
+        .replace(/([a-z0-9])([A-Z])/g, "$1 $2")
+        .toLowerCase()
+        .split(/[^a-z0-9.+#]+/)
+        .filter((t) => t !== ""));
+    const ta = tokens(a);
+    const tb = tokens(b);
+    if (ta.size === 0 || tb.size === 0)
+        return false;
+    for (const t of ta)
+        if (tb.has(t))
+            return false;
+    return true;
+}
+//# sourceMappingURL=c4-containers.js.map

package/dist/lib/catalogue/builders/c4-entity-rollups.js

@@ -0,0 +1,87 @@
+// Phase 3 C4-to-entity roll-up walkers per ADR 0159 §4.8.
+// Both are pure transitive joins over already-FK-enforced inputs.
+//
+// buildC4ContainerEntity:
+//   service_entity ⋈ c4_containers.service_id
+//   → emit (container_id, entity_id, relation) inheriting relation from
+//     upstream service_entity. Dedup by (container_id, entity_id, relation).
+//
+// buildC4SystemEntity:
+//   c4_container_entity ⋈ c4_containers.system_id
+//   → aggregate (system_id, entity_id) with container_count.
+//
+// Both handle empty inputs gracefully (an adopter's pre-lock state has zero
+// service_entity edges → both roll-up outputs are empty; no errors).
+export function buildC4ContainerEntity(inputs) {
+    // Index containers by service_id.
+    const containersByServiceId = new Map();
+    for (const c of inputs.c4Containers) {
+        const sid = String(c["service_id"] ?? "");
+        if (!sid)
+            continue;
+        const cid = String(c["id"]);
+        const list = containersByServiceId.get(sid) ?? [];
+        list.push(cid);
+        containersByServiceId.set(sid, list);
+    }
+    const rowsByPk = new Map();
+    for (const se of inputs.serviceEntityRows) {
+        const sid = String(se["service_id"]);
+        const eid = String(se["entity_id"]);
+        const rel = String(se["relation"] ?? "");
+        const containers = containersByServiceId.get(sid);
+        if (!containers)
+            continue;
+        for (const cid of containers) {
+            const pk = `${cid}__${eid}`;
+            if (rowsByPk.has(pk))
+                continue; // first-relation-wins on dup
+            rowsByPk.set(pk, {
+                id: pk,
+                container_id: cid,
+                entity_id: eid,
+                relation: rel,
+                source_sdd_id: "",
+            });
+        }
+    }
+    return [...rowsByPk.values()];
+}
+export function buildC4SystemEntity(inputs) {
+    // Index containers by id for system lookup.
+    const containerById = new Map();
+    for (const c of inputs.c4Containers) {
+        containerById.set(String(c["id"]), c);
+    }
+    const counts = new Map(); // key: `${system_id}|${entity_id}`
+    const systemByKey = new Map();
+    for (const ce of inputs.containerEntityRows) {
+        const c = containerById.get(String(ce["container_id"]));
+        if (!c)
+            continue;
+        const sysId = String(c["system_id"] ?? "");
+        if (!sysId)
+            continue;
+        const eid = String(ce["entity_id"]);
+        const key = `${sysId}|${eid}`;
+        counts.set(key, (counts.get(key) ?? 0) + 1);
+        if (!systemByKey.has(key)) {
+            systemByKey.set(key, { system_id: sysId, entity_id: eid });
+        }
+    }
+    const rows = [];
+    for (const [key, count] of counts) {
+        const e = systemByKey.get(key);
+        if (!e)
+            continue;
+        rows.push({
+            id: `${e.system_id}__${e.entity_id}`,
+            system_id: e.system_id,
+            entity_id: e.entity_id,
+            container_count: count,
+            source_sdd_id: "",
+        });
+    }
+    return rows;
+}
+//# sourceMappingURL=c4-entity-rollups.js.map