@sdd-method/verify-cli 0.1.0

package/dist/lib/catalogue/finding-identity.js

@@ -0,0 +1,183 @@
+/**
+ * Finding IDENTITY — the stable key a findings baseline is compared on, per
+ * M-ADR 0132 §4.3 as amended, delivering the ruling recorded at ledger §3p.
+ *
+ * THE PROBLEM THIS EXISTS FOR, measured rather than asserted. A findings
+ * baseline stores whole `[finding]` lines, so improving a message invalidates
+ * every baselined line carrying it. Wave №6 added a remedy sentence to one
+ * orphan message: 57 baselined lines went inert and 57 replacements arrived
+ * unbaselined, with ZERO genuinely new findings underneath. At the baseline, a
+ * wave that improves wording is indistinguishable from a wave that introduces
+ * 57 new problems. It recurred at wave №11 (9 lines, one estate) because the
+ * class was understood and the mechanism had not changed.
+ *
+ * WHY IDENTITY IS EMITTED AND NOT RECOVERED. The obvious cheaper fix is to let
+ * a comparator extract (category, subject) from stored lines and leave every
+ * estate file untouched. Measured across every baseline in both estates — 86
+ * files, 74 non-empty, 1,677 body lines — that works for 1,434 lines (85.5%)
+ * and fails for 243 (14.5%), which embed their subject in prose:
+ *
+ *   [finding] orphan: repo integration-calamp resolves to no capability ...
+ *
+ * One renderer template, all orphan class, spread across 62 repos. Recovering
+ * identity there means teaching the comparator the renderer's message
+ * templates — which re-couples identity to message text, the exact coupling
+ * this module removes, and fails SILENTLY the next time a template changes.
+ * Identity that was never emitted cannot be reconstructed from prose after the
+ * fact; it has to be emitted where it is known.
+ *
+ * THE RENDERED FORM keeps the identity in the line a human reads, because a
+ * baseline is reviewed by people and a side-channel nobody sees is a side
+ * channel nobody maintains:
+ *
+ *   [finding] orphan (repo:integration-calamp): repo integration-calamp ...
+ *   [finding] divergence (docs/domains/asset/product/x.traceability.yaml): ...
+ *
+ * A finding with no declared subject renders EXACTLY as it does today. That is
+ * deliberate and load-bearing: migration is per-emission-site rather than
+ * flag-day, an unmigrated site is unchanged rather than broken, and the size of
+ * an estate's re-take is proportional to how many sites have actually moved.
+ */
+/**
+ * A subject is `kind:id` where the finding knows the kind (`repo:x`,
+ * `capability:y`), or a repo-relative path where the subject IS a file. Both
+ * are stable under rewording; neither is a sentence.
+ *
+ * Parentheses are the delimiter because no subject may contain one — asserted
+ * below rather than assumed, since a subject that could contain the delimiter
+ * would make the parse ambiguous exactly when it mattered.
+ */
+export function assertRenderableSubject(subject) {
+    if (subject.includes("(") || subject.includes(")")) {
+        throw new Error(`finding subject may not contain parentheses (they delimit the identity): ${subject}`);
+    }
+    if (subject.trim() !== subject || subject === "") {
+        throw new Error(`finding subject must be non-empty and untrimmed-clean: '${subject}'`);
+    }
+}
+export function renderFindingLine(f) {
+    const err = f.severity === "error" ? " [error]" : "";
+    if (f.subject === undefined || f.subject === null) {
+        return `[finding] ${f.category}${err}: ${f.summary}`;
+    }
+    assertRenderableSubject(f.subject);
+    return `[finding] ${f.category}${err} (${f.subject}): ${f.summary}`;
+}
+const EXPLICIT = /^\[finding\] (\w+)(?: \[error\])? \(([^)]+)\): /;
+const LEGACY = /^\[finding\] (\w+)(?: \[error\])?: /;
+/**
+ * Recovers the identity of a stored baseline line.
+ *
+ * Three outcomes, and the third is the one that matters: an explicit identity
+ * is read exactly; a LEGACY line is keyed on its whole summary, which
+ * reproduces today's whole-line behaviour for lines that have not moved yet;
+ * and a line that is not a finding at all returns null.
+ *
+ * Keying a legacy line on its summary is not a silent approximation of
+ * identity — it IS the old contract, kept deliberately so an unmigrated line
+ * behaves exactly as it does now rather than matching something it should not.
+ */
+export function parseFindingLine(line) {
+    const m = EXPLICIT.exec(line);
+    if (m) {
+        return { identity: { category: m[1], subject: m[2] }, explicit: true };
+    }
+    const l = LEGACY.exec(line);
+    if (!l)
+        return null;
+    return {
+        identity: { category: l[1], subject: null },
+        explicit: false,
+    };
+}
+/**
+ * The comparison key. For an explicit identity that is (category, subject); for
+ * a legacy line it falls back to the whole line, preserving current behaviour.
+ */
+export function findingKey(line) {
+    const parsed = parseFindingLine(line);
+    if (!parsed)
+        return `raw\u0000${line}`;
+    if (parsed.identity.subject === null)
+        return `legacy\u0000${line}`;
+    return `id\u0000${parsed.identity.category}\u0000${parsed.identity.subject}`;
+}
+/**
+ * The MIGRATION BRIDGE: a live identity-carrying line with its identity token
+ * removed, which is byte-identical to how that same finding rendered before its
+ * emission site migrated.
+ *
+ * This is not inference. The token is exactly the ` (subject)` this module's own
+ * renderer inserts, and the summary either side of it is untouched — so removing
+ * it reconstructs the previous rendering deterministically, not plausibly.
+ *
+ * WHY IT EXISTS, measured on a real estate: a baseline dominated by findings
+ * from the FIRST migrated emission sites read 629 unbaselined / 380 closed / 0
+ * REWORDED — one closed and one new, which is the exact outcome §9 was written
+ * to prevent. The rewording bucket could not catch it because rewording is
+ * matched between two identity-carrying lines, and a pre-migration baseline has
+ * no identity on its side. The mechanism worked; the migration boundary sat
+ * underneath it, invisible to any estate whose baseline predates emission.
+ */
+export function strippedOfIdentity(line) {
+    const m = EXPLICIT.exec(line);
+    if (!m)
+        return null;
+    return line.replace(` (${m[2]})`, "");
+}
+/**
+ * Compares live findings against a baseline by identity.
+ *
+ * Only gate-acting categories belong in a baseline (M-ADR 0132 §4.3 — `orphan`
+ * and `divergence`); filtering is the caller's, because a comparator that
+ * silently dropped categories would make an empty result ambiguous between
+ * "nothing gate-acting" and "nothing at all".
+ */
+export function compareToBaseline(live, baseline) {
+    const baseByKey = new Map();
+    let legacyKeyed = 0;
+    for (const b of baseline) {
+        const key = findingKey(b);
+        if (key.startsWith("legacy\u0000") || key.startsWith("raw\u0000"))
+            legacyKeyed++;
+        // First occurrence wins; a baseline holding the same identity twice is a
+        // duplicate, and collapsing it here matches what a re-take does anyway.
+        if (!baseByKey.has(key))
+            baseByKey.set(key, b);
+    }
+    const unbaselined = [];
+    const reworded = [];
+    const matched = new Set();
+    let unchanged = 0;
+    for (const l of live) {
+        const key = findingKey(l);
+        let b = baseByKey.get(key);
+        if (b === undefined) {
+            // MIGRATION BRIDGE: before calling a finding new, ask whether this is the
+            // same finding wearing its pre-migration rendering. Exact match on the
+            // stripped form only — never a fuzzy one.
+            const stripped = strippedOfIdentity(l);
+            if (stripped !== null) {
+                const legacyKey = findingKey(stripped);
+                const legacyMatch = baseByKey.get(legacyKey);
+                if (legacyMatch !== undefined) {
+                    matched.add(legacyKey);
+                    reworded.push({ baseline: legacyMatch, live: l });
+                    continue;
+                }
+            }
+            unbaselined.push(l);
+            continue;
+        }
+        matched.add(key);
+        if (b === l)
+            unchanged++;
+        else
+            reworded.push({ baseline: b, live: l });
+    }
+    const stale = [...baseByKey.entries()]
+        .filter(([k]) => !matched.has(k))
+        .map(([, v]) => v);
+    return { unbaselined, stale, reworded, unchanged, legacyKeyed };
+}
+//# sourceMappingURL=finding-identity.js.map

