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

package/dist/lib/catalogue/population-checks.js

@@ -0,0 +1,87 @@
+const norm = (s) => s.toLowerCase().replace(/^ext-/, "").replace(/[^a-z0-9]/g, "");
+const slug = (s) => s.toLowerCase().trim().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "");
+/** Does a services[] id name a declared C4 container — by id, by the system-anchored id, or by the slug of its name? */
+export function matchesContainer(sid, containers) {
+    const target = sid.toLowerCase();
+    return containers.some((c) => {
+        const id = c.id.toLowerCase();
+        if (id === target || slug(c.name) === target)
+            return true;
+        const sys = (c.system_id ?? "").toLowerCase();
+        return sys !== "" && id === `${sys}-${target}`;
+    });
+}
+/**
+ * A near-miss is an external-system id that the unresolved id contains or is contained by after
+ * normalisation (a separator changed, a prefix or suffix added — the three measured shapes), with a
+ * length floor so a short common token does not fire on everything. It is NAMED, never applied.
+ */
+export function nearMiss(id, externalIds) {
+    const n = norm(id);
+    let best;
+    for (const ext of externalIds) {
+        const e = norm(ext);
+        if (ext === id || e === "" || Math.min(n.length, e.length) < 6)
+            continue;
+        if (n === e || n.includes(e) || e.includes(n)) {
+            if (best === undefined || e.length > norm(best).length)
+                best = ext; // prefer the most specific
+        }
+    }
+    return best;
+}
+// @rule population-capability-service
+export function checkCapabilityServicePopulation(inputs) {
+    let declared = 0, unresolved = 0, deduplicated = 0, capabilityUnknown = 0, crossSdd = 0;
+    let externalSystem = 0, declaredContainer = 0, nowhere = 0, expectedRows = 0;
+    const seen = new Set();
+    for (const m of inputs.manifests) {
+        const capId = m.capability.id;
+        for (const entry of m.traceability.services ?? []) {
+            declared++;
+            if (!inputs.knownCapabilityIds.has(capId)) {
+                capabilityUnknown++;
+                continue;
+            }
+            const sid = entry.id;
+            // Resolution order (M-ADR 0211 §4.3): owner_sdd FIRST — a declared cross-SDD
+            // reference is resolved by declaration, not by the local services catalogue.
+            const resolved = entry.owner_sdd !== undefined || inputs.knownServiceIds.has(sid);
+            if (entry.owner_sdd !== undefined)
+                crossSdd++;
+            if (!resolved) {
+                unresolved++;
+                if (inputs.knownExternalSystemIds.has(sid)) {
+                    externalSystem++;
+                }
+                else if (matchesContainer(sid, inputs.knownContainers)) {
+                    declaredContainer++;
+                    inputs.findings.add("convention", `capability_service: ${capId} services[] id "${sid}" resolves as a DECLARED C4 CONTAINER, not a service — capability_service has no locus for it; the id is correct and there is nothing to fix here (M-ADR 0211 §4.3, class 2: a dependency on a container that is not a service, filed as its own item)`);
+                }
+                else {
+                    nowhere++;
+                    const cand = nearMiss(sid, inputs.knownExternalSystemIds);
+                    if (cand !== undefined) {
+                        inputs.findings.add("convention", `capability_service: ${capId} services[] id "${sid}" resolves nowhere; nearest external-system id is "${cand}" — a CANDIDATE, not applied (M-ADR 0211 §4.3, class 3)`);
+                    }
+                }
+                continue;
+            }
+            const key = `${capId}__${sid}__${(entry.role ?? "") !== "" ? entry.role : "related"}`;
+            if (seen.has(key)) {
+                deduplicated++;
+                continue;
+            }
+            seen.add(key);
+            expectedRows++;
+        }
+    }
+    const rows = inputs.capabilityServiceRows.length;
+    const balances = declared === rows + unresolved + deduplicated + capabilityUnknown;
+    inputs.findings.add("metric", `capability_service: declared=${declared} rows=${rows} unresolved=${unresolved} deduplicated=${deduplicated} capability-unknown=${capabilityUnknown} (cross-SDD via owner_sdd=${crossSdd}); unresolved by class: external-system=${externalSystem} declared-container=${declaredContainer} nowhere=${nowhere}`);
+    if (!balances) {
+        inputs.findings.add("coverage", `capability_service: the population does not balance — declared ${declared} ≠ rows ${rows} + unresolved ${unresolved} + deduplicated ${deduplicated} + capability-unknown ${capabilityUnknown} (expected rows from declarations: ${expectedRows}). Two instruments disagree; adjudicate, do not smooth (M-ADR 0211 §4.3)`);
+    }
+    return { declared, rows, unresolved, deduplicated, capabilityUnknown, crossSdd, externalSystem, declaredContainer, nowhere, balances };
+}
+//# sourceMappingURL=population-checks.js.map

