@sdd-method/verify-cli 5.5.1 → 5.7.0

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

@@ -0,0 +1,501 @@
+// Derived living specs (M-ADR 0232): living specs generated, one way, from an executable source the SDD declares, never
+// edited by hand. This module reads the declaration (.sdd/derived-specs.yaml) and the derivation record
+// (.sdd/derived-specs.lock.yaml), runs a source's generator under the method's contract, resolves `Source:` lines
+// against the source, and checks the living specs a source owns. The generator and the source's format are the
+// adopter's; nothing here knows any schema.
+import { execFile as execFileCb } from "node:child_process";
+import { createHash } from "node:crypto";
+import { existsSync } from "node:fs";
+import { lstat, mkdir, mkdtemp, readdir, readFile, rm, writeFile } from "node:fs/promises";
+import { homedir, tmpdir } from "node:os";
+import { join, resolve } from "node:path";
+import { promisify } from "node:util";
+import { parse as parseYaml, parseDocument } from "yaml";
+import { resolvePath, splitSourceLine } from "./source-path.js";
+export { pathWithin, parsePath, renderPath, resolveNode, resolvePath, splitSourceLine } from "./source-path.js";
+const execFile = promisify(execFileCb);
+export const DERIVED_CONFIG = ".sdd/derived-specs.yaml";
+export const DERIVED_LOCK = ".sdd/derived-specs.lock.yaml";
+const SPECS = "openspec/specs";
+export const sha256 = (text) => createHash("sha256").update(text).digest("hex");
+/** The SDD's derived sources, or null when it declares none. Throws on a malformed declaration. */
+export async function loadDerivedSources(repo) {
+    const text = await readFile(join(repo, DERIVED_CONFIG), "utf8").catch(() => null);
+    if (text === null)
+        return null;
+    const raw = parseYaml(text);
+    if (!Array.isArray(raw?.sources))
+        throw new Error(`${DERIVED_CONFIG}: expected a 'sources:' list`);
+    const out = [];
+    for (const [i, s] of raw.sources.entries()) {
+        const g = (s?.["generator"] ?? {});
+        const cmd = g["command"];
+        const id = String(s?.["id"] ?? "");
+        const source = String(s?.["source"] ?? "");
+        if (id === "" || source === "" || !Array.isArray(cmd) || cmd.length === 0 || !g["identity"] || !g["version"]) {
+            throw new Error(`${DERIVED_CONFIG}: sources[${i}] needs id, source, and generator.command (a list), generator.identity and generator.version`);
+        }
+        const fm = new Map();
+        const rawMap = s["features"];
+        if (rawMap !== undefined && rawMap !== null) {
+            if (typeof rawMap !== "object" || Array.isArray(rawMap))
+                throw new Error(`${DERIVED_CONFIG}: sources[${i}].features must map a feature id to a list of source paths`);
+            for (const [f, paths] of Object.entries(rawMap)) {
+                if (!Array.isArray(paths) || paths.length === 0)
+                    throw new Error(`${DERIVED_CONFIG}: sources[${i}].features.${f} must be a non-empty list of source paths`);
+                fm.set(f, paths.map(String));
+            }
+        }
+        const keys = new Map();
+        const rawKeys = s["keys"];
+        if (rawKeys !== undefined && rawKeys !== null) {
+            if (typeof rawKeys !== "object" || Array.isArray(rawKeys))
+                throw new Error(`${DERIVED_CONFIG}: sources[${i}].keys must map a list's path to its key field (or a list of fields)`);
+            for (const [lp, k] of Object.entries(rawKeys)) {
+                const fields = (Array.isArray(k) ? k : [k]).map(String).filter((x) => x !== "");
+                if (fields.length === 0)
+                    throw new Error(`${DERIVED_CONFIG}: sources[${i}].keys.${lp} names no key field`);
+                keys.set(lp, fields);
+            }
+        }
+        const inputs = [];
+        const rawInputs = s["inputs"];
+        if (rawInputs !== undefined && rawInputs !== null) {
+            if (!Array.isArray(rawInputs))
+                throw new Error(`${DERIVED_CONFIG}: sources[${i}].inputs must be a list of {id, path, sha256}`);
+            for (const [k, raw] of rawInputs.entries()) {
+                const inId = String(raw?.["id"] ?? "");
+                const inPath = String(raw?.["path"] ?? "");
+                const pin = String(raw?.["sha256"] ?? "");
+                if (!/^[a-z0-9][a-z0-9-]*$/.test(inId) || inPath === "" || !/^[0-9a-f]{64}$/.test(pin)) {
+                    throw new Error(`${DERIVED_CONFIG}: sources[${i}].inputs[${k}] needs an id (lower-case, digits, hyphens), a path, and sha256 (64 hex digits: the input's digest, M-ADR 0232 §4.2)`);
+                }
+                if (inputs.some((x) => x.id === inId))
+                    throw new Error(`${DERIVED_CONFIG}: sources[${i}].inputs: '${inId}' appears twice`);
+                inputs.push({ id: inId, path: inPath, sha256: pin });
+            }
+        }
+        for (const arg of cmd.map(String)) {
+            for (const m of arg.matchAll(/\{input:([^}]*)\}/g)) {
+                if (!inputs.some((x) => x.id === m[1]))
+                    throw new Error(`${DERIVED_CONFIG}: sources[${i}].generator.command names {input:${m[1]}}, which sources[${i}].inputs does not declare`);
+            }
+        }
+        const rawShared = s["shared"];
+        if (rawShared !== undefined && rawShared !== null && !Array.isArray(rawShared))
+            throw new Error(`${DERIVED_CONFIG}: sources[${i}].shared must be a list of source paths`);
+        out.push({
+            id,
+            source,
+            ...(s["schema"] ? { schema: String(s["schema"]) } : {}),
+            generator: { command: cmd.map(String), identity: String(g["identity"]), version: String(g["version"]) },
+            features: fm,
+            keys,
+            shared: (rawShared ?? []).map(String),
+            inputs,
+        });
+    }
+    const ids = out.map((s) => s.id);
+    const dup = ids.find((x, k) => ids.indexOf(x) !== k);
+    if (dup !== undefined)
+        throw new Error(`${DERIVED_CONFIG}: source id '${dup}' appears twice`);
+    return out;
+}
+export async function loadLock(repo) {
+    const text = await readFile(join(repo, DERIVED_LOCK), "utf8").catch(() => null);
+    if (text === null)
+        return [];
+    const raw = parseYaml(text);
+    return Array.isArray(raw?.sources) ? raw.sources : [];
+}
+/**
+ * The generator's `--version`: one line, `<identity> <version> <release commit>`. Null when the generator cannot be run
+ * on this machine (not installed), so the caller falls back to comparing digests and says so.
+ */
+export async function generatorIdentity(repo, g, inputs = []) {
+    try {
+        const cmd = commandFor(repo, g, inputs);
+        const { stdout } = await execFile(cmd[0], [...cmd.slice(1), "--version"], { cwd: repo, timeout: 60_000 });
+        const [identity, version, commit] = stdout.trim().split(/\s+/);
+        if (!identity || !version || !commit)
+            return null;
+        return { identity, version, commit };
+    }
+    catch {
+        return null;
+    }
+}
+/** Where an input lives on this machine: relative to the SDD's root, absolute, or under the home directory. */
+export function inputLocation(repo, path) {
+    if (path === "~" || path.startsWith("~/"))
+        return join(homedir(), path.slice(1));
+    return resolve(repo, path);
+}
+/** The generator's command with each `{input:<id>}` replaced by that input's location. */
+export function commandFor(repo, g, inputs) {
+    return g.command.map((a) => a.replace(/\{input:([^}]*)\}/g, (_, id) => {
+        const x = inputs.find((i) => i.id === id);
+        return x === undefined ? `{input:${id}}` : inputLocation(repo, x.path);
+    }));
+}
+/**
+ * An input's digest, computed by the method. A file: the sha256 of its bytes. A directory: the sha256 of the
+ * `sha256sum`-format listing ("<sha256>  <relative path>\n") of every regular file under it, sorted bytewise by path,
+ * which is `cd <dir> && find . -type f -printf '%P\n' | LC_ALL=C sort | xargs -d '\n' sha256sum | sha256sum`.
+ * A symbolic link inside it is refused, so the digest never depends on what a link points at. Null when absent.
+ */
+export async function inputDigest(location) {
+    const st = await lstat(location).catch(() => null);
+    if (st === null)
+        return null;
+    if (st.isFile())
+        return sha256(await readFile(location));
+    if (!st.isDirectory())
+        throw new Error(`${location} is neither a file nor a directory`);
+    const files = [];
+    const walk = async (rel) => {
+        for (const e of await readdir(join(location, rel), { withFileTypes: true })) {
+            const r = rel === "" ? e.name : `${rel}/${e.name}`;
+            if (e.isSymbolicLink())
+                throw new Error(`${join(location, r)} is a symbolic link; an input's digest never follows one`);
+            if (e.isDirectory())
+                await walk(r);
+            else if (e.isFile())
+                files.push(r);
+        }
+    };
+    await walk("");
+    files.sort((a, b) => Buffer.compare(Buffer.from(a, "utf8"), Buffer.from(b, "utf8")));
+    const listing = [];
+    for (const f of files)
+        listing.push(`${sha256(await readFile(join(location, f)))}  ${f}\n`);
+    return sha256(listing.join(""));
+}
+/** Each declared input's state here: its location, and its digest (null: not available on this machine). */
+export async function inputStates(repo, inputs) {
+    const out = [];
+    for (const input of inputs) {
+        const location = inputLocation(repo, input.path);
+        out.push({ input, location, digest: await inputDigest(location) });
+    }
+    return out;
+}
+/** Run the generator into a fresh directory; returns feature id -> spec text. Throws if it fails or writes stray files. */
+export async function generate(repo, s, sourcePath) {
+    const out = await mkdtemp(join(tmpdir(), "sdd-derived-"));
+    try {
+        const cmd = commandFor(repo, s.generator, s.inputs);
+        await execFile(cmd[0], [...cmd.slice(1), "--source", resolve(repo, sourcePath), "--out", out], {
+            cwd: repo,
+            timeout: 600_000,
+        });
+        const specs = new Map();
+        for (const e of await readdir(out, { withFileTypes: true })) {
+            const file = join(out, e.name, "spec.md");
+            if (!e.isDirectory() || !existsSync(file))
+                throw new Error(`generator ${s.generator.identity} wrote '${e.name}', which is not <feature>/spec.md`);
+            const extra = (await readdir(join(out, e.name))).filter((f) => f !== "spec.md");
+            if (extra.length > 0)
+                throw new Error(`generator ${s.generator.identity} wrote ${extra.join(", ")} beside ${e.name}/spec.md; it writes nothing else`);
+            specs.set(e.name, await readFile(file, "utf8"));
+        }
+        return specs;
+    }
+    finally {
+        await rm(out, { recursive: true, force: true });
+    }
+}
+export function specBlocks(text) {
+    const out = [];
+    for (const line of text.split("\n")) {
+        const r = /^###\s+Requirement:\s*(.+?)\s*$/.exec(line);
+        const sc = /^####\s+Scenario:\s*(.+?)\s*$/.exec(line);
+        if (r)
+            out.push({ kind: "requirement", name: r[1], sources: [], dataItems: [], via: [] });
+        else if (sc)
+            out.push({ kind: "scenario", name: sc[1], sources: [], dataItems: [], via: [] });
+        else {
+            const ov = /^\s*(?:[-*]\s*)?Observed via:\s*(.+?)\s*$/.exec(line);
+            if (ov && out.length > 0) {
+                out[out.length - 1].via.push(...splitSourceLine(ov[1]));
+                continue;
+            }
+            const di = /^\s*(?:[-*]\s*)?Data item:\s*(.+?)\s*$/.exec(line);
+            if (di && out.length > 0) {
+                out[out.length - 1].dataItems.push(...di[1].split(",").map((x) => x.trim().replace(/^`|`$/g, "")).filter(Boolean));
+                continue;
+            }
+            const src = /^\s*(?:[-*]\s*)?Source:\s*(.+?)\s*$/.exec(line);
+            if (src && out.length > 0)
+                out[out.length - 1].sources.push(...splitSourceLine(src[1]));
+        }
+    }
+    return out;
+}
+/** Resolve a `Source:` path in a source parsed by `parseSource` (the grammar is source-path.ts's). Null when it resolves. */
+export function resolveSourcePath(doc, path, keys = new Map()) {
+    return resolvePath(doc, path, { keys });
+}
+/** A derived source parsed for path resolution: typed map keys, so `[200]` and `["200"]` stay distinct. */
+export function parseSource(text) {
+    const d = parseDocument(text);
+    if (d.errors.length > 0)
+        throw new Error(d.errors[0].message);
+    return d.toJS({ mapAsMap: true });
+}
+/** The living specs on disk, feature id -> text. */
+export async function livingSpecs(repo) {
+    const out = new Map();
+    const root = join(repo, SPECS);
+    if (!existsSync(root))
+        return out;
+    for (const e of await readdir(root, { withFileTypes: true })) {
+        if (!e.isDirectory())
+            continue;
+        const t = await readFile(join(root, e.name, "spec.md"), "utf8").catch(() => null);
+        if (t !== null)
+            out.set(e.name, t);
+    }
+    return out;
+}
+/** A living spec's or a delta's requirement blocks: name -> the block's text (heading to the next requirement or section). */
+export function requirementBlocks(text) {
+    const out = new Map();
+    let name = null;
+    let buf = [];
+    const flush = () => {
+        if (name !== null)
+            out.set(name, buf.join("\n").replace(/\s+$/, ""));
+    };
+    for (const line of text.split("\n")) {
+        const r = /^###\s+Requirement:\s*(.+?)\s*$/.exec(line);
+        if (r || /^##\s/.test(line)) {
+            flush();
+            name = r ? r[1] : null;
+            buf = r ? [line] : [];
+            continue;
+        }
+        if (name !== null)
+            buf.push(line);
+    }
+    flush();
+    return out;
+}
+/**
+ * The OpenSpec delta that turns `living` (absent: a new feature) into `derived`, requirement by requirement: ADDED for
+ * a new requirement, MODIFIED (stated whole) for a changed one, REMOVED for one the source no longer declares. Null when
+ * nothing changes.
+ */
+export function deltaFor(living, derived) {
+    const before = living === undefined ? new Map() : requirementBlocks(living);
+    const after = derived === undefined ? new Map() : requirementBlocks(derived);
+    const added = [];
+    const modified = [];
+    const removed = [];
+    for (const [n, t] of after) {
+        const b = before.get(n);
+        if (b === undefined)
+            added.push(t);
+        else if (b !== t)
+            modified.push(t);
+    }
+    for (const n of before.keys()) {
+        if (!after.has(n))
+            removed.push(`### Requirement: ${n}\n**Reason**: the source no longer declares it\n**Migration**: none`);
+    }
+    if (added.length + modified.length + removed.length === 0)
+        return null;
+    const parts = [];
+    if (added.length)
+        parts.push(`## ADDED Requirements\n\n${added.join("\n\n")}`);
+    if (modified.length)
+        parts.push(`## MODIFIED Requirements\n\n${modified.join("\n\n")}`);
+    if (removed.length)
+        parts.push(`## REMOVED Requirements\n\n${removed.join("\n\n")}`);
+    return parts.join("\n\n") + "\n";
+}
+/** The derived/ files a change carries: source id -> its path in the change. */
+export async function changeDerivedSources(changeDir) {
+    const dir = join(changeDir, "derived");
+    const out = new Map();
+    if (!existsSync(dir))
+        return out;
+    for (const e of await readdir(dir, { withFileTypes: true })) {
+        if (e.isFile())
+            out.set(e.name.replace(/\.[^.]+$/, ""), join(dir, e.name));
+    }
+    return out;
+}
+/** The lock's text for these entries. */
+export function renderLock(entries) {
+    const lines = ["# Derivation record (M-ADR 0232 §4.3), written by sdd-cli; never edit by hand.", 'schema_version: "1.0.0"', "sources:"];
+    for (const e of [...entries].sort((a, b) => a.id.localeCompare(b.id))) {
+        lines.push(`  - id: ${e.id}`, `    source: ${e.source}`, `    source_sha256: ${e.source_sha256}`);
+        lines.push(`    generator: { identity: ${JSON.stringify(e.generator.identity)}, version: ${JSON.stringify(e.generator.version)}, commit: ${JSON.stringify(e.generator.commit)} }`);
+        if (e.inputs && e.inputs.length > 0) {
+            lines.push("    inputs:");
+            for (const x of [...e.inputs].sort((a, b) => a.id.localeCompare(b.id)))
+                lines.push(`      - { id: ${x.id}, sha256: ${x.sha256} }`);
+        }
+        lines.push("    specs:");
+        for (const sp of [...e.specs].sort((a, b) => a.feature.localeCompare(b.feature)))
+            lines.push(`      - { feature: ${sp.feature}, sha256: ${sp.sha256} }`);
+    }
+    return lines.join("\n") + "\n";
+}
+/** Which derived source owns each feature: the derivation record's specs and the features map both declare it. */
+export function ownership(sources, lock) {
+    const out = new Map();
+    for (const l of lock)
+        for (const sp of l.specs)
+            out.set(sp.feature, l.id);
+    for (const s of sources)
+        for (const f of s.features.keys())
+            out.set(f, s.id);
+    return out;
+}
+/**
+ * Regenerate each derived source a change carries (M-ADR 0232 §4.5) from its proposed copy and diff it against the
+ * living specs. Throws when a source id is undeclared or its pinned generator cannot run here: a derived change's deltas
+ * are only ever the regenerated difference, so without the generator there is nothing to write or compare.
+ */
+export async function planDerivedChange(repo, changeDir) {
+    const carried = await changeDerivedSources(changeDir);
+    if (carried.size === 0)
+        return [];
+    const sources = (await loadDerivedSources(repo)) ?? [];
+    const lock = await loadLock(repo);
+    const owners = ownership(sources, lock);
+    const living = await livingSpecs(repo);
+    const out = [];
+    for (const [id, proposed] of carried) {
+        const s = sources.find((x) => x.id === id);
+        if (s === undefined)
+            throw new Error(`derived/${id}: no derived source '${id}' is declared in ${DERIVED_CONFIG}`);
+        for (const st of await inputStates(repo, s.inputs)) {
+            if (st.digest === null)
+                throw new Error(`derived/${id}: input '${st.input.id}' is not available here (${st.location}), so the change cannot be regenerated`);
+            if (st.digest !== st.input.sha256)
+                throw new Error(`derived/${id}: input '${st.input.id}' at ${st.location} is ${st.digest.slice(0, 12)}, not the pinned ${st.input.sha256.slice(0, 12)}, so the change cannot be regenerated`);
+        }
+        const ident = await generatorIdentity(repo, s.generator, s.inputs);
+        if (ident === null || ident.identity !== s.generator.identity || ident.version !== s.generator.version) {
+            throw new Error(`derived/${id}: the pinned generator ${s.generator.identity} ${s.generator.version} is not available here (${ident === null ? "not installed" : `found ${ident.identity} ${ident.version}`}), so the change cannot be regenerated`);
+        }
+        const specs = await generate(repo, s, proposed);
+        for (const [f, t] of specs) {
+            const bare = requirementsWithoutScenario(t);
+            if (bare.length > 0)
+                throw new Error(`derived/${id}: generator ${s.generator.identity} ${s.generator.version} emitted ${f} requirement(s) with no scenario (${bare.map((x) => `'${x}'`).join(", ")}); OpenSpec's strict validation refuses them, so fix the generator`);
+        }
+        const deltas = new Map();
+        const features = new Set([...specs.keys(), ...[...owners].filter(([, o]) => o === id).map(([f]) => f)]);
+        for (const f of [...features].sort())
+            deltas.set(f, deltaFor(living.get(f), specs.get(f)));
+        out.push({ source: s, proposed, specs, deltas, generator: ident });
+    }
+    return out;
+}
+/**
+ * The behaviour-store rule for derived features (M-ADR 0232 §4.1, §4.5): a change never authors a delta to a feature
+ * a derived source owns; a change carrying a proposed source has exactly the regenerated deltas for that source's
+ * features. Returns the problems (empty: none).
+ */
+export async function derivedChangeProblems(repo, change) {
+    const problems = [];
+    const sources = await loadDerivedSources(repo).catch(() => null);
+    if (sources === null || sources.length === 0)
+        return problems;
+    const changeDir = join(repo, SPECS, "..", "changes", change);
+    const owners = ownership(sources, await loadLock(repo));
+    const carried = await changeDerivedSources(changeDir);
+    const deltaDir = join(changeDir, "specs");
+    const authored = existsSync(deltaDir) ? (await readdir(deltaDir, { withFileTypes: true })).filter((e) => e.isDirectory()).map((e) => e.name) : [];
+    for (const f of authored) {
+        const o = owners.get(f);
+        if (o !== undefined && !carried.has(o)) {
+            problems.push(`${change}: authors a delta to '${f}', which derived source '${o}' owns; change the source instead (derived/${o}.<ext>) and let \`sdd-cli change derive\` write the deltas (M-ADR 0232 §4.1)`);
+        }
+    }
+    if (carried.size === 0)
+        return problems;
+    let plans;
+    try {
+        plans = await planDerivedChange(repo, changeDir);
+    }
+    catch (e) {
+        problems.push(`${change}: ${e.message}`);
+        return problems;
+    }
+    for (const p of plans) {
+        for (const [f, want] of p.deltas) {
+            const have = await readFile(join(deltaDir, f, "spec.md"), "utf8").catch(() => null);
+            if ((have?.trim() ?? null) !== (want?.trim() ?? null)) {
+                problems.push(`${change}: the delta for '${f}' is not the difference regenerated from derived/${p.source.id} (${want === null ? "it should have none" : have === null ? "it is missing" : "it differs"}); run \`sdd-cli change derive ${change}\` (M-ADR 0232 §4.5)`);
+            }
+        }
+    }
+    return problems;
+}
+/** Write a derived change's deltas: the regenerated difference, and nothing authored. Returns what it wrote and removed. */
+export async function writeDerivedDeltas(repo, change) {
+    const changeDir = join(repo, SPECS, "..", "changes", change);
+    if (!existsSync(changeDir))
+        throw new Error(`no open change '${change}'`);
+    const plans = await planDerivedChange(repo, changeDir);
+    if (plans.length === 0)
+        throw new Error(`change '${change}' carries no proposed source (openspec/changes/${change}/derived/<source-id>.<ext>)`);
+    const written = [];
+    const removed = [];
+    for (const p of plans) {
+        for (const [f, delta] of p.deltas) {
+            const dir = join(changeDir, "specs", f);
+            if (delta === null) {
+                if (existsSync(dir)) {
+                    await rm(dir, { recursive: true, force: true });
+                    removed.push(f);
+                }
+                continue;
+            }
+            await mkdir(dir, { recursive: true });
+            await writeFile(join(dir, "spec.md"), delta, "utf8");
+            written.push(f);
+        }
+    }
+    return { written, removed };
+}
+/** Two specs state the same requirements, whatever their order and trailing whitespace. */
+export function sameRequirements(a, b) {
+    const norm = (t) => {
+        const m = requirementBlocks(t);
+        return new Map([...m].map(([k, v]) => [k, v.split("\n").map((l) => l.trimEnd()).join("\n").replace(/\n{2,}/g, "\n\n")]));
+    };
+    const x = norm(a);
+    const y = norm(b);
+    return x.size === y.size && [...x].every(([k, v]) => y.get(k) === v);
+}
+/** Requirements with no scenario: OpenSpec's strict validation refuses them, so a derivation that emits one is refused early. */
+export function requirementsWithoutScenario(text) {
+    const out = [];
+    const blocks = specBlocks(text);
+    blocks.forEach((b, k) => {
+        if (b.kind === "requirement" && blocks[k + 1]?.kind !== "scenario")
+            out.push(b.name);
+    });
+    return out;
+}
+/** Open changes carrying a proposed copy of this source (derived/<id>.<ext>): a first derivation under review. */
+export async function openDerivations(repo, sourceId) {
+    const dir = join(repo, SPECS, "..", "changes");
+    if (!existsSync(dir))
+        return [];
+    const out = [];
+    for (const e of await readdir(dir, { withFileTypes: true })) {
+        if (!e.isDirectory() || e.name === "archive")
+            continue;
+        if ((await changeDerivedSources(join(dir, e.name))).has(sourceId))
+            out.push(e.name);
+    }
+    return out.sort();
+}
+//# sourceMappingURL=index.js.map