agent-sdd 1.0.3

package/dist/features/doctor/domain/RegistryRow.js

@@ -0,0 +1,114 @@
+/*
+ * ENF-008: parser for the methodology `enforcement_registry.md`
+ * (compatibility metadata + registry rows). See the spec record for the
+ * table shape and diagnostic_id escaping rules. Pure parser, no node:*.
+ */
+/** Parse a methodology enforcement-registry markdown blob into a typed
+ *  RegistryDocument. Returns a discriminated outcome — never throws. */
+export function parseRegistry(markdown) {
+    const compat = readCompatibilityRange(markdown);
+    if (compat === null) {
+        return {
+            ok: false,
+            error: {
+                reason: "missing or invalid compatible_sdd_cli in ## Compatibility section",
+            },
+        };
+    }
+    const rows = readRegistryRows(markdown);
+    return { ok: true, doc: { compatibleSddCli: compat, rows } };
+}
+function readCompatibilityRange(markdown) {
+    for (const line of markdown.split(/\r?\n/)) {
+        const row = parseTableRow(line);
+        if (row === null) {
+            continue;
+        }
+        if (row.length >= 2 && row[0] === "compatible_sdd_cli") {
+            const value = row[1].replace(/^"|"$/g, "").trim();
+            return value === "" ? null : value;
+        }
+    }
+    return null;
+}
+function readRegistryRows(markdown) {
+    const out = [];
+    const lines = markdown.split(/\r?\n/);
+    let inTable = false;
+    let cols = [];
+    for (const line of lines) {
+        if (!inTable) {
+            const header = parseTableRow(line);
+            if (header !== null &&
+                header.includes("id") &&
+                header.includes("requirement") &&
+                header.includes("maturity") &&
+                header.includes("diagnostic_id")) {
+                cols = header;
+                inTable = true;
+            }
+            continue;
+        }
+        /* skip the |---|---| separator immediately after the header */
+        if (/^\s*\|?\s*-+/.test(line)) {
+            continue;
+        }
+        const row = parseTableRow(line);
+        if (row === null) {
+            inTable = false;
+            continue;
+        }
+        if (row.length !== cols.length) {
+            continue;
+        }
+        const rec = {};
+        for (let i = 0; i < cols.length; i++) {
+            rec[cols[i]] = row[i].trim();
+        }
+        /*
+         * A trailing `:hybrid` marks rows mixing mechanical + human verdicts; the
+         * base maturity drives reconciliation.
+         */
+        const maturity = rec.maturity.split(":")[0].trim();
+        if (!isRegistryMaturity(maturity)) {
+            continue;
+        }
+        const enfId = rec.id;
+        const ruleName = rec.requirement;
+        if (!enfId || !ruleName) {
+            continue;
+        }
+        const diagnosticIds = parseDiagnosticIds(rec.diagnostic_id ?? "");
+        out.push({ enfId, ruleName, maturity, diagnosticIds });
+    }
+    return out;
+}
+function isRegistryMaturity(value) {
+    return (value === "planned" ||
+        value === "implemented" ||
+        value === "deprecated" ||
+        value === "out_of_scope");
+}
+function parseDiagnosticIds(cell) {
+    return cell
+        .split("|")
+        .map((s) => s.trim())
+        .filter((s) => s !== "" && s !== "—" && s !== "-");
+}
+function parseTableRow(line) {
+    const trimmed = line.trim();
+    if (!trimmed.startsWith("|")) {
+        return null;
+    }
+    if (!trimmed.endsWith("|")) {
+        return null;
+    }
+    const inner = trimmed.slice(1, -1);
+    const cells = inner
+        .split(/(?<!\\)\|/)
+        .map((c) => c.replace(/\\\|/g, "|").trim());
+    if (cells.length < 2) {
+        return null;
+    }
+    return cells;
+}

package/dist/features/doctor/domain/SemverRange.d.ts

@@ -0,0 +1,7 @@
+export interface ParsedVersion {
+    major: number;
+    minor: number;
+    patch: number;
+}
+export declare function parseVersion(s: string): ParsedVersion | null;
+export declare function rangeIncludes(range: string, version: string): boolean;

package/dist/features/doctor/domain/SemverRange.js

