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

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

@@ -0,0 +1,402 @@
+// Contracts discoverer — emits `contracts.csv` rows from
+// `contracts/{openapi,proto,avro}/<domain>/<name>.<ext>` (canonical) and
+// `docs/domains/<domain>/contracts/{openapi,proto,avro}/<name>.<ext>`
+// (platform-profile per reverse/workflows/contract.md).
+//
+// Per the canonical schema (catalogue-schema.yaml):
+//   - kind enum: rest | graphql | rpc | event
+//     - openapi/*.yaml → rest
+//     - proto/*.proto  → rpc
+//     - avro/*.avsc    → event
+//   - service_id and source_repo_id are nullable; per ADR 0110 the real
+//     contract sources may live in sibling contracts-* repos. The
+//     canonical builder leaves these empty by default; an OpenAPI
+//     `x-source-repo` extension is honoured as a hint when present
+//     (resolved against the known repository set).
+//   - For OpenAPI files only, `info.title` becomes `description`,
+//     `info.version` becomes `version`. Other formats keep these empty.
+import { readdir, readFile } from "node:fs/promises";
+import { extname, join, relative, sep } from "node:path";
+import { parse as parseYaml } from "yaml";
+import { contractIdWithKind } from "../contract-id.js";
+const CONTRACTS_DIR_REL = "contracts";
+const DOCS_DOMAINS_DIR_REL = join("docs", "domains");
+const KIND_SPECS = [
+    { subdir: "openapi", extensions: [".yaml", ".yml"], kind: "rest" },
+    { subdir: "proto", extensions: [".proto"], kind: "rpc" },
+    { subdir: "avro", extensions: [".avsc"], kind: "event" },
+    // `authz` — authorization/policy schemas (SpiceDB `.zed` and equivalents).
+    //
+    // Added because an adopter's contract lock-in gate APPROVED two `.zed` schemas
+    // as contracts ("all 11 contracts lock"), while `kind` had no member able to
+    // represent them — so the catalogue could not hold an artefact the method's own
+    // gate had certified. That gate had already recorded the tension itself, passing
+    // SpiceDB "with-waiver on rubric-fit grounds"; this closes the same gap one
+    // layer down.
+    //
+    // Zero-delta when added: no estate holds an in-repo `contracts/spicedb/` tree,
+    // so this discovers nothing today and exists so that a declared or migrated
+    // authz schema HAS a kind rather than being silently unrepresentable.
+    { subdir: "spicedb", extensions: [".zed"], kind: "authz" },
+    // `graphql` — GraphQL SDL. Added last of the five, and the reason it was last is
+    // the finding: `graphql` had been a member of the `kind` enum since the enum
+    // existed, while NO code path could ever produce it. Not discovered here, not
+    // mapped from a manifest key, not extracted by the loader, not walked by the
+    // validator, and not offered by the template. **A vocabulary member unreachable
+    // by construction** — the same class as a rubric anchor no artefact can satisfy,
+    // and it stayed invisible for the same reason: an unreachable value is emitted
+    // for nothing and so never complains.
+    //
+    // NOT zero-delta, unlike spicedb: the reverse estate already holds 7 `.graphql`
+    // files under the conventional `docs/domains/<domain>/contracts/graphql/` layout
+    // (vehicle 5, applications 2), invisible to the catalogue until now. An author
+    // whose GraphQL surface could not be keyed documented the wall in their own
+    // manifest — naming the schema lines that blocked them — and wrote the only
+    // token left in `contracts.status`.
+    { subdir: "graphql", extensions: [".graphql", ".graphqls"], kind: "graphql" },
+];
+export async function buildContracts(inputs) {
+    const rows = [];
+    const idByPath = new Map();
+    const seen = new Set();
+    // Contract deprecation source (schema 2.22.0): BASELINE.md deprecation-
+    // runway entries per ADR 0073 §4.8 — the same source
+    // validate-deprecation-runway.sh enforces. Absent file = no deprecations.
+    const deprecatedPaths = await readBaselineDeprecations(inputs.sddPath, inputs.findings);
+    const discovered = [];
+    // Layout 1: canonical SDD-root layout — contracts/<subdir>/<domain>/<file>.<ext>.
+    for (const spec of KIND_SPECS) {
+        const dir = join(inputs.sddPath, CONTRACTS_DIR_REL, spec.subdir);
+        const files = await collectFiles(dir, spec.extensions);
+        for (const path of files) {
+            const rel = relative(inputs.sddPath, path);
+            discovered.push({
+                absPath: path,
+                relPath: rel,
+                domain: domainSegmentCanonical(rel),
+                kind: spec.kind,
+            });
+        }
+    }
+    // Layout 2: platform-profile layout — docs/domains/<domain>/contracts/<subdir>/<file>.<ext>.
+    // Canonical for platform-profile SDDs per reverse/workflows/contract.md and
+    // reverse/workflow.md §3 ("docs/domains/{domain}/contracts/openapi/*.yaml ←
+    // refresh API surfaces"). Federated SDDs without docs/domains/ harmlessly
+    // contribute zero rows.
+    const domainsRoot = join(inputs.sddPath, DOCS_DOMAINS_DIR_REL);
+    const domainDirs = await listDirs(domainsRoot);
+    for (const domainName of domainDirs) {
+        for (const spec of KIND_SPECS) {
+            const dir = join(domainsRoot, domainName, CONTRACTS_DIR_REL, spec.subdir);
+            const files = await collectFiles(dir, spec.extensions);
+            for (const path of files) {
+                const rel = relative(inputs.sddPath, path);
+                discovered.push({
+                    absPath: path,
+                    relPath: rel,
+                    domain: domainName,
+                    kind: spec.kind,
+                });
+            }
+        }
+    }
+    discovered.sort((a, b) => a.relPath.localeCompare(b.relPath));
+    for (const entry of discovered) {
+        const filename = basenameOf(entry.absPath);
+        // Skip schema/config files at any depth.
+        if (filename === "schema.yaml" || filename === "schema.yml")
+            continue;
+        const stem = stemOf(filename);
+        // Schema 3.0.0 (M-ADR 0203 §4.4): the id carries its kind component,
+        // so one service published as two contract families (openapi + proto)
+        // mints two rows instead of colliding — the measured 2.x standing cost
+        // this format exists to end. A remaining collision is same-kind and
+        // still reported.
+        const kindless = entry.domain !== ""
+            ? slugify(`${entry.domain}-${stem}`)
+            : slugify(stem);
+        const slug = contractIdWithKind(kindless, entry.kind);
+        if (seen.has(slug)) {
+            inputs.findings.add("divergence", `${entry.relPath}: contract id "${slug}" already emitted by an earlier file`);
+            continue;
+        }
+        seen.add(slug);
+        let description = "";
+        let version = "";
+        let sourceRepoId = "";
+        let context = "";
+        let evidenceClass = "";
+        if (entry.kind === "rest") {
+            const meta = await tryReadOpenapiInfo(entry.absPath);
+            description = meta.description;
+            version = meta.version;
+            context = meta.context;
+            evidenceClass = meta.evidenceClass;
+            if (meta.xSourceRepo !== "" && inputs.knownRepositoryIds.has(meta.xSourceRepo)) {
+                sourceRepoId = meta.xSourceRepo;
+            }
+        }
+        const normalisedRelPath = entry.relPath.split(sep).join("/");
+        rows.push({
+            id: slug,
+            name: stem,
+            service_id: "",
+            source_repo_id: sourceRepoId,
+            kind: entry.kind,
+            version,
+            status: deprecatedPaths.has(normalisedRelPath) ? "deprecated" : "active",
+            spec_path: entry.relPath,
+            visibility: "internal",
+            context,
+            evidence_class: evidenceClass,
+            description,
+            discovery: "discovered",
+            source_sdd_id: "",
+        });
+        idByPath.set(entry.relPath, slug);
+    }
+    // A deprecated BASELINE.md entry that matched no discovered spec is doc
+    // drift (path typo, file moved, or already removed) — surface it; the
+    // runway gate enforces file existence separately.
+    const emittedPaths = new Set(rows.map((r) => String(r["spec_path"]).split(sep).join("/")));
+    for (const path of deprecatedPaths) {
+        if (!emittedPaths.has(path)) {
+            inputs.findings.add("divergence", `contracts: BASELINE.md deprecates "${path}" but no discovered contract spec matches that path`);
+        }
+    }
+    return { rows, idByPath };
+}
+/**
+ * Read deprecated contract paths from BASELINE.md at the SDD root.
+ *
+ * Shape per ADR 0073 §4.8 (the deprecation-runway gate's source):
+ *   contracts:
+ *     openapi: [ { path, status, sunset_date? }, ... ]
+ *     proto:   [ ... ]
+ *     avro:    [ ... ]
+ *
+ * Returns the set of `path` values (forward-slash, SDD-root-relative) whose
+ * status is "deprecated". Missing file → empty set (pre-go-live SDDs have no
+ * BASELINE.md). Unparseable file → empty set with a divergence finding.
+ */
+async function readBaselineDeprecations(sddPath, findings) {
+    const baselinePath = join(sddPath, "BASELINE.md");
+    let text;
+    try {
+        text = await readFile(baselinePath, "utf-8");
+    }
+    catch (err) {
+        const code = err.code;
+        if (code === "ENOENT")
+            return new Set();
+        throw err;
+    }
+    let raw;
+    try {
+        raw = parseYaml(text);
+    }
+    catch {
+        findings.add("divergence", `contracts: BASELINE.md exists but is not parseable YAML — contract deprecation statuses not wired`);
+        return new Set();
+    }
+    const deprecated = new Set();
+    const contracts = raw?.["contracts"];
+    if (!contracts || typeof contracts !== "object")
+        return deprecated;
+    for (const typeKey of ["openapi", "proto", "avro"]) {
+        const entries = contracts[typeKey];
+        if (!Array.isArray(entries))
+            continue;
+        for (const entry of entries) {
+            if (!entry || typeof entry !== "object")
+                continue;
+            const e = entry;
+            if (String(e["status"] ?? "") !== "deprecated")
+                continue;
+            const path = String(e["path"] ?? "").trim();
+            if (path !== "")
+                deprecated.add(path);
+        }
+    }
+    return deprecated;
+}
+async function listDirs(parent) {
+    try {
+        const entries = await readdir(parent, { withFileTypes: true });
+        return entries.filter((e) => e.isDirectory()).map((e) => e.name);
+    }
+    catch (err) {
+        const code = err.code;
+        if (code === "ENOENT")
+            return [];
+        throw err;
+    }
+}
+async function tryReadOpenapiInfo(path) {
+    try {
+        const text = await readFile(path, "utf-8");
+        const raw = parseYaml(text);
+        if (!raw || typeof raw !== "object") {
+            return { description: "", version: "", xSourceRepo: "", context: "", evidenceClass: "" };
+        }
+        const info = raw["info"];
+        const xSourceRepo = String(raw["x-source-repo"] ?? "").trim();
+        // `x-context` may sit on info (preferred) or at the document root.
+        const contextRaw = info?.["x-context"] ?? raw["x-context"];
+        const context = typeof contextRaw === "string" ? contextRaw.trim() : "";
+        // `x-evidence-class` mirrors x-context: info (preferred), document root fallback.
+        const evidenceRaw = info?.["x-evidence-class"] ?? raw["x-evidence-class"];
+        const evidenceClass = typeof evidenceRaw === "string" ? evidenceRaw.trim() : "";
+        const versionRaw = info?.["version"];
+        const descRaw = info?.["description"];
+        const description = typeof descRaw === "string"
+            ? firstSentence(descRaw)
+            : "";
+        const version = typeof versionRaw === "string"
+            ? versionRaw
+            : versionRaw !== undefined
+                ? String(versionRaw)
+                : "";
+        return { description, version, xSourceRepo, context, evidenceClass };
+    }
+    catch {
+        // Not all *.yaml files in contracts/openapi/ are full specs (some are
+        // shared component fragments). Failing to parse is not an error here.
+        return { description: "", version: "", xSourceRepo: "", context: "", evidenceClass: "" };
+    }
+}
+function firstSentence(s) {
+    // Take up to the first paragraph break, capped at 500 chars.
+    const para = s.split(/\r?\n\r?\n/)[0] ?? "";
+    return para.replace(/\s+/g, " ").trim().slice(0, 500);
+}
+async function collectFiles(dir, extensions) {
+    const out = [];
+    let entries;
+    try {
+        entries = await readdir(dir, { withFileTypes: true });
+    }
+    catch (err) {
+        const code = err.code;
+        if (code === "ENOENT")
+            return [];
+        throw err;
+    }
+    for (const entry of entries) {
+        const full = join(dir, entry.name);
+        if (entry.isDirectory()) {
+            out.push(...(await collectFiles(full, extensions)));
+        }
+        else if (entry.isFile() && extensions.includes(extname(entry.name).toLowerCase())) {
+            out.push(full);
+        }
+    }
+    return out;
+}
+function basenameOf(absPath) {
+    return absPath.split(sep).slice(-1)[0] ?? "";
+}
+function stemOf(filename) {
+    return filename.replace(/\.[^.]+$/, "");
+}
+function domainSegmentCanonical(relPath) {
+    // Canonical layout: contracts/<subdir>/<domain>/<file>.<ext>
+    // → parts = ["contracts", subdir, domain, file]
+    const parts = relPath.split(sep);
+    if (parts.length < 4)
+        return "";
+    return parts[2] ?? "";
+}
+function slugify(s) {
+    return s
+        .toLowerCase()
+        .replace(/^_+/, "") // turn _common into common
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-+|-+$/g, "");
+}
+const DECLARED_KINDS = {
+    openapi: "rest",
+    proto: "rpc",
+    avro: "event",
+    spicedb: "authz",
+    graphql: "graphql",
+};
+export function buildDeclaredExternalContracts(inputs) {
+    const rows = [];
+    const idByPath = new Map();
+    const emitted = new Set(inputs.existingIds);
+    // Every declared path processed so far — WINNERS AND LOSERS BOTH. A
+    // re-declaration of a path already processed is two capabilities citing
+    // one contract: a no-op whatever the first outcome was (row emitted, or
+    // collision already reported once). The first fix registered only paths
+    // that EMITTED, so a path that LOST a slug collision was never recorded
+    // and re-collided afresh in every manifest citing it — measured: the one
+    // genuine collision reported twice, once per citing manifest. A finding
+    // is a fact about the contract, not about each reader of it.
+    const seenDeclaredPaths = new Set();
+    const localBasenames = new Set([...inputs.discoveredIdByPath.keys()].map((p) => basenameOf(p.split("/").join(sep))));
+    for (const m of inputs.manifests) {
+        if (!m.contracts)
+            continue;
+        for (const [blockKey, entries] of Object.entries(m.contracts)) {
+            const kind = DECLARED_KINDS[blockKey];
+            if (kind === undefined || !Array.isArray(entries))
+                continue;
+            for (const raw of entries) {
+                // Only an OBJECT entry carrying `external: true` qualifies. A bare
+                // string is the pre-D13 form and must keep its existing behaviour
+                // (resolve locally, or drop with a finding) — otherwise every
+                // unresolvable typo in a contracts_root estate becomes a row.
+                if (raw === null || typeof raw !== "object" || Array.isArray(raw))
+                    continue;
+                const entry = raw;
+                if (entry["external"] !== true)
+                    continue;
+                const declared = String(entry["path"] ?? "").replace(/^\/+/, "");
+                if (declared === "")
+                    continue;
+                const base = basenameOf(declared.split("/").join(sep));
+                // If it resolves locally it is not external — the discovered row wins
+                // and carries real parsed metadata.
+                if (inputs.discoveredIdByPath.has(declared) || localBasenames.has(base))
+                    continue;
+                const stem = stemOf(base);
+                const kindless = m.domain !== "" ? slugify(`${m.domain}-${stem}`) : slugify(stem);
+                const slug = contractIdWithKind(kindless, kind);
+                if (seenDeclaredPaths.has(declared)) {
+                    // Same path, same contract: legitimate cross-capability sharing.
+                    // Whatever happened on first sight (row, or collision reported)
+                    // already happened once; a second citation adds no information.
+                    continue;
+                }
+                seenDeclaredPaths.add(declared);
+                if (emitted.has(slug)) {
+                    inputs.findings.add("divergence", `${m.relPath}: declared-external contract id "${slug}" (${declared}) already emitted — `
+                        + `a same-kind collision (the cross-family collision class ended at schema 3.0.0, `
+                        + `M-ADR 0203 §4.4); row dropped`);
+                    continue;
+                }
+                emitted.add(slug);
+                idByPath.set(declared, slug);
+                rows.push({
+                    id: slug,
+                    name: stem,
+                    service_id: "",
+                    source_repo_id: "",
+                    kind,
+                    version: "",
+                    status: "active",
+                    spec_path: declared,
+                    visibility: "",
+                    context: "",
+                    evidence_class: "",
+                    description: "",
+                    discovery: "declared-external",
+                    source_sdd_id: "",
+                });
+            }
+        }
+    }
+    return { rows, idByPath };
+}
+//# sourceMappingURL=contracts.js.map