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

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

@@ -0,0 +1,348 @@
+/**
+ * Capability-spec feature extractor per ADR 0145 (schema 2.7.0).
+ *
+ * Walks `docs/domains/<dom>/product/<capability>.md` (platform-profile),
+ * parses the `## Feature Grounding (code-path trace)` markdown table,
+ * and emits four catalogue contributions:
+ *
+ *   - `features.csv` rows with `source: capability-spec`.
+ *   - `capability_feature.csv` rows (1:1 with each feature row).
+ *   - `feature_repo.csv` rows derived from file-path references in
+ *     the Implementation column.
+ *   - `feature_service.csv` rows derived from class names / file
+ *     basenames / route fragments in the Implementation column,
+ *     resolved via `services.csv` + the optional per-SDD alias map
+ *     introduced by ADR 0143.
+ *
+ * Resolution is best-effort and never breaks FK validation — only
+ * confidently-resolved rows are emitted. Unresolved CAPABILITY ids emit
+ * findings (convention/orphan). Unresolved SERVICE and REPO tokens are
+ * dropped silently, deliberately: the token stream comes from free-text
+ * Implementation columns (class names, route fragments, path segments),
+ * so most tokens legitimately resolve to nothing and a finding per miss
+ * would be noise. The row-level finding — a non-empty Implementation
+ * cell yielding ZERO repo resolutions — IS signal and is emitted as a
+ * coverage finding per row plus one summary line (M-ADR 0143 §4.4 as
+ * amended); it measures resolution coverage, never correctness.
+ *
+ * Precedence per ADR 0145 §4.7: feature-tree, feature-spec, and
+ * feature-grounding rows win on id collision (they are more specific
+ * sources); capability-spec rows are skipped with a divergence finding
+ * when their id is already taken.
+ */
+import { readFile } from "node:fs/promises";
+import { relative } from "node:path";
+import { capabilityIdFromSpecPath, findCapabilitySpecFiles, parseCapabilitySpecTable, } from "./capability-spec-walker.js";
+const DESCRIPTION_MAX = 500;
+/** Columns the service-name resolver scans for class names / route fragments. */
+const SERVICE_RESOLUTION_COLUMNS = ["implementation"];
+/** Columns the repo-name resolver scans for file-path references. */
+const REPO_RESOLUTION_COLUMNS = ["implementation", "grounding_doc"];
+export async function buildCapabilitySpec(inputs) {
+    const featureRows = [];
+    const capabilityFeatureRows = [];
+    const featureRepoRows = [];
+    // M-ADR 0143 §4.4 (amended): rows whose Implementation cell is non-empty but resolves to
+    // ZERO repos. Counted for the summary finding below; each row also gets its own
+    // line. This measures evidence→repo RESOLUTION COVERAGE, not correctness.
+    let repoEvidenceRows = 0;
+    const repoZeroResolutionFeatureIds = [];
+    const featureServiceRows = [];
+    const seenFeatureRepo = new Set();
+    const seenFeatureService = new Set();
+    const seenCapabilityFeature = new Set();
+    const seenFeatures = new Set(inputs.existingFeatureIds);
+    // Frozen copy — `seenFeatures` grows during this walk, so only this set can
+    // answer "did an EARLIER SOURCE emit this id?" at the collision site below.
+    const fromEarlierSource = new Set(inputs.existingFeatureIds);
+    if (inputs.profile !== "platform-profile") {
+        return {
+            featureRows,
+            capabilityFeatureRows,
+            featureRepoRows,
+            featureServiceRows,
+            repoEvidenceRows,
+            repoZeroResolutionFeatureIds,
+        };
+    }
+    const files = await findCapabilitySpecFiles(inputs.sddPath);
+    for (const absPath of files) {
+        const capabilityId = capabilityIdFromSpecPath(absPath, inputs.sddPath);
+        const relPath = relative(inputs.sddPath, absPath);
+        if (capabilityId === "") {
+            inputs.findings.add("convention", `${relPath}: capability id could not be resolved from file path`);
+            continue;
+        }
+        if (!inputs.knownCapabilityIds.has(capabilityId)) {
+            // Common for product README-style files that aren't capability specs.
+            // Treat as orphan, not convention — silently skip.
+            inputs.findings.add("orphan", `${relPath}: filename stem "${capabilityId}" does not match any capability id in capabilities.csv — skipping`);
+            continue;
+        }
+        const text = await readFile(absPath, "utf-8");
+        const rows = parseCapabilitySpecTable(text);
+        if (rows.length === 0) {
+            inputs.findings.add("coverage", `${relPath}: capability spec found but no "## Feature Grounding (code-path trace)" table recognised`);
+            continue;
+        }
+        const slugsInThisFile = new Set();
+        for (const row of rows) {
+            if (slugsInThisFile.has(row.slug)) {
+                inputs.findings.add("divergence", `${relPath}:${row.lineNumber}: duplicate feature slug "${row.slug}" in same file (first occurrence wins)`);
+                continue;
+            }
+            slugsInThisFile.add(row.slug);
+            const featureId = `${capabilityId}-${row.slug}`;
+            // Narrow the collision skip to the feature ROW only. When an earlier
+            // source already emitted this feature id, feature-tree / feature-spec /
+            // feature-grounding win the ROW (they carry runway / group / grounding
+            // context). EVERY edge below still emits — including capability_feature:
+            // a file-authored feature's row arrives from the feature files with NO
+            // capability_feature edge, so for that shape this extractor's edge is
+            // the ONLY source of the binding, and suppressing a non-duplicate edge
+            // because its sibling row duplicated silently unbinds the feature
+            // (measured: four owned-but-untraced pairs from exactly this rule).
+            // When the earlier source DID also emit the edge, the ids are identical
+            // (`${cap}__${feature}` in every emitter) and keyed-table dedup unions
+            // them — dedup rows, keep edges. feature_repo / feature_service remain
+            // this source's unique contribution (ADR 0145) as before.
+            if (seenFeatures.has(featureId)) {
+                // Same one-check-two-meanings split as feature-grounding.ts: a hit on
+                // an id seeded from an EARLIER SOURCE is the documented precedence rule
+                // firing (correct output, `inferred`, does not gate); a hit on an id
+                // this pass emitted itself is a real collision between two capability
+                // specs (`divergence`, gates). See the long comment there.
+                if (fromEarlierSource.has(featureId)) {
+                    inputs.findings.add("inferred", `${relPath}:${row.lineNumber}: feature id "${featureId}" already emitted by an earlier source (feature-tree / feature-spec / feature-grounding wins the row; edges still emitted, incl. capability_feature)`);
+                }
+                else {
+                    inputs.findings.add("divergence", `${relPath}:${row.lineNumber}: feature id "${featureId}" already emitted by another capability spec in this same pass (first occurrence wins the row; edges still emitted, incl. capability_feature)`);
+                }
+            }
+            else {
+                seenFeatures.add(featureId);
+                featureRows.push({
+                    id: featureId,
+                    name: row.slug,
+                    product_id: "",
+                    capability_id: capabilityId,
+                    parent_group_id: "",
+                    parent_feature_id: "",
+                    description: deriveDescription(row),
+                    maturity: "",
+                    status: "active",
+                    source: "capability-spec",
+                    runway: "",
+                    source_sdd_id: "",
+                });
+            }
+            // capability_feature edge — emitted on BOTH paths (the binding is not a
+            // duplicate just because the row was; PK-identical duplicates union at
+            // keyed-table dedup).
+            const cfId = `${capabilityId}__${featureId}`;
+            if (!seenCapabilityFeature.has(cfId)) {
+                seenCapabilityFeature.add(cfId);
+                capabilityFeatureRows.push({
+                    id: cfId,
+                    capability_id: capabilityId,
+                    feature_id: featureId,
+                });
+            }
+            // feature_service edges — always emit (unique to capability-spec)
+            const services = resolveServices(row, inputs);
+            for (const serviceId of services) {
+                const edgeId = `${featureId}__${serviceId}`;
+                if (seenFeatureService.has(edgeId))
+                    continue;
+                seenFeatureService.add(edgeId);
+                featureServiceRows.push({
+                    id: edgeId,
+                    feature_id: featureId,
+                    service_id: serviceId,
+                });
+            }
+            // feature_repo edges — always emit (unique to capability-spec)
+            const repos = resolveRepos(row, inputs);
+            if ((row.cells.get("implementation") ?? "").trim() !== "") {
+                repoEvidenceRows++;
+                if (repos.length === 0) {
+                    repoZeroResolutionFeatureIds.push(featureId);
+                    inputs.findings.add("coverage", `${relPath}:${row.lineNumber}: feature "${featureId}" — Implementation cell is non-empty but resolved to ZERO repos; name a repo key or path the resolver can match, or map the token in .sdd/feature-grounding-aliases.yaml repo_aliases (M-ADR 0143 §4.4)`);
+                }
+            }
+            for (const repoKey of repos) {
+                const edgeId = `${featureId}__${repoKey}`;
+                if (seenFeatureRepo.has(edgeId))
+                    continue;
+                seenFeatureRepo.add(edgeId);
+                featureRepoRows.push({
+                    id: edgeId,
+                    feature_id: featureId,
+                    repo_id: repoKey,
+                });
+            }
+        }
+    }
+    // The summary line is emitted by the build (build.ts, after feature_repo is
+    // final) so it can split rows fired against features left with NO anchor.
+    return {
+        featureRows,
+        capabilityFeatureRows,
+        featureRepoRows,
+        featureServiceRows,
+        repoEvidenceRows,
+        repoZeroResolutionFeatureIds,
+    };
+}
+/**
+ * Build the description column by joining non-feature cells, capped at
+ * 500 chars to match the feature-grounding convention.
+ */
+function deriveDescription(row) {
+    const parts = [];
+    for (const [key, value] of row.cells) {
+        if (value === "")
+            continue;
+        parts.push(`${prettyHeader(key)}: ${value}`);
+    }
+    const joined = parts.join(" • ");
+    return joined.length > DESCRIPTION_MAX
+        ? joined.slice(0, DESCRIPTION_MAX)
+        : joined;
+}
+function prettyHeader(key) {
+    return key
+        .split("_")
+        .map((p) => (p.length === 0 ? p : p[0].toUpperCase() + p.slice(1)))
+        .join(" ");
+}
+/**
+ * Resolve service ids referenced in a row's Implementation cell.
+ * Same strategy as feature-grounding: tokenize, alias-lookup, normalise,
+ * known-id lookup.
+ */
+function resolveServices(row, inputs) {
+    const out = new Set();
+    for (const col of SERVICE_RESOLUTION_COLUMNS) {
+        const cell = row.cells.get(col) ?? "";
+        if (cell === "")
+            continue;
+        for (const token of tokenize(cell)) {
+            const resolved = resolveServiceToken(token, inputs);
+            if (resolved !== null)
+                out.add(resolved);
+        }
+    }
+    return [...out].sort();
+}
+function resolveServiceToken(rawToken, inputs) {
+    if (inputs.aliases !== null) {
+        const aliased = inputs.aliases.serviceAliases.get(rawToken);
+        if (aliased !== undefined && inputs.knownServiceIds.has(aliased)) {
+            return aliased;
+        }
+    }
+    const normalised = normaliseToken(rawToken);
+    if (normalised === "")
+        return null;
+    if (inputs.knownServiceIds.has(normalised))
+        return normalised;
+    if (inputs.aliases !== null) {
+        const aliased = inputs.aliases.serviceAliases.get(normalised);
+        if (aliased !== undefined && inputs.knownServiceIds.has(aliased)) {
+            return aliased;
+        }
+    }
+    return null;
+}
+function resolveRepos(row, inputs) {
+    const out = new Set();
+    for (const col of REPO_RESOLUTION_COLUMNS) {
+        const cell = row.cells.get(col) ?? "";
+        if (cell === "")
+            continue;
+        const coded = inputs.repoTokenPolicy === "identifier" ? codeSpanTokens(cell) : null;
+        for (const token of tokenize(cell)) {
+            const resolved = resolveRepoToken(token, inputs);
+            if (resolved === null)
+                continue;
+            if (coded !== null && isPlainWord(token) && !coded.has(token) && inputs.aliases?.repoAliases.get(token) !== resolved)
+                continue;
+            out.add(resolved);
+        }
+    }
+    return [...out].sort();
+}
+function resolveRepoToken(rawToken, inputs) {
+    if (inputs.aliases !== null) {
+        const aliased = inputs.aliases.repoAliases.get(rawToken);
+        if (aliased !== undefined && inputs.knownRepoKeys.has(aliased)) {
+            return aliased;
+        }
+    }
+    if (inputs.knownRepoKeys.has(rawToken))
+        return rawToken;
+    for (const segment of rawToken.split("/")) {
+        const stripped = segment
+            .replace(/-master@.*$/, "")
+            .replace(/@[^/]+$/, "");
+        if (stripped !== "" && inputs.knownRepoKeys.has(stripped)) {
+            return stripped;
+        }
+        const trailingMaster = stripped.replace(/-master$/, "");
+        if (trailingMaster !== stripped &&
+            inputs.knownRepoKeys.has(trailingMaster)) {
+            return trailingMaster;
+        }
+    }
+    return null;
+}
+/**
+ * Tokenize a markdown cell — mirrors the feature-grounding tokenizer.
+ * Matches backticked spans, bare CamelCase / kebab-case identifiers,
+ * and path-like tokens. Strips method call parens and array indexers.
+ */
+function tokenize(cell) {
+    const out = new Set();
+    for (const match of cell.matchAll(/`([^`]+)`/g)) {
+        const inner = match[1] ?? "";
+        addCandidatesFromToken(inner, out);
+    }
+    const stripped = cell.replace(/`[^`]+`/g, " ");
+    for (const match of stripped.matchAll(/[A-Za-z][A-Za-z0-9._@/-]*[A-Za-z0-9]/g)) {
+        addCandidatesFromToken(match[0], out);
+    }
+    return [...out];
+}
+function addCandidatesFromToken(token, out) {
+    if (token === "")
+        return;
+    if (token.includes("/")) {
+        out.add(token);
+        const first = token.split("/")[0] ?? "";
+        if (first !== "" && first !== token)
+            out.add(first);
+        return;
+    }
+    const head = token.split(/[(.[]/)[0] ?? "";
+    if (head !== "")
+        out.add(head);
+    out.add(token);
+}
+/** Candidate tokens that came from backticked code spans only. */
+function codeSpanTokens(cell) {
+    const out = new Set();
+    for (const match of cell.matchAll(/`([^`]+)`/g))
+        addCandidatesFromToken(match[1] ?? "", out);
+    return out;
+}
+/** A letters-only word — ordinary prose unless it is written as code. */
+const isPlainWord = (token) => /^[A-Za-z]+$/.test(token);
+function normaliseToken(token) {
+    return token
+        .toLowerCase()
+        .replace(/\.(ts|tsx|js|jsx|java|kt|kts|py|go|rs|yaml|yml|json|md)$/i, "")
+        .replace(/\(\)$/, "")
+        .trim();
+}
+//# sourceMappingURL=capability-spec.js.map

package/dist/lib/catalogue/builders/container-dependency.js

@@ -0,0 +1,183 @@
+// container_dependency member-tier builder — F19 (M-ADR 0189 §4.4/F17
+// follow-on, schema 2.33.1).
+//
+// F17 made the aggregator's adjudication leg the ONLY source of
+// container_dependency rows — populated exactly when an author
+// mis-declared an internal container as `System_Ext`. An author who wrote
+// the C4-correct thing instead — `Rel(container_a, container_b)` between
+// two `Container(...)` nodes — got no row and no finding: the metamodel
+// rewarded the wrong authoring and silently discarded the right one,
+// inverting the incentive F17 was built to create.
+//
+// This builder harvests intra-SDD container→container `Rel(...)` lines:
+// both endpoints must resolve to local containers (via the entry-id map
+// the c4-containers builder fills), neither may be external, and the
+// syndicated platform L1 is skipped for non-root SDDs (F14 — its Rel
+// lines are the platform's statements). The adjudication leg then MERGES
+// into a catalogue that already has content, rather than being its only
+// source; dedup is by id, member rows first.
+import { readFile } from "node:fs/promises";
+import { collectC4DiagramFiles } from "./c4-external-systems.js";
+import { mergeEdgeLabel } from "./edge-label-merge.js";
+import { techContradicts } from "./c4-containers.js";
+const REL_RE = /^(?:Bi)?Rel(?:_[A-Za-z]+)?\s*\(\s*(\w+)\s*,\s*(\w+)\s*(?:,\s*"([^"]*)")?/;
+export async function buildContainerDependency(inputs) {
+    if (inputs.containerIdByEntryId.size === 0)
+        return [];
+    const isRoot = inputs.manifest.category === "platform-root";
+    const files = await collectC4DiagramFiles(inputs.sddPath);
+    const rows = [];
+    const seen = new Set();
+    const rowsById = new Map();
+    const PERSON_DECL_RE = /Person(?:_Ext)?\s*\(\s*(\w+)\s*,/;
+    for (const { abs, syndicated } of files) {
+        if (syndicated && !isRoot)
+            continue;
+        const content = await readFile(abs, "utf-8");
+        // F26: per-file Person entries — the endpoint class that has no edge
+        // catalogue to a container.
+        const personEntries = new Set();
+        for (const raw of content.split(/\r?\n/)) {
+            const pm = PERSON_DECL_RE.exec(raw.trim());
+            if (pm)
+                personEntries.add(pm[1] ?? "");
+        }
+        for (const raw of content.split(/\r?\n/)) {
+            const m = REL_RE.exec(raw.trim());
+            if (!m)
+                continue;
+            const [, fromEntry, toEntry, label] = m;
+            // F20: resolve the container FIRST. Both maps are SDD-wide, and an
+            // entry-id that resolves to a local container IS a container —
+            // whatever a sibling diagram in the same SDD called it. The old
+            // external-guard-first order silently discarded a true edge whenever
+            // the id was also used for a System_Ext elsewhere in the SDD, which
+            // is precisely the shape shared load-bearing containers produce
+            // (measured: the estate's commonest collision class). The sibling's
+            // System_Ext usage is separately harvested and adjudicated; a
+            // converted candidate's rewritten edge dedups against the member row
+            // by id, so nothing is double-represented.
+            const from = inputs.containerIdByEntryId.get(fromEntry ?? "");
+            const to = inputs.containerIdByEntryId.get(toEntry ?? "");
+            if (from === undefined || to === undefined) {
+                // F26: a Rel the builder RESOLVES but cannot catalogue must say so
+                // — following F23's rename prescription turned exactly this
+                // silence into a two-edge delete. Classification is
+                // container-first (F20), then external, then Person (file-local);
+                // anything unknown stays silent (no confident classification, no
+                // guess). Pairs with a home elsewhere (one-external →
+                // system_external_dependency; person→system → persona_c4system)
+                // are not reported here.
+                const classify = (entry, resolved) => resolved !== undefined
+                    ? "container"
+                    : inputs.externalIdByEntryId?.has(entry)
+                        ? "external"
+                        : personEntries.has(entry)
+                            ? "person"
+                            : "unknown";
+                const fromKind = classify(fromEntry ?? "", from);
+                const toKind = classify(toEntry ?? "", to);
+                const pair = `${fromKind}→${toKind}`;
+                // person↔container pairs are catalogued by persona_container as of
+                // schema 2.34.0 (or reported there when the persona doesn't
+                // resolve) — only the pairs with NO home remain findings here.
+                if (pair === "external→external") {
+                    inputs.findings.add("convention", `container_dependency: Rel(${fromEntry}, ${toEntry}${label ? `, "${label}"` : ""}) resolves as ` +
+                        `${pair} — no catalogue holds that pair; the relationship is recorded nowhere (F26)`);
+                }
+                continue;
+            }
+            if (from === to)
+                continue;
+            const id = `${from}__${to}`;
+            const existing = rowsById.get(id);
+            if (existing !== undefined) {
+                mergeEdgeLabel(existing, label ?? "", "container_dependency", inputs.findings);
+                continue;
+            }
+            seen.add(id);
+            rowsById.set(id, {
+                id,
+                from_container_id: from,
+                to_container_id: to,
+                interaction: label ?? "",
+                source_sdd_id: inputs.manifest.sddId,
+            });
+            rows.push(rowsById.get(id));
+        }
+    }
+    rows.sort((a, b) => String(a["id"]).localeCompare(String(b["id"])));
+    return rows;
+}
+/**
+ * F21 referent-collision check — corroborate on an INDEPENDENT evidence
+ * channel, never the one under guard. The F20-era version decided referent
+ * identity by comparing display names — the same evidence class the guard
+ * existed to distrust — so it was circular: the estate sweep that declared
+ * different-referent collisions absent USED this predicate and could not
+ * have found the counterexample it then declared inexercisable. Measured:
+ * nested names (a client layer and the server it proxies, names nesting)
+ * are DIFFERENT referents and stayed silent; acronym-vs-expansion is the
+ * SAME referent and fired. The predicate was inverted on the two
+ * name-shapes the estate actually uses.
+ *
+ * The independent channel is the technology string: ".NET 6 (in Linton)"
+ * against "Java" is a flat contradiction and needs no NLP. A dual-use
+ * entry-id (Container + System_Ext in one SDD) whose technologies
+ * contradict draws the finding REGARDLESS of what the names say — name
+ * agreement is precisely what makes the collision quiet today. Where no
+ * technology evidence exists on either side, silence: absence of evidence
+ * is not corroboration, and it is not contradiction either.
+ */
+export function reportEntryIdReferentCollisions(inputs) {
+    const techTokens = (s) => new Set(s
+        .replace(/([a-z0-9])([A-Z])/g, "$1 $2")
+        .toLowerCase()
+        .split(/[^a-z0-9.+#]+/)
+        .filter((t) => t !== ""));
+    for (const [entryId, containerName] of inputs.containerNameByEntryId) {
+        const externalName = inputs.externalNameByEntryId.get(entryId);
+        if (externalName === undefined)
+            continue;
+        const containerTech = inputs.containerTechByEntryId.get(entryId) ?? "";
+        const externalTech = inputs.externalTechByEntryId.get(entryId) ?? "";
+        if (externalTech !== "" && techContradicts(containerTech, externalTech)) {
+            inputs.findings.add("convention", `c4 diagrams: entry-id "${entryId}" is declared Container ("${containerName}", "${containerTech}") and ` +
+                `System_Ext ("${externalName}", "${externalTech}") with contradictory technologies — ` +
+                `different referents wearing one id; the container interpretation wins for Rel edges — rename one entry-id to split them (F21)`);
+            continue;
+        }
+        if (externalTech !== "")
+            continue; // corroborating tech — same referent, silent
+        // F23: System_Ext carries no technology argument, so the primary
+        // dual-use case has NO independent evidence channel — measured: 0 of
+        // 109 external rows carry a technology. Weak corroboration is
+        // accepted (the external's description mentioning a container-tech
+        // token); otherwise the guard says what it cannot do, loudly. A
+        // dual-use entry-id buys nothing post-F20 (the container always wins
+        // for Rel edges) and risks a silent different-referent bind — the
+        // retirement is a rename, cheap because entry-ids are diagram-local
+        // and row identity derives from the display name.
+        const externalDesc = inputs.externalDescByEntryId.get(entryId) ?? "";
+        if (containerTech !== "" && externalDesc !== "") {
+            const ct = techTokens(containerTech);
+            const dt = techTokens(externalDesc);
+            let overlap = false;
+            for (const t of ct)
+                if (dt.has(t)) {
+                    overlap = true;
+                    break;
+                }
+            if (overlap)
+                continue; // description mentions the container's tech — weak corroboration
+        }
+        inputs.findings.add("convention", `c4 diagrams: entry-id "${entryId}" is declared Container ("${containerName}") and System_Ext ` +
+            `("${externalName}") with no independent evidence to adjudicate referent identity — System_Ext ` +
+            `carries no technology field; cannot corroborate, cannot contradict. Rename one entry-id to split ` +
+            `the namespaces — but check first whether the dual use is load-bearing: if Rel edges exist only via ` +
+            `the Container reading, a rename orphans them (they will surface as F26 findings); in that case ` +
+            `annotate the System_Ext description with the technology instead, so weak corroboration can silence ` +
+            `this honestly (F23/F26)`);
+    }
+}
+//# sourceMappingURL=container-dependency.js.map