@@ -0,0 +1,82 @@
+/*
+ * Tiny semver-range tester. Supports only the form sdd-cli's enforcement
+ * registry actually uses: `">=A.B <C.D"` (whitespace-separated comparators).
+ * No prerelease, no caret/tilde, no logical OR.
+ *
+ * Pure logic. No node:* imports.
+ */
+export function parseVersion(s) {
+    const m = /^(\d+)\.(\d+)(?:\.(\d+))?$/.exec(s.trim());
+    if (m === null) {
+        return null;
+    }
+    return {
+        major: Number.parseInt(m[1], 10),
+        minor: Number.parseInt(m[2], 10),
+        patch: m[3] !== undefined ? Number.parseInt(m[3], 10) : 0,
+    };
+}
+export function rangeIncludes(range, version) {
+    const parsed = parseVersion(version);
+    if (parsed === null) {
+        return false;
+    }
+    const comparators = parseRange(range);
+    if (comparators === null) {
+        return false;
+    }
+    return comparators.every((c) => satisfies(parsed, c));
+}
+function parseRange(range) {
+    const parts = range.trim().split(/\s+/);
+    const out = [];
+    for (const part of parts) {
+        const m = /^(>=|<=|>|<|=)?(\d+)\.(\d+)(?:\.(\d+))?$/.exec(part);
+        if (m === null) {
+            return null;
+        }
+        const rawOp = m[1] ?? "=";
+        if (!isComparatorOp(rawOp)) {
+            return null;
+        }
+        const op = rawOp;
+        const version = {
+            major: Number.parseInt(m[2], 10),
+            minor: Number.parseInt(m[3], 10),
+            patch: m[4] !== undefined ? Number.parseInt(m[4], 10) : 0,
+        };
+        out.push({ op, version });
+    }
+    return out;
+}
+function isComparatorOp(value) {
+    return (value === ">=" ||
+        value === ">" ||
+        value === "<=" ||
+        value === "<" ||
+        value === "=");
+}
+function satisfies(v, c) {
+    const cmp = compare(v, c.version);
+    switch (c.op) {
+        case ">=":
+            return cmp >= 0;
+        case ">":
+            return cmp > 0;
+        case "<=":
+            return cmp <= 0;
+        case "<":
+            return cmp < 0;
+        case "=":
+            return cmp === 0;
+    }
+}
+function compare(a, b) {
+    if (a.major !== b.major) {
+        return a.major - b.major;
+    }
+    if (a.minor !== b.minor) {
+        return a.minor - b.minor;
+    }
+    return a.patch - b.patch;
+}

package/dist/features/doctor/ports/inbound/DoctorCommand.d.ts

@@ -0,0 +1,8 @@
+import type { CommandResult, OutputFormat } from "../../../../shared/domain/CliOutput.js";
+export interface DoctorRequest {
+    rulesPath: string;
+    ruleVersion: boolean;
+}
+export interface DoctorCommand {
+    execute(cwd: string, req: DoctorRequest, format: Exclude<OutputFormat, "yaml">): Promise<CommandResult>;
+}

package/dist/features/doctor/ports/inbound/DoctorCommand.js

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

package/dist/features/doctor/ports/outbound/RegistryReader.d.ts

@@ -0,0 +1,12 @@
+export type RegistryFile = {
+    kind: "found";
+    path: string;
+    content: string;
+} | {
+    kind: "not-found";
+    path: string;
+};
+export interface RegistryReader {
+    readRegistry(rulesPath: string): Promise<RegistryFile>;
+    cliVersion(): Promise<string>;
+}

package/dist/features/doctor/ports/outbound/RegistryReader.js

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

package/dist/features/finalize/adapters/inbound/CliFinalizeHandler.d.ts

@@ -0,0 +1,8 @@
+import { type CommandResult, type OutputFormat } from "../../../../shared/domain/CliOutput.js";
+import { type RunFinalizePorts } from "../../application/RunFinalize.js";
+import type { FinalizeCommand, FinalizeRequest } from "../../ports/inbound/FinalizeCommand.js";
+export declare class CliFinalizeHandler implements FinalizeCommand {
+    private readonly ports;
+    constructor(ports: RunFinalizePorts);
+    execute(cwd: string, req: FinalizeRequest, format: Exclude<OutputFormat, "yaml">): Promise<CommandResult>;
+}

package/dist/features/finalize/adapters/inbound/CliFinalizeHandler.js

