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

package/dist/lib/conformance/finding.js

@@ -0,0 +1,69 @@
+import { mkdir, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+// Emits the `conformance_finding` catalogue (canonical-schema.yaml, schema 2.25.0) — one summary row per
+// check, so estate-wide drift is queryable (aggregate unions every SDD's conformance_finding.csv and
+// stamps source_sdd_id) and trendable (snapshots are run-dated; diff across commits/runs). The verb is
+// the producer (it needs the *code* repo, which catalogue builders don't see); aggregation federates it.
+// Column order is authoritative — matches the canonical-schema conformance_finding definition.
+//
+// ⚠ It said that while emitting 15 of canon's 16 — `platform_sdd_id` was absent — so a
+// conformance run wrote a file one column short of the schema it claimed to match, and the
+// comment's confidence is why nobody re-checked it. Every other per-SDD catalogue
+// (services, repositories, capabilities) emits the column empty and lets aggregation stamp
+// it, so 15 was never the per-SDD shape. Found by an adopter reading the list because a
+// change to it was proposed; verified against canon and against every conformance_finding
+// on disk in two estates, all 16 columns.
+export const FINDING_COLUMNS = [
+    "id",
+    "check_id",
+    "target",
+    "implementation_repo",
+    "role",
+    "lifecycle",
+    "declared",
+    "observed",
+    "matched",
+    "conformance_pct",
+    "declared_not_observed",
+    "observed_not_declared",
+    "needs_triage",
+    "run_date",
+    "source_sdd_id",
+    "platform_sdd_id",
+];
+function csvCell(v) {
+    const s = String(v);
+    return /[",\n]/.test(s) ? `"${s.replace(/"/g, '""')}"` : s;
+}
+export function findingRows(results, runDate) {
+    const lines = [FINDING_COLUMNS.join(",")];
+    for (const r of results) {
+        const row = {
+            id: r.id,
+            check_id: r.id,
+            target: r.target,
+            implementation_repo: r.implementationRepo ?? "",
+            role: r.role ?? "",
+            lifecycle: r.lifecycle ?? "",
+            declared: r.declared,
+            observed: r.observed,
+            matched: r.matched,
+            conformance_pct: r.conformancePct,
+            declared_not_observed: r.declaredNotObserved.length,
+            observed_not_declared: r.observedNotDeclared.length,
+            needs_triage: r.needsTriage,
+            run_date: runDate,
+            source_sdd_id: "", // populated by the aggregator per ADR 0134
+            platform_sdd_id: "", // stamped at organisation tier per M-ADR 0208
+        };
+        lines.push(FINDING_COLUMNS.map((c) => csvCell(row[c])).join(","));
+    }
+    return lines;
+}
+export async function writeFindings(cataloguesDir, results, runDate) {
+    await mkdir(cataloguesDir, { recursive: true });
+    const path = join(cataloguesDir, "conformance_finding.csv");
+    await writeFile(path, findingRows(results, runDate).join("\n") + "\n", "utf-8");
+    return path;
+}
+//# sourceMappingURL=finding.js.map

package/dist/lib/conformance/index.js

@@ -0,0 +1,578 @@
+import { readFile, readdir } from "node:fs/promises";
+import { existsSync } from "node:fs";
+import { homedir } from "node:os";
+import { isAbsolute, resolve } from "node:path";
+import { parse as parseYaml } from "yaml";
+import { deriveChecksFromBinding, hasBinding, } from "./binding.js";
+import { writeFindings } from "./finding.js";
+// ---------------------------------------------------------------- path + extractors
+function resolveSource(targetRepo, source, codeRoot) {
+    // `@code/...` resolves against --code-root (the checkout root of implementation member repos —
+    // code typically lives in a repo separate from the spec SDD). Absent code-root → unresolved → skip.
+    if (source.startsWith("@code/")) {
+        return codeRoot ? resolve(codeRoot, source.slice("@code/".length)) : "";
+    }
+    const expanded = source.startsWith("~") ? source.replace(/^~/, homedir()) : source;
+    return isAbsolute(expanded) ? expanded : resolve(targetRepo, expanded);
+}
+const markdownProviderSignals = async (path, spec) => {
+    const out = new Set();
+    // `section` (ADR 0180 delta-pilot extension) scopes the scan to one heading block and accepts a plain
+    // "Field" header, so a check can read ONE entity table inside a multi-table data-model doc (e.g.
+    // data-model.mermaid.md "### Collection: feature") without duplicating the field list into a bespoke
+    // surface file. With no `section` the behaviour is byte-for-byte the legacy one (whole file, strict
+    // header, no `*` stripping) — existing gateway bindings are unaffected.
+    const section = spec?.section;
+    // One provider variant uses "Provider Signal"; another uses "Provider Field" — both name the vendor surface col.
+    // Sectioned reads also accept the data-model docs' plain "Field" first column.
+    const headers = spec?.column
+        ? new Set([spec.column])
+        : section
+            ? new Set(["Provider Signal", "Provider Field", "Field"])
+            : new Set(["Provider Signal", "Provider Field"]);
+    let inTable = false;
+    let inSection = !section; // no filter → the whole file counts as in-section
+    for (const raw of (await readFile(path, "utf-8")).split("\n")) {
+        const s = raw.trim();
+        if (section && s.startsWith("#")) {
+            // strip leading #'s and any markdown code/emphasis in the title (`### Collection: ` + "`feature`")
+            inSection = s.replace(/^#+\s*/, "").replace(/[`*]/g, "").includes(section);
+            inTable = false;
+            continue;
+        }
+        if (!s.startsWith("|")) {
+            inTable = false;
+            continue;
+        }
+        if (!inSection)
+            continue;
+        const cells = s.replace(/^\||\|$/g, "").split("|").map((c) => c.trim());
+        const first = cells[0] ?? "";
+        if (first === "" || /^[-: ]+$/.test(first))
+            continue;
+        if (headers.has(first)) {
+            inTable = true;
+            continue;
+        }
+        if (inTable) {
+            let sig = first.replace(/`/g, "").trim();
+            if (section)
+                sig = sig.replace(/\*/g, "").trim(); // strip markdown emphasis around field names
+            if (!sig || sig === "—" || sig.startsWith("Computed") || sig.startsWith("MB "))
+                continue;
+            sig = sig.replace(/\([^)]*\)/g, "").replace(/\[\]/g, "").trim(); // drop inline "(...)" notes + array markers
+            // Range shorthand: `datacoldTemp1..6` / `setpointTemp1..3` -> one declared name per index.
+            const range = sig.match(/^(.*?)(\d+)\.\.(\d+)$/);
+            if (range?.[1] !== undefined) {
+                const base = range[1];
+                for (let i = Number(range[2]); i <= Number(range[3]); i++)
+                    out.add(`${base}${i}`);
+            }
+            else if (sig) {
+                out.add(sig);
+            }
+        }
+    }
+    return out;
+};
+const javaStringConst = async (path) => {
+    const out = new Set();
+    const re = /public\s+static\s+final\s+String\s+\w+\s*=\s*"([^"]+)"/g;
+    const text = await readFile(path, "utf-8");
+    for (const m of text.matchAll(re))
+        if (m[1])
+            out.add(m[1]);
+    return out;
+};
+// Vendor field/signal names expressed as Java DTO fields (`private Double latitude;`) or record
+// components (`Long hrTotalVehicleDistance,`). The per-field DTO shape (e.g. a signal class) some
+// providers use, vs another provider's string-constant class. Targeted at pure data classes/records (DTO files).
+const javaFieldNames = async (path) => {
+    const out = new Set();
+    const text = await readFile(path, "utf-8");
+    // class fields: [modifier] <Type> <name>;  or  [modifier] <Type> <name> = <initialiser>;
+    // (an initialised field — `List<T> x = new ArrayList<>()` — was invisible, so a check could
+    // not tell "not read" from "not seen").
+    for (const m of text.matchAll(/(?:private|protected|public)\s+[\w<>,.?\[\]\s]+?\s+(\w+)\s*[;=]/g)) {
+        if (m[1])
+            out.add(m[1]);
+    }
+    // Lombok: a class annotated @Data/@Getter/@Value generates accessors for package-private fields, which
+    // carry no access modifier. Accept `<Type> <name>;` / `<Type> <name> = …;` at exactly one indentation level
+    // (4 spaces or a tab), where fields sit; a local variable inside a method is deeper and is not read.
+    if (/@(?:Data|Getter|Value)\b/.test(text)) {
+        for (const m of text.matchAll(/^(?: {4}|\t)(?![ \t])(?:final\s+)?(?!return\b|throw\b|new\b)[A-Z][\w<>,.?\[\]\s]*?\s+([a-z]\w*)\s*[;=]/gm)) {
+            if (m[1])
+                out.add(m[1]);
+        }
+    }
+    // record components: <Type> <name>, | <Type> <name>)  (Type uppercase-initial, name lowercase-initial)
+    for (const m of text.matchAll(/\b[A-Z][\w<>.]*\s+([a-z]\w*)\s*[,)]/g)) {
+        if (m[1])
+            out.add(m[1]);
+    }
+    // Wire aliases: @JsonProperty("long") / @SerializedName("...") name the on-the-wire field, which is
+    // what the provider-surface grounding declares — emit it alongside the Java identifier.
+    for (const m of text.matchAll(/@(?:JsonProperty|SerializedName|JsonAlias)\s*\(\s*"([^"]+)"/g)) {
+        if (m[1])
+            out.add(m[1]);
+    }
+    return out;
+};
+const yamlProducedEvents = async (path) => {
+    const out = new Set();
+    const doc = parseYaml(await readFile(path, "utf-8"));
+    for (const p of doc?.events?.produces ?? []) {
+        const schema = p?.schema;
+        if (typeof schema === "string") {
+            const base = schema.split("/").pop() ?? schema;
+            out.add(base.replace(/\.avsc$/, ""));
+        }
+    }
+    return out;
+};
+const tsAvscRefs = async (path) => {
+    const out = new Set();
+    const text = await readFile(path, "utf-8");
+    for (const m of text.matchAll(/([A-Za-z0-9_-]+)\.avsc/g))
+        if (m[1])
+            out.add(m[1]);
+    return out;
+};
+const dirListing = async (path, spec) => {
+    const suffix = spec.suffix ?? "";
+    const entries = await readdir(path);
+    return new Set(entries
+        .filter((f) => f.endsWith(suffix))
+        .map((f) => (suffix ? f.slice(0, -suffix.length) : f)));
+};
+// Split a yaml path on dots outside brackets, so a filter value may itself contain dots.
+function pathParts(p) {
+    const parts = [];
+    let cur = "";
+    let depth = 0;
+    for (const ch of p) {
+        if (ch === "[")
+            depth++;
+        if (ch === "]")
+            depth--;
+        if (ch === "." && depth === 0) {
+            parts.push(cur);
+            cur = "";
+        }
+        else
+            cur += ch;
+    }
+    parts.push(cur);
+    return parts;
+}
+// The nodes at a dotted path. `a.b[].c` walks every element of list `b`; `a.b[k=v].c` walks only the
+// elements whose field `k` equals `v` (compared as strings). A missing path reaches nothing.
+function yamlNodes(doc, path) {
+    const out = [];
+    const walk = (node, parts) => {
+        if (node === undefined || node === null)
+            return;
+        if (parts.length === 0) {
+            out.push(node);
+            return;
+        }
+        const [head, ...rest] = parts;
+        const m = /^(.*?)\[(?:([^=\]]+)=([^\]]*))?\]$/.exec(head);
+        const key = m ? m[1] : head;
+        const next = key === "" ? node : node[key];
+        if (!m)
+            return walk(next, rest);
+        if (!Array.isArray(next))
+            return;
+        for (const el of next) {
+            if (m[2] !== undefined && String(el?.[m[2]] ?? "") !== m[3])
+                continue;
+            walk(el, rest);
+        }
+    };
+    walk(doc, pathParts(path));
+    return out;
+}
+const isScalar = (v) => typeof v === "string" || typeof v === "number" || typeof v === "boolean";
+// yaml-path: scalar values at the given dotted paths of a YAML file (path syntax: yamlNodes).
+// A missing path contributes nothing (the observed side is then what exists).
+const yamlPath = async (path, spec) => {
+    const paths = spec?.paths ?? [];
+    if (paths.length === 0)
+        throw new Error("yaml-path needs `paths:` (one or more dotted paths)");
+    const doc = parseYaml(await readFile(path, "utf-8"));
+    const out = new Set();
+    for (const p of paths)
+        for (const n of yamlNodes(doc, p))
+            if (isScalar(n))
+                out.add(String(n));
+    return out;
+};
+// ---- value maps: both sides emit `key→value` pairs, the fallback as `*→value`, so a declared map and the
+// code that implements it diff like any other value set. Keys and values are normalised alike: numeric
+// literals to decimal (hex, a `L` suffix), quotes dropped, a qualified constant to its last segment.
+const ARROW = "→";
+function mapToken(raw, constants = new Map()) {
+    let t = raw.trim().replace(/^\((.*)\)$/, "$1").trim();
+    t = constants.get(t) ?? t;
+    if (/^-?0[xX][0-9a-fA-F]+[lL]?$/.test(t))
+        return BigInt(t.replace(/[lL]$/, "")).toString();
+    if (/^-?\d+[lL]?$/.test(t))
+        return BigInt(t.replace(/[lL]$/, "")).toString();
+    if (/^"(.*)"$/.test(t) || /^'(.*)'$/.test(t))
+        return t.slice(1, -1);
+    if (/^[A-Za-z_$][\w$]*(\.[A-Za-z_$][\w$]*)+$/.test(t))
+        return t.split(".").pop();
+    return t;
+}
+// yaml-value-map: the map node(s) at `paths:`, read through the key names in `map:`.
+const yamlValueMap = async (path, spec) => {
+    const paths = spec?.paths ?? [];
+    const keys = spec?.map;
+    if (paths.length === 0 || !keys?.cases || !keys.key || !keys.value)
+        throw new Error("yaml-value-map needs `paths:` and `map: {cases, key, value, otherwise?}`");
+    const doc = parseYaml(await readFile(path, "utf-8"));
+    const out = new Set();
+    for (const p of paths) {
+        for (const node of yamlNodes(doc, p)) {
+            if (!node || typeof node !== "object")
+                continue;
+            const rec = node;
+            const cases = rec[keys.cases];
+            if (Array.isArray(cases)) {
+                for (const c of cases) {
+                    const k = c?.[keys.key];
+                    const v = c?.[keys.value];
+                    if (isScalar(k) && isScalar(v))
+                        out.add(`${mapToken(String(k))}${ARROW}${mapToken(String(v))}`);
+                }
+            }
+            const other = keys.otherwise ? rec[keys.otherwise] : undefined;
+            if (isScalar(other))
+                out.add(`*${ARROW}${mapToken(String(other))}`);
+        }
+    }
+    return out;
+};
+// The body of the first method named `name`: from its opening brace to the matching close. Braces inside
+// string and char literals are skipped; comments are stripped first.
+function javaMethodBody(src, name) {
+    const code = src.replace(/\/\*[\s\S]*?\*\//g, "").replace(/\/\/[^\n]*/g, "");
+    const decl = new RegExp(`\\b${name}\\s*\\([^)]*\\)\\s*(?:throws[^{]*)?\\{`).exec(code);
+    if (!decl)
+        return undefined;
+    let i = decl.index + decl[0].length;
+    const start = i;
+    let depth = 1;
+    for (; i < code.length && depth > 0; i++) {
+        const ch = code[i];
+        if (ch === '"' || ch === "'") {
+            for (i++; i < code.length && code[i] !== ch; i++)
+                if (code[i] === "\\")
+                    i++;
+        }
+        else if (ch === "{")
+            depth++;
+        else if (ch === "}")
+            depth--;
+    }
+    return code.slice(start, i - 1);
+}
+// java-value-map: the mapping one method implements. Three shapes, as written in practice:
+//   switch      `case A, B -> X;` · `case A: case B: return X;` · `default -> Y;` / `default: return Y;`
+//   if-chain    `if (v == A) { return X; } else if (v == B) ...` then a final `return Y;`
+//   ternary     `return v == A ? X : v == B ? Z : Y;`
+// A constant named in the method resolves through a `static final` literal in the same file. A method
+// that maps by any other means (a lookup table, arithmetic, a range guard) yields nothing, and the check
+// then reports every declared pair as unobserved rather than passing.
+const javaValueMap = async (path, spec) => {
+    if (!spec?.method)
+        throw new Error("java-value-map needs `method:` (the mapping method's name)");
+    const src = await readFile(path, "utf-8");
+    const body = javaMethodBody(src, spec.method);
+    if (body === undefined)
+        throw new Error(`java-value-map: no method ${spec.method} in ${path}`);
+    const constants = new Map();
+    for (const m of src.matchAll(/\bstatic\s+final\s+[\w<>.]+\s+([A-Za-z_$][\w$]*)\s*=\s*([^;]+);/g))
+        constants.set(m[1], m[2].trim());
+    const tok = (s) => mapToken(s, constants);
+    const out = new Set();
+    const add = (k, v) => out.add(`${k === "*" ? "*" : tok(k)}${ARROW}${tok(v)}`);
+    if (/\bswitch\s*\(/.test(body)) {
+        // The two forms cannot match each other's cases: an arrow label holds no colon, and a colon case
+        // is read only when `return` follows it.
+        for (const m of body.matchAll(/\bcase\s+([^:;]+?)\s*->\s*(?:\{\s*(?:yield|return)\s+)?([^;{}]+?)\s*;/g))
+            for (const k of m[1].split(","))
+                add(k, m[2]);
+        for (const m of body.matchAll(/((?:\bcase\s+[^:]+?\s*:\s*)+)return\s+([^;]+?)\s*;/g))
+            for (const c of m[1].matchAll(/\bcase\s+([^:]+?)\s*:/g))
+                for (const k of c[1].split(","))
+                    add(k, m[2]);
+        const d = /\bdefault\s*(?:->\s*(?:\{\s*(?:yield|return)\s+)?|:\s*return\s+)([^;{}]+?)\s*;/.exec(body);
+        if (d)
+            add("*", d[1]);
+        return out;
+    }
+    const ternary = /\breturn\s+([^;]*\?[^;]*);/.exec(body);
+    if (ternary) {
+        let rest = ternary[1];
+        for (;;) {
+            const m = /^\s*\(?\s*[\w$.]+\s*==\s*([^?]+?)\s*\)?\s*\?\s*([^:]+?)\s*:\s*([\s\S]+)$/.exec(rest);
+            if (!m)
+                break;
+            add(m[1], m[2]);
+            rest = m[3];
+        }
+        if (!/\?/.test(rest))
+            add("*", rest);
+        return out;
+    }
+    const branch = /(?:\belse\s+)?\bif\s*\(\s*[\w$.]+\s*==\s*([^)]+?)\s*\)\s*\{?\s*return\s+([^;]+?)\s*;\s*\}?/g;
+    for (const m of body.matchAll(branch))
+        add(m[1], m[2]);
+    if (out.size > 0) {
+        // The fallback: the first return left once the matched branches are removed (a trailing return, or
+        // an `else { return …; }`).
+        const fb = /\breturn\s+([^;]+?)\s*;/.exec(body.replace(branch, ""));
+        if (fb)
+            add("*", fb[1]);
+    }
+    return out;
+};
+// regex-captures: capture group 1 of every match of `pattern` in one file. Covers setter calls, builder
+// calls, assignments — any accounting a coding style expresses — without one extractor per style.
+const regexCaptures = async (path, spec) => {
+    if (!spec?.pattern)
+        throw new Error("regex-captures needs `pattern:` (a regex with one capture group)");
+    const re = new RegExp(spec.pattern, "gm");
+    const out = new Set();
+    for (const m of (await readFile(path, "utf-8")).matchAll(re))
+        if (m[1])
+            out.add(m[1]);
+    return out;
+};
+const REGISTRY = {
+    "markdown-provider-signals": markdownProviderSignals,
+    "markdown-provider-fields": markdownProviderSignals, // same fn; matches "Provider Signal" | "Provider Field"
+    "java-string-const": javaStringConst,
+    "java-field-names": javaFieldNames,
+    "yaml-produced-events": yamlProducedEvents,
+    "ts-avsc-refs": tsAvscRefs,
+    "dir-listing": dirListing,
+    "yaml-path": yamlPath,
+    "regex-captures": regexCaptures,
+    "yaml-value-map": yamlValueMap,
+    "java-value-map": javaValueMap,
+};
+// ---------------------------------------------------------------- diff core
+function norm(s, mode) {
+    if (mode === "leaf") {
+        // Match a nested/dotted declared path against a leaf code identifier: take the last dotted
+        // segment, drop array markers, then lower-nosep. `statusInfo.truStatus` ~ `truStatus`.
+        const leaf = s.split(".").pop() ?? s;
+        return leaf.replace(/\[\]/g, "").replace(/[-_./ ]/g, "").toLowerCase();
+    }
+    return mode === "lower-nosep" ? s.replace(/[-_./ ]/g, "").toLowerCase() : s;
+}
+function collapsedGroups(values, mode) {
+    const byToken = new Map();
+    for (const v of values) {
+        const k = norm(v, mode);
+        byToken.set(k, [...(byToken.get(k) ?? []), v]);
+    }
+    return [...byToken]
+        .filter(([, vs]) => vs.length > 1)
+        .map(([token, vs]) => ({ token, values: vs.sort() }))
+        .sort((a, b) => a.token.localeCompare(b.token));
+}
+async function extract(targetRepo, codeRoot, spec) {
+    const specs = Array.isArray(spec) ? spec : [spec];
+    const values = new Set();
+    let ok = true;
+    for (const sp of specs) {
+        const fn = REGISTRY[sp.extractor];
+        if (!fn)
+            throw new Error(`unknown extractor: ${sp.extractor}`);
+        const path = sp.source ? resolveSource(targetRepo, sp.source, codeRoot) : "";
+        if (!path || !existsSync(path)) {
+            ok = false;
+            continue;
+        }
+        for (const v of await fn(path, sp))
+            values.add(v);
+    }
+    return { values, ok };
+}
+async function runCheck(targetRepo, codeRoot, chk, member) {
+    const dRes = await extract(targetRepo, codeRoot, chk.declared);
+    const oRes = await extract(targetRepo, codeRoot, chk.observed);
+    if (!dRes.ok || !oRes.ok)
+        return null; // SKIP — a source is absent here
+    const mode = chk.normalise ?? "none";
+    const dMap = new Map([...dRes.values].map((x) => [norm(x, mode), x]));
+    const oMap = new Map([...oRes.values].map((x) => [norm(x, mode), x]));
+    const dCollapsed = collapsedGroups(dRes.values, mode);
+    const oCollapsed = collapsedGroups(oRes.values, mode);
+    const D = new Set(dMap.keys());
+    const O = new Set(oMap.keys());
+    const matched = [...D].filter((k) => O.has(k));
+    const dOnly = [...D].filter((k) => !O.has(k));
+    const oOnly = [...O].filter((k) => !D.has(k));
+    const denom = (chk.denom ?? "union") === "declared" ? D.size : new Set([...D, ...O]).size;
+    return {
+        id: chk.id,
+        target: chk.target,
+        declared: D.size,
+        observed: O.size,
+        matched: matched.length,
+        conformancePct: denom ? Math.round((matched.length / denom) * 100) : 0,
+        denom: chk.denom ?? "union",
+        matchedNames: matched.map((k) => dMap.get(k)).sort(),
+        declaredNotObserved: dOnly.map((k) => dMap.get(k)).sort(),
+        observedNotDeclared: oOnly.map((k) => oMap.get(k)).sort(),
+        candidates: chk.candidates ?? {},
+        needsTriage: dOnly.length > 0 || oOnly.length > 0,
+        ...(dCollapsed.length ? { declaredCollapsed: dCollapsed } : {}),
+        ...(oCollapsed.length ? { observedCollapsed: oCollapsed } : {}),
+        ...(member?.repo ? { implementationRepo: member.repo } : {}),
+        ...(member?.role ? { role: member.role } : {}),
+        ...(member?.lifecycle ? { lifecycle: member.lifecycle } : {}),
+    };
+}
+// ---------------------------------------------------------------- output
+function printHuman(r, out) {
+    out(`\n=== ${r.id}  [${r.target}] ===\n`);
+    // An empty denominator is nothing to measure, not 0% conformance.
+    const denomSize = r.denom === "declared"
+        ? r.declared
+        : r.matched + r.declaredNotObserved.length + r.observedNotDeclared.length;
+    const pct = denomSize === 0 ? `n/a (0/0 — nothing declared or observed)` : `${r.conformancePct}%`;
+    out(`declared=${r.declared}  observed=${r.observed}  matched=${r.matched}  ` +
+        `conformance=${pct} (matched/${r.denom})\n`);
+    if (r.matchedNames.length)
+        out(`  [OK] matched: ${r.matchedNames.join(", ")}\n`);
+    for (const [side, groups] of [["declared", r.declaredCollapsed], ["observed", r.observedCollapsed]]) {
+        if (!groups?.length)
+            continue;
+        const n = groups.reduce((a, g) => a + g.values.length, 0);
+        out(`  [i] ${side} collapsed: ${n} distinct value(s) counted as ${groups.length} token(s) — ` +
+            `a match on a token credits every value in its group:\n`);
+        for (const g of groups)
+            out(`      ${g.token} <- ${g.values.join(", ")}\n`);
+    }
+    if (r.declaredNotObserved.length) {
+        out(`  [!] declared-not-observed (${r.declaredNotObserved.length}) -> NEEDS-TRIAGE ` +
+            `[${r.candidates.declared_only ?? ""}]:\n`);
+        for (const m of r.declaredNotObserved)
+            out(`      - ${m}\n`);
+    }
+    if (r.observedNotDeclared.length) {
+        out(`  [!] observed-not-declared (${r.observedNotDeclared.length}) -> NEEDS-TRIAGE ` +
+            `[${r.candidates.observed_only ?? ""}]:\n`);
+        for (const m of r.observedNotDeclared)
+            out(`      - ${m}\n`);
+    }
+}
+function printReconcile(chk, r, out) {
+    if (!chk.reconcile || r.target !== "binding-vs-reality")
+        return;
+    const rc = chk.reconcile;
+    out(`\n--- reconcile ${r.id} -> regenerate \`${rc.block}\` in ${rc.binding} (ADR 0181 §2.3) ---\n`);
+    out(`# generated from the observed-set (${r.observed} schemas); the binding cannot drift if generated.\n`);
+    if (rc.note)
+        out(`# NOTE: ${rc.note}\n`);
+    const full = [...new Set([...r.matchedNames, ...r.observedNotDeclared])].sort();
+    out(`${rc.block.split(".")[0]}:\n`);
+    out(`  produces:  # ${full.length} schemas (was ${r.declared} declared)\n`);
+    for (const name of full)
+        out(`    - schema: party/events/${name}.avsc\n`);
+    if (r.declaredNotObserved.length) {
+        out(`  # DROP (dangling — no such schema in code/contracts): ${r.declaredNotObserved.join(", ")}\n`);
+    }
+}
+async function planChecks(opts, stdout) {
+    // Resolution order: explicit --config wins; else the ADR 0181 binding (checks derived from it);
+    // else the conventional .sdd/conformance-checks.yaml; else nothing to do.
+    if (!opts.config && hasBinding(opts.targetRepo)) {
+        const derived = await deriveChecksFromBinding(opts.targetRepo);
+        return derived.map((d) => ({ check: d.check, member: d.member }));
+    }
+    const configPath = opts.config
+        ? resolveSource(opts.targetRepo, opts.config, opts.codeRoot)
+        : resolve(opts.targetRepo, ".sdd/conformance-checks.yaml");
+    if (!existsSync(configPath)) {
+        stdout(`[skip] no spec↔implementation binding (.sdd/implementation-binding.yaml or .sdd/implementation-bindings/, ADR 0181) and no ` +
+            `checks file at ${configPath}\n`);
+        return null;
+    }
+    const parsed = parseYaml(await readFile(configPath, "utf-8"));
+    return (parsed?.checks ?? []).map((check) => ({ check }));
+}
+export async function runConformance(opts, stdout = (line) => process.stdout.write(line)) {
+    let planned = await planChecks(opts, stdout);
+    // Under --strict, a run that measured nothing must not pass the gate (empty-set
+    // sweep, R2, ruled 2026-09-29): no binding, a --check filter that matched no
+    // check, or every check SKIPPED all used to exit 0 with no verdict at all.
+    if (planned === null) {
+        if (opts.strict) {
+            stdout(`[FAIL] conformance --strict: 0 checks planned — nothing was measured, which is not a pass\n`);
+            return { exitCode: 1, results: [], skipped: [] };
+        }
+        return { exitCode: 0, results: [], skipped: [] };
+    }
+    const plannedBeforeFilter = planned.length;
+    if (opts.check)
+        planned = planned.filter((p) => p.check.id === opts.check);
+    const results = [];
+    const skipped = [];
+    const reconcileByline = new Map();
+    for (const { check, member } of planned) {
+        const r = await runCheck(opts.targetRepo, opts.codeRoot, check, member);
+        if (r) {
+            results.push(r);
+            reconcileByline.set(r.id, check);
+        }
+        else {
+            skipped.push(check.id);
+        }
+    }
+    if (opts.json) {
+        stdout(JSON.stringify({ checks: results, skipped }, null, 2) + "\n");
+    }
+    else {
+        stdout("Conformance-reverse (advisory; disposition is triage — ADR 0180 §2.3).\n");
+        for (const r of results) {
+            printHuman(r, stdout);
+            if (opts.reconcile) {
+                const chk = reconcileByline.get(r.id);
+                if (chk)
+                    printReconcile(chk, r, stdout);
+            }
+        }
+        for (const id of skipped)
+            stdout(`\n=== ${id} === SKIP (source not found)\n`);
+        if (!opts.strict)
+            stdout("\n--- exit 0 (advisory). Use --strict to gate on un-triaged drift. ---\n");
+    }
+    if (opts.emitFinding) {
+        const runDate = opts.runDate ?? new Date().toISOString().slice(0, 10);
+        const path = await writeFindings(opts.emitFinding, results, runDate);
+        if (!opts.json)
+            stdout(`\n[OK] wrote conformance_finding catalogue: ${path}\n`);
+    }
+    const anyTriage = results.some((r) => r.needsTriage);
+    const noneRan = results.length === 0;
+    if (!opts.json) {
+        const filterNote = opts.check && planned.length === 0
+            ? ` — --check "${opts.check}" matched none of ${plannedBeforeFilter}`
+            : "";
+        stdout(`\n[metric] conformance: ${results.length} of ${planned.length} planned check(s) ran, ` +
+            `${skipped.length} skipped${filterNote}\n`);
+        if (opts.strict && noneRan) {
+            stdout(`[FAIL] conformance --strict: 0 checks ran — nothing was measured, which is not a pass\n`);
+        }
+    }
+    return { exitCode: opts.strict && (anyTriage || noneRan) ? 1 : 0, results, skipped };
+}
+//# sourceMappingURL=index.js.map