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

package/dist/lib/catalogue/builders/service-capability-exemption.js

@@ -0,0 +1,63 @@
+// service_capability_exemption builder — M-ADR 0133 §4.2b.
+//
+// Emits one row per repo-config declaring a `service_capability_exemption:` block:
+//
+//   service_capability_exemption:
+//     reason: platform-internal   # closed vocabulary, see canonical-schema.yaml
+//     note: "Internal ops dashboard; serves the platform, not a product capability."
+//
+// One tier down from `repo_capability_exemption` (M-ADR 0188 §4.3), for the same
+// reason that table exists: M-ADR 0197 gave a repository a `services:` block, so a
+// repository resolving under M-ADR 0188 no longer implies its services do. This
+// keys on the repo's own DEFAULT/PRIMARY service id — a declared, non-primary
+// `services:` entry has no per-entry authoring surface yet (M-ADR 0197 §4.7,
+// design-only) and cannot be exempted through this block. That is a stated scope
+// limit, not a silent one: an exemption block on a repo whose primary service id
+// doesn't resolve is dropped with a finding, never guessed onto a different entry.
+//
+// VALIDATION ORDER MIRRORS repo-capability-exemption.ts. Every rejection below
+// drops the exemption row and leaves the service unresolved — reported by
+// check-service-capability-coverage.sh's tier-scoped verdict. It never drops the
+// service. Fail open on the row; fail closed on the service.
+export function buildServiceCapabilityExemption(inputs) {
+    const rows = [];
+    const seen = new Set();
+    for (const cfg of inputs.configs) {
+        const block = cfg.data.service_capability_exemption;
+        if (block === undefined || block === null)
+            continue;
+        const reason = typeof block.reason === "string" ? block.reason.trim() : "";
+        const note = typeof block.note === "string" ? block.note.trim() : "";
+        if (reason === "") {
+            inputs.findings.add("convention", `${cfg.relPath}: service_capability_exemption declares no reason — exemption dropped, service stays unresolved (per M-ADR 0133 §4.2b)`);
+            continue;
+        }
+        if (!inputs.allowedReasons.has(reason)) {
+            const allowed = [...inputs.allowedReasons].sort().join(", ");
+            inputs.findings.add("convention", `${cfg.relPath}: service_capability_exemption reason "${reason}" is outside the closed vocabulary (${allowed}) — exemption dropped, service stays unresolved (per M-ADR 0133 §4.2b)`);
+            continue;
+        }
+        if (note === "") {
+            inputs.findings.add("convention", `${cfg.relPath}: service_capability_exemption (${reason}) has an empty note — exemption dropped, service stays unresolved (per M-ADR 0133 §4.2b)`);
+            continue;
+        }
+        // Keyed to the repo's own default/primary service id. A repo whose
+        // `services:` block dropped that id entirely (declared entries only) has
+        // no service for this block to attach to yet — a stated scope limit
+        // (M-ADR 0197 §4.7), not a guess at which declared entry is "really" this
+        // one.
+        if (!inputs.knownServiceIds.has(cfg.repoId)) {
+            inputs.findings.add("orphan", `${cfg.relPath}: service_capability_exemption declared but "${cfg.repoId}" does not resolve to a known service — exemption dropped. A repo whose services: block dropped its own default id has no per-entry authoring surface for this yet (M-ADR 0197 §4.7)`);
+            continue;
+        }
+        const id = cfg.repoId;
+        if (seen.has(id)) {
+            inputs.findings.add("divergence", `${cfg.relPath}: duplicate service_capability_exemption for service ${id} — first declaration wins`);
+            continue;
+        }
+        seen.add(id);
+        rows.push({ id, service_id: id, reason, note });
+    }
+    return rows;
+}
+//# sourceMappingURL=service-capability-exemption.js.map

package/dist/lib/catalogue/builders/service-contract-consumes.js