@@ -0,0 +1,80 @@
+import { ok, } from "../../../../shared/domain/CliOutput.js";
+import { runFinalize, } from "../../application/RunFinalize.js";
+export class CliFinalizeHandler {
+    ports;
+    constructor(ports) {
+        this.ports = ports;
+    }
+    async execute(cwd, req, format) {
+        const outcome = await runFinalize(cwd, req.planId, this.ports);
+        return render(outcome, format);
+    }
+}
+function render(outcome, format) {
+    if (outcome.kind === "finalized") {
+        return renderFinalized(outcome, format);
+    }
+    return renderRefusal(outcome, format);
+}
+function renderFinalized(outcome, format) {
+    if (format === "json") {
+        return ok(JSON.stringify({
+            format_version: 1,
+            ok: true,
+            plan_id: outcome.planId,
+            finalized_ids: outcome.finalizedIds,
+            files_changed: outcome.filesChanged,
+            archived_path: outcome.archivedPath,
+        }));
+    }
+    const lines = [];
+    lines.push(`finalize: ${outcome.finalizedIds.length} record(s) flipped in ${outcome.filesChanged.length} file(s).`);
+    for (const id of outcome.finalizedIds) {
+        lines.push(`  - ${id}`);
+    }
+    lines.push("");
+    lines.push(`finalize: plan archived at ${outcome.archivedPath}`);
+    return ok(lines.join("\n"));
+}
+function renderRefusal(outcome, format) {
+    if (outcome.kind === "no-active-plan") {
+        return refusal({ format_version: 1, ok: false, kind: "no-active-plan" }, "no active plan", 2, format);
+    }
+    if (outcome.kind === "invalid-plan") {
+        return refusal({
+            format_version: 1,
+            ok: false,
+            kind: "invalid-plan-file",
+            plan_id: outcome.planId,
+            source: outcome.sourcePath,
+            reason: outcome.reason,
+        }, `invalid plan file at ${outcome.sourcePath}: ${outcome.reason}`, 2, format);
+    }
+    if (outcome.kind === "graph-violation") {
+        return refusal({
+            format_version: 1,
+            ok: false,
+            reason: "proposed-references",
+            plan_id: outcome.planId,
+            offending: outcome.violations.map((v) => ({
+                id: v.flippedId,
+                references_id: v.referencesId,
+                references_status: v.referencesStatus,
+                via: v.via,
+            })),
+        }, `${outcome.violations.length} proposed-reference violation(s) — re-run after the referenced IDs are approved or added to the plan`, 1, format);
+    }
+    return refusal({
+        format_version: 1,
+        ok: false,
+        kind: "no-id-match",
+        plan_id: outcome.planId,
+        missing_ids: outcome.missingIds,
+    }, `${outcome.missingIds.length} attestation id(s) did not match any spec record`, 1, format);
+}
+function refusal(envelope, human, exitCode, format) {
+    if (format === "json") {
+        return { exitCode, stdout: `${JSON.stringify(envelope)}\n`, stderr: "" };
+    }
+    return { exitCode, stdout: "", stderr: `finalize: ${human}\n` };
+}

package/dist/features/finalize/adapters/outbound/NodeFinalizeFileSystem.d.ts

@@ -0,0 +1,11 @@
+import { type SddConfig } from "../../../../shared/domain/Config.js";
+import type { FinalizeConfigPort } from "../../ports/outbound/FinalizeConfigPort.js";
+import type { FinalizeFileSystem, SpecFileEntry } from "../../ports/outbound/FinalizeFileSystem.js";
+export declare class NodeFinalizeFileSystem implements FinalizeConfigPort, FinalizeFileSystem {
+    config(repoRoot: string): Promise<SddConfig>;
+    resolveSpecFiles(repoRoot: string, patterns: readonly string[]): Promise<SpecFileEntry[]>;
+    writeBatch(repoRoot: string, entries: ReadonlyArray<{
+        path: string;
+        content: string;
+    }>): Promise<void>;
+}

package/dist/features/finalize/adapters/outbound/NodeFinalizeFileSystem.js

