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

package/dist/lib/catalogue/builders/capability-edges.js

@@ -0,0 +1,256 @@
+// Edge builders for capability_* catalogues — capability_service,
+// capability_adr, capability_feature, capability_contract.
+//
+// All four read traceability YAMLs as the authoritative source. The
+// canonical schema declares capability_id and the target column as
+// required FKs — so each builder skips entries whose target doesn't
+// resolve in the known-target set passed in.
+// capability_service is the exception (F4, schema 2.29.0): its service_id
+// FK is external, and an entry marked `owner_sdd:` declares a cross-SDD
+// reference — the edge is emitted despite not resolving locally and is
+// validated hard at aggregation against the owning sibling's rows.
+// Every other skipped `services[].id` still surfaces as a finding (orphan,
+// or convention when the id names a known external system) — unresolved
+// edges must never drop silently.
+//
+// capability_event is intentionally not built here: its source per the
+// metamodel is `## Related Events` markdown tables in capability specs,
+// which depends on a spec-formatting convention that's only partial in
+// the field. Defer to a later phase.
+import { basename, sep } from "node:path";
+import { declaredContractPaths } from "../traceability-loader.js";
+import { ORIGIN_PREFIX_SRC } from "../../adr-origin.js";
+export function buildCapabilityService(inputs) {
+    const rows = [];
+    const seen = new Set();
+    for (const m of inputs.manifests) {
+        const capId = m.capability.id;
+        if (!inputs.knownCapabilityIds.has(capId)) {
+            // M-ADR 0211 §4.3 — the second bare `continue` in this file, now named. A manifest
+            // whose capability produced no row loses every services[] entry; that used to
+            // happen in silence, the same shape as the spec-only stem collision.
+            const n = (m.traceability.services ?? []).length;
+            if (n > 0) {
+                inputs.findings.add("coverage", `capability_service: ${m.relPath} declares ${n} services[] entr${n === 1 ? "y" : "ies"} but its capability "${capId}" produced no capabilities row — all ${n} dropped (M-ADR 0211 §4.3)`);
+            }
+            continue;
+        }
+        for (const entry of m.traceability.services ?? []) {
+            const sid = entry.id;
+            if (!inputs.knownServiceIds.has(sid)) {
+                // Never drop silently (61 missing edges sat invisible in the field
+                // until a manual sweep). Resolution order:
+                //  - `owner_sdd:` marked (F4, schema 2.29.0) — a DECLARED cross-SDD
+                //    reference (e.g. the service moved to a sibling at a carve).
+                //    Emit the edge; the external FK logs it and aggregation
+                //    validates it hard against the sibling's rows.
+                //  - id naming a known external system — a modelling convention.
+                //  - anything else — a dangling reference, member-tier orphan
+                //    finding. NOT emitted: measured in the field, almost all
+                //    unmarked danglings are local authoring gaps, and emitting
+                //    them would fail aggregation on a defect that isn't theirs.
+                if (entry.owner_sdd !== undefined) {
+                    // Emit and fall through — the external FK validation logs the
+                    // single `[finding] external` line for it (one fact, one finding).
+                }
+                else if (inputs.knownExternalSystemIds?.has(sid)) {
+                    inputs.findings.add("convention", `capability_service: ${capId} services[] id "${sid}" resolves to an external system, not a service — edge skipped`);
+                    continue;
+                }
+                else {
+                    // Name the remedy the branch above already implements (M-ADR 0199
+                    // §4.4: a remedy must be true at the emitting tier). Measured cost
+                    // of not naming it: an adopter read this line, concluded a
+                    // cross-SDD capability_service edge was unrepresentable, and
+                    // reported two permanently-unresolvable orphans that were one
+                    // authored line from resolving.
+                    inputs.findings.add("orphan", `capability_service: ${capId} services[] id "${sid}" — no matching service (edge skipped). ` +
+                        `If that service is owned by a SIBLING SDD, declare \`owner_sdd:\` on this entry ` +
+                        `(schema 2.29.0) — the edge is then emitted and validated at aggregation. ` +
+                        `Otherwise it is a local authoring gap: fix the id, or add the service.`);
+                    continue;
+                }
+            }
+            const role = entry.role ?? "";
+            const id = `${capId}__${sid}__${role !== "" ? role : "related"}`;
+            if (seen.has(id))
+                continue;
+            seen.add(id);
+            rows.push({
+                id,
+                capability_id: capId,
+                service_id: sid,
+                role,
+                // M-ADR 0211 §4.1 / schema 3.9.0 — the dependency's contract and wire coupling as
+                // catalogued fields. Empty when the entry declares none; the validator has already
+                // held `interaction_pattern` to the bound vocabulary and `contract` to resolution.
+                contract_id: entry.contract ?? "",
+                interaction_pattern: entry.interaction_pattern ?? "",
+                qualifier: entry.qualifier ?? "",
+                evidence_ref: entry.evidence ?? "",
+            });
+        }
+    }
+    return rows;
+}
+export function buildCapabilityAdr(inputs) {
+    const rows = [];
+    const seen = new Set();
+    for (const m of inputs.manifests) {
+        const capId = m.capability.id;
+        if (!inputs.knownCapabilityIds.has(capId))
+            continue;
+        for (const entry of m.traceability.adrs ?? []) {
+            const adrId = canonicaliseAdrId(entry.id);
+            if (adrId === "")
+                continue;
+            if (!inputs.knownAdrIds.has(adrId))
+                continue;
+            const id = `${capId}__${adrId}`;
+            if (seen.has(id))
+                continue;
+            seen.add(id);
+            rows.push({
+                id,
+                capability_id: capId,
+                adr_id: adrId,
+                confidence: "spec",
+            });
+        }
+    }
+    return rows;
+}
+export function buildCapabilityFeature(inputs) {
+    const rows = [];
+    const seen = new Set();
+    for (const m of inputs.manifests) {
+        const capId = m.capability.id;
+        if (!inputs.knownCapabilityIds.has(capId))
+            continue;
+        for (const path of m.traceability.runway?.enables ?? []) {
+            const featureId = resolveFeaturePath(path, inputs.featureIdByPath);
+            if (featureId === "")
+                continue;
+            const id = `${capId}__${featureId}`;
+            if (seen.has(id))
+                continue;
+            seen.add(id);
+            rows.push({
+                id,
+                capability_id: capId,
+                feature_id: featureId,
+            });
+        }
+    }
+    return rows;
+}
+export function buildCapabilityContract(inputs) {
+    const rows = [];
+    const seen = new Set();
+    for (const m of inputs.manifests) {
+        const capId = m.capability.id;
+        if (!inputs.knownCapabilityIds.has(capId))
+            continue;
+        const block = m.traceability.contracts;
+        if (!block)
+            continue;
+        const all = [];
+        // Each list holds bare string paths AND object entries ({path,
+        // external} — the D13 declared-external form). Both contribute their
+        // path here: a declared-external entry's path resolves against the
+        // merged id index (which includes the rows buildDeclaredExternalContracts
+        // just emitted), which is exactly how an external contract gains its
+        // capability_contract edge. spicedb joins the walk with the loader —
+        // .zed declarations previously never reached this builder at all.
+        // Iterates the SHARED kind list, not a hand-written one. This site is why
+        // that helper exists: it carried a four-kind array while discovery, mapping
+        // and the loader all knew five, so an estate's 9 correct graphql declarations
+        // produced ZERO capability_contract edges and left 7 orphans standing. The
+        // comment below already recorded the same bug one kind earlier.
+        for (const path of declaredContractPaths(block)) {
+            all.push(path);
+        }
+        for (const path of all) {
+            const contractId = resolveContractPath(path, inputs.contractIdByPath);
+            if (contractId === "") {
+                // Never drop silently. This guard dropped every unresolvable entry with no
+                // trace until WS2 of the coverage-invariants work measured it: 62 of 188
+                // declared entries across two estates, and NOT ONE of them dangling — every
+                // one named a real artefact. So the resolution failure is the interesting
+                // fact, and the reader needs it.
+                //
+                // WORDING IS DELIBERATELY CAUSE-AGNOSTIC (M-ADR 0189 §8 / M-ADR 0199 §4.4).
+                // The tempting remedy — "declare the contract" or "fix the path" — is FALSE
+                // for the measured majority: 56 of the 62 name a spec that exists at exactly
+                // that path in a sibling code repository (the M-ADR 0110 sibling-repo
+                // pattern), which the contracts discoverer does not walk, so there is
+                // nothing for the author to fix. 4 more name a contract row owned by a
+                // sibling SDD, which this edge has no cross-SDD form to express. State the
+                // fact, name the candidate causes, prescribe nothing.
+                inputs.findings.add("orphan", `capability_contract: ${m.relPath} traceability.contracts entry "${path}" `
+                    + `resolved to no contract row — edge dropped. The spec may sit outside `
+                    + `this SDD's contract-discovery paths (contracts/{openapi,proto,avro}/ or `
+                    + `docs/domains/*/contracts/{openapi,proto,avro}/), or name a contract owned `
+                    + `by a sibling SDD — capability_contract has no cross-SDD form, unlike `
+                    + `capability_service's owner_sdd`);
+                continue;
+            }
+            const id = `${capId}__${contractId}`;
+            if (seen.has(id))
+                continue;
+            seen.add(id);
+            rows.push({
+                id,
+                capability_id: capId,
+                contract_id: contractId,
+                source: "declared",
+            });
+        }
+    }
+    return rows;
+}
+// ─── helpers ────────────────────────────────────────────────────────────
+/**
+ * Normalise an ADR ID from a traceability entry. Accepts bare numerics
+ * (`"0037"`, `"0058"`) and full forms (`"ADR-0037"`, `"ADR 0037"`); emits
+ * `ADR-XXXX` (4-digit zero-padded) which is the canonical adrs.id form.
+ */
+function canonicaliseAdrId(raw) {
+    // Accept a bare number, `ADR-NNNN`/`ADR NNNN`, or any canonical origin prefix
+    // (`M-ADR`/`RA-ADR`/`P-ADR`/`D-ADR NNNN`) — all resolve by number.
+    const m = new RegExp(`^(?:${ORIGIN_PREFIX_SRC}ADR[-\\s]+)?(\\d+)`, "i").exec(raw);
+    if (!m || m[1] === undefined)
+        return "";
+    const num = parseInt(m[1], 10);
+    if (!Number.isFinite(num))
+        return "";
+    return `ADR-${String(num).padStart(4, "0")}`;
+}
+function resolveFeaturePath(path, index) {
+    const cleaned = path.replace(/^\/+/, "");
+    return index.get(cleaned) ?? "";
+}
+function resolveContractPath(path, index) {
+    const cleaned = path.replace(/^\/+/, "");
+    // Try exact path, then suffix matches.
+    const direct = index.get(cleaned);
+    if (direct !== undefined)
+        return direct;
+    // Suffix: last two parts (e.g. "asset/asset-twin.yaml")
+    const parts = cleaned.split(sep);
+    if (parts.length >= 2) {
+        const suffix = parts.slice(-2).join("/");
+        for (const [k, v] of index) {
+            if (k.endsWith(suffix))
+                return v;
+        }
+    }
+    // Basename fallback
+    const base = basename(cleaned);
+    for (const [k, v] of index) {
+        if (basename(k) === base)
+            return v;
+    }
+    return "";
+}
+//# sourceMappingURL=capability-edges.js.map