@@ -0,0 +1,186 @@
+// service_contract consumes edges — emits one row per (service,
+// contract, consumes) triple derived from each service's
+// `repos/<service>/docs/service-architecture.md` External Interfaces
+// table (Outbound rows).
+//
+// Resolution path:
+//   1. Read the External Interfaces section of the service-architecture
+//      markdown. Pipe-delimited table; Direction column = "Outbound"
+//      (case-insensitive).
+//   2. For each Outbound row, lookup the Interface column text against
+//      the adopter's `.sdd/service-contract-aliases.yaml` (interface_aliases
+//      exact match, then interface_contains substring) to get a target
+//      contract id.
+//   3. Fall back to same_product_inference: if the interface matches a
+//      generic placeholder (e.g. "Private API Gateway"), substitute
+//      `{prefix}` with the caller's prefix (service_id minus known
+//      suffix). The resolved value is also a contract id.
+//   4. Targets are contract IDs (not names). The schema marks both
+//      service_contract.{service_id,contract_id} as `external: true`
+//      (schema 2.8.0) — federated SDDs that lack a local services.csv +
+//      contracts.csv emit consumes rows whose FKs resolve at aggregation;
+//      the platform-root SDD validates internally first per the fk-validator
+//      optimistic-resolve rule.
+//
+// Pattern documented in sdd-method ADR 0147.
+import { readFile, readdir } from "node:fs/promises";
+import { join } from "node:path";
+const REPOS_DIR_REL = "repos";
+const SERVICE_ARCHITECTURE_REL = join("docs", "service-architecture.md");
+const KNOWN_SUFFIXES = ["-api", "-bff", "-ui", "-consumer", "-web", "-service"];
+export async function buildServiceContractConsumes(inputs) {
+    const rows = [];
+    const seen = new Set();
+    if (inputs.aliases === null)
+        return rows;
+    const useKnownGate = inputs.knownServiceIds.size > 0;
+    const repoNames = await listRepoDirs(join(inputs.sddPath, REPOS_DIR_REL));
+    for (const serviceId of repoNames) {
+        if (useKnownGate && !inputs.knownServiceIds.has(serviceId))
+            continue;
+        if (inputs.aliases.skipCallers.has(serviceId))
+            continue;
+        const archPath = join(inputs.sddPath, REPOS_DIR_REL, serviceId, SERVICE_ARCHITECTURE_REL);
+        let text;
+        try {
+            text = await readFile(archPath, "utf-8");
+        }
+        catch (err) {
+            const code = err.code;
+            if (code === "ENOENT")
+                continue;
+            throw err;
+        }
+        const outbound = parseOutboundInterfaces(text);
+        for (const iface of outbound) {
+            let contractId = resolveContractId(serviceId, iface.interfaceText, inputs.aliases);
+            if (contractId === null)
+                continue;
+            const mapped = inputs.legacyContractIdMap?.get(contractId);
+            if (mapped !== undefined && mapped.length === 1) {
+                inputs.findings.add("inferred", `service_contract: alias target "${contractId}" (${serviceId} ← "${iface.interfaceText}") re-keyed to ` +
+                    `"${mapped[0]}" — 2.x kindless contract id migrated per the 3.0.0 map (regenerable, not drift); ` +
+                    `update .sdd/service-contract-aliases.yaml to retire this finding`);
+                contractId = mapped[0];
+            }
+            else if (mapped !== undefined && mapped.length > 1) {
+                inputs.findings.add("convention", `service_contract: alias target "${contractId}" (${serviceId} ← "${iface.interfaceText}") maps to ` +
+                    `${mapped.length} contracts at 3.0.0 [${mapped.join(", ")}] — a 2.x cross-family collision; ` +
+                    `qualify the alias with the kind-suffixed id; edge dropped`);
+                continue;
+            }
+            const id = `${serviceId}__${contractId}__consumes`;
+            if (seen.has(id))
+                continue;
+            seen.add(id);
+            rows.push({
+                id,
+                service_id: serviceId,
+                contract_id: contractId,
+                role: "consumes",
+            });
+        }
+    }
+    return rows;
+}
+function resolveContractId(callerServiceId, interfaceText, aliases) {
+    const key = interfaceText.toLowerCase().trim();
+    // 1. Direct (exact) alias → contract id.
+    const direct = aliases.interfaceAliases.get(key);
+    if (direct !== undefined)
+        return direct;
+    // 2. Substring (contains) alias — longest-first.
+    for (const [substr, target] of aliases.interfaceContains) {
+        if (key.includes(substr))
+            return target;
+    }
+    // 3. Same-product template inference.
+    const template = aliases.sameProductTemplates.get(key);
+    if (template !== undefined) {
+        const prefix = derivePrefix(callerServiceId);
+        return template.replace(/\{prefix\}/g, prefix);
+    }
+    return null;
+}
+function derivePrefix(serviceId) {
+    for (const suffix of KNOWN_SUFFIXES) {
+        if (serviceId.endsWith(suffix)) {
+            return serviceId.slice(0, -suffix.length);
+        }
+    }
+    return serviceId;
+}
+export function parseOutboundInterfaces(markdown) {
+    const out = [];
+    const sectionRegex = /^##\s+External Interfaces\s*$/im;
+    const match = sectionRegex.exec(markdown);
+    if (match === null)
+        return out;
+    // Slice from end of heading to start of next ## heading (or EOF).
+    const rest = markdown.slice(match.index + match[0].length);
+    const nextHeading = /^##\s+/m.exec(rest);
+    const section = nextHeading !== null ? rest.slice(0, nextHeading.index) : rest;
+    const lines = section.split(/\r?\n/);
+    let headerSeen = false;
+    let dividerSeen = false;
+    let cols = null;
+    for (const raw of lines) {
+        const line = raw.trim();
+        if (line === "" || !line.startsWith("|")) {
+            if (headerSeen)
+                break;
+            continue;
+        }
+        const cells = splitRow(line);
+        if (!headerSeen) {
+            const interfaceIdx = cells.findIndex((c) => c.toLowerCase() === "interface");
+            const directionIdx = cells.findIndex((c) => c.toLowerCase() === "direction");
+            if (interfaceIdx === -1 || directionIdx === -1)
+                continue;
+            cols = { iface: interfaceIdx, direction: directionIdx };
+            headerSeen = true;
+            continue;
+        }
+        if (!dividerSeen) {
+            // Divider row: cells of dashes (e.g. "---")
+            if (cells.every((c) => /^:?-+:?$/.test(c.trim()))) {
+                dividerSeen = true;
+                continue;
+            }
+            // Some authors omit dividers — accept and fall through.
+            dividerSeen = true;
+        }
+        if (cols === null)
+            continue;
+        const direction = (cells[cols.direction] ?? "").trim().toLowerCase();
+        if (direction !== "outbound")
+            continue;
+        const ifaceText = (cells[cols.iface] ?? "").trim();
+        if (ifaceText === "")
+            continue;
+        out.push({ interfaceText: ifaceText });
+    }
+    return out;
+}
+function splitRow(line) {
+    // Drop leading + trailing | then split on internal |.
+    let s = line;
+    if (s.startsWith("|"))
+        s = s.slice(1);
+    if (s.endsWith("|"))
+        s = s.slice(0, -1);
+    return s.split("|").map((c) => c.trim());
+}
+async function listRepoDirs(reposRoot) {
+    try {
+        const entries = await readdir(reposRoot, { withFileTypes: true });
+        return entries.filter((e) => e.isDirectory()).map((e) => e.name).sort();
+    }
+    catch (err) {
+        const code = err.code;
+        if (code === "ENOENT")
+            return [];
+        throw err;
+    }
+}
+//# sourceMappingURL=service-contract-consumes.js.map