package/dist/lib/catalogue/findings.js

@@ -0,0 +1,46 @@
+/**
+ * Findings collector for the canonical builder per ADR 0134 / builder-spec
+ * §"Emit findings as it parses".
+ *
+ * Findings are human-readable AND machine-parseable. Format per finding:
+ *   [finding] {category}: {one-line summary}
+ *
+ * Categories are an open set; the canonical catalogue is in the builder
+ * spec. This module hardcodes the well-known ones for type safety; new
+ * categories may be passed as freeform strings if they emerge.
+ */
+import { renderFindingLine } from "./finding-identity.js";
+export class FindingsLog {
+    findings = [];
+    add(category, summary, severity = "warn", subject) {
+        // Spread rather than an explicit `subject: undefined`, which
+        // exactOptionalPropertyTypes rejects — an absent subject and a subject
+        // whose value is undefined are different things here, and the type is
+        // right to insist on the distinction.
+        this.findings.push({
+            category,
+            summary,
+            severity,
+            ...(subject === undefined ? {} : { subject }),
+        });
+    }
+    /** Returns a copy of recorded findings, in insertion order. */
+    all() {
+        return [...this.findings];
+    }
+    /** Count findings, optionally filtered to a single category. */
+    count(category) {
+        if (category === undefined)
+            return this.findings.length;
+        return this.findings.filter((f) => f.category === category).length;
+    }
+    /** Count error-severity findings (these fail the build by default). */
+    errorCount() {
+        return this.findings.filter((f) => f.severity === "error").length;
+    }
+    /** Render every finding as a stdout line. Error-severity findings are marked. */
+    render() {
+        return this.findings.map((f) => renderFindingLine(f)).join("\n");
+    }
+}
+//# sourceMappingURL=findings.js.map

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

