@sdd-method/verify-cli 5.5.1 → 5.7.0

package/dist/lib/validate/derived-specs.js

@@ -0,0 +1,300 @@
+// derived-specs (M-ADR 0232): the living specs an executable source owns are what its pinned generator derives from it,
+// with no hand edit and no stale derivation; every requirement and scenario names the declared field behind it
+// (M-ADR 0211); and every derived feature is a catalogue feature. Where the pinned generator cannot run on this
+// machine, digests are compared instead, and the report says so, so a weaker check never reads as the full one.
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { parse as parseYaml } from "yaml";
+import { parseCatalogueCsv } from "../catalogue/csv-reader.js";
+import { DERIVED_CONFIG, DERIVED_LOCK, generate, generatorIdentity, inputStates, livingSpecs, loadDerivedSources, openDerivations, requirementsWithoutScenario, loadLock, parseSource, pathWithin, resolvePath, resolveSourcePath, renderPath, sha256, specBlocks, } from "../derived-specs/index.js";
+const POSITIVE_SUPPLY = new Set(["supported", "partial"]);
+async function csvRows(path) {
+    return readFile(path, "utf8")
+        .then((t) => parseCatalogueCsv(t).rows.map((r) => Object.fromEntries(Object.entries(r).map(([k, v]) => [k, String(v ?? "")]))))
+        .catch(() => null);
+}
+async function supplyContext(repo, platformRoot) {
+    const m = await readFile(join(repo, ".sdd", "sdd-manifest.yaml"), "utf8").then((t) => parseYaml(t)).catch(() => null);
+    if (m?.["profile"] !== "integration-product")
+        return null;
+    const sddId = String(m["sdd_id"] ?? "");
+    let registry = null;
+    let registryFrom = "no data-item registry here (the platform's catalogue was not found)";
+    for (const [root, label] of [[repo, "this repository's catalogue"], [platformRoot, "the platform's catalogue"]]) {
+        if (root === undefined)
+            continue;
+        const rows = await csvRows(join(root, "catalogues", "data_items.csv"));
+        if (rows !== null && rows.length > 0) {
+            registry = new Map(rows.map((r) => [r["id"], r["category"]]));
+            registryFrom = label;
+            break;
+        }
+    }
+    const supply = (await csvRows(join(repo, "catalogues", "integration_data_item.csv"))) ?? [];
+    const supplied = new Set(supply.filter((r) => POSITIVE_SUPPLY.has(r["verdict"] ?? "")).map((r) => r["data_item_id"]));
+    return { sddId, registry, registryFrom, supplied };
+}
+export async function checkDerivedSpecs(repo, platformRoot) {
+    let sources;
+    try {
+        sources = await loadDerivedSources(repo);
+    }
+    catch (e) {
+        return { exitCode: 1, stdout: `[FAIL] ${e.message}\n` };
+    }
+    if (sources === null || sources.length === 0) {
+        return { exitCode: 0, stdout: `[N/A] no derived sources (${DERIVED_CONFIG}) in this repository\n` };
+    }
+    const lock = new Map((await loadLock(repo)).map((l) => [l.id, l]));
+    const living = await livingSpecs(repo);
+    const catalogueFeatures = await readFile(join(repo, "catalogues", "features.csv"), "utf8")
+        .then((t) => new Set(parseCatalogueCsv(t).rows.map((r) => String(r["id"]))))
+        .catch(() => null);
+    const failures = [];
+    const warnings = [];
+    const lines = [];
+    const owner = new Map();
+    const supply = await supplyContext(repo, platformRoot);
+    for (const s of sources) {
+        const where = `derived source '${s.id}' (${s.source})`;
+        const sourceText = await readFile(join(repo, s.source), "utf8").catch(() => null);
+        if (sourceText === null) {
+            failures.push(`${where}: the source file does not exist`);
+            continue;
+        }
+        const rec = lock.get(s.id);
+        if (rec === undefined) {
+            const pending = await openDerivations(repo, s.id);
+            if (pending.length > 0)
+                warnings.push(`${where}: first derivation pending in ${pending.map((c) => `'${c}'`).join(", ")}; no derivation record until it archives (M-ADR 0232 §4.7)`);
+            else
+                failures.push(`${where}: no derivation record in ${DERIVED_LOCK}, and no open change derives it; derive it through a baseline (M-ADR 0232 §4.7)`);
+            continue;
+        }
+        for (const sp of rec.specs) {
+            const prior = owner.get(sp.feature);
+            if (prior !== undefined)
+                failures.push(`feature '${sp.feature}' is owned by two derived sources ('${prior}' and '${s.id}')`);
+            owner.set(sp.feature, s.id);
+        }
+        // What the specs were derived with must be what is pinned now: the generator and every declared input. A pin that moved
+        // without regeneration is a stale derivation, named by its cause, never read as a hand edit. It is pending, a warning,
+        // while an open change carries the source's regeneration (derived/<id>); otherwise it fails.
+        const drift = [];
+        if (rec.generator?.identity !== s.generator.identity || rec.generator?.version !== s.generator.version) {
+            drift.push(`the generator pin is ${s.generator.identity} ${s.generator.version}, but the specs were derived with ${rec.generator?.identity ?? "?"} ${rec.generator?.version ?? "?"}`);
+        }
+        const recordedInputs = new Map((rec.inputs ?? []).map((x) => [x.id, x.sha256]));
+        for (const x of s.inputs) {
+            const was = recordedInputs.get(x.id);
+            if (was === undefined)
+                drift.push(`input '${x.id}' is pinned at ${x.sha256.slice(0, 12)}, but the specs were derived without it`);
+            else if (was !== x.sha256)
+                drift.push(`input '${x.id}' is pinned at ${x.sha256.slice(0, 12)}, but the specs were derived with ${was.slice(0, 12)}`);
+        }
+        for (const id of recordedInputs.keys()) {
+            if (!s.inputs.some((x) => x.id === id))
+                drift.push(`input '${id}' is recorded but no longer declared`);
+        }
+        if (drift.length > 0) {
+            const pending = await openDerivations(repo, s.id);
+            for (const d of drift) {
+                if (pending.length > 0)
+                    warnings.push(`${where}: ${d}; regeneration pending in ${pending.map((c) => `'${c}'`).join(", ")} (M-ADR 0232 §4.3)`);
+                else
+                    failures.push(`${where}: ${d} (a stale derivation, not a hand edit); regenerate through a change (M-ADR 0232 §4.3)`);
+            }
+        }
+        // Full check: regenerate with the pinned generator from the pinned inputs, and compare. Fallback: compare digests,
+        // and say why, so a weaker check never reads as the full one.
+        const ident = await generatorIdentity(repo, s.generator, s.inputs);
+        let why = null;
+        if (ident === null)
+            why = "the generator is not available here";
+        else if (ident.identity !== s.generator.identity || ident.version !== s.generator.version)
+            why = `the installed generator is ${ident.identity} ${ident.version}, not the pinned ${s.generator.version}`;
+        for (const st of await inputStates(repo, s.inputs)) {
+            if (why !== null)
+                break;
+            if (st.digest === null)
+                why = `input '${st.input.id}' is not available here (${st.location})`;
+            else if (st.digest !== st.input.sha256)
+                why = `input '${st.input.id}' at ${st.location} is ${st.digest.slice(0, 12)}, not the pinned ${st.input.sha256.slice(0, 12)}`;
+        }
+        if (why === null && drift.length > 0)
+            why = "a pin moved since the derivation was recorded";
+        if (why === null) {
+            let derived;
+            try {
+                derived = await generate(repo, s, s.source);
+            }
+            catch (e) {
+                failures.push(`${where}: the generator failed: ${e.message}`);
+                continue;
+            }
+            const recorded = new Set(rec.specs.map((x) => x.feature));
+            for (const [feature, text] of derived) {
+                if (!recorded.has(feature))
+                    failures.push(`${where}: the generator emits '${feature}', which the derivation record does not own; regenerate through a change`);
+                else if (living.get(feature) !== text)
+                    failures.push(`${where}: openspec/specs/${feature}/spec.md differs from what the source derives (a hand edit, or the source changed without regeneration)`);
+            }
+            for (const f of recorded)
+                if (!derived.has(f))
+                    failures.push(`${where}: '${f}' is recorded as derived but the generator no longer emits it`);
+            const fromInputs = s.inputs.length > 0 ? ` from ${s.inputs.map((x) => `${x.id} ${x.sha256.slice(0, 12)}`).join(", ")}` : "";
+            lines.push(`  ${s.id}: regenerated with ${ident.identity} ${ident.version} (${ident.commit})${fromInputs} and compared: ${derived.size} living spec(s)`);
+        }
+        else {
+            if (sha256(sourceText) !== rec.source_sha256)
+                failures.push(`${where}: the source changed since its derivation was recorded (a stale derivation); regenerate through a change`);
+            for (const sp of rec.specs) {
+                const t = living.get(sp.feature);
+                if (t === undefined)
+                    failures.push(`${where}: recorded living spec '${sp.feature}' is missing`);
+                else if (sha256(t) !== sp.sha256)
+                    failures.push(`${where}: openspec/specs/${sp.feature}/spec.md differs from its recorded digest (a hand edit)`);
+            }
+            lines.push(`  ${s.id}: digests compared, NOT regenerated (${why}): ${rec.specs.length} living spec(s)`);
+        }
+        // M-ADR 0211: every requirement and scenario names the declared field behind it, and each one resolves.
+        let doc;
+        try {
+            doc = parseSource(sourceText);
+        }
+        catch (e) {
+            failures.push(`${where}: the source does not parse: ${e.message}`);
+            continue;
+        }
+        // M-ADR 0232 §4.1: the features map says which part of the source each feature specifies.
+        if (s.features.size === 0) {
+            failures.push(`${where}: declares no features map (features: {<feature-id>: [<path>, ...]}, M-ADR 0232 §4.1)`);
+        }
+        const mapped = [];
+        for (const path of s.shared) {
+            const why = resolvePath(doc, path, { keys: s.keys, positions: false });
+            if (why !== null)
+                failures.push(`${where}: shared path '${path}' does not resolve: ${why}`);
+        }
+        for (const [feature, paths] of s.features) {
+            for (const path of paths) {
+                const why = resolvePath(doc, path, { keys: s.keys, positions: false });
+                if (why !== null)
+                    failures.push(`${where}: features map: '${feature}' path '${path}' does not resolve: ${why}`);
+                for (const o of mapped) {
+                    if (o.feature !== feature && (pathWithin(path, o.path) || pathWithin(o.path, path))) {
+                        failures.push(`${where}: features map: '${path}' (${feature}) and '${o.path}' (${o.feature}) map one part of the source to two features`);
+                    }
+                }
+                mapped.push({ feature, path });
+            }
+        }
+        if (s.features.size > 0) {
+            for (const sp of rec.specs) {
+                if (!s.features.has(sp.feature))
+                    failures.push(`${where}: derived feature '${sp.feature}' is not in the features map`);
+            }
+            // A mapped feature not derived yet is a visible gap, not a failure: features are derived incrementally.
+            const derivedNow = new Set(rec.specs.map((x) => x.feature));
+            const pending = [...s.features.keys()].filter((f) => !derivedNow.has(f)).sort();
+            if (pending.length > 0)
+                lines.push(`  ${s.id}: gap: mapped but not derived yet: ${pending.map((f) => `'${f}'`).join(", ")} (visible, not a failure)`);
+            if (doc instanceof Map) {
+                const gaps = [...doc.keys()].map((k) => (typeof k === "string" ? renderPath([{ kind: "key", name: k }]) : `[${String(k)}]`)).filter((k) => ![...mapped.map((m) => m.path), ...s.shared].some((p) => pathWithin(p, k) || pathWithin(k, p)));
+                if (gaps.length > 0)
+                    lines.push(`  ${s.id}: gap: no feature maps ${gaps.map((g) => `'${g}'`).join(", ")} (visible, not a failure)`);
+            }
+        }
+        let blocks = 0;
+        let named = 0; // Data item lines across this source's supply features
+        const observes = new Map();
+        for (const sp of rec.specs) {
+            const t = living.get(sp.feature);
+            if (t === undefined)
+                continue;
+            const featurePaths = s.features.get(sp.feature) ?? [];
+            const supplyFeature = supply !== null;
+            const slug = supply !== null && sp.feature.startsWith(`${supply.sddId}-`) ? sp.feature.slice(supply.sddId.length + 1) : null;
+            if (supplyFeature && slug === null) {
+                failures.push(`derived feature '${sp.feature}' is not a supply feature named '${supply.sddId}-<category>' (M-ADR 0143 as amended)`);
+            }
+            let items = 0;
+            for (const bare of requirementsWithoutScenario(t)) {
+                failures.push(`openspec/specs/${sp.feature}/spec.md: requirement '${bare}' has no scenario; OpenSpec's strict validation refuses it (a generator defect: ${s.generator.identity} ${s.generator.version})`);
+            }
+            for (const b of specBlocks(t)) {
+                blocks++;
+                if (b.sources.length === 0) {
+                    failures.push(`openspec/specs/${sp.feature}/spec.md: ${b.kind} '${b.name}' names no Source: (a derived spec asserts only what its source declares, M-ADR 0211)`);
+                }
+                for (const path of b.sources) {
+                    const why = resolveSourcePath(doc, path, s.keys);
+                    if (why !== null)
+                        failures.push(`openspec/specs/${sp.feature}/spec.md: ${b.kind} '${b.name}': Source '${path}' does not resolve in ${s.source}: ${why}`);
+                    else if (featurePaths.length > 0 && !featurePaths.some((fp) => pathWithin(path, fp)) && !s.shared.some((sp) => pathWithin(path, sp))) {
+                        failures.push(`openspec/specs/${sp.feature}/spec.md: ${b.kind} '${b.name}': Source '${path}' is outside the paths the features map gives '${sp.feature}'`);
+                    }
+                }
+                // Observed via: a path the block is observed through, owned by another feature (a dependency, never an assertion).
+                for (const path of b.via) {
+                    const why = resolveSourcePath(doc, path, s.keys);
+                    if (why !== null) {
+                        failures.push(`openspec/specs/${sp.feature}/spec.md: ${b.kind} '${b.name}': Observed via '${path}' does not resolve in ${s.source}: ${why}`);
+                        continue;
+                    }
+                    const other = [...s.features].find(([, ps]) => ps.some((fp) => pathWithin(path, fp)))?.[0] ?? "(no feature: unmapped)";
+                    if (other === sp.feature)
+                        continue;
+                    const set = observes.get(sp.feature) ?? new Set();
+                    set.add(other);
+                    observes.set(sp.feature, set);
+                }
+                if (!supplyFeature || slug === null)
+                    continue;
+                if (b.kind === "requirement" && b.dataItems.length === 0 && slug !== "operation") {
+                    failures.push(`openspec/specs/${sp.feature}/spec.md: requirement '${b.name}' names no Data item: (a supply feature's requirement names the item it supplies, M-ADR 0232 §4.4)`);
+                }
+                for (const di of b.dataItems) {
+                    items++;
+                    const at = `openspec/specs/${sp.feature}/spec.md: ${b.kind} '${b.name}': Data item '${di}'`;
+                    if (supply.registry !== null) {
+                        const cat = supply.registry.get(di);
+                        if (cat === undefined)
+                            failures.push(`${at} is not a data item in ${supply.registryFrom}`);
+                        else if (cat !== slug)
+                            failures.push(`${at} is in category '${cat}', not the feature's '${slug}'`);
+                    }
+                    if (!supply.supplied.has(di))
+                        failures.push(`${at} is not supplied by this integration (no supported or partial integration_data_item row)`);
+                }
+            }
+            named += items;
+            if (supplyFeature && slug !== null && slug !== "operation" && items === 0) {
+                failures.push(`supply feature '${sp.feature}' supplies no data item (only the operation feature may, M-ADR 0232 §4.4)`);
+            }
+            if (catalogueFeatures !== null && !catalogueFeatures.has(sp.feature)) {
+                failures.push(`derived feature '${sp.feature}' is not a feature in catalogues/features.csv (add it through a structural change first, M-ADR 0232 §4.7)`);
+            }
+        }
+        lines.push(`  ${s.id}: ${blocks} requirement and scenario block(s) checked for Source:`);
+        for (const [f, others] of [...observes].sort(([a], [b]) => a.localeCompare(b))) {
+            lines.push(`  ${s.id}: '${f}' is observed via ${[...others].sort().map((o) => `'${o}'`).join(", ")} (a dependency, not an assertion)`);
+        }
+        // A data item's existence and category are read from the platform's registry. Where none was found, those checks
+        // did not run: that is unresolved, never a pass, so it fails while any item is named (pilot finding for M-ADR 0232).
+        if (supply !== null && supply.registry === null && named > 0) {
+            failures.push(`${s.id}: ${named} Data item line(s) whose existence and category are unresolved: no data-item registry was found (${supply.registryFrom}); run with --platform-root <the platform root's directory> so its catalogues/data_items.csv is read (M-ADR 0232 §4.4)`);
+        }
+        if (supply !== null) {
+            lines.push(supply.registry !== null
+                ? `  ${s.id}: data items checked against ${supply.registryFrom} and this integration's supply`
+                : `  ${s.id}: data items checked against this integration's supply only; existence and category NOT checked (${supply.registryFrom})`);
+        }
+    }
+    const body = lines.join("\n") + "\n" + warnings.map((w) => `[WARN] ${w}\n`).join("");
+    if (failures.length > 0) {
+        return { exitCode: 1, stdout: body + failures.map((f) => `[FAIL] ${f}\n`).join("") + `[FAIL] derived specs: ${failures.length} problem(s)\n` };
+    }
+    return { exitCode: 0, stdout: body + `[PASS] derived specs: every owned living spec is what its source derives\n` };
+}
+//# sourceMappingURL=derived-specs.js.map

