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

package/dist/lib/catalogue/builders/c4-external-systems.js

@@ -0,0 +1,194 @@
+// C4 external software systems discoverer — emits `c4_external_systems.csv`
+// rows (per ADR 0155). External systems are C4 L1 peers the ecosystem
+// integrates with but does not own; they are rendered `System_Ext(...)` on
+// L1/L2 diagrams (and occasionally `Container_Ext(...)` for an external
+// system's container). They are NOT c4_containers (not inside your system)
+// and NOT c4_systems (no owning Product).
+//
+// We scan the same L1 + L2 files the c4-systems / c4-containers builders
+// read, and pull every `System_Ext(id, "name", "desc")` and
+// `Container_Ext(id, "name", "tech", "desc")` declaration. The row id
+// derives from the DECLARED diagram entry id — `ext-{slug(entry-id)}`
+// (schema 3.0.0, M-ADR 0203 §4.2) — so identity is the author's declared
+// assertion, the same identity the aggregator adjudicates (M-ADR 0189
+// §4.2). The same declared identity across SDDs collapses to one row at
+// aggregation (the dedup-by-PK exception to ADR 0134). Two entries whose
+// DISPLAY NAMES agree but whose entry ids differ are two rows — the
+// same-entity-two-labels case made visible instead of silently merged;
+// the 2.x name-slug ids map to these via the ext-id migration map.
+//
+// The returned `idByEntryId` map (diagram entry-id → row id) lets the
+// system_external_dependency builder resolve `Rel(...)` endpoints.
+import { readdir, readFile, stat } from "node:fs/promises";
+import { join, sep } from "node:path";
+import { C4_L1_CANDIDATES, SYNDICATED_PLATFORM_L1, findDomainScopedL1s, } from "./c4-l1-candidates.js";
+import { extIdFromEntryId } from "../ext-id.js";
+// `System_Ext(id, "name", "desc")` — no technology argument.
+const SYSTEM_EXT_RE = /System_Ext\s*\(\s*(\w+)\s*,\s*"([^"]+)"\s*(?:,\s*"([^"]*)")?\s*\)/;
+// `Container_Ext(id, "name", "tech", "desc")` — external container.
+const CONTAINER_EXT_RE = /Container_Ext\s*\(\s*(\w+)\s*,\s*"([^"]+)"\s*(?:,\s*"([^"]*)")?\s*(?:,\s*"([^"]*)")?\s*\)/;
+// Shares the candidate list with c4-systems / persona-c4system for DRY (one
+// source of truth — see c4-l1-candidates.ts). NOTE: unlike those two, this
+// builder does NOT pick one file — it UNIONS every existing L1 file (own +
+// domain-scoped + syndicated) plus the L2 files and dedups externals by slug
+// at aggregation, so the candidate ORDER is irrelevant here. The syndicated
+// copy deliberately stays in the union (unlike identity sourcing, M-ADR 0189
+// §4.5): a sibling's own diagram Rel(...) lines may reference entries the
+// syndicated file declares, and dropping it would silently orphan those
+// edges. Its dedup-by-slug makes the extra harvest idempotent at aggregation.
+const L1_CANDIDATES = C4_L1_CANDIDATES;
+const L2_BASENAME = "c4-l2-container.mermaid.md";
+export async function buildC4ExternalSystems(inputs) {
+    const files = await collectC4DiagramFiles(inputs.sddPath);
+    const rows = [];
+    const idByEntryId = new Map();
+    const nameByEntryId = new Map();
+    const technologyByEntryId = new Map();
+    const descriptionByEntryId = new Map();
+    const seen = new Map();
+    for (const { abs, scope } of files) {
+        const content = await readFile(abs, "utf-8");
+        for (const ext of parseExternals(content)) {
+            // Identity is the declared entry id (schema 3.0.0). An entry id that
+            // normalises to nothing cannot key a row — announced, never silent
+            // (M-ADR 0133 §4.2c).
+            const id = extIdFromEntryId(ext.entryId);
+            if (id === "") {
+                inputs.findings.add("convention", `c4_external_systems: entry id "${ext.entryId}" ("${ext.name}") normalises to an empty slug — no row emitted; rename the diagram entry id`);
+                continue;
+            }
+            idByEntryId.set(ext.entryId, id);
+            if (!nameByEntryId.has(ext.entryId))
+                nameByEntryId.set(ext.entryId, ext.name);
+            if (!technologyByEntryId.has(ext.entryId) && ext.technology !== "") {
+                technologyByEntryId.set(ext.entryId, ext.technology);
+            }
+            if (!descriptionByEntryId.has(ext.entryId) && ext.description !== "") {
+                descriptionByEntryId.set(ext.entryId, ext.description);
+            }
+            const existing = seen.get(id);
+            if (existing) {
+                // Same declared identity referenced again — first row wins; flag
+                // attribute conflicts so authors can reconcile. Name joins the
+                // checked set at 3.0.0: with the id keyed on the entry id, one
+                // identity under two display names is exactly this conflict.
+                if ((ext.name !== "" &&
+                    existing["name"] !== "" &&
+                    existing["name"] !== ext.name) ||
+                    (ext.technology !== "" &&
+                        existing["technology"] !== "" &&
+                        existing["technology"] !== ext.technology) ||
+                    (ext.description !== "" &&
+                        existing["description"] !== "" &&
+                        existing["description"] !== ext.description)) {
+                    inputs.findings.add("convention", `c4_external_systems: id "${id}" declared with conflicting attributes within ${inputs.manifest.sddId} — first-seen kept`);
+                }
+                continue;
+            }
+            const row = {
+                id,
+                name: ext.name,
+                technology: ext.technology,
+                description: ext.description,
+                // Adjudication provenance (M-ADR 0189 §4.1/§4.2, schema 2.30.0):
+                // the declared entry id is the identity the aggregator resolves;
+                // the scope records whether the first-seen declaration was
+                // ecosystem-context (l1) or scope-relative (l2).
+                declared_id: ext.entryId,
+                source_scope: scope,
+                source_sdd_id: "",
+            };
+            seen.set(id, row);
+            rows.push(row);
+        }
+    }
+    rows.sort((a, b) => String(a["id"]).localeCompare(String(b["id"])));
+    return { rows, idByEntryId, nameByEntryId, technologyByEntryId, descriptionByEntryId };
+}
+function parseExternals(content) {
+    const out = [];
+    for (const raw of content.split(/\r?\n/)) {
+        const line = raw.trim();
+        const se = SYSTEM_EXT_RE.exec(line);
+        if (se) {
+            out.push({
+                entryId: se[1] ?? "",
+                name: se[2] ?? "",
+                technology: "",
+                description: se[3] ?? "",
+            });
+            continue;
+        }
+        const ce = CONTAINER_EXT_RE.exec(line);
+        if (ce) {
+            out.push({
+                entryId: ce[1] ?? "",
+                name: ce[2] ?? "",
+                technology: ce[3] ?? "",
+                description: ce[4] ?? "",
+            });
+        }
+    }
+    return out;
+}
+/**
+ * Every C4 diagram file an SDD can carry (all L1 candidates incl.
+ * domain-scoped, plus every L2), scope-tagged. Shared with
+ * system-external-dependency (F11c: that builder kept a private,
+ * pre-0.30.1-ordered copy MISSING the domain-scoped path — the fourth
+ * divergent copy of this list, and a silent drop inside adjudication:
+ * a Rel in a domain-scoped L1 was never harvested, so a converted
+ * candidate's relationship was recorded nowhere).
+ */
+export async function collectC4DiagramFiles(sddPath) {
+    const out = [];
+    for (const rel of L1_CANDIDATES) {
+        const abs = join(sddPath, rel);
+        if (await isFile(abs)) {
+            out.push({ abs, scope: "l1", syndicated: rel === SYNDICATED_PLATFORM_L1 });
+        }
+    }
+    // Domain-scoped L1s (M-ADR 0189 §4.5) — union, like every other candidate.
+    for (const rel of await findDomainScopedL1s(sddPath)) {
+        out.push({ abs: join(sddPath, rel), scope: "l1", syndicated: false });
+    }
+    // Per-domain L2 files.
+    const domainsDir = join(sddPath, "docs", "domains");
+    try {
+        const entries = (await readdir(domainsDir, { withFileTypes: true }))
+            .filter((e) => e.isDirectory())
+            .map((e) => e.name)
+            .sort((a, b) => a.localeCompare(b));
+        for (const name of entries) {
+            const abs = join(sddPath, "docs", "domains", name, "architecture", "diagrams", L2_BASENAME);
+            if (await isFile(abs))
+                out.push({ abs, scope: "l2", syndicated: false });
+        }
+    }
+    catch (err) {
+        if (err.code !== "ENOENT")
+            throw err;
+    }
+    // Platform-wide + per-product L2.
+    for (const rel of [
+        join("docs", "platform", "diagrams", L2_BASENAME),
+        join("docs", L2_BASENAME),
+    ]) {
+        const abs = join(sddPath, rel);
+        if (await isFile(abs))
+            out.push({ abs, scope: "l2", syndicated: false });
+    }
+    void sep;
+    return out;
+}
+async function isFile(path) {
+    try {
+        return (await stat(path)).isFile();
+    }
+    catch (err) {
+        if (err.code === "ENOENT")
+            return false;
+        throw err;
+    }
+}
+//# sourceMappingURL=c4-external-systems.js.map