@@ -0,0 +1,136 @@
+/**
+ * FK validator per ADR 0134 builder-spec §"Run internal FK validation
+ * before exiting" + §"External FK handling".
+ *
+ * For each catalogue's foreign keys:
+ *   - Internal FKs (external=false): every non-empty value MUST resolve
+ *     to a primary-key in the referenced catalogue's emitted rows. Missing
+ *     resolution is a hard failure.
+ *   - External FKs (external=true, or external for the build's profile via
+ *     `externalForProfiles` — schema 2.23.0): every non-empty value is logged
+ *     as a `[finding] external` line and skipped from validation. The
+ *     aggregator resolves these post-merge per ADR 0134 §4.5. A required
+ *     (non-nullable) external FK still fails when EMPTY — the value must be
+ *     named even if it resolves cross-SDD.
+ *
+ * Returns a structured result; the caller decides exit code + reporting.
+ *
+ * POST-CUTOVER ROLE (M-ADR 0205 §4.4, A4): no production path calls this
+ * module — validate/build/aggregate run the engine path. It remains as the
+ * reference side of the standing differential (parity-harness.ts and the
+ * estate sweep driver), so implementation drift between the two gets
+ * caught by the suite instead of lurking.
+ */
+/** The stamp column M-ADR 0208 §4.4 keys on. */
+export const PLATFORM_STAMP_COLUMN = "platform_sdd_id";
+/**
+ * Whether the FK `cat.fk → targetCat` resolves under the platform-scoped
+ * key (see FkValidationOptions.platformScopedTargets). One definition,
+ * shared with the query generator so the two paths cannot drift.
+ */
+export function isPlatformScopedFk(cat, targetCat, options) {
+    if (!(options.platformScopedTargets ?? []).includes(targetCat.name))
+        return false;
+    const has = (c) => c.columns.some((col) => col.name === PLATFORM_STAMP_COLUMN);
+    return has(cat) && has(targetCat);
+}
+/**
+ * Build an in-memory map of every catalogue's primary-key set, then walk
+ * every row's FK columns and check resolution.
+ */
+export function validateForeignKeys(schema, rowsByCatalogue, findings, options = {}) {
+    // Index primary keys per catalogue, and — for platform-scoped targets —
+    // the set of stamps each pk is present under ('' for an unstamped row).
+    const pkIndex = new Map();
+    const stampIndex = new Map();
+    const catByName = new Map(schema.catalogues.map((c) => [c.name, c]));
+    for (const cat of schema.catalogues) {
+        const rows = rowsByCatalogue.get(cat.name) ?? [];
+        const pks = new Set();
+        const stamps = new Map();
+        for (const row of rows) {
+            const pk = row[cat.primaryKey];
+            if (pk !== undefined && pk !== null && pk !== "") {
+                pks.add(String(pk));
+                const stamp = String(row[PLATFORM_STAMP_COLUMN] ?? "");
+                const set = stamps.get(String(pk)) ?? new Set();
+                set.add(stamp);
+                stamps.set(String(pk), set);
+            }
+        }
+        pkIndex.set(cat.name, pks);
+        stampIndex.set(cat.name, stamps);
+    }
+    const failures = [];
+    let externalCount = 0;
+    for (const cat of schema.catalogues) {
+        const rows = rowsByCatalogue.get(cat.name) ?? [];
+        for (const fk of cat.foreignKeys) {
+            // Effective-external (2.23.0): declared external OR external for the
+            // profile under build. Governs the resolution skip only — the
+            // required-empty check below stays keyed on the DECLARED `external` so
+            // a profile-external FK still requires a (cross-SDD) value to be named.
+            const effectiveExternal = fk.external ||
+                (options.profile !== undefined &&
+                    (fk.externalForProfiles ?? []).includes(options.profile));
+            const [targetCat, targetCol] = fk.references.split(".");
+            if (!targetCat || !targetCol) {
+                throw new Error(`malformed FK reference "${fk.references}" on ${cat.name}.${fk.column}`);
+            }
+            const targetPks = pkIndex.get(targetCat);
+            const targetDef = catByName.get(targetCat);
+            if (!targetPks || !targetDef) {
+                throw new Error(`FK ${cat.name}.${fk.column} references unknown catalogue "${targetCat}"`);
+            }
+            const scoped = isPlatformScopedFk(cat, targetDef, options);
+            const targetStamps = stampIndex.get(targetCat);
+            for (const row of rows) {
+                const raw = row[fk.column];
+                if (raw === undefined || raw === null || raw === "") {
+                    if (!fk.nullable && !fk.external) {
+                        // Required FK with no value — internal violation regardless of external flag.
+                        failures.push({
+                            catalogue: cat.name,
+                            column: fk.column,
+                            referencingRow: String(row[cat.primaryKey] ?? ""),
+                            value: "",
+                            target: fk.references,
+                        });
+                    }
+                    continue;
+                }
+                const value = String(raw);
+                let resolved = targetPks.has(value);
+                if (resolved && scoped) {
+                    const mine = String(row[PLATFORM_STAMP_COLUMN] ?? "");
+                    const theirs = targetStamps.get(value) ?? new Set();
+                    resolved = mine === "" || theirs.has("") || theirs.has(mine);
+                }
+                if (effectiveExternal && !options.treatExternalAsInternal) {
+                    if (!resolved) {
+                        // Per spec: optimistically resolve against own rows; only log when unresolved.
+                        externalCount++;
+                        findings.add("external", `${cat.name}.${fk.column} → ${fk.references}=${value} ` +
+                            `(referencing row pk=${row[cat.primaryKey] ?? "?"}; resolves at aggregation)`);
+                    }
+                    continue;
+                }
+                if (!resolved) {
+                    failures.push({
+                        catalogue: cat.name,
+                        column: fk.column,
+                        referencingRow: String(row[cat.primaryKey] ?? ""),
+                        value,
+                        target: fk.references,
+                    });
+                }
+            }
+        }
+    }
+    return {
+        internalPass: failures.length === 0,
+        internalFailures: failures,
+        externalFindings: externalCount,
+    };
+}
+//# sourceMappingURL=fk-validator.js.map