package/dist/lib/catalogue/builders/service-contract.js

@@ -0,0 +1,74 @@
+// service_contract edge — emits one row per (service, contract, exposes)
+// triple from `contracts.{openapi,proto,avro}` blocks in repo-config.
+//
+// Forward method convention: a service's repo-config declares the
+// contracts it exposes. The "consumes" role isn't declared in current
+// adopters; this builder emits role=exposes only.
+import { basename, sep } from "node:path";
+export function buildServiceContract(inputs) {
+    const rows = [];
+    const seen = new Set();
+    // Pre-compute fuzzy indexes for matching.
+    const suffixIndex = new Map();
+    const basenameIndex = new Map();
+    for (const [path, id] of inputs.contractIdByPath) {
+        const parts = path.split(sep);
+        if (parts.length >= 2)
+            suffixIndex.set(parts.slice(-2).join("/"), id);
+        basenameIndex.set(basename(path), id);
+    }
+    for (const cfg of inputs.configs) {
+        const block = cfg.data.contracts;
+        if (!inputs.knownServiceIds.has(cfg.repoId)) {
+            // Interim guard (M-ADR 0197 stopgap, ahead of Phase B's attribution
+            // mechanism): this check pre-dates M-ADR 0197 and always dropped a
+            // non-resolving repo id silently, on the assumption knownServiceIds
+            // was always a superset of every repo id — true until a repo could
+            // declare a `services:` block that drops its own default id. Only
+            // warn when there was actually a contracts block to lose; a repo
+            // with no service and no contracts (the ordinary library/infra case)
+            // stays silent, as it always has.
+            // NOTE: `block` here is repo-config's `contracts` (cfg.data.contracts), a
+            // DIFFERENT schema from the traceability manifest's contracts block — so its
+            // three kinds are not a stale copy of the manifest's five and must not be
+            // "fixed" by the shared traceability helper. Whether repo-config should also
+            // key graphql is its own question, on its own schema.
+            const hasContracts = block !== undefined &&
+                ((block.openapi?.length ?? 0) > 0 ||
+                    (block.proto?.length ?? 0) > 0 ||
+                    (block.avro?.length ?? 0) > 0);
+            if (hasContracts) {
+                inputs.findings.add("orphan", `${cfg.relPath}: contracts block declares exposes-edges for service "${cfg.repoId}", which does not resolve in services.csv — dropped. Check a services: block entry exists at this id (M-ADR 0197); this can also mean the repo's own default service id was never a runtime type.`);
+            }
+            continue;
+        }
+        if (!block)
+            continue;
+        for (const kind of ["openapi", "proto", "avro"]) {
+            const list = block[kind] ?? [];
+            for (const rawEntry of list) {
+                const entry = rawEntry.replace(/^\/+/, "");
+                const fullCandidate = `contracts/${kind}/${entry}`;
+                const cid = inputs.contractIdByPath.get(fullCandidate)
+                    ?? inputs.contractIdByPath.get(entry)
+                    ?? suffixIndex.get(fullCandidate)
+                    ?? suffixIndex.get(entry)
+                    ?? basenameIndex.get(basename(entry));
+                if (cid === undefined)
+                    continue;
+                const id = `${cfg.repoId}__${cid}__exposes`;
+                if (seen.has(id))
+                    continue;
+                seen.add(id);
+                rows.push({
+                    id,
+                    service_id: cfg.repoId,
+                    contract_id: cid,
+                    role: "exposes",
+                });
+            }
+        }
+    }
+    return rows;
+}
+//# sourceMappingURL=service-contract.js.map