@@ -0,0 +1,167 @@
+import { readFile, readdir, stat, writeFile, rename, unlink, } from "node:fs/promises";
+import { dirname, join, relative, resolve } from "node:path";
+import { configFromJson, } from "../../../../shared/domain/Config.js";
+import { configFailure, errorMessage, } from "../../../../shared/domain/Errors.js";
+export class NodeFinalizeFileSystem {
+    async config(repoRoot) {
+        const configPath = join(repoRoot, ".sdd", "config.json");
+        let text;
+        try {
+            text = await readFile(configPath, "utf8");
+        }
+        catch (e) {
+            throw configFailure("config-invalid", `cannot read .sdd/config.json: ${errorMessage(e)}`, undefined, configPath);
+        }
+        let parsed;
+        try {
+            parsed = JSON.parse(text);
+        }
+        catch (e) {
+            throw configFailure("config-invalid", `JSON parse error: ${errorMessage(e)}`, undefined, configPath);
+        }
+        return configFromJson(parsed, configPath);
+    }
+    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 list = [...matched].sort();
+        const out = [];
+        for (const abs of list) {
+            const text = await readFile(abs, "utf8");
+            const rel = relative(repoRoot, abs).split("\\").join("/");
+            out.push({ path: rel, content: text });
+        }
+        return out;
+    }
+    async writeBatch(repoRoot, entries) {
+        if (entries.length === 0) {
+            return;
+        }
+        const tmps = [];
+        try {
+            for (const e of entries) {
+                const finalAbs = resolve(repoRoot, e.path);
+                const tmp = `${finalAbs}.finalize.tmp.${process.pid}.${Date.now()}.${tmps.length}`;
+                await writeFile(tmp, e.content, "utf8");
+                tmps.push({ tmp, final: finalAbs });
+            }
+            for (const { tmp, final } of tmps) {
+                await rename(tmp, final);
+            }
+        }
+        catch (e) {
+            /* Best-effort cleanup of any tmp files left behind. */
+            for (const { tmp } of tmps) {
+                try {
+                    await unlink(tmp);
+                }
+                catch {
+                    /* tmp may already be gone; original error is rethrown */
+                }
+            }
+            throw e;
+        }
+    }
+}
+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 literal = [];
+    let firstGlobIndex = -1;
+    for (let i = 0; i < segments.length; i++) {
+        if (hasGlob(segments[i])) {
+            firstGlobIndex = i;
+            break;
+        }
+        literal.push(segments[i]);
+    }
+    const baseDir = resolve(repoRoot, ...literal);
+    const remainder = segments.slice(firstGlobIndex);
+    return walk(baseDir, remainder);
+}
+function hasGlob(s) {
+    return s.includes("*") || s.includes("?");
+}
+async function walk(baseDir, segments) {
+    if (segments.length === 0) {
+        return (await isFile(baseDir)) ? [baseDir] : [];
+    }
+    const [head, ...rest] = segments;
+    if (head === "**") {
+        const out = [];
+        out.push(...(await walk(baseDir, rest)));
+        let entries;
+        try {
+            entries = await readdir(baseDir, { withFileTypes: true });
+        }
+        catch {
+            return [];
+        }
+        for (const e of entries) {
+            if (!e.isDirectory()) {
+                continue;
+            }
+            out.push(...(await walk(join(baseDir, e.name), segments)));
+        }
+        return out;
+    }
+    const re = segmentToRegExp(head);
+    let entries;
+    try {
+        entries = await readdir(baseDir, { withFileTypes: true });
+    }
+    catch {
+        return [];
+    }
+    const out = [];
+    for (const e of entries) {
+        if (!re.test(e.name)) {
+            continue;
+        }
+        const next = join(baseDir, e.name);
+        if (rest.length === 0) {
+            if (await isFile(next)) {
+                out.push(next);
+            }
+            continue;
+        }
+        if (e.isDirectory()) {
+            out.push(...(await walk(next, rest)));
+        }
+    }
+    return out;
+}
+function segmentToRegExp(seg) {
+    let body = "^";
+    for (const ch of seg) {
+        if (ch === "*") {
+            body += "[^/]*";
+        }
+        else if (ch === "?") {
+            body += "[^/]";
+        }
+        else {
+            body += ch.replace(/[-./\\^$+?()|[\]{}]/g, "\\$&");
+        }
+    }
+    body += "$";
+    return new RegExp(body);
+}
+async function isFile(abs) {
+    try {
+        const st = await stat(abs);
+        return st.isFile();
+    }
+    catch {
+        return false;
+    }
+}
+void dirname; /* reserved */

package/dist/features/finalize/adapters/outbound/NodePlanRepo.d.ts

@@ -0,0 +1,7 @@
+import type { PlanLoad, PlanRepo } from "../../ports/outbound/PlanRepo.js";
+export declare class NodePlanRepo implements PlanRepo {
+    load(repoRoot: string, plansDir: string, planId: string | undefined): Promise<PlanLoad>;
+    archive(repoRoot: string, plansDir: string, planId: string): Promise<{
+        archivedPath: string;
+    }>;
+}

package/dist/features/finalize/adapters/outbound/NodePlanRepo.js