package/dist/lib/catalogue/relationship-semantics.js

@@ -0,0 +1,66 @@
+// Relationship semantics and catalogue kinds, read from the vendored
+// rubric-coverage-map.yaml — READ-ONLY. Split out of `graph-run.ts`, which also
+// holds `runCatalogueGraph`, the verb that writes `<catalogues-dir>-graph.jsonl`
+// by default. `catalogue impact` needs these loaders and nothing that writes,
+// and the verify-only CLI ships `impact` (M-ADR 0212 §4.3b): while they lived in
+// graph-run the writer came along with them, and the package build caught it.
+// `graph-run.ts` re-exports everything here, so existing imports are unchanged.
+import { readFile } from "node:fs/promises";
+import { fileURLToPath } from "node:url";
+import { join } from "node:path";
+import { parse as parseYaml } from "yaml";
+/**
+ * Vendored copy of sdd-method's orchestration/rubric-coverage-map.yaml —
+ * byte-identical to the canonical (rubric-coverage-map-drift.test.ts guards
+ * it, same one-way contract as canonical-schema.yaml). The build copies it
+ * alongside the compiled module via scripts/copy-yaml-assets.mjs.
+ */
+export const VENDORED_COVERAGE_MAP_PATH = join(fileURLToPath(new URL(".", import.meta.url)), "rubric-coverage-map.yaml");
+function toDecl(where, e) {
+    if (e.class === undefined) {
+        throw new Error(`rubric-coverage-map: ${where} has no class declaration (M-ADR 0206)`);
+    }
+    if ((e.impact_flow === undefined) === (e.impact_flow_by === undefined)) {
+        throw new Error(`rubric-coverage-map: ${where} must declare exactly one of impact_flow / impact_flow_by`);
+    }
+    return {
+        class: e.class,
+        ...(e.impact_flow !== undefined
+            ? { impactFlow: e.impact_flow }
+            : {}),
+        ...(e.impact_flow_by !== undefined
+            ? {
+                impactFlowBy: {
+                    column: e.impact_flow_by.column,
+                    values: e.impact_flow_by.values,
+                },
+            }
+            : {}),
+    };
+}
+export async function loadRelationshipSemantics(mapPath = VENDORED_COVERAGE_MAP_PATH) {
+    const raw = parseYaml(await readFile(mapPath, "utf-8"));
+    const kinds = new Map();
+    const edges = new Map();
+    const entityFks = new Map();
+    for (const [name, entry] of Object.entries(raw.coverage)) {
+        kinds.set(name, entry.kind);
+        if (entry.kind === "edge" || entry.kind === "annotation") {
+            // an annotation classifies at top level exactly as an edge does (schema 3.9.0)
+            edges.set(name, toDecl(`edge ${name}`, entry));
+        }
+        for (const [col, decl] of Object.entries(entry.relationships ?? {})) {
+            entityFks.set(`${name}.${col}`, toDecl(`entity FK ${name}.${col}`, decl));
+        }
+    }
+    return { kinds, edges, entityFks };
+}
+export async function loadCatalogueKinds(mapPath = VENDORED_COVERAGE_MAP_PATH) {
+    const raw = parseYaml(await readFile(mapPath, "utf-8"));
+    const kinds = new Map();
+    for (const [name, entry] of Object.entries(raw.coverage)) {
+        kinds.set(name, entry.kind);
+    }
+    return kinds;
+}
+//# sourceMappingURL=relationship-semantics.js.map

package/dist/lib/catalogue/reverse-product-quality.js