package/dist/lib/catalogue/builders/service-entity-tables.js

@@ -0,0 +1,187 @@
+// Primary reverse-method walker for the service_entity edge catalogue per
+// ADR 0159 §4.5. Reads per-domain `## Data Store Mapping` markdown tables in
+// `docs/domains/{domain}/architecture/data-model.mermaid.md` files.
+//
+// Prototype findings (per ADR 0159 — data-store-mapping table variations):
+// - Two heading variants: `## Data Store Mapping` and `## Data Store Inventory`
+//   (the latter is store-centric — different schema, no Entity column — and
+//   gets skipped with a convention finding).
+// - Three column-shape variants: standard (Entity | Store | Schema/Collection
+//   | Owning Service | PPT/Notes), developer's first col = `Entity / Artefact`,
+//   and vehicle's lack of `Owning Service` column (skipped).
+// - Compound owning-service cells split on ` / ` — emit one edge per part.
+// - Trailing `(annotation)` on entity texts stripped before slug-lookup.
+// - Cross-domain entity references in tables resolve against entities.csv
+//   from any domain (not just the table's own domain) — same-domain first.
+//
+// Service-name resolution rules (ADR 0159 §4.7):
+// 1. Try alias-map exact match (case-insensitive on display name).
+// 2. Try entitySlug(display_name) ⋈ entitySlug(services.name).
+// 3. Try entitySlug(display_name) ⋈ last_segment(services.id).
+// 4. Fire [finding] orphan; skip edge.
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { parse as parseYaml } from "yaml";
+import { entitySlug } from "./entity-slug.js";
+import { RE_DATA_STORE_HEADING, collectTableLines, splitRow, } from "./data-store-mapping.js";
+const ALIAS_REL_PATH = join("docs", "platform", "reference", "service-name-aliases.yaml");
+export async function buildServiceEntityFromTables(inputs) {
+    const aliasMap = await loadAliasMap(inputs.sddPath, inputs.findings);
+    // Pre-compute service lookups.
+    const serviceIdBySlugName = new Map();
+    const serviceIdByTrailSegment = new Map();
+    for (const s of inputs.services) {
+        const id = String(s["id"]);
+        const name = String(s["name"] ?? "");
+        if (name)
+            serviceIdBySlugName.set(entitySlug(name), id);
+        const lastSeg = id.split("-").pop() ?? "";
+        if (lastSeg && !serviceIdByTrailSegment.has(lastSeg)) {
+            serviceIdByTrailSegment.set(lastSeg, id);
+        }
+    }
+    const rowsByPk = new Map();
+    for (const dm of inputs.domainModels) {
+        if (!dm.doc_path.endsWith(".mermaid.md"))
+            continue;
+        const fullPath = dm.doc_path.startsWith("/")
+            ? dm.doc_path
+            : join(inputs.sddPath, dm.doc_path);
+        let text;
+        try {
+            text = await readFile(fullPath, "utf-8");
+        }
+        catch (err) {
+            if (err.code === "ENOENT")
+                continue;
+            throw err;
+        }
+        const lines = text.split(/\r?\n/);
+        const headingIdx = lines.findIndex((l) => RE_DATA_STORE_HEADING.test(l));
+        if (headingIdx === -1)
+            continue;
+        const tableLines = collectTableLines(lines, headingIdx + 1);
+        if (tableLines === null || tableLines.length < 2) {
+            inputs.findings.add("convention", `service-entity-tables: ${dm.doc_path}: Data Store heading present but no markdown table follows — skipped`);
+            continue;
+        }
+        const headers = splitRow(tableLines[0]);
+        let entityColIdx = -1;
+        let serviceColIdx = -1;
+        for (let i = 0; i < headers.length; i++) {
+            const h = headers[i].toLowerCase();
+            if (entityColIdx === -1 && (h === "entity" || h.startsWith("entity"))) {
+                entityColIdx = i;
+            }
+            if (serviceColIdx === -1 && h.includes("owning service")) {
+                serviceColIdx = i;
+            }
+        }
+        if (entityColIdx === -1 || serviceColIdx === -1) {
+            inputs.findings.add("convention", `service-entity-tables: ${dm.doc_path}: Data Store table missing Entity or Owning Service column (headers: ${headers.join(" | ")}) — skipped`);
+            continue;
+        }
+        // Skip the |---|---| separator row (lineLine[1]); data rows start at index 2.
+        for (let i = 2; i < tableLines.length; i++) {
+            const cells = splitRow(tableLines[i]);
+            if (cells.length <= Math.max(entityColIdx, serviceColIdx))
+                continue;
+            const entityText = cells[entityColIdx].trim();
+            const serviceText = cells[serviceColIdx].trim();
+            if (!entityText || !serviceText)
+                continue;
+            // Strip trailing parenthetical annotation: "Role (fleet)" → "Role".
+            const entityNorm = entityText.replace(/\s*\([^)]+\)\s*$/, "").trim();
+            const entSlug = entitySlug(entityNorm);
+            let entityId = inputs.entityIdByDomainSlug.get(`${dm.domain_id}|${entSlug}`);
+            if (entityId === undefined) {
+                entityId = inputs.entityIdBySlug.get(entSlug);
+            }
+            if (entityId === undefined) {
+                inputs.findings.add("orphan", `service-entity-tables: ${dm.doc_path}: entity "${entityText}" doesn't resolve to an entities.csv row — edge skipped`);
+                continue;
+            }
+            // Compound owning-service: split on " / ".
+            const serviceParts = serviceText
+                .split(/\s+\/\s+/)
+                .map((s) => s.trim())
+                .filter((s) => s.length > 0);
+            for (const sp of serviceParts) {
+                const serviceId = resolveService(sp, aliasMap, serviceIdBySlugName, serviceIdByTrailSegment, inputs.knownServiceIds);
+                if (serviceId === undefined) {
+                    inputs.findings.add("orphan", `service-entity-tables: ${dm.doc_path}: owning-service "${sp}" doesn't resolve to a services.csv row — edge skipped`);
+                    continue;
+                }
+                const pk = `${serviceId}__${entityId}__owns`;
+                if (rowsByPk.has(pk))
+                    continue;
+                rowsByPk.set(pk, {
+                    id: pk,
+                    service_id: serviceId,
+                    entity_id: entityId,
+                    relation: "owns",
+                    evidence_path: dm.doc_path,
+                    source_sdd_id: "",
+                });
+            }
+        }
+    }
+    return [...rowsByPk.values()];
+}
+async function loadAliasMap(sddPath, findings) {
+    const empty = { byDisplayLower: new Map() };
+    const path = join(sddPath, ALIAS_REL_PATH);
+    let text;
+    try {
+        text = await readFile(path, "utf-8");
+    }
+    catch (err) {
+        if (err.code === "ENOENT")
+            return empty;
+        throw err;
+    }
+    let raw;
+    try {
+        raw = parseYaml(text);
+    }
+    catch (err) {
+        findings.add("convention", `${ALIAS_REL_PATH}: failed to parse YAML — ${err.message}`);
+        return empty;
+    }
+    if (!raw || typeof raw !== "object")
+        return empty;
+    const obj = raw;
+    const aliases = obj["aliases"];
+    if (!Array.isArray(aliases))
+        return empty;
+    const map = new Map();
+    for (const a of aliases) {
+        if (!a || typeof a !== "object")
+            continue;
+        const e = a;
+        const display = String(e["display"] ?? "").trim();
+        const canonical = String(e["canonical"] ?? "").trim();
+        if (display && canonical)
+            map.set(display.toLowerCase(), canonical);
+    }
+    return { byDisplayLower: map };
+}
+function resolveService(display, alias, serviceIdBySlugName, serviceIdByTrailSegment, knownServiceIds) {
+    // 1. Alias map exact (case-insensitive).
+    const aliased = alias.byDisplayLower.get(display.toLowerCase());
+    if (aliased && knownServiceIds.has(aliased))
+        return aliased;
+    // 2. Slug-of-name match.
+    const slug = entitySlug(display);
+    if (!slug)
+        return undefined;
+    const bySlugName = serviceIdBySlugName.get(slug);
+    if (bySlugName && knownServiceIds.has(bySlugName))
+        return bySlugName;
+    // 3. Trailing-id-segment match.
+    const byTrail = serviceIdByTrailSegment.get(slug);
+    if (byTrail && knownServiceIds.has(byTrail))
+        return byTrail;
+    return undefined;
+}
+//# sourceMappingURL=service-entity-tables.js.map