@@ -0,0 +1,82 @@
+import { promises as fs } from "node:fs";
+import { dirname, join, relative, resolve } from "node:path";
+import { parse as yamlParse } from "yaml";
+import { errorMessage } from "../../../../shared/domain/Errors.js";
+import { parsePlanFile } from "../../../../shared/domain/PlanFile.js";
+export class NodePlanRepo {
+    async load(repoRoot, plansDir, planId) {
+        const dirAbs = resolve(repoRoot, plansDir);
+        const id = planId ?? (await readActive(dirAbs));
+        if (id === null) {
+            return { kind: "no-active-plan" };
+        }
+        const sourceRel = join(plansDir, `${id}.yaml`).split("\\").join("/");
+        const sourceAbs = resolve(repoRoot, sourceRel);
+        let raw;
+        try {
+            raw = await fs.readFile(sourceAbs, "utf8");
+        }
+        catch {
+            return {
+                kind: "invalid-plan-file",
+                planId: id,
+                sourcePath: sourceRel,
+                reason: "plan file not found",
+            };
+        }
+        let parsed;
+        try {
+            parsed = yamlParse(raw);
+        }
+        catch (e) {
+            return {
+                kind: "invalid-plan-file",
+                planId: id,
+                sourcePath: sourceRel,
+                reason: `YAML parse error: ${errorMessage(e)}`,
+            };
+        }
+        try {
+            const plan = parsePlanFile(parsed);
+            return { kind: "found", plan, sourcePath: sourceRel };
+        }
+        catch (e) {
+            return {
+                kind: "invalid-plan-file",
+                planId: id,
+                sourcePath: sourceRel,
+                reason: errorMessage(e),
+            };
+        }
+    }
+    async archive(repoRoot, plansDir, planId) {
+        const dirAbs = resolve(repoRoot, plansDir);
+        const finalizedDirAbs = join(dirAbs, "finalized");
+        await fs.mkdir(finalizedDirAbs, { recursive: true });
+        const fromAbs = join(dirAbs, `${planId}.yaml`);
+        const toAbs = join(finalizedDirAbs, `${planId}.yaml`);
+        await fs.rename(fromAbs, toAbs);
+        const active = await readActive(dirAbs);
+        if (active === planId) {
+            try {
+                await fs.unlink(join(dirAbs, ".active"));
+            }
+            catch {
+                /* missing is fine */
+            }
+        }
+        const rel = relative(repoRoot, toAbs).split("\\").join("/");
+        return { archivedPath: rel };
+    }
+}
+async function readActive(dirAbs) {
+    try {
+        const raw = await fs.readFile(join(dirAbs, ".active"), "utf8");
+        const id = raw.trim();
+        return id.length > 0 ? id : null;
+    }
+    catch {
+        return null;
+    }
+}
+void dirname; /* reserved */

package/dist/features/finalize/adapters/outbound/SystemFinalizeClock.d.ts

@@ -0,0 +1,4 @@
+import type { FinalizeClock } from "../../ports/outbound/FinalizeClock.js";
+export declare class SystemFinalizeClock implements FinalizeClock {
+    now(): Date;
+}

package/dist/features/finalize/adapters/outbound/SystemFinalizeClock.js

@@ -0,0 +1,5 @@
+export class SystemFinalizeClock {
+    now() {
+        return new Date();
+    }
+}

package/dist/features/finalize/application/RunFinalize.d.ts

@@ -0,0 +1,34 @@
+import { type GraphViolation } from "../domain/ValidateFinalizeGraph.js";
+import type { FinalizeClock } from "../ports/outbound/FinalizeClock.js";
+import type { FinalizeConfigPort } from "../ports/outbound/FinalizeConfigPort.js";
+import type { FinalizeFileSystem } from "../ports/outbound/FinalizeFileSystem.js";
+import type { PlanRepo } from "../ports/outbound/PlanRepo.js";
+export interface RunFinalizePorts {
+    clock: FinalizeClock;
+    config: FinalizeConfigPort;
+    files: FinalizeFileSystem;
+    plans: PlanRepo;
+}
+export type RunFinalizeOutcome = {
+    kind: "no-active-plan";
+} | {
+    kind: "invalid-plan";
+    planId: string;
+    sourcePath: string;
+    reason: string;
+} | {
+    kind: "graph-violation";
+    planId: string;
+    violations: GraphViolation[];
+} | {
+    kind: "no-id-match";
+    planId: string;
+    missingIds: string[];
+} | {
+    kind: "finalized";
+    planId: string;
+    finalizedIds: string[];
+    filesChanged: string[];
+    archivedPath: string;
+};
+export declare function runFinalize(cwd: string, planId: string | undefined, ports: RunFinalizePorts): Promise<RunFinalizeOutcome>;