package/dist/lib/validate/dispatch.js

@@ -2,6 +2,7 @@ import { checkArchetypeCitations } from "./archetype-citations.js";
 import { checkBehaviourStore, checkBehaviourStoreOpenspec } from "./behaviour-store.js";
 import { checkBundleCoherence } from "./bundle-coherence.js";
 import { checkCarveCitations } from "./carve-citations.js";
+import { checkDerivedSpecs } from "./derived-specs.js";
 import { checkFeatureSpecPointers } from "./feature-spec-pointers.js";
 import { checkIntents } from "./intents.js";
 import { checkJourneyImpact } from "./journey-impact.js";
@@ -29,7 +30,13 @@ const BEHAVIOUR_STORE_VALIDATORS = [
     // Behaviour carved into another SDD keeps one home at a time (the carving guide); without citations it reports [N/A].
     {
         name: "carve-citations",
-        source: { kind: "native", run: async (ctx) => checkCarveCitations(ctx.targetRepo) },
+        source: { kind: "native", run: async (ctx) => checkCarveCitations(ctx.targetRepo, process.env.SDD_SNAPSHOT_STORE ?? "") },
+        build: () => ({ status: "run", args: [] }),
+    },
+    // Living specs derived from an executable source (M-ADR 0232); [N/A] where the SDD declares none.
+    {
+        name: "derived-specs",
+        source: { kind: "native", run: async (ctx) => checkDerivedSpecs(ctx.targetRepo, ctx.platformRoot) },
         build: () => ({ status: "run", args: [] }),
     },
     // Intents (M-ADR 0227) can sit in an SDD of any profile; without any the check reports [N/A].

package/dist/maintain-version.json

@@ -1,4 +1,4 @@
 {
-  "version": "0.19.1",
-  "built_against_sdd_cli": "5.5.1"
+  "version": "0.21.0",
+  "built_against_sdd_cli": "5.7.0"
 }

package/dist/verbs/catalogue-verify.js

@@ -59,6 +59,7 @@ export function registerCatalogueImpact(catalogue) {
         .option("--sdd-path <path>", "Path to the SDD repo root (defaults to cwd)")
         .option("--catalogues-dir <dir>", "Catalogues directory relative to the SDD root (default: catalogues, or catalogues-aggregated at --tier aggregate)")
         .option("--tier <tier>", "Tier, explicit never inferred (member | aggregate; default member)")
+        .option("--consumers", "Report the node's consumers instead: only dependency relationships, in the consumer direction, each with a shortest path", false)
         .action(async (opts) => {
         if (opts.tier !== undefined &&
             opts.tier !== "member" &&
@@ -75,6 +76,7 @@ export function registerCatalogueImpact(catalogue) {
             ...(opts.tier !== undefined
                 ? { tier: opts.tier }
                 : {}),
+            ...(opts.consumers ? { consumers: true } : {}),
         }, (s) => process.stdout.write(s));
         if (result.exitCode !== 0)
             process.exit(result.exitCode);

package/dist/verify-version.json

@@ -1,4 +1,4 @@
 {
-  "version": "5.5.1",
-  "built_against_sdd_cli": "5.5.1"
+  "version": "5.7.0",
+  "built_against_sdd_cli": "5.7.0"
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@sdd-method/verify-cli",
-  "version": "5.5.1",
-  "sddCliVersion": "5.5.1",
+  "version": "5.7.0",
+  "sddCliVersion": "5.7.0",
   "description": "Verify an SDD repository without changing it — validate, list, and read-only catalogue and pack checks. Ships only the code those verbs reach; it cannot write to the repository it is pointed at. Authoring and maintenance are in @sdd-method/sdd-cli.",
   "license": "UNLICENSED",
   "type": "module",