@@ -0,0 +1,99 @@
+// Reverse product-quality scores → the `products` maturity columns.
+//
+// WHY THIS EXISTS. `products` carried two maturity mechanisms and BOTH were inert:
+//   - `status` (documented `scaffolded | populated | reviewed`) was hardcoded to
+//     `"active"`, a value outside its own vocabulary — removed at schema 3.0.0;
+//   - `synthesis_quality` / `synthesis_band` / `last_assessed`, designed for exactly
+//     this data, were populated on 0 of 208 rows across two estates.
+//
+// Meanwhile the reverse estate holds 131 gate-registry score files, of which
+// `reverse-product-quality-scores.yaml` is the family at PRODUCT granularity — the
+// only one whose unit is a product row. So the fix is to fill the richer column from
+// the data that already exists, rather than populate the coarser one from a weaker
+// signal and leave this empty beside it.
+//
+// SCOPE, measured rather than assumed: 45 such files exist, but 24 are empty shells
+// and several units describe *covered* sub-products rather than the SDD's own. Using
+// the self-product rule below, 15 units qualify and 12 carry a score. So this
+// populates ~12 rows today — a real but modest yield, and additive: it only fills
+// empty nullable cells, so no existing row changes value.
+//
+// THE SELF-PRODUCT RULE. A file may list several units (one estate file lists nine).
+// The SDD's own product is the unit whose `product_path` is `.` AND whose key equals
+// the SDD's `sdd_id`. Both conditions are required: `product_path` alone admits
+// synthetic gate fixtures (three exist under one platform SDD with keys like
+// `beta/product-pass`), and key-matching alone admits covered sub-products.
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { parse as parseYaml } from "yaml";
+export const REVERSE_PRODUCT_QUALITY_REL = "orchestration/gate-registry/reverse-product-quality-scores.yaml";
+/** The closed band vocabulary (catalogue-schema `products.synthesis_band`). */
+export const SYNTHESIS_BANDS = ["developing", "working", "strong"];
+/**
+ * Read this SDD's own product-quality score, if the reverse gate registry has one.
+ *
+ * Returns an empty object when the file is absent, unparseable, has no units, or has
+ * no self-product unit — all normal states, not defects. A forward-authored estate has
+ * no reverse scores at all, and the columns stay empty there by design (the schema
+ * documents them as reverse-method only).
+ */
+export async function loadReverseProductQuality(sddPath, sddId, findings) {
+    let text;
+    try {
+        text = await readFile(join(sddPath, REVERSE_PRODUCT_QUALITY_REL), "utf-8");
+    }
+    catch (err) {
+        if (err.code === "ENOENT")
+            return {};
+        throw err;
+    }
+    let raw;
+    try {
+        raw = parseYaml(text);
+    }
+    catch (err) {
+        // A malformed registry must not fail the build: the catalogue is still correct
+        // without the score. Say so rather than silently emitting empty columns.
+        findings.add("convention", `${REVERSE_PRODUCT_QUALITY_REL}: failed to parse YAML — product maturity columns left empty (${err.message})`);
+        return {};
+    }
+    const doc = (raw ?? {});
+    const units = doc.units;
+    if (typeof units !== "object" || units === null)
+        return {};
+    // The self-product rule: `product_path: .` AND key === sdd_id. See the header.
+    const unit = units[sddId];
+    if (!unit || typeof unit !== "object")
+        return {};
+    const productPath = String(unit.product_path ?? "").trim();
+    if (productPath !== ".")
+        return {};
+    const q = unit.product_synthesis_quality;
+    if (!q || typeof q !== "object")
+        return {};
+    const out = {};
+    if (typeof q.total === "number" && Number.isFinite(q.total)) {
+        if (q.total < 0 || q.total > 10) {
+            findings.add("convention", `${REVERSE_PRODUCT_QUALITY_REL}: units.${sddId} total ${q.total} is outside the rubric range 0-10 — left empty`);
+        }
+        else {
+            out.quality = q.total;
+        }
+    }
+    const band = String(q.band ?? "").trim();
+    if (band !== "") {
+        if (SYNTHESIS_BANDS.includes(band)) {
+            out.band = band;
+        }
+        else {
+            // A band outside the closed vocabulary is reported, not passed through: the
+            // column would otherwise carry a value no consumer can interpret.
+            findings.add("convention", `${REVERSE_PRODUCT_QUALITY_REL}: units.${sddId} band "${band}" is not in {${SYNTHESIS_BANDS.join(" | ")}} — left empty`);
+        }
+    }
+    const assessedAt = String(doc.assessed_at ?? "").trim();
+    if (/^\d{4}-\d{2}-\d{2}$/.test(assessedAt))
+        out.assessedAt = assessedAt;
+    return out;
+}
+//# sourceMappingURL=reverse-product-quality.js.map