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

package/dist/lib/catalogue/runway-vocabulary-loader.js

@@ -0,0 +1,56 @@
+/**
+ * Loader for the optional `feature-runway-vocabulary.yaml` config that
+ * adopters can ship at the SDD root (schema 2.2.0+).
+ *
+ * The file declares a controlled vocabulary for the `runway` column on
+ * `features.csv`. When present, the canonical builder validates
+ * captured runway values against the declared `values[*].id` set;
+ * unknown values emit a `convention` finding. When absent, no
+ * validation runs and any runway value is accepted verbatim.
+ *
+ * The method does NOT bless any vocabulary — there is no method-level
+ * enum, no canonical mapping, no normalisation. See
+ * catalogue-metamodel.md §"Runway vocabulary (informative recipe)" for
+ * the rationale.
+ */
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { parse as parseYaml } from "yaml";
+const VOCABULARY_FILENAME = "feature-runway-vocabulary.yaml";
+/**
+ * Load the optional vocabulary from `<sddPath>/feature-runway-vocabulary.yaml`.
+ * Returns `null` when the file is absent — callers treat that as "no
+ * validation runs". Throws on malformed YAML or a missing/non-array
+ * `values` key (the file exists, so the adopter intends validation;
+ * fail loud rather than silently disable it).
+ */
+export async function loadRunwayVocabulary(sddPath) {
+    const full = join(sddPath, VOCABULARY_FILENAME);
+    let text;
+    try {
+        text = await readFile(full, "utf-8");
+    }
+    catch (err) {
+        const code = err.code;
+        if (code === "ENOENT")
+            return null;
+        throw err;
+    }
+    const raw = parseYaml(text);
+    if (raw === null || typeof raw !== "object") {
+        throw new Error(`${VOCABULARY_FILENAME}: expected a mapping at the document root`);
+    }
+    if (!Array.isArray(raw.values)) {
+        throw new Error(`${VOCABULARY_FILENAME}: expected a 'values:' array at the document root`);
+    }
+    const values = new Set();
+    for (const entry of raw.values) {
+        if (entry === null || typeof entry !== "object")
+            continue;
+        const id = entry.id;
+        if (typeof id === "string" && id !== "")
+            values.add(id);
+    }
+    return { values, relPath: VOCABULARY_FILENAME };
+}
+//# sourceMappingURL=runway-vocabulary-loader.js.map

package/dist/lib/catalogue/scaffold-delta.js

