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

package/dist/lib/catalogue/dedupe-keyed-tables.js

@@ -0,0 +1,100 @@
+/**
+ * Metamodel-driven primary-key normalisation for the per-SDD build.
+ *
+ * Every catalogue declares a `primary_key` in the canonical schema. The build
+ * collects each catalogue's rows from one or more per-source walkers and
+ * concatenates them (see `build.ts` `collectRows`). For most catalogues each
+ * walker emits PK-unique rows or dedupes internally, but **edge tables fed by
+ * more than one source** (`feature_service`, `feature_repo` — from the
+ * feature-grounding *and* capability-spec walkers) can legitimately have the
+ * same fact asserted by both sources. Each walker's own `seen…` guard only
+ * dedupes intra-walker, so the concatenated result carried duplicate PKs into
+ * `catalogues/*.csv`, which `catalogue aggregate` then correctly rejected.
+ *
+ * This pass makes keyed-table emission **set-correct over the declared PK** for
+ * every catalogue, by construction:
+ *   - identical rows for the same PK → keep one (silent union — the same fact
+ *     asserted by ≥2 sources is not an error);
+ *   - same PK with a **differing** payload → a hard conflict the caller fails
+ *     the build on, with provenance, so this class of defect surfaces at
+ *     `build` (where the offending SDD is unambiguous) instead of only at
+ *     `aggregate`.
+ *
+ * Background: the method's coordination record feature-edge-cross-source-duplicate.
+ * Sibling precedents (the unconditional-emit fixes whose per-walker dedup this
+ * generalises across sources): `feature-grounding-collision-edges-coordination.md`
+ * (0.30.2) and `capability-spec-collision-edges-coordination.md` (0.30.3).
+ */
+/**
+ * Render a cell exactly as the CSV writer will, so two rows count as identical
+ * iff they would serialise to the same CSV line. Kept in lock-step with
+ * `csv-writer.ts` `formatCell` (null/undefined and "" collapse to the same
+ * empty cell; booleans normalise to "true"/"false").
+ */
+function cell(value) {
+    if (value === null || value === undefined)
+        return "";
+    if (typeof value === "boolean")
+        return (value ? "true" : "false");
+    return String(value);
+}
+/** Signature over the schema-declared columns — the row's rendered identity. */
+function rowSignature(row, columns) {
+    // NUL separator can't appear in a rendered cell, so it's an unambiguous join.
+    return columns.map((c) => cell(row[c])).join("\u0000");
+}
+/**
+ * Normalise every keyed catalogue in `rowsByCatalogue` to PK-unique rows.
+ * Mutates the map in place (replacing only catalogues that actually had
+ * exact-duplicate PKs) and returns the conflicts + union count.
+ *
+ * First-seen row wins for ordering; the CSV writer re-sorts by PK anyway, so
+ * order here is immaterial beyond determinism.
+ */
+export function dedupeKeyedTables(schema, rowsByCatalogue, findings) {
+    const conflicts = [];
+    let unionedRows = 0;
+    for (const cat of schema.catalogues) {
+        const rows = rowsByCatalogue.get(cat.name) ?? [];
+        if (rows.length < 2)
+            continue;
+        const columns = cat.columns.map((c) => c.name);
+        const pk = cat.primaryKey;
+        const seen = new Map(); // PK value → row signature
+        const deduped = [];
+        let changed = false;
+        for (const row of rows) {
+            const pkRaw = row[pk];
+            // Rows with no PK value can't be set-keyed — keep verbatim and let FK
+            // validation surface the empty key (mirrors the aggregate dup-check,
+            // which also skips empty PKs).
+            if (pkRaw === undefined || pkRaw === null || pkRaw === "") {
+                deduped.push(row);
+                continue;
+            }
+            const value = String(pkRaw);
+            const sig = rowSignature(row, columns);
+            const existingSig = seen.get(value);
+            if (existingSig === undefined) {
+                seen.set(value, sig);
+                deduped.push(row);
+                continue;
+            }
+            changed = true;
+            if (existingSig === sig) {
+                // Same PK, identical payload — the same fact asserted by another
+                // source. Silent union: drop the duplicate.
+                unionedRows += 1;
+                continue;
+            }
+            // Same PK, differing payload — a genuine data-integrity conflict.
+            conflicts.push({ catalogue: cat.name, primaryKey: pk, value });
+            findings.add("divergence", `${cat.name}: primary key ${pk}="${value}" emitted with conflicting ` +
+                `payloads by multiple build sources — cannot union (fix the source data)`);
+        }
+        if (changed)
+            rowsByCatalogue.set(cat.name, deduped);
+    }
+    return { conflicts, unionedRows };
+}
+//# sourceMappingURL=dedupe-keyed-tables.js.map

