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

package/dist/lib/catalogue/builders/adr-supersedes.js

@@ -0,0 +1,103 @@
+// adr_supersedes edge builder — emits one row per (superseding, superseded)
+// ADR pair where either side declares the relationship:
+//   - the superseding ADR's `Supersedes:` text references a known ADR id, or
+//   - the superseded ADR's `Superseded By:` text references a known ADR id
+//     (the ADR 0174 §4.5 lazy-migration case: distributed reference ADRs are
+//     adopter-agnostic and cannot name adopter ADR numbers, so only the
+//     superseded local copy carries the link — including the cross-repo
+//     `<repo>#9000` form, whose number resolves locally once the bundle that
+//     ships ADR 9000 is pinned).
+//
+// Only rows where BOTH endpoints resolve to known ADR ids are emitted —
+// the canonical schema's FKs on this edge are required+internal.
+//
+// Also computes the inverse (`superseded_by_id`) backfill values that the
+// orchestrator stitches into adrs.csv after this builder runs.
+const ADR_REF_RE = /\bADR[\s\-_]?(\d{3,4})\b/gi;
+// `Superseded By:` additionally accepts the ADR 0140 cross-repo reference
+// form `<repo>#9000` — the lazy-migration case, where the superseding
+// record lives in a distributed bundle. Procedural citations of the
+// migration rule itself ("per sdd-method#0174 §4.5") are stripped first
+// so they never read as supersession targets.
+const ADR_REF_WITH_HASH_RE = /(?:\bADR[\s\-_]?|#)(\d{3,4})\b/gi;
+const PROCEDURAL_CITATION_RE = /\bper\s+[\w./-]*#\d{3,4}(?:\s*§[\d.]+)?/gi;
+export function buildAdrSupersedes(inputs) {
+    const knownIds = new Set(inputs.adrs.map((a) => a.id));
+    const rows = [];
+    const seen = new Set();
+    const supersededByIndex = new Map();
+    for (const adr of inputs.adrs) {
+        if (adr.supersedesRaw === "")
+            continue;
+        const refs = extractAdrRefs(adr.supersedesRaw);
+        for (const supersededId of refs) {
+            if (supersededId === adr.id)
+                continue; // self-supersession is nonsense
+            if (!knownIds.has(supersededId)) {
+                inputs.findings.add("orphan", `${adr.docPath}: Supersedes references "${supersededId}" but no such ADR exists`);
+                continue;
+            }
+            const id = `${adr.id}__${supersededId}`;
+            if (seen.has(id))
+                continue;
+            seen.add(id);
+            rows.push({
+                id,
+                superseding_adr_id: adr.id,
+                superseded_adr_id: supersededId,
+            });
+            // Last writer wins on the inverse index — multiple superseders for
+            // the same ADR is rare; if it happens we surface a finding.
+            const prior = supersededByIndex.get(supersededId);
+            if (prior !== undefined && prior !== adr.id) {
+                inputs.findings.add("divergence", `ADR ${supersededId} is superseded by both ${prior} and ${adr.id}`);
+            }
+            supersededByIndex.set(supersededId, adr.id);
+        }
+    }
+    // Second pass: edges declared from the superseded side (`Superseded By:`).
+    for (const adr of inputs.adrs) {
+        if (adr.supersededByRaw === "" || /^none$/i.test(adr.supersededByRaw.trim()))
+            continue;
+        const refs = extractAdrRefs(adr.supersededByRaw.replace(PROCEDURAL_CITATION_RE, " "), ADR_REF_WITH_HASH_RE);
+        for (const supersedingId of refs) {
+            if (supersedingId === adr.id)
+                continue;
+            if (!knownIds.has(supersedingId)) {
+                inputs.findings.add("orphan", `${adr.docPath}: Superseded By references "${supersedingId}" but no such ADR exists locally — edge skipped (pin the bundle that ships it, or fix the reference)`);
+                continue;
+            }
+            const id = `${supersedingId}__${adr.id}`;
+            if (seen.has(id))
+                continue; // already declared from the Supersedes side
+            seen.add(id);
+            rows.push({
+                id,
+                superseding_adr_id: supersedingId,
+                superseded_adr_id: adr.id,
+            });
+            const prior = supersededByIndex.get(adr.id);
+            if (prior !== undefined && prior !== supersedingId) {
+                inputs.findings.add("divergence", `ADR ${adr.id} is superseded by both ${prior} and ${supersedingId}`);
+            }
+            supersededByIndex.set(adr.id, supersedingId);
+        }
+    }
+    return { rows, supersededByIndex };
+}
+function extractAdrRefs(raw, re = ADR_REF_RE) {
+    const out = [];
+    let m;
+    // Reset regex state between calls.
+    re.lastIndex = 0;
+    while ((m = re.exec(raw)) !== null) {
+        if (m[1] === undefined)
+            continue;
+        const num = parseInt(m[1], 10);
+        if (!Number.isFinite(num))
+            continue;
+        out.push(`ADR-${String(num).padStart(4, "0")}`);
+    }
+    return out;
+}
+//# sourceMappingURL=adr-supersedes.js.map

package/dist/lib/catalogue/builders/adrs.js

@@ -0,0 +1,222 @@
+// ADR discoverer — emits `adrs.csv` rows from every `adr/*.md` file
+// under `docs/`.
+//
+// Source paths discovered:
+//   - docs/platform/adr/ADR XXXX: Title.md   (platform-scoped)
+//   - docs/method/adr/ADR XXXX: Title.md     (method-scoped → domain_id EMPTY, schema 3.10.0)
+//   - docs/method/platform-adr/ADR XXXX: Title.md  (method-scoped; the frozen
+//     platform-foundational 0001-0099 band per M-ADR 0140)
+//   - docs/domains/<domain>/architecture/adr/ADR XXXX: Title.md
+//
+// Per ADR 0136 the method-scope ADRs are owned by the platform-root in
+// the federation chain (the highest-up SDD that holds them via the seed-
+// file distribution). App and integration profile SDDs skip emission of
+// method-scope ADRs so the aggregated catalogue carries each method ADR
+// exactly once with an unambiguous source_sdd_id.
+//
+// File-content extraction (best-effort, no failure on missing fields):
+//   - **Status:** value
+//   - **Date:** YYYY-MM-DD
+//   - **Supersedes:** raw text (captured into supersedes_raw for the
+//     adr_supersedes builder to parse)
+//
+// ID canonicalisation: filename stem `ADR XXXX[: Title]` → `ADR-{0-padded}`.
+// Title = the portion after the colon when present, else the file stem
+// minus the prefix.
+import { readdir, readFile, stat } from "node:fs/promises";
+import { join, relative, sep } from "node:path";
+import { ORIGIN_PREFIX_SRC } from "../../adr-origin.js";
+const PROFILES_THAT_OWN_METHOD_SCOPE = new Set([
+    "platform-profile",
+]);
+const CATEGORIES_THAT_DO_NOT_OWN_METHOD_SCOPE = new Set([
+    "platform-subsystem",
+]);
+// Dual-resolution (M-ADR 0140 §4.1 / M-ADR 0186): the durable identity is the
+// NUMBER, not the origin prefix. A file named `ADR NNNN` (bare/legacy), or any
+// canonical prefix — `M-ADR`, `RA-ADR`, `P-ADR`, `D-ADR` — all resolve to the
+// same `ADR-NNNN` id. The prefix set is composed from the shared source so a new
+// tier is a one-line change in adr-origin.ts.
+const FILENAME_RE = new RegExp(`^${ORIGIN_PREFIX_SRC}ADR[\\s-]?(\\d{3,4})(?:[:\\s-]+(.*))?$`, "i");
+export async function buildAdrs(inputs) {
+    const docsDir = join(inputs.sddPath, "docs");
+    const files = await collectAdrFiles(docsDir);
+    const seen = new Set();
+    const parsed = [];
+    const ownsMethodScope = PROFILES_THAT_OWN_METHOD_SCOPE.has(inputs.profile) &&
+        !CATEGORIES_THAT_DO_NOT_OWN_METHOD_SCOPE.has(inputs.category ?? "");
+    let methodScopeSkipCount = 0;
+    for (const file of files.sort()) {
+        const stem = baseStem(file);
+        const m = FILENAME_RE.exec(stem);
+        if (!m || m[1] === undefined) {
+            // Template file (e.g. `ADR {0000}: ...`) or non-ADR markdown — skip silently.
+            continue;
+        }
+        const num = parseInt(m[1], 10);
+        if (!Number.isFinite(num))
+            continue;
+        const adrId = `ADR-${String(num).padStart(4, "0")}`;
+        if (seen.has(adrId)) {
+            inputs.findings.add("divergence", `${relative(inputs.sddPath, file)}: ADR id ${adrId} already emitted by an earlier file`);
+            continue;
+        }
+        const relPath = relative(inputs.sddPath, file);
+        const { domainId, scope } = scopeFromPath(relPath);
+        if ((scope === "method" || scope === "platform") && !ownsMethodScope) {
+            // Per ADR 0136: method- and platform-scope ADRs are emitted only by
+            // the SDD that owns the platform scope (platform-profile in
+            // adopting ecosystems). App and integration SDDs hold seed-file
+            // copies on disk but do not contribute them to the federated
+            // catalogue.
+            methodScopeSkipCount++;
+            continue;
+        }
+        seen.add(adrId);
+        const titleFromFilename = (m[2] ?? "").trim() || stem;
+        const text = await readFile(file, "utf-8");
+        const title = extractH1Title(text) || titleFromFilename;
+        const status = extractField(text, "Status") || "Accepted";
+        const decisionDate = extractField(text, "Date") || "";
+        const supersedesRaw = extractField(text, "Supersedes") || "";
+        const supersededByRaw = extractField(text, "Superseded By") || "";
+        if (scope === "domain" && !inputs.knownDomainIds.has(domainId)) {
+            inputs.findings.add("orphan", `${relPath}: ADR is in domain "${domainId}" but no docs/domains/${domainId}/ exists`);
+        }
+        // Method-scoped ADRs are cross-cutting governance and belong to no
+        // domain: domain_id stays EMPTY (schema 3.10.0, M-ADR 0136 §4.3
+        // amendment). The former pin to `platform` resolved only where the
+        // root happened to own a domain of that name and dangled everywhere
+        // else — every method ADR row in a packaged-SaaS root failed FK.
+        parsed.push({
+            id: adrId,
+            title,
+            status,
+            domainId,
+            decisionDate,
+            docPath: relPath,
+            supersedesRaw,
+            supersededByRaw,
+        });
+    }
+    if (methodScopeSkipCount > 0) {
+        inputs.findings.add("coverage", `${methodScopeSkipCount} method/platform-scope ADR(s) skipped — emitted by ecosystem root only per ADR 0136`);
+    }
+    const rows = parsed.map((a) => ({
+        id: a.id,
+        title: a.title,
+        status: a.status,
+        domain_id: a.domainId,
+        decision_date: a.decisionDate,
+        doc_path: a.docPath,
+        superseded_by_id: "", // populated in a backfill pass after adr_supersedes builds
+        inference_confidence: "",
+        supersedes_raw: a.supersedesRaw,
+        source_sdd_id: "",
+    }));
+    return { rows, parsed };
+}
+function baseStem(absPath) {
+    const base = absPath.split(sep).slice(-1)[0] ?? "";
+    return base.replace(/\.md$/i, "");
+}
+function scopeFromPath(relPath) {
+    const parts = relPath.split(sep);
+    const domainsIdx = parts.indexOf("domains");
+    if (domainsIdx !== -1 && domainsIdx + 1 < parts.length) {
+        return { domainId: parts[domainsIdx + 1] ?? "", scope: "domain" };
+    }
+    if (parts.includes("method")) {
+        return { domainId: "", scope: "method" };
+    }
+    return { domainId: "platform", scope: "platform" };
+}
+function extractH1Title(text) {
+    for (const line of text.split(/\r?\n/)) {
+        const t = line.trim();
+        if (t === "")
+            continue;
+        if (!t.startsWith("#"))
+            return "";
+        // `# ADR 0001: Title` → `Title`; otherwise return the heading text.
+        // Accepts any canonical origin prefix (M-/RA-/P-/D-) — dual-resolution.
+        const stripped = t.replace(/^#+\s*/, "").trim();
+        const adrPrefix = new RegExp(`^${ORIGIN_PREFIX_SRC}ADR[\\s-]?\\d+(?:[:\\s-]+(.*))?$`, "i").exec(stripped);
+        if (adrPrefix) {
+            return (adrPrefix[1] ?? "").trim();
+        }
+        return stripped;
+    }
+    return "";
+}
+/**
+ * Extract a value from a metadata bullet of the form:
+ *   * **Field:** value
+ *   - **Field:** value
+ *   **Field:** value
+ * Returns the trimmed value, or empty string if not found.
+ */
+function extractField(text, field) {
+    const re = new RegExp(`^\\s*[*\\-]?\\s*\\*\\*${escapeRegex(field)}:\\*\\*\\s*(.*?)\\s*$`, "im");
+    const m = re.exec(text);
+    if (!m || m[1] === undefined)
+        return "";
+    return m[1].trim();
+}
+function escapeRegex(s) {
+    return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+/**
+ * Directory names that hold ADR files. An EXPLICIT SET, not a pattern.
+ *
+ * `platform-adr` was invisible until 2026-08-06 because this walk tested for a
+ * directory named exactly "adr" — so `docs/method/platform-adr/` was recursed
+ * into and its files were never collected. Measured at discovery: 14 files
+ * present, 0 rows, in EVERY SDD of both reference estates (~1,414 files), while
+ * the directory is bundle payload and its ADRs are cited, superseded and scored
+ * like any other. One estate held 13 assessments of them, which read as orphaned
+ * scores and were nearly withdrawn as ADRs that no longer existed.
+ *
+ * Named rather than matched (`endsWith("adr")`, `/adr$/`) on purpose: a pattern
+ * here would also swallow any future directory an adopter happens to name
+ * `<something>-adr`, and this file has just paid for one loose match.
+ */
+const ADR_DIR_NAMES = new Set(["adr", "platform-adr"]);
+async function collectAdrFiles(docsDir) {
+    const out = [];
+    let entries;
+    try {
+        entries = await readdir(docsDir, { withFileTypes: true });
+    }
+    catch (err) {
+        const code = err.code;
+        if (code === "ENOENT")
+            return [];
+        throw err;
+    }
+    for (const entry of entries) {
+        const full = join(docsDir, entry.name);
+        if (entry.isDirectory()) {
+            if (ADR_DIR_NAMES.has(entry.name)) {
+                // Walk all files in the adr/ directory (no nesting expected).
+                const inner = await readdir(full, { withFileTypes: true });
+                for (const f of inner) {
+                    if (f.isFile() && f.name.endsWith(".md") && !isTemplate(f.name)) {
+                        out.push(join(full, f.name));
+                    }
+                }
+            }
+            else {
+                out.push(...(await collectAdrFiles(full)));
+            }
+        }
+    }
+    return out;
+}
+function isTemplate(filename) {
+    // Excludes template files like `ADR {0000}: {Short, Descriptive Title}.md`.
+    return /[{}]/.test(filename);
+}
+/** Drop-in stat used during testing — unused at runtime but kept exported for symmetry. */
+export const _statForTest = stat;
+//# sourceMappingURL=adrs.js.map

package/dist/lib/catalogue/builders/application-conformance-coverage.js

@@ -0,0 +1,47 @@
+// application_conformance_coverage builder (M-ADR 0191 §4.3 overlay, WS4).
+//
+// Emits one row per conformance tag the product declares about its archetype's
+// conformance expectations: `status=covered` (its suite exercises the tag) or
+// `status=deviated` (deliberately not covered, with a rationale). Built per-SDD
+// from the manifest's `conformance` block so the AGGREGATION-tier conformance
+// gate can read it — the gate itself runs at aggregation, where the reference-
+// architecture bundle's per-archetype `conformance` tags resolve.
+export function buildApplicationConformanceCoverage(inputs) {
+    const { manifest, findings } = inputs;
+    const rows = [];
+    const conformance = manifest.conformance;
+    if (conformance === undefined)
+        return rows;
+    if (manifest.profile !== "application-product") {
+        if ((conformance.coverage?.length ?? 0) > 0 || (conformance.deviations?.length ?? 0) > 0) {
+            findings.add("convention", `application_conformance_coverage: conformance declared on non-application-product SDD "${manifest.sddId}" (profile=${manifest.profile}) — ignored (M-ADR 0191 §4.3 is application-product only)`);
+        }
+        return rows;
+    }
+    const seen = new Set();
+    const emit = (tag, status, rationale) => {
+        const t = tag.trim();
+        if (t === "")
+            return;
+        const id = `${manifest.sddId}__${t}`;
+        if (seen.has(id)) {
+            findings.add("divergence", `application_conformance_coverage: duplicate conformance tag id="${id}" — same (product_id, tag) already emitted; second dropped`);
+            return;
+        }
+        seen.add(id);
+        rows.push({
+            id,
+            product_id: manifest.sddId,
+            tag: t,
+            status,
+            rationale,
+            source_sdd_id: "",
+        });
+    };
+    for (const tag of conformance.coverage ?? [])
+        emit(tag, "covered", "");
+    for (const d of conformance.deviations ?? [])
+        emit(d.tag, "deviated", d.rationale);
+    return rows;
+}
+//# sourceMappingURL=application-conformance-coverage.js.map

package/dist/lib/catalogue/builders/application-data-plane-bindings.js

@@ -0,0 +1,115 @@
+// application_data_plane_bindings builder — emits one row per declared
+// data-plane binding (M-ADR 0193).
+//
+// The data-plane axis models an application-product as a COMPOSITION of typed
+// data bindings, orthogonal to `application_archetype` (0191). Each binding is
+// one `{pattern, locality, transport, runtime, target, notes}` tuple declared
+// in the manifest's `data_plane.bindings` block. The manifest loader has
+// already validated the closed enums and the runtime/locality rules (malformed
+// bindings FAIL at load), so this builder only shapes valid bindings into rows.
+//
+// The `pattern` vocabulary splits by DIRECTION (§4.7): an INBOUND data-sourcing
+// sub-set (retrieve/own-store/stream-ingest/project) and an OUTPUT-side sub-set
+// (generate/publish). Each row carries a derived `direction` column so consumers
+// can branch on the sub-set the ADR declares instead of re-deriving the split.
+//
+// An INBOUND binding whose target is a platform capability/service reconciles
+// with `product_platform_dependencies` (a retrieve@internal binding is a
+// synchronous platform dependency; a stream-ingest@internal binding is the
+// M-ADR 0192 contract_type:event async dependency). OUTPUT-side rows do NOT
+// participate in that reconciliation (§4.7 rule 1) — `publish` is a contract the
+// service PROVIDES, so it has no inbound counterpart to cross-check.
+import { dataPlaneDirection } from "../manifest-loader.js";
+// Recommended transport values (open string per the schema; a value outside the
+// set is a convention finding, never a hard fail — the M-ADR 0156/0192 pattern).
+const RECOMMENDED_TRANSPORTS = new Set([
+    "rest",
+    "graphql",
+    "grpc",
+    "appsync",
+    "kinesis",
+    "kafka",
+    "eventhub",
+    "cdc",
+]);
+export function buildApplicationDataPlaneBindings(inputs) {
+    const { manifest, findings } = inputs;
+    const rows = [];
+    const bindings = manifest.dataPlane?.bindings;
+    if (bindings === undefined || bindings.length === 0)
+        return rows;
+    // data_plane is an application-product-only axis. A binding block on another
+    // profile is a manifest smell — report it and emit nothing.
+    if (manifest.profile !== "application-product") {
+        findings.add("convention", `application_data_plane_bindings: data_plane declared on non-application-product SDD "${manifest.sddId}" (profile=${manifest.profile}) — ignored (M-ADR 0193 is application-product only)`);
+        return rows;
+    }
+    const seen = new Set();
+    for (const b of bindings) {
+        const pattern = b.pattern;
+        const locality = b.locality ?? "";
+        const transport = b.transport ?? "";
+        const runtime = b.runtime ?? "";
+        const target = b.target ?? "";
+        const notes = b.notes ?? "";
+        const id = `${manifest.sddId}__${pattern}__${locality}__${target}`;
+        if (seen.has(id)) {
+            findings.add("divergence", `application_data_plane_bindings: duplicate binding id="${id}" — same (product_id, pattern, locality, target) already emitted; second dropped`);
+            continue;
+        }
+        seen.add(id);
+        if (transport !== "" && !RECOMMENDED_TRANSPORTS.has(transport.toLowerCase())) {
+            findings.add("convention", `application_data_plane_bindings: binding "${id}" declares transport="${transport}" outside the recommended set (${[...RECOMMENDED_TRANSPORTS].join(", ")})`);
+        }
+        rows.push({
+            id,
+            product_id: manifest.sddId,
+            pattern,
+            // Derived from `pattern` (M-ADR 0193 §4.7), not authored — it materialises
+            // the output-side sub-set so consumers can branch on direction (notably
+            // the inbound-only platform-dep reconciliation) without re-deriving the
+            // pattern split. Not a PK component: it adds nothing to identity.
+            direction: dataPlaneDirection(pattern),
+            locality,
+            transport,
+            runtime,
+            target,
+            notes,
+            source_sdd_id: "",
+        });
+    }
+    return rows;
+}
+/**
+ * Emit `application_data_plane_deviations` rows from the manifest's
+ * `data_plane.deviations` block (M-ADR 0191 §4.3). Built per-SDD so the
+ * aggregation-tier overlay WARN can read them; the WARN itself runs at
+ * aggregation, where the reference-architecture `expected_bindings` resolve.
+ */
+export function buildApplicationDataPlaneDeviations(inputs) {
+    const { manifest, findings } = inputs;
+    const rows = [];
+    const deviations = manifest.dataPlane?.deviations;
+    if (deviations === undefined || deviations.length === 0)
+        return rows;
+    if (manifest.profile !== "application-product")
+        return rows;
+    const seen = new Set();
+    for (const d of deviations) {
+        const id = `${manifest.sddId}__${d.expectation}`;
+        if (seen.has(id)) {
+            findings.add("divergence", `application_data_plane_deviations: duplicate deviation id="${id}" — same (product_id, expectation) already emitted; second dropped`);
+            continue;
+        }
+        seen.add(id);
+        rows.push({
+            id,
+            product_id: manifest.sddId,
+            expectation: d.expectation,
+            rationale: d.rationale,
+            source_sdd_id: "",
+        });
+    }
+    return rows;
+}
+//# sourceMappingURL=application-data-plane-bindings.js.map