agent-sdd 1.0.3

package/dist/features/ready/domain/SpecDiff.js

@@ -0,0 +1,321 @@
+/*
+ * ENF-004A — Semver cascade diff engine. Classifies per-ID changes and
+ * computes the required Surface bump (rationale lives in the spec record).
+ * Pure logic — no I/O.
+ */
+const PREDICATE_FIELDS = new Set([
+    "always",
+    "never",
+    "when",
+    "then",
+    "predicate",
+    "schema",
+    "preconditions",
+    "postconditions",
+    "error_taxonomy",
+    "compatibility_rules",
+    "rule" /* Constraint, Policy */,
+    "metric" /* NFR */,
+    "target" /* NFR */,
+    "given" /* Behavior */,
+]);
+/** Per-ID diff: classify each ID present in `curr` against `prev`. IDs new to
+ *  `curr` are classified as "content_change" (additive). IDs removed in
+ *  `curr` are not returned (the consumer detects removal separately via
+ *  lifecycle.status flips, which lint already covers). */
+export function classifyDiff(prev, curr) {
+    const prevById = new Map(prev.map((r) => [r.id, r]));
+    const out = [];
+    for (const c of curr) {
+        const p = prevById.get(c.id);
+        if (p === undefined) {
+            out.push({
+                id: c.id,
+                template: c.template,
+                classification: "content_change",
+                changedFields: ["__new__"],
+            });
+            continue;
+        }
+        const changed = changedTopLevelKeys(p.parsed, c.parsed);
+        if (changed.length === 0) {
+            out.push({
+                id: c.id,
+                template: c.template,
+                classification: "none",
+                changedFields: [],
+            });
+            continue;
+        }
+        const isPredicate = changed.some((k) => {
+            /*
+             * CTR-016 / CTR-012: append-only schema additions are content, not
+             * predicate (see spec record for the full rule).
+             */
+            if (k === "schema" &&
+                isAppendOnlySchemaChange(p.parsed.schema, c.parsed.schema)) {
+                return false;
+            }
+            return PREDICATE_FIELDS.has(k);
+        });
+        out.push({
+            id: c.id,
+            template: c.template,
+            classification: isPredicate ? "predicate_change" : "content_change",
+            changedFields: changed,
+        });
+    }
+    return out;
+}
+export function requiredSurfaceBumps(prev, curr, diffs) {
+    const prevById = new Map(prev.map((r) => [r.id, r]));
+    const diffById = new Map(diffs.map((d) => [d.id, d]));
+    const currSurfaces = curr.filter((r) => r.template === "Surface");
+    const out = [];
+    for (const sur of currSurfaces) {
+        const reachable = reachableFrom(sur, curr);
+        const drivenBy = [];
+        for (const id of reachable) {
+            const d = diffById.get(id);
+            if (d !== undefined && d.classification !== "none") {
+                drivenBy.push(d);
+            }
+        }
+        const required = drivenBy.some((d) => d.classification === "predicate_change")
+            ? "major"
+            : drivenBy.some((d) => d.classification === "content_change")
+                ? "minor"
+                : "patch";
+        const declaredVersion = readVersion(sur);
+        const prevSur = prevById.get(sur.id);
+        const prevDeclaredVersion = prevSur !== undefined ? readVersion(prevSur) : null;
+        out.push({
+            surfaceId: sur.id,
+            declaredVersion,
+            prevDeclaredVersion,
+            required,
+            drivenBy,
+        });
+    }
+    return out;
+}
+function reachableFrom(surface, all) {
+    const out = new Set([surface.id]);
+    const byId = new Map(all.map((r) => [r.id, r]));
+    const queue = [surface.id];
+    while (queue.length > 0) {
+        const id = queue[0];
+        queue.shift();
+        const r = byId.get(id);
+        if (r === undefined) {
+            continue;
+        }
+        const members = r.parsed.members;
+        if (Array.isArray(members)) {
+            for (const m of members) {
+                if (typeof m === "string" && !out.has(m)) {
+                    out.add(m);
+                    queue.push(m);
+                }
+            }
+        }
+        const policyRefs = r.parsed.policy_refs;
+        if (Array.isArray(policyRefs)) {
+            for (const p of policyRefs) {
+                if (typeof p === "string" && !out.has(p)) {
+                    out.add(p);
+                    queue.push(p);
+                }
+            }
+        }
+    }
+    return out;
+}
+function readVersion(rec) {
+    const v = rec.parsed.version;
+    return typeof v === "string" ? v : null;
+}
+export function generatedArtifactStructuralDiffs(prev, curr, diffs) {
+    const byId = new Map(curr.map((r) => [r.id, r]));
+    const diffById = new Map(diffs.map((d) => [d.id, d]));
+    void prev;
+    const out = [];
+    const surfaces = curr.filter((r) => r.template === "Surface");
+    for (const sur of surfaces) {
+        const reachable = reachableFrom(sur, curr);
+        for (const id of reachable) {
+            if (id === sur.id) {
+                continue;
+            }
+            const rec = byId.get(id);
+            if (rec === undefined) {
+                continue;
+            }
+            if (rec.template !== "GeneratedArtifact") {
+                continue;
+            }
+            if (rec.parsed.published_surface !== "yes") {
+                continue;
+            }
+            const d = diffById.get(id);
+            if (d === undefined || d.classification === "none") {
+                continue;
+            }
+            out.push({
+                surfaceId: sur.id,
+                generatedArtifactId: id,
+                classification: d.classification,
+            });
+        }
+    }
+    return out;
+}
+/** Compare two semver strings ("0.3.0" vs "0.4.0") and return the actual bump.
+ *  Returns null if either string is unparseable. */
+export function actualBump(prev, curr) {
+    if (prev === null || curr === null) {
+        return null;
+    }
+    const p = parseSemver(prev);
+    const c = parseSemver(curr);
+    if (p === null || c === null) {
+        return null;
+    }
+    if (c.major > p.major) {
+        return "major";
+    }
+    if (c.major === p.major && c.minor > p.minor) {
+        return "minor";
+    }
+    if (c.major === p.major && c.minor === p.minor && c.patch > p.patch) {
+        return "patch";
+    }
+    return "patch"; /* unchanged or downgrade — treat as patch (no cascade triggered) */
+}
+function parseSemver(v) {
+    const m = /^(\d+)\.(\d+)\.(\d+)$/.exec(v.trim());
+    if (m === null) {
+        return null;
+    }
+    return {
+        major: Number.parseInt(m[1], 10),
+        minor: Number.parseInt(m[2], 10),
+        patch: Number.parseInt(m[3], 10),
+    };
+}
+const BUMP_RANK = {
+    patch: 0,
+    minor: 1,
+    major: 2,
+};
+export function bumpAtLeast(actual, required) {
+    if (actual === null) {
+        return false;
+    }
+    return BUMP_RANK[actual] >= BUMP_RANK[required];
+}
+function isPlainObject(v) {
+    return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+/* CTR-016 / CTR-012 / CTR-014 — schema sub-trees that are append-only at minor
+ * (see spec records). */
+const APPEND_ONLY_ZONE_KEYS = new Set([
+    "members",
+    "fields",
+    "json",
+]);
+/* True when a `schema` change is confined to pure additions inside an
+ * append-only zone; any removal or modification stays a predicate change. */
+function isAppendOnlySchemaChange(prev, curr) {
+    if (!isPlainObject(prev) || !isPlainObject(curr)) {
+        return false;
+    }
+    return appendOnlyWithinZones(prev, curr, false) && !deepEqual(prev, curr);
+}
+function appendOnlyWithinZones(prev, curr, inZone) {
+    if (deepEqual(prev, curr)) {
+        return true;
+    }
+    if (Array.isArray(prev) && Array.isArray(curr)) {
+        if (!inZone) {
+            return false;
+        }
+        return prev.every((e) => curr.some((c) => deepEqual(c, e)));
+    }
+    if (isPlainObject(prev) && isPlainObject(curr)) {
+        if (inZone) {
+            return Object.keys(prev).every((k) => k in curr && appendOnlyWithinZones(prev[k], curr[k], true));
+        }
+        const prevKeys = Object.keys(prev);
+        const currKeys = Object.keys(curr);
+        if (prevKeys.length !== currKeys.length) {
+            return false;
+        }
+        return prevKeys.every((k) => k in curr &&
+            appendOnlyWithinZones(prev[k], curr[k], APPEND_ONLY_ZONE_KEYS.has(k)));
+    }
+    return false;
+}
+function changedTopLevelKeys(prev, curr) {
+    const out = [];
+    const keys = new Set([...Object.keys(prev), ...Object.keys(curr)]);
+    /*
+     * Skip metadata keys that don't affect semver: id, type, partition_id,
+     * lifecycle (status flips are governed separately), approval_record.
+     */
+    const SKIP = new Set([
+        "id",
+        "type",
+        "partition_id",
+        "lifecycle",
+        "approval_record",
+        "version",
+    ]);
+    for (const k of keys) {
+        if (SKIP.has(k)) {
+            continue;
+        }
+        if (!deepEqual(prev[k], curr[k])) {
+            out.push(k);
+        }
+    }
+    return out;
+}
+function deepEqual(a, b) {
+    if (a === b) {
+        return true;
+    }
+    if (a === null || b === null) {
+        return false;
+    }
+    if (typeof a !== typeof b) {
+        return false;
+    }
+    if (typeof a !== "object") {
+        return false;
+    }
+    if (Array.isArray(a) !== Array.isArray(b)) {
+        return false;
+    }
+    if (Array.isArray(a) && Array.isArray(b)) {
+        if (a.length !== b.length) {
+            return false;
+        }
+        for (let i = 0; i < a.length; i++) {
+            if (!deepEqual(a[i], b[i])) {
+                return false;
+            }
+        }
+        return true;
+    }
+    if (!isPlainObject(a) || !isPlainObject(b)) {
+        return false;
+    }
+    const keys = new Set([...Object.keys(a), ...Object.keys(b)]);
+    for (const k of keys) {
+        if (!deepEqual(a[k], b[k])) {
+            return false;
+        }
+    }
+    return true;
+}

package/dist/features/ready/ports/inbound/ReadyCommand.d.ts

@@ -0,0 +1,4 @@
+import type { CommandResult, OutputFormat } from "../../../../shared/domain/CliOutput.js";
+export interface ReadyCommand {
+    execute(cwd: string, format: OutputFormat, partition?: string, against?: string): Promise<CommandResult>;
+}

package/dist/features/ready/ports/inbound/ReadyCommand.js

@@ -0,0 +1 @@
+export {};

package/dist/features/ready/ports/outbound/ReadyConfigPort.d.ts

@@ -0,0 +1,4 @@
+import type { SddConfig } from "../../../../shared/domain/Config.js";
+export interface ReadyConfigPort {
+    config(repoRoot: string): Promise<SddConfig>;
+}

package/dist/features/ready/ports/outbound/ReadyConfigPort.js

@@ -0,0 +1 @@
+export {};

package/dist/features/ready/ports/outbound/ReadyFileReader.d.ts

@@ -0,0 +1,12 @@
+export interface SpecFileEntry {
+    path: string;
+    content: string;
+}
+export interface TestFileEntry {
+    path: string;
+    content: string;
+}
+export interface ReadyFileReader {
+    resolveSpecFiles(repoRoot: string, patterns: readonly string[]): Promise<SpecFileEntry[]>;
+    resolveTestFiles(repoRoot: string, patterns: readonly string[]): Promise<TestFileEntry[]>;
+}

package/dist/features/ready/ports/outbound/ReadyFileReader.js

@@ -0,0 +1 @@
+export {};

package/dist/features/ready/ports/outbound/ReadyGitPort.d.ts

@@ -0,0 +1,10 @@
+export interface ReadyGitPort {
+    isGitRepo(cwd: string): Promise<boolean>;
+    repoRoot(cwd: string): Promise<string>;
+    treeBytes(repoRoot: string, scope: readonly string[]): Promise<Uint8Array>;
+    treePaths(repoRoot: string, scope: readonly string[]): Promise<string[]>;
+    dirtyPaths(repoRoot: string, scope: readonly string[]): Promise<string[]>;
+    /** Read a single file at a given ref (e.g. HEAD~5). Returns null if the
+     *  ref or file is missing. Used by P2.3 semver-cascade diff. */
+    readAtRef(repoRoot: string, ref: string, relativePath: string): Promise<string | null>;
+}

package/dist/features/ready/ports/outbound/ReadyGitPort.js

@@ -0,0 +1,5 @@
+/*
+ * Optional git port for the aggregated_check leg. When git is unavailable or
+ * the cwd is not a git repo, the caller may skip baseline checking.
+ */
+export {};

package/dist/features/record/adapters/inbound/CliRecordHandler.d.ts

@@ -0,0 +1,10 @@
+import { type CommandResult, type OutputFormat } from "../../../../shared/domain/CliOutput.js";
+import { type RecordWritePorts } from "../../application/SetRecord.js";
+import type { RecordAction, RecordCommand } from "../../ports/inbound/RecordCommand.js";
+type Format = Exclude<OutputFormat, "yaml">;
+export declare class CliRecordHandler implements RecordCommand {
+    private readonly ports;
+    constructor(ports: RecordWritePorts);
+    execute(cwd: string, action: RecordAction, format: Format): Promise<CommandResult>;
+}
+export {};

package/dist/features/record/adapters/inbound/CliRecordHandler.js

@@ -0,0 +1,111 @@
+import { ok, } from "../../../../shared/domain/CliOutput.js";
+import { addRecord } from "../../application/AddRecord.js";
+import { getRecord } from "../../application/GetRecord.js";
+import { listRecords, } from "../../application/ListRecords.js";
+import { setRecord, } from "../../application/SetRecord.js";
+export class CliRecordHandler {
+    ports;
+    constructor(ports) {
+        this.ports = ports;
+    }
+    async execute(cwd, action, format) {
+        if (action.kind === "list") {
+            const records = await listRecords(cwd, this.ports, action.partition);
+            return format === "json" ? listJson(records) : listHuman(records);
+        }
+        if (action.kind === "get") {
+            const matches = await getRecord(cwd, action.id, this.ports);
+            return format === "json"
+                ? getJson(action.id, matches)
+                : getHuman(action.id, matches);
+        }
+        const result = action.kind === "set"
+            ? await setRecord(cwd, action.id, action.body, this.ports)
+            : await addRecord(cwd, action.afterId, action.body, this.ports);
+        return writeResult(result, format);
+    }
+}
+function listJson(records) {
+    return ok(JSON.stringify({
+        format_version: 1,
+        count: records.length,
+        records: records.map((r) => ({
+            id: r.id,
+            type: r.type,
+            status: r.status,
+            title: r.title,
+            file: r.file,
+            line: r.line,
+        })),
+    }));
+}
+function listHuman(records) {
+    if (records.length === 0) {
+        return ok("");
+    }
+    const idW = Math.max(...records.map((r) => r.id.length));
+    const typeW = Math.max(...records.map((r) => (r.type ?? "—").length));
+    const statusW = Math.max(...records.map((r) => (r.status ?? "—").length));
+    const lines = records.map((r) => {
+        const id = r.id.padEnd(idW);
+        const type = (r.type ?? "—").padEnd(typeW);
+        const status = (r.status ?? "—").padEnd(statusW);
+        return `${id}  ${type}  ${status}  ${r.title ?? ""}`.trimEnd();
+    });
+    return ok(lines.join("\n"));
+}
+function getJson(id, matches) {
+    const found = matches[0];
+    if (found === undefined) {
+        return {
+            exitCode: 1,
+            stdout: `${JSON.stringify({ format_version: 1, found: false, id })}\n`,
+            stderr: "",
+        };
+    }
+    return ok(JSON.stringify({
+        format_version: 1,
+        found: true,
+        id: found.id,
+        file: found.file,
+        start_line: found.startLine,
+        end_line: found.endLine,
+        raw: found.raw,
+    }));
+}
+function getHuman(id, matches) {
+    if (matches.length === 0) {
+        return { exitCode: 1, stdout: "", stderr: `record not found: ${id}\n` };
+    }
+    return ok(matches.map((m) => m.raw).join("\n---\n"));
+}
+function writeResult(result, format) {
+    if (!result.ok) {
+        if (format === "json") {
+            const body = JSON.stringify({
+                format_version: 1,
+                ok: false,
+                reason: result.reason,
+                detail: result.message,
+            });
+            return { exitCode: result.exitCode, stdout: `${body}\n`, stderr: "" };
+        }
+        return {
+            exitCode: result.exitCode,
+            stdout: "",
+            stderr: `${result.reason}: ${result.message}\n`,
+        };
+    }
+    if (format === "json") {
+        return ok(JSON.stringify({
+            format_version: 1,
+            ok: true,
+            action: result.action,
+            id: result.id,
+            file: result.file,
+            start_line: result.startLine,
+            end_line: result.endLine,
+        }));
+    }
+    return ok(`record ${result.action}: ${result.id} (${result.file}:${result.startLine}-${result.endLine})`);
+}

package/dist/features/record/adapters/outbound/NodeRecordFileSystem.d.ts

@@ -0,0 +1,9 @@
+import { type SddConfig } from "../../../../shared/domain/Config.js";
+import type { RecordConfigPort } from "../../ports/outbound/RecordConfigPort.js";
+import type { RecordFileReader, SpecFileEntry } from "../../ports/outbound/RecordFileReader.js";
+import type { RecordFileWriter } from "../../ports/outbound/RecordFileWriter.js";
+export declare class NodeRecordFileSystem implements RecordConfigPort, RecordFileReader, RecordFileWriter {
+    config(repoRoot: string): Promise<SddConfig>;
+    writeSpecFile(repoRoot: string, relativePath: string, content: string): Promise<void>;
+    resolveSpecFiles(repoRoot: string, patterns: readonly string[]): Promise<SpecFileEntry[]>;
+}

package/dist/features/record/adapters/outbound/NodeRecordFileSystem.js

@@ -0,0 +1,152 @@
+import { readFile, readdir, rename, stat, writeFile } from "node:fs/promises";
+import { join, relative, resolve } from "node:path";
+import { configFromJson, } from "../../../../shared/domain/Config.js";
+import { configFailure } from "../../../../shared/domain/Errors.js";
+export class NodeRecordFileSystem {
+    async config(repoRoot) {
+        const configPath = join(repoRoot, ".sdd", "config.json");
+        const text = await readConfig(configPath);
+        return configFromJson(parseConfigJson(text, configPath), configPath);
+    }
+    async writeSpecFile(repoRoot, relativePath, content) {
+        const abs = resolve(repoRoot, relativePath);
+        const tmp = `${abs}.tmp.${process.pid}.${Date.now()}`;
+        await writeFile(tmp, content, "utf8");
+        await rename(tmp, abs);
+    }
+    async resolveSpecFiles(repoRoot, patterns) {
+        const matched = new Set();
+        for (const pattern of patterns) {
+            for (const abs of await expandGlob(repoRoot, pattern)) {
+                matched.add(abs);
+            }
+        }
+        const out = [];
+        for (const abs of [...matched].sort()) {
+            const text = await readFile(abs, "utf8");
+            const rel = relative(repoRoot, abs);
+            out.push({ path: rel.split("\\").join("/"), content: text });
+        }
+        return out;
+    }
+}
+async function expandGlob(repoRoot, pattern) {
+    const normalised = pattern.split("\\").join("/");
+    if (!hasGlob(normalised)) {
+        const abs = resolve(repoRoot, normalised);
+        return (await isFile(abs)) ? [abs] : [];
+    }
+    const segments = normalised.split("/");
+    const literalSegments = [];
+    let firstGlobIndex = -1;
+    for (let i = 0; i < segments.length; i++) {
+        if (hasGlob(segments[i])) {
+            firstGlobIndex = i;
+            break;
+        }
+        literalSegments.push(segments[i]);
+    }
+    const baseDir = resolve(repoRoot, ...literalSegments);
+    const out = [];
+    await walkAndMatch(baseDir, segments.slice(firstGlobIndex), out);
+    return out;
+}
+async function walkAndMatch(dir, remaining, acc) {
+    if (remaining.length === 0) {
+        return;
+    }
+    const head = remaining[0];
+    const rest = remaining.slice(1);
+    let entries;
+    try {
+        entries = await readdir(dir, { withFileTypes: true });
+    }
+    catch {
+        return;
+    }
+    if (head === "**") {
+        if (rest.length === 0) {
+            for (const entry of entries) {
+                const abs = join(dir, entry.name);
+                if (entry.isDirectory()) {
+                    await walkAndMatch(abs, ["**"], acc);
+                }
+                else if (entry.isFile()) {
+                    acc.push(abs);
+                }
+            }
+            return;
+        }
+        for (const entry of entries) {
+            if (entry.isDirectory()) {
+                await walkAndMatch(join(dir, entry.name), remaining, acc);
+            }
+        }
+        await walkAndMatch(dir, rest, acc);
+        return;
+    }
+    for (const entry of entries) {
+        if (!matchSegment(head, entry.name)) {
+            continue;
+        }
+        const abs = join(dir, entry.name);
+        if (rest.length === 0) {
+            if (entry.isFile()) {
+                acc.push(abs);
+            }
+            continue;
+        }
+        if (entry.isDirectory()) {
+            await walkAndMatch(abs, rest, acc);
+        }
+    }
+}
+function matchSegment(pattern, name) {
+    if (!hasGlob(pattern)) {
+        return pattern === name;
+    }
+    const re = new RegExp(`^${pattern
+        .split("")
+        .map((c) => {
+        if (c === "*") {
+            return "[^/]*";
+        }
+        if (c === "?") {
+            return "[^/]";
+        }
+        return c.replace(/[.+^${}()|[\]\\]/g, "\\$&");
+    })
+        .join("")}$`);
+    return re.test(name);
+}
+function hasGlob(value) {
+    return /[*?[\]]/.test(value);
+}
+async function isFile(abs) {
+    try {
+        const s = await stat(abs);
+        return s.isFile();
+    }
+    catch {
+        return false;
+    }
+}
+async function readConfig(path) {
+    try {
+        return await readFile(path, "utf8");
+    }
+    catch (error) {
+        throw configFailure("config-missing", ".sdd/config.json is missing or unreadable", errorMessage(error), path);
+    }
+}
+function parseConfigJson(text, path) {
+    try {
+        return JSON.parse(text);
+    }
+    catch (error) {
+        throw configFailure("config-invalid", ".sdd/config.json is not valid JSON", errorMessage(error), path);
+    }
+}
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}

package/dist/features/record/application/AddRecord.d.ts

@@ -0,0 +1,11 @@
+import { type RecordWriteResult } from "../domain/RecordWrite.js";
+import type { RecordConfigPort } from "../ports/outbound/RecordConfigPort.js";
+import type { RecordFileReader } from "../ports/outbound/RecordFileReader.js";
+import type { RecordFileWriter } from "../ports/outbound/RecordFileWriter.js";
+type WritePorts = {
+    config: RecordConfigPort;
+    files: RecordFileReader;
+    writer: RecordFileWriter;
+};
+export declare function addRecord(cwd: string, afterId: string, rawBody: string, ports: WritePorts): Promise<RecordWriteResult>;
+export {};