package/dist/lib/catalogue/engine-validator.js

@@ -0,0 +1,239 @@
+/**
+ * Engine-path FK/PK/enum validation — M-ADR 0205 §4.4 (Phase A2).
+ *
+ * Runs the ddl-generator's queries on the embedded engine and returns
+ * results in the SAME shapes as fk-validator.ts / enum-validator.ts, so
+ * the parity harness can compare count AND list, field for field. The
+ * input is the same rowsByCatalogue map the in-memory validators take:
+ * A2 compares the two VALIDATION implementations on identical parsed
+ * input — CSV-read equivalence is deliberately out of this comparison's
+ * scope and belongs to the cutover evaluation.
+ *
+ * The engine package is a devDependency until cutover (M-ADR 0205 §4.1's
+ * no-fallback rule governs how it eventually ships). It is imported
+ * dynamically inside the entry function so merely loading this module
+ * never requires it: no production path imports the engine today, and an
+ * adopter install without the package only fails if something actually
+ * calls it — loudly.
+ *
+ * PK-duplicate detection has NO in-memory counterpart at validate time
+ * (builders dedupe at emission instead), so pkDuplicates is engine-only
+ * information: reported, never part of the parity claim — you cannot
+ * claim agreement with an instrument that does not exist.
+ */
+import { generateConstraintQueries, generateExternalFindingQueries, generateTableDdl, sqlType, } from "./ddl-generator.js";
+const INSERT_CHUNK = 500;
+function sqlStringLiteral(value) {
+    return `'${value.replace(/'/g, "''")}'`;
+}
+/**
+ * One loaded engine: schema DDL applied, every provided catalogue's rows
+ * inserted. Shared by the FK/PK/enum path and the coverage predicates so
+ * there is exactly one load semantics to reason about.
+ */
+export async function createEngineSession(schema, rowsByCatalogue) {
+    const { DuckDBInstance } = await import("@duckdb/node-api");
+    const instance = await DuckDBInstance.create(":memory:");
+    const conn = await instance.connect();
+    for (const ddl of generateTableDdl(schema)) {
+        await conn.run(ddl);
+    }
+    await loadRows(conn, schema, rowsByCatalogue);
+    return { conn, dispose: () => conn.disconnectSync() };
+}
+// @rule engine-fk-validation
+export async function validateWithEngine(schema, rowsByCatalogue, options = {}) {
+    const session = await createEngineSession(schema, rowsByCatalogue);
+    const conn = session.conn;
+    try {
+        const typeNonconformances = await findTypeNonconformances(conn, schema, rowsByCatalogue);
+        const failures = [];
+        const enumViolations = [];
+        const pkDuplicates = [];
+        for (const q of generateConstraintQueries(schema, options)) {
+            const reader = await conn.runAndReadAll(q.sql);
+            for (const row of reader.getRows()) {
+                if (q.kind === "fk") {
+                    failures.push({
+                        catalogue: q.catalogue,
+                        column: q.column,
+                        referencingRow: String(row[0] ?? ""),
+                        value: String(row[1] ?? ""),
+                        target: q.target,
+                    });
+                }
+                else if (q.kind === "enum") {
+                    const enumDef = schema.enums[q.target];
+                    enumViolations.push({
+                        catalogue: q.catalogue,
+                        column: q.column,
+                        rowPk: row[0] === null || row[0] === undefined ? "<no-pk>" : String(row[0]),
+                        value: String(row[1] ?? ""),
+                        allowed: enumDef.values.map((v) => v.value).join(" | "),
+                    });
+                }
+                else {
+                    pkDuplicates.push({
+                        catalogue: q.catalogue,
+                        rowPk: String(row[0] ?? ""),
+                        count: Number(row[1]),
+                    });
+                }
+            }
+        }
+        const externalFindingDetails = [];
+        for (const q of generateExternalFindingQueries(schema, options)) {
+            const reader = await conn.runAndReadAll(q.sql);
+            for (const row of reader.getRows()) {
+                externalFindingDetails.push({
+                    catalogue: q.catalogue,
+                    column: q.column,
+                    target: q.target,
+                    rowPk: row[0] === null || row[0] === undefined ? "?" : String(row[0]),
+                    value: String(row[1] ?? ""),
+                });
+            }
+        }
+        return {
+            fk: {
+                internalPass: failures.length === 0,
+                internalFailures: failures,
+                externalFindings: externalFindingDetails.length,
+            },
+            enums: { pass: enumViolations.length === 0, violations: enumViolations },
+            externalFindingDetails,
+            pkDuplicates,
+            typeNonconformances,
+        };
+    }
+    finally {
+        session.dispose();
+    }
+}
+/**
+ * The A4 cutover surface: runs the engine validation and writes findings
+ * into the caller's FindingsLog with BYTE-IDENTICAL text to what
+ * fk-validator.ts / enum-validator.ts wrote — adopters' committed
+ * findings baselines hold those literal lines, so the text is a
+ * compatibility contract, not a style choice. Line ORDER within a
+ * category follows the engine's total ORDER BY (M-ADR 0205 §4.2) and may
+ * differ from the old file-order rendering; baselines compare by
+ * membership, so ordering is free — declared in the change-set anyway.
+ */
+export async function validateWithEngineToLog(schema, rowsByCatalogue, findings, options = {}, extras = {}) {
+    const logEnumFindings = extras.logEnumFindings !== false;
+    const res = await validateWithEngine(schema, rowsByCatalogue, options);
+    for (const d of res.externalFindingDetails) {
+        findings.add("external", `${d.catalogue}.${d.column} → ${d.target}=${d.value} ` +
+            `(referencing row pk=${d.rowPk}; resolves at aggregation)`);
+    }
+    if (logEnumFindings) {
+        const enumNameByCatalogueColumn = new Map();
+        for (const cat of schema.catalogues) {
+            for (const [column, enumRef] of Object.entries(cat.columnEnums)) {
+                enumNameByCatalogueColumn.set(`${cat.name}.${column}`, enumRef.replace(/^enums\./, ""));
+            }
+        }
+        for (const v of res.enums.violations) {
+            const enumName = enumNameByCatalogueColumn.get(`${v.catalogue}.${v.column}`);
+            findings.add("divergence", `${v.catalogue}.${v.column}: row ${v.rowPk} value "${v.value}" is outside the bound enum ${enumName} (${v.allowed})`, "error");
+        }
+    }
+    return { fk: res.fk, enums: res.enums };
+}
+async function loadRows(conn, schema, rowsByCatalogue) {
+    for (const cat of schema.catalogues) {
+        const rows = rowsByCatalogue.get(cat.name) ?? [];
+        if (rows.length === 0)
+            continue;
+        for (let i = 0; i < rows.length; i += INSERT_CHUNK) {
+            const chunk = rows.slice(i, i + INSERT_CHUNK);
+            const tuples = chunk
+                .map((row) => `(${cat.columns
+                .map((c) => literal(row[c.name], cat.name, c.name, c.type))
+                .join(", ")})`)
+                .join(",\n");
+            await conn.run(`INSERT INTO "${cat.name}" VALUES\n${tuples};`);
+        }
+    }
+}
+/**
+ * Renders one cell. String columns keep the empty string AS an empty
+ * string — the in-memory validators' emptiness predicates see '' from the
+ * CSV reader, and the generated queries test both NULL and ''. Non-string
+ * columns TRY_CAST with '' becoming NULL: one uncastable cell must not
+ * abort a whole run (measured on a real estate: a prose value in a
+ * date-typed column), and the miss is not smoothed either —
+ * findTypeNonconformances re-derives every such cell with the engine's
+ * own cast semantics and reports it.
+ */
+function literal(value, catalogue, column, type) {
+    const s = value === null || value === undefined ? "" : String(value);
+    if (type === "string")
+        return sqlStringLiteral(s);
+    if (s === "")
+        return "NULL";
+    return `TRY_CAST(${sqlStringLiteral(s)} AS ${sqlType(catalogue, column, type)})`;
+}
+/**
+ * Exact engine-semantics detection of the cells TRY_CAST nulled: the
+ * distinct non-empty values of every typed column are re-checked with the
+ * SAME cast the load used — a JS re-implementation of the engine's parsers
+ * would be a second opinion pretending to be the first.
+ */
+async function findTypeNonconformances(conn, schema, rowsByCatalogue) {
+    const out = [];
+    for (const cat of schema.catalogues) {
+        const rows = rowsByCatalogue.get(cat.name) ?? [];
+        if (rows.length === 0)
+            continue;
+        for (const col of cat.columns) {
+            if (col.type === "string")
+                continue;
+            const counts = new Map();
+            for (const row of rows) {
+                const v = row[col.name];
+                const s = v === null || v === undefined ? "" : String(v);
+                if (s === "")
+                    continue;
+                counts.set(s, (counts.get(s) ?? 0) + 1);
+            }
+            if (counts.size === 0)
+                continue;
+            const engineType = sqlType(cat.name, col.name, col.type);
+            const values = [...counts.keys()].sort();
+            const tuples = values.map((v) => `(${sqlStringLiteral(v)})`).join(", ");
+            const reader = await conn.runAndReadAll(`SELECT v FROM (VALUES ${tuples}) t(v) ` +
+                `WHERE TRY_CAST(v AS ${engineType}) IS NULL ORDER BY v;`);
+            for (const row of reader.getRows()) {
+                const value = String(row[0]);
+                out.push({
+                    catalogue: cat.name,
+                    column: col.name,
+                    declaredType: col.type,
+                    value,
+                    rows: counts.get(value) ?? 0,
+                });
+            }
+        }
+    }
+    return out;
+}
+/**
+ * The population a PASS was measured over, for the verdict line. An FK or enum
+ * PASS over zero rows is true of nothing (empty-set sweep, R2): the count makes
+ * the zero visible. The `PASS` token itself is kept for anything that greps it.
+ */
+export function validatedPopulation(rowsByCatalogue) {
+    let rows = 0;
+    let nonEmpty = 0;
+    for (const r of rowsByCatalogue.values()) {
+        rows += r.length;
+        if (r.length > 0)
+            nonEmpty += 1;
+    }
+    return rows === 0
+        ? "0 rows — nothing was validated"
+        : `${rows} row(s) across ${nonEmpty} non-empty catalogue(s)`;
+}
+//# sourceMappingURL=engine-validator.js.map