package/dist/lib/catalogue/builders/c4-l1-candidates.js

@@ -0,0 +1,107 @@
+// Shared L1 context-diagram path resolution for the L1-reading C4 builders
+// (c4-systems, persona-c4system, c4-external-systems).
+//
+// **Own-L1-first, syndicated-for-platform-root-only** (M-ADR 0189 §4.5).
+// Under federation a sibling SDD typically carries a syndicated copy of the
+// platform-root's L1 at `docs/platform/diagrams/c4-l1-context.mermaid.md`
+// for cross-reference, AND may author its own L1. The sibling's own L1 must
+// outrank the syndicated copy — and, per F7/WS8, the syndicated copy must
+// not source a sibling's identity AT ALL: on two measured estates roughly
+// half of all systems carried the platform's name and description because
+// the fallback fired for every sibling that authored no own L1. A sibling
+// with no own L1 resolves to "" — the caller derives the name from the
+// manifest and emits a coverage finding (the M-ADR 0133 §4.2c rule, applied
+// to columns instead of rows).
+//
+// This module is shared so the L1-reading builders cannot keep divergent
+// copies. They drifted before: the c4-systems L1-priority fix (sdd-cli
+// 0.30.1) reversed only c4-systems' private copy; persona-c4system kept the
+// old syndicated-first order, so `persona_c4system` matched the platform's
+// personas instead of the sibling's. c4-external-systems UNIONS every
+// existing L1 file rather than picking one, so candidate order is irrelevant
+// there; it shares these paths only to avoid a divergent copy.
+// See sdd-method-gov/coordination/persona-c4system-l1-priority-bug-coordination.md.
+import { readdir, stat } from "node:fs/promises";
+import { join } from "node:path";
+/** Own-L1 candidates usable by ANY SDD, in priority order. */
+export const OWN_L1_CANDIDATES = [
+    "docs/c4-l1.md", // sibling's own L1 — highest priority
+    "docs/application/c4-l1.md",
+    "docs/diagrams/c4-l1-context.mermaid.md",
+];
+/**
+ * The syndicated platform L1. For the platform-root SDD this file IS its own
+ * L1 (lowest-priority own candidate). For every other SDD it may not source
+ * identity (M-ADR 0189 §4.5).
+ */
+export const SYNDICATED_PLATFORM_L1 = "docs/platform/diagrams/c4-l1-context.mermaid.md";
+/**
+ * Full candidate list, retained for union-style consumers
+ * (c4-external-systems) where order and ownership are irrelevant.
+ */
+export const C4_L1_CANDIDATES = [
+    ...OWN_L1_CANDIDATES,
+    SYNDICATED_PLATFORM_L1,
+];
+const DOMAIN_L1_REL = ["architecture", "diagrams", "c4-l1-context.mermaid.md"];
+/**
+ * Domain-scoped L1s: `docs/domains/<slug>/architecture/diagrams/
+ * c4-l1-context.mermaid.md` — the natural home for a promoted subsystem with
+ * one eponymous domain (M-ADR 0189 §4.5). Returned as repo-relative paths,
+ * sorted by domain slug.
+ */
+export async function findDomainScopedL1s(sddPath) {
+    const domainsDir = join(sddPath, "docs", "domains");
+    let entries;
+    try {
+        entries = (await readdir(domainsDir, { withFileTypes: true }))
+            .filter((e) => e.isDirectory())
+            .map((e) => e.name)
+            .sort((a, b) => a.localeCompare(b));
+    }
+    catch (err) {
+        if (err.code === "ENOENT")
+            return [];
+        throw err;
+    }
+    const out = [];
+    for (const name of entries) {
+        const rel = join("docs", "domains", name, ...DOMAIN_L1_REL);
+        if (await isFile(join(sddPath, rel)))
+            out.push(rel);
+    }
+    return out;
+}
+/**
+ * Resolve the L1 diagram that may source THIS SDD's identity (name,
+ * description, personas): own candidates in priority order, then a unique
+ * domain-scoped L1, then — for the platform root only — the syndicated
+ * platform path (which is its own L1).
+ */
+export async function resolveIdentityL1(sddPath, isPlatformRoot) {
+    for (const rel of OWN_L1_CANDIDATES) {
+        if (await isFile(join(sddPath, rel))) {
+            return { path: rel, ambiguousDomainL1Count: 0 };
+        }
+    }
+    const domainL1s = await findDomainScopedL1s(sddPath);
+    if (domainL1s.length === 1) {
+        return { path: domainL1s[0], ambiguousDomainL1Count: 0 };
+    }
+    const ambiguous = domainL1s.length > 1 ? domainL1s.length : 0;
+    if (isPlatformRoot && (await isFile(join(sddPath, SYNDICATED_PLATFORM_L1)))) {
+        return { path: SYNDICATED_PLATFORM_L1, ambiguousDomainL1Count: ambiguous };
+    }
+    return { path: "", ambiguousDomainL1Count: ambiguous };
+}
+async function isFile(path) {
+    try {
+        return (await stat(path)).isFile();
+    }
+    catch (err) {
+        if (err.code === "ENOENT")
+            return false;
+        throw err;
+    }
+}
+//# sourceMappingURL=c4-l1-candidates.js.map

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