package/dist/lib/catalogue/builders/capability-spec-walker.js

@@ -0,0 +1,99 @@
+/**
+ * Walker for capability spec markdown files per ADR 0145 (schema 2.7.0).
+ *
+ * Reads `## Feature Grounding (code-path trace)` markdown tables of the
+ * canonical shape:
+ *
+ *     | Feature | Implementation | Grounding Doc |
+ *     |---|---|---|
+ *     | `alerts-module` | `alerts` Vuex module + `src/components/alerts` | docs/.../feature-grounding.md |
+ *
+ * Path convention (per ADR 0145 §4.3):
+ *   - platform-profile: `docs/domains/<dom>/product/<capability>.md`
+ *
+ * Capability id resolves from the filename stem. Tolerant of column
+ * re-ordering and missing optional columns. Reuses the table-parsing
+ * logic from `feature-grounding-walker.ts` (any markdown table whose
+ * first header normalises to `feature` is parsed).
+ *
+ * Recovery is row-local — a malformed row emits a finding and the
+ * walker continues with the next row.
+ */
+import { readdir } from "node:fs/promises";
+import { basename, join, relative, sep } from "node:path";
+import { parseGroundingTable, } from "./feature-grounding-walker.js";
+const DOMAINS_DIR_REL = join("docs", "domains");
+const PRODUCT_DIR_NAME = "product";
+/**
+ * Find all `docs/domains/<dom>/product/<capability>.md` files under the
+ * SDD root. Excludes `.traceability.yaml` sidecars. Sorted for
+ * deterministic output.
+ */
+export async function findCapabilitySpecFiles(sddPath) {
+    const out = [];
+    const domainsDir = join(sddPath, DOMAINS_DIR_REL);
+    let domains;
+    try {
+        domains = await readdir(domainsDir, { withFileTypes: true });
+    }
+    catch {
+        return out;
+    }
+    for (const d of domains) {
+        if (!d.isDirectory())
+            continue;
+        const productDir = join(domainsDir, d.name, PRODUCT_DIR_NAME);
+        let files;
+        try {
+            files = await readdir(productDir, { withFileTypes: true });
+        }
+        catch {
+            continue;
+        }
+        for (const f of files) {
+            if (!f.isFile())
+                continue;
+            if (!f.name.endsWith(".md"))
+                continue;
+            // Skip the README that lives in some product/ dirs.
+            if (f.name === "README.md")
+                continue;
+            out.push(join(productDir, f.name));
+        }
+    }
+    return out.sort();
+}
+/**
+ * Resolve the capability id from a capability spec file's absolute
+ * path. Returns the filename stem (`.md` stripped).
+ *
+ *   docs/domains/applications/product/alerts-and-notifications.md
+ *     → "alerts-and-notifications"
+ */
+export function capabilityIdFromSpecPath(absPath, sddPath) {
+    const rel = relative(sddPath, absPath);
+    const parts = rel.split(sep);
+    // Expected: ["docs", "domains", "<dom>", "product", "<file>.md"]
+    if (parts.length < 5)
+        return "";
+    const file = parts[parts.length - 1] ?? "";
+    if (!file.endsWith(".md"))
+        return "";
+    return file.slice(0, -3);
+}
+/**
+ * Parse the markdown content of a capability spec file and return the
+ * rows from its `## Feature Grounding (code-path trace)` table.
+ *
+ * Implementation detail: we delegate to `parseGroundingTable`, which
+ * picks the first table whose first column normalises to `feature`.
+ * Capability specs typically have one such table under
+ * `## Feature Grounding (code-path trace)`; the parser tolerates
+ * variations in the heading text.
+ */
+export function parseCapabilitySpecTable(text) {
+    return parseGroundingTable(text);
+}
+/** Re-export basename for convenience in tests. */
+export { basename };
+//# sourceMappingURL=capability-spec-walker.js.map