package/dist/lib/catalogue/ext-id.js

@@ -0,0 +1,76 @@
+// External-system row identity (schema 3.0.0) and the legacy-id migration
+// map — M-ADR 0203 §4.2, completing M-ADR 0189 §4.2.
+//
+// From 3.0.0 a `c4_external_systems` row id derives from the DECLARED
+// diagram entry id (`System_Ext(<entry-id>, …)`), not from a slug of the
+// display name. The declared id is the identity the aggregator resolves
+// (M-ADR 0189 §4.2); keying the row on anything else meant the row's own
+// PK was label-keyed evidence — the exact identity class 0189 measured
+// false-positiving at 14 of 15.
+//
+// The 2.x name-slug ids remain derivable from data every 2.30.0+ catalogue
+// carries (`name`), so the old→new map is a build artefact, not an authored
+// migration: `sdd-cli catalogue migration-map` emits it, and the exemption
+// loader consults it during the cut window (an authored exemption keyed by
+// a mapped old id is regenerable, NOT drift — the F30 rule at schema scale).
+/**
+ * Normalise a declared diagram entry id to slug form. Camel humps split
+ * BEFORE lowercasing (the F11a rule, matching the aggregator's resolver):
+ * most SDD ids are hyphenated, and `bvfmGatewayFramework` must derive the
+ * same identity the adjudicator resolves for it (`bvfm-gateway-framework`).
+ */
+export function normaliseEntryId(entryId) {
+    return entryId
+        .replace(/([a-z0-9])([A-Z])/g, "$1-$2")
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-+|-+$/g, "");
+}
+/** The 3.0.0 row id for a declared diagram entry id, or "" when the entry id normalises to nothing. */
+export function extIdFromEntryId(entryId) {
+    const slug = normaliseEntryId(entryId);
+    return slug === "" ? "" : `ext-${slug}`;
+}
+/**
+ * The 2.x row id for a display name — the pre-3.0.0 derivation, kept
+ * VERBATIM (including the parenthetical strip) so the migration map
+ * reproduces exactly the ids the old builder minted.
+ */
+export function legacyExtIdFromName(name) {
+    const slug = name
+        .toLowerCase()
+        .replace(/\s*\([^)]+\)/g, "")
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-+|-+$/g, "");
+    return slug === "" ? "" : `ext-${slug}`;
+}
+/**
+ * legacy (2.x, name-derived) id → the 3.0.0 ids it maps to, from built
+ * rows. Usually one; MORE than one means two distinct declared identities
+ * shared a display-name slug and were wrongly merged as one row under 2.x
+ * — the map surfaces the split rather than guessing (the consumer decides,
+ * loudly).
+ */
+export function buildLegacyExtIdMap(rows) {
+    const map = new Map();
+    for (const row of rows) {
+        const legacy = legacyExtIdFromName(String(row["name"] ?? ""));
+        if (legacy === "")
+            continue;
+        const current = String(row["id"] ?? "");
+        if (current === "" || legacy === current)
+            continue;
+        const ids = map.get(legacy);
+        if (ids) {
+            if (!ids.includes(current))
+                ids.push(current);
+        }
+        else {
+            map.set(legacy, [current]);
+        }
+    }
+    for (const ids of map.values())
+        ids.sort((a, b) => a.localeCompare(b));
+    return map;
+}
+//# sourceMappingURL=ext-id.js.map