@@ -0,0 +1,261 @@
+// Scaffold delta — M-ADR 0207 §4.8: the declared-vs-derived delta computed on
+// the engine, plus the scaffold-coverage predicate (every non-closed scaffold
+// carries a current anchor and a computable delta; a closed scaffold sits at
+// delta zero). REPORTING-ONLY at both tiers per §4.9 — no gating tier ships
+// until the pilot's stated-in-advance figures land, and promotion is a
+// deliberate later act (change the class in one place, say so in the
+// change-set — the scores-coverage precedent, word for word).
+//
+// Finding classes:
+//   declared-unrealised — a `declared` item under a CLOSED scaffold. §4.3's
+//       first presumption: the scaffold is right, the work is incomplete.
+//       Under an OPEN scaffold the same state is the computable backlog and
+//       lands in the per-scaffold metric, never as a finding (§4.2).
+//   realised-undeclared — an edge row whose BOTH endpoints are this
+//       scaffold's own realised entity targets, with no declaring item. The
+//       unit's scope is the entity set it declares (§4.2/§4.4): work fully
+//       inside that set that was never declared is scope drift made loud;
+//       edges to the rest of the estate are integration, not drift.
+//   resolution-disagreement — the builder's derived `state` disagrees with
+//       the engine's own re-derivation. Conforming builds cannot produce it
+//       (resolution is what computes state), so any instance is an
+//       instrument defect, adjudicated per M-ADR 0205 §4.4 — never smoothed.
+//   scaffold-stale — the §4.6 verdict. MEMBER TIER ONLY, stated not silent
+//       (the staleness-verdicts precedent): a per-target verdict needs the
+//       target's git history, which only contract items carry a path for.
+//       Entity/edge items are counted as pathless rather than guessed at;
+//       an anchor the repo does not know is UNKNOWN, never presumed stale.
+import { execFile as execFileCb } from "node:child_process";
+import { promisify } from "node:util";
+const execFile = promisify(execFileCb);
+const EMPTY = {
+    findings: [],
+    metrics: [],
+    staleness: { assessedPaths: 0, unknownAnchor: 0, pathlessItems: 0 },
+};
+const sqlStr = (s) => `'${s.replace(/'/g, "''")}'`;
+async function rows(session, sql) {
+    const reader = await session.conn.runAndReadAll(sql);
+    return reader.getRows();
+}
+function refCatalogue(reference) {
+    return reference.split(".")[0] ?? "";
+}
+/**
+ * Re-derive one item's realisation on the engine — the §4.8 self-check. A
+ * target whose catalogue is absent from the session cannot resolve.
+ */
+async function engineResolves(session, available, catalogue, item) {
+    if (!available.has(item.targetKind))
+        return false;
+    if (item.itemKind === "edge") {
+        const [srcFk, dstFk] = [catalogue.foreignKeys[0], catalogue.foreignKeys[1]];
+        if (!srcFk || !dstFk)
+            return false;
+        const n = await rows(session, `SELECT COUNT(*) FROM "${item.targetKind}" WHERE "${srcFk.column}" = ${sqlStr(item.edgeSourceRef)} AND "${dstFk.column}" = ${sqlStr(item.edgeTargetRef)};`);
+        return Number(n[0][0]) > 0;
+    }
+    const matchCol = item.itemKind === "contract" ? "spec_path" : catalogue.primaryKey;
+    const n = await rows(session, `SELECT COUNT(*) FROM "${item.targetKind}" WHERE "${matchCol}" = ${sqlStr(item.targetRef)};`);
+    return Number(n[0][0]) > 0;
+}
+async function gitKnowsCommit(sddRoot, ref) {
+    try {
+        await execFile("git", ["-C", sddRoot, "cat-file", "-e", `${ref}^{commit}`]);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function pathChangedSince(sddRoot, anchor, path) {
+    try {
+        const { stdout } = await execFile("git", [
+            "-C",
+            sddRoot,
+            "log",
+            "-1",
+            "--format=%h %ad",
+            "--date=short",
+            `${anchor}..HEAD`,
+            "--",
+            path,
+        ]);
+        const line = stdout.trim();
+        return line === "" ? null : line;
+    }
+    catch {
+        return null;
+    }
+}
+export async function runScaffoldDelta(session, options) {
+    const { tier, available, schema, sddRoot } = options;
+    if (!available.has("scaffolds") || !available.has("scaffold_items"))
+        return EMPTY;
+    const scaffoldRows = await rows(session, `SELECT id, status, corpus_ref FROM "scaffolds" ORDER BY id;`);
+    if (scaffoldRows.length === 0)
+        return EMPTY;
+    const itemRows = (await rows(session, `SELECT scaffold_id, item_kind, target_kind, target_ref, edge_source_ref, edge_target_ref, state
+       FROM "scaffold_items" ORDER BY id;`)).map((r) => ({
+        scaffoldId: String(r[0]),
+        itemKind: String(r[1]),
+        targetKind: String(r[2]),
+        targetRef: String(r[3]),
+        edgeSourceRef: String(r[4] ?? ""),
+        edgeTargetRef: String(r[5] ?? ""),
+        state: String(r[6]),
+    }));
+    const catalogueByName = new Map(schema.catalogues.map((c) => [c.name, c]));
+    const findings = [];
+    const metrics = [];
+    const staleness = { assessedPaths: 0, unknownAnchor: 0, pathlessItems: 0 };
+    if (tier === "aggregate") {
+        staleness.skipped =
+            "aggregate tier — sibling repos' git histories are not local, and a verdict there would be a guess";
+    }
+    for (const s of scaffoldRows) {
+        const scaffoldId = String(s[0]);
+        const status = String(s[1]);
+        const corpusRef = String(s[2]);
+        const items = itemRows.filter((i) => i.scaffoldId === scaffoldId);
+        const declared = items.filter((i) => i.state === "declared");
+        const realised = items.filter((i) => i.state === "realised");
+        metrics.push({ scaffoldId, status, declared: declared.length, realised: realised.length });
+        // declared-unrealised — only a finding once the scaffold is closed (§4.2/§4.3).
+        if (status === "closed") {
+            for (const item of declared) {
+                findings.push({
+                    kind: "declared-unrealised",
+                    scaffoldId,
+                    detail: `${item.itemKind} ${item.targetKind}/${item.targetRef} is declared but unrealised under a closed scaffold — the scaffold presumes right: the work is incomplete, or the scaffold needs a recorded amendment (M-ADR 0207 §4.3)`,
+                });
+            }
+        }
+        // resolution self-check (§4.8) — the engine re-derives every item's state.
+        for (const item of items) {
+            const cat = catalogueByName.get(item.targetKind);
+            if (!cat)
+                continue; // builder already reported unknown target_kind
+            const resolves = await engineResolves(session, available, cat, item);
+            const expected = resolves ? "realised" : "declared";
+            if (item.state !== expected) {
+                findings.push({
+                    kind: "resolution-disagreement",
+                    scaffoldId,
+                    detail: `${item.itemKind} ${item.targetKind}/${item.targetRef} carries state '${item.state}' but the engine derives '${expected}' — an instrument defect in one side, adjudicated, never smoothed (M-ADR 0205 §4.4)`,
+                });
+            }
+        }
+        // realised-undeclared — edges wholly inside the scaffold's own realised
+        // entity set that no item declares (§4.2).
+        const realisedEntityRefs = new Map();
+        for (const item of realised) {
+            if (item.itemKind !== "entity")
+                continue;
+            const set = realisedEntityRefs.get(item.targetKind) ?? new Set();
+            set.add(item.targetRef);
+            realisedEntityRefs.set(item.targetKind, set);
+        }
+        const declaredEdgePairs = new Set(items
+            .filter((i) => i.itemKind === "edge")
+            .map((i) => `${i.targetKind}|${i.edgeSourceRef}|${i.edgeTargetRef}`));
+        if (realisedEntityRefs.size > 0) {
+            for (const cat of schema.catalogues) {
+                const [srcFk, dstFk] = [cat.foreignKeys[0], cat.foreignKeys[1]];
+                if (!srcFk || !dstFk || !available.has(cat.name))
+                    continue;
+                const srcRefs = realisedEntityRefs.get(refCatalogue(srcFk.references));
+                const dstRefs = realisedEntityRefs.get(refCatalogue(dstFk.references));
+                if (!srcRefs?.size || !dstRefs?.size)
+                    continue;
+                const inList = (vals) => [...vals].sort().map(sqlStr).join(", ");
+                const pairs = await rows(session, `SELECT "${srcFk.column}", "${dstFk.column}" FROM "${cat.name}"
+           WHERE "${srcFk.column}" IN (${inList(srcRefs)})
+             AND "${dstFk.column}" IN (${inList(dstRefs)})
+           ORDER BY 1, 2;`);
+                for (const [a, b] of pairs) {
+                    const key = `${cat.name}|${String(a)}|${String(b)}`;
+                    if (declaredEdgePairs.has(key))
+                        continue;
+                    findings.push({
+                        kind: "realised-undeclared",
+                        scaffoldId,
+                        detail: `edge ${cat.name} ${String(a)} -> ${String(b)} joins two of this scaffold's declared entities but is not itself declared — scope drift made loud; amend the scaffold in the same change-set (M-ADR 0207 §4.3)`,
+                    });
+                }
+            }
+        }
+        // scaffold-stale (§4.6) — member tier, per-path verdicts only.
+        if (tier === "member") {
+            if (!(await gitKnowsCommit(sddRoot, corpusRef))) {
+                staleness.unknownAnchor += 1;
+            }
+            else {
+                for (const item of items) {
+                    if (item.itemKind !== "contract") {
+                        staleness.pathlessItems += 1;
+                        continue;
+                    }
+                    staleness.assessedPaths += 1;
+                    const moved = await pathChangedSince(sddRoot, corpusRef, item.targetRef);
+                    if (moved !== null) {
+                        findings.push({
+                            kind: "scaffold-stale",
+                            scaffoldId,
+                            detail: `anchor ${corpusRef} predates a change to ${item.targetRef} (${moved}) — re-declare against the current corpus before acting on this scaffold's delta (M-ADR 0207 §4.6/§4.3)`,
+                        });
+                    }
+                }
+            }
+        }
+    }
+    findings.sort((a, b) => a.scaffoldId.localeCompare(b.scaffoldId) ||
+        a.kind.localeCompare(b.kind) ||
+        a.detail.localeCompare(b.detail));
+    return { findings, metrics, staleness };
+}
+/**
+ * The delta's DEFECT classes are gate-acting (`divergence`), PROMOTED by a
+ * recorded governance act after the M-ADR 0207 §4.9 pilot completed with no
+ * surprise in any gated figure (2026-08-08) — the deliberate later act the
+ * scores-coverage precedent reserves, performed. `scaffold-stale` stays
+ * `coverage` with its staleness family: a stale anchor is a re-declare
+ * prompt, and gating on git-history movement would alarm, not measure.
+ */
+const PROMOTED = new Set([
+    "declared-unrealised",
+    "realised-undeclared",
+    "resolution-disagreement",
+]);
+export function renderScaffoldDelta(res, tier) {
+    // Silent only when there is genuinely nothing measured: no scaffolds is the
+    // designed zero-adoption state (M-ADR 0207 §4.4), not a suppressed report.
+    if (res.metrics.length === 0)
+        return [];
+    const out = [];
+    for (const f of res.findings) {
+        const cls = PROMOTED.has(f.kind) ? "divergence" : "coverage";
+        out.push(`[finding] ${cls}: scaffold ${f.scaffoldId}: [${f.kind}] ${f.detail}`);
+    }
+    for (const m of res.metrics) {
+        // The line carries the TOTAL, not just the outstanding count: the first
+        // pilot's checkpoint log read like a shrinking denominator because
+        // "N declared" meant outstanding. "M outstanding of T declared" cannot
+        // be misread that way.
+        const delta = m.declared;
+        const total = m.declared + m.realised;
+        out.push(`[metric] scaffold_delta (${tier}): ${m.scaffoldId} (${m.status}) — ` +
+            `${m.realised} realised, ${m.declared} outstanding of ${total} declared; delta ${delta}` +
+            (m.status === "closed" && delta > 0 ? " (closed scaffold, delta not zero)" : ""));
+    }
+    const s = res.staleness;
+    if (s.skipped) {
+        out.push(`[metric] scaffold_staleness: skipped — ${s.skipped}`);
+    }
+    else if (s.assessedPaths + s.unknownAnchor + s.pathlessItems > 0) {
+        out.push(`[metric] scaffold_staleness: ${s.assessedPaths} path verdict(s) attempted, ` +
+            `${s.unknownAnchor} unknown anchor(s), ${s.pathlessItems} pathless item(s) (no per-target verdict possible — stated, not guessed)`);
+    }
+    return out;
+}
+//# sourceMappingURL=scaffold-delta.js.map

package/dist/lib/catalogue/schema-compat.js

@@ -0,0 +1,52 @@
+/**
+ * Per-schema compatibility ranges declared by this sdd-cli build.
+ *
+ * Per resolution of adopt-canonical-catalogue-builder.md §7.5, the three
+ * sdd-method-distributed schemas version independently. The CLI declares
+ * the version range it accepts for each and fails fast at read time on
+ * out-of-range manifests.
+ *
+ * Range semantics: caret-prefixed semver (`^X.Y.Z`) — accept any version
+ * in the same major. Bump these in lockstep with sdd-method releases that
+ * change a schema's major version. Minor/patch bumps in sdd-method should
+ * NOT require updating the entries here.
+ *
+ * Schemas:
+ *   - catalogue_schema:        docs/method/foundations/schemas/catalogue-schema.yaml
+ *   - sdd_manifest:            docs/method/foundations/schemas/sdd-manifest-schema.yaml
+ *   - aggregation_manifest:    docs/method/foundations/schemas/aggregation-manifest-schema.yaml
+ *
+ * Bump rules per schema (in their respective YAML headers):
+ *   - Patch: typo / description / non-structural fix.
+ *   - Minor: additive change. Backward compatible — older readers ignore
+ *     new fields. SCHEMA_COMPAT does NOT need updating.
+ *   - Major: breaking change. SCHEMA_COMPAT MUST be updated in this
+ *     release; migration tooling (`sdd-cli migrate <schema> --to <v>`,
+ *     planned) covers downgrade paths.
+ *
+ * See ADR 0132 (catalogue-integrity gate's schema-drift digest hook) +
+ * ADR 0134 §4.6 (canonical builder + aggregator).
+ */
+export const SCHEMA_COMPAT = {
+    catalogue_schema: "^3.0.0",
+    sdd_manifest: "^1.0.0",
+    aggregation_manifest: "^1.0.0",
+};
+/**
+ * Format a schema-version mismatch error consistently across all three
+ * schemas. Used by the per-SDD builder, the aggregator, and the
+ * `sdd-cli catalogue validate` subcommand.
+ */
+export function formatSchemaVersionMismatch(args) {
+    const supports = SCHEMA_COMPAT[args.schema];
+    return [
+        `schema version mismatch for ${args.schema}`,
+        `  read:      ${args.sourcePath} @ schema_version ${args.readVersion}`,
+        `  cli:       sdd-cli v${args.cliVersion}`,
+        `  supports:  ${supports}`,
+        "",
+        "Upgrade sdd-cli or downgrade the manifest. Migration tooling:",
+        `sdd-cli migrate ${args.schema} --to <version> (planned, not yet shipped).`,
+    ].join("\n");
+}
+//# sourceMappingURL=schema-compat.js.map

package/dist/lib/catalogue/schema-loader.js

@@ -0,0 +1,87 @@
+/**
+ * Loader for the canonical catalogue-schema.yaml vendored from sdd-method.
+ *
+ * Per ADR 0134 §4.6 the canonical builder reads the schema rather than
+ * hardcoding column shapes or FK rules. This loader is the only place in
+ * the CLI that knows the schema file's location.
+ */
+import { readFile } from "node:fs/promises";
+import { fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
+import { parse as parseYaml } from "yaml";
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+/**
+ * Default location of the vendored canonical schema, relative to this
+ * compiled module. The build copies the YAML alongside the JS via
+ * scripts/copy-yaml-assets.mjs, so at runtime it sits next to the
+ * compiled schema-loader.js.
+ */
+export const VENDORED_SCHEMA_PATH = join(__dirname, "canonical-schema.yaml");
+export async function loadCanonicalSchema(schemaPath = VENDORED_SCHEMA_PATH) {
+    const text = await readFile(schemaPath, "utf-8");
+    // `merge: true` resolves YAML merge keys (`<<: *anchor`) — used by
+    // `applications: <<: *products_def` in the canonical schema to express
+    // the filtered-view catalogue without duplicating the products def.
+    const raw = parseYaml(text, { merge: true });
+    return normalise(raw);
+}
+function normalise(raw) {
+    const catalogues = Object.entries(raw.catalogues).map(([name, def]) => ({
+        name,
+        primaryKey: def.primary_key,
+        ...(def.description !== undefined ? { description: def.description } : {}),
+        columns: def.columns.map((c) => ({
+            name: c.name,
+            type: c.type,
+            nullable: c.nullable ?? false,
+            ...(c.description !== undefined ? { description: c.description } : {}),
+        })),
+        foreignKeys: (def.foreign_keys ?? []).map((fk) => ({
+            column: fk.column,
+            references: fk.references,
+            nullable: fk.nullable ?? false,
+            external: fk.external ?? false,
+            externalForProfiles: fk.external_for_profiles ?? [],
+        })),
+        columnEnums: def.column_enums ?? {},
+    }));
+    const enums = {};
+    for (const [name, def] of Object.entries(raw.enums ?? {})) {
+        enums[name] = {
+            name,
+            ...(def.description !== undefined ? { description: def.description } : {}),
+            values: def.values.map((v) => ({
+                value: v.value,
+                ...(v.runtime !== undefined ? { runtime: v.runtime } : {}),
+                ...(v.emits_service_row !== undefined
+                    ? { emitsServiceRow: v.emits_service_row }
+                    : {}),
+                ...(v.description !== undefined ? { description: v.description } : {}),
+            })),
+        };
+    }
+    return {
+        schemaVersion: raw.schema_version,
+        schemaOwner: raw.schema_owner,
+        schemaStatus: raw.schema_status,
+        catalogues,
+        enums,
+    };
+}
+/** Look up a catalogue by name; throws if absent. */
+export function findCatalogue(schema, name) {
+    const found = schema.catalogues.find((c) => c.name === name);
+    if (!found) {
+        throw new Error(`catalogue "${name}" not declared in canonical schema`);
+    }
+    return found;
+}
+/** Returns the set of `service_type` values that are runtime services (emit_service_row=true). */
+export function runtimeServiceTypes(schema) {
+    const enumDef = schema.enums["service_type"];
+    if (!enumDef)
+        return new Set();
+    return new Set(enumDef.values.filter((v) => v.emitsServiceRow === true).map((v) => v.value));
+}
+//# sourceMappingURL=schema-loader.js.map