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

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