@@ -0,0 +1,98 @@
+// C4 L1 systems discoverer — emits at most one `c4_systems.csv` row.
+//
+// Per ADR 0134's federation model, each SDD emits its OWN c4_systems
+// row when its manifest category is architectural. Categories map to
+// the c4_system_kind enum (canonical-schema.yaml):
+//   platform-root        → platform
+//   platform-subsystem   → subsystem   (M-ADR 0170 §4.2 promotion; schema 2.28.0)
+//   application-product  → application
+//   integration-provider → integration
+// Non-architectural categories (integration-umbrella, support-repo) emit
+// zero rows — with a coverage finding, never silently (M-ADR 0133 §4.2c).
+//
+// The id is `{sddId}-system` to match the products row's product_id FK.
+// Description is parsed from the L1 mermaid `System(...)` line when an
+// identity-sourcing L1 exists (M-ADR 0189 §4.5 — own L1, or a unique
+// domain-scoped L1, or the syndicated platform path for the platform root
+// only), otherwise left empty (visible coverage gap) with the name derived
+// from the manifest.
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { resolveIdentityL1 } from "./c4-l1-candidates.js";
+const KIND_BY_CATEGORY = {
+    "platform-root": "platform",
+    "platform-subsystem": "subsystem",
+    "application-product": "application",
+    "integration-provider": "integration",
+};
+// Match `System(id, "name", "description")` — the L1 root-system entry.
+// Permissive about whitespace and the optional description argument.
+const SYSTEM_RE = /^System\s*\(\s*\w+\s*,\s*"([^"]+)"\s*(?:,\s*"([^"]*)")?\s*\)/;
+export async function buildC4Systems(inputs) {
+    const kind = KIND_BY_CATEGORY[inputs.manifest.category];
+    if (kind === undefined) {
+        // Non-architectural (or unmapped) — no system row, but never silently:
+        // a builder returning [] without a finding is indistinguishable from
+        // one that found nothing to return (M-ADR 0133 §4.2c no-silent-drop).
+        inputs.findings.add("coverage", `c4_systems: category '${inputs.manifest.category}' has no system kind; no row emitted`);
+        return [];
+    }
+    const { diagramPath, name, description, ambiguousDomainL1Count } = await findL1(inputs.sddPath, inputs.manifest.category === "platform-root");
+    if (ambiguousDomainL1Count > 0) {
+        inputs.findings.add("convention", `c4_systems: ${ambiguousDomainL1Count} domain-scoped L1 diagrams found for ${inputs.manifest.sddId} — ambiguous, none used as the SDD's L1`);
+    }
+    if (diagramPath === "") {
+        inputs.findings.add("coverage", `c4_systems: no L1 diagram found for ${inputs.manifest.sddId} — diagram_path empty`);
+    }
+    const sddId = inputs.manifest.sddId;
+    return [
+        {
+            id: inputs.manifest.c4SystemId ?? `${sddId}-system`,
+            name: name !== "" ? name : titleCase(sddId),
+            product_id: sddId,
+            kind,
+            diagram_path: diagramPath,
+            description,
+            source_sdd_id: "",
+        },
+    ];
+}
+async function findL1(sddPath, isPlatformRoot) {
+    const resolved = await resolveIdentityL1(sddPath, isPlatformRoot);
+    if (resolved.path === "") {
+        return {
+            diagramPath: "",
+            name: "",
+            description: "",
+            ambiguousDomainL1Count: resolved.ambiguousDomainL1Count,
+        };
+    }
+    const content = await readFile(join(sddPath, resolved.path), "utf-8");
+    const parsed = parseSystemLine(content);
+    return {
+        diagramPath: resolved.path,
+        name: parsed?.name ?? "",
+        description: parsed?.description ?? "",
+        ambiguousDomainL1Count: resolved.ambiguousDomainL1Count,
+    };
+}
+function parseSystemLine(content) {
+    for (const raw of content.split(/\r?\n/)) {
+        const line = raw.trim();
+        if (line.startsWith("System_Ext") || line.startsWith("System_Boundary")) {
+            continue;
+        }
+        const m = SYSTEM_RE.exec(line);
+        if (m) {
+            return { name: m[1] ?? "", description: m[2] ?? "" };
+        }
+    }
+    return null;
+}
+function titleCase(slug) {
+    return slug
+        .split("-")
+        .map((p) => (p.length === 0 ? p : p[0].toUpperCase() + p.slice(1)))
+        .join(" ");
+}
+//# sourceMappingURL=c4-systems.js.map