package/dist/lib/catalogue/feature-grounding-aliases-loader.js

@@ -0,0 +1,65 @@
+/**
+ * Loader for the optional `.sdd/feature-grounding-aliases.yaml` config
+ * per ADR 0143 (schema 2.5.0).
+ *
+ * Adopters use this map to translate display names in
+ * `feature-grounding.md` tables (class names, file basenames, route
+ * fragments) into canonical service / repo ids that resolve against
+ * `services.csv` and `repositories.csv`. Follows the same shape
+ * convention as the existing capability_service alias map.
+ *
+ * File shape:
+ *
+ *     service_aliases:
+ *       AuthHandler: example-service-api
+ *       web-ui: example-web-ui
+ *     repo_aliases:
+ *       camera-bff: global-camera-bff
+ *
+ * Either block is optional. Empty / missing file = no aliases (every
+ * reference must resolve directly against the canonical id).
+ */
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { parse as parseYaml } from "yaml";
+const ALIASES_FILENAME = join(".sdd", "feature-grounding-aliases.yaml");
+/**
+ * Load the optional alias map. Returns `null` when the file is absent
+ * — callers treat that as "no aliases, all references must resolve
+ * directly against the canonical id." Throws on malformed YAML.
+ */
+export async function loadFeatureGroundingAliases(sddPath) {
+    const full = join(sddPath, ALIASES_FILENAME);
+    let text;
+    try {
+        text = await readFile(full, "utf-8");
+    }
+    catch (err) {
+        const code = err.code;
+        if (code === "ENOENT")
+            return null;
+        throw err;
+    }
+    const raw = parseYaml(text);
+    if (raw === null || typeof raw !== "object") {
+        throw new Error(`${ALIASES_FILENAME}: expected a mapping at the document root`);
+    }
+    return {
+        serviceAliases: toStringMap(raw.service_aliases),
+        repoAliases: toStringMap(raw.repo_aliases),
+        relPath: ALIASES_FILENAME,
+    };
+}
+function toStringMap(raw) {
+    const out = new Map();
+    if (raw === null || raw === undefined)
+        return out;
+    if (typeof raw !== "object" || Array.isArray(raw))
+        return out;
+    for (const [k, v] of Object.entries(raw)) {
+        if (typeof v === "string" && v !== "")
+            out.set(k, v);
+    }
+    return out;
+}
+//# sourceMappingURL=feature-grounding-aliases-loader.js.map

package/dist/lib/catalogue/feature-repo-zero-resolution-summary.js

@@ -0,0 +1,31 @@
+/**
+ * feature_repo zero-resolution SUMMARY line (M-ADR 0143 §4.4), split against
+ * the final feature_repo table.
+ *
+ * A builder (feature-grounding: Evidence cell; capability-spec:
+ * Implementation cell) fires one per-row finding for every feature row whose
+ * cell is non-empty but resolves to zero repos. That measures the CELL. The
+ * feature may still be anchored by another surface — feature-tree
+ * `## Feature Services`, feature-spec, or the feature_service ⋈
+ * service_repo derivation — and only the build, holding the final
+ * feature_repo, can say so. The summary therefore states both numbers:
+ * how many rows fired, and how many of those fired on features that no
+ * surface anchors.
+ *
+ * Returns null when nothing fired: an absent line is the designed shape
+ * for zero (the per-row lines are absent too), and this keeps the finding
+ * surface identical to pre-1.20.2 in that case.
+ */
+export function zeroResolutionSummary(cellLabel, evidenceRows, firedFeatureIds, anchoredFeatures) {
+    if (firedFeatureIds.length === 0)
+        return null;
+    const distinctFired = new Set(firedFeatureIds);
+    const unanchoredFeatures = new Set([...distinctFired].filter((fid) => !anchoredFeatures.has(fid)));
+    const unanchoredRows = firedFeatureIds.filter((fid) => unanchoredFeatures.has(fid)).length;
+    const anchoredElsewhere = distinctFired.size - unanchoredFeatures.size;
+    return (`feature_repo: ${firedFeatureIds.length} of ${evidenceRows} feature rows with a non-empty ${cellLabel} cell resolved to zero repos, ` +
+        `of which ${unanchoredRows} on ${unanchoredFeatures.size} feature(s) with no anchor from ANY surface in the final feature_repo ` +
+        `(${anchoredElsewhere} of the ${distinctFired.size} named features are anchored by another surface — those rows are cell quality, not coverage) ` +
+        `(member tier; evidence→repo resolution coverage only — a resolved row is not thereby correct; M-ADR 0143 §4.4)`);
+}
+//# sourceMappingURL=feature-repo-zero-resolution-summary.js.map