agent-sdd 1.0.3

package/dist/features/refresh/adapters/outbound/NodeRefreshFileReader.js

@@ -0,0 +1,44 @@
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { configFromJson, } from "../../../../shared/domain/Config.js";
+import { configFailure } from "../../../../shared/domain/Errors.js";
+import { specBlocks } from "../../../../shared/domain/SpecBlocks.js";
+export class NodeRefreshFileReader {
+    async config(repoRoot) {
+        const configPath = join(repoRoot, ".sdd", "config.json");
+        const text = await readConfig(configPath);
+        const config = configFromJson(parseConfigJson(text, configPath), configPath);
+        await this.spec(repoRoot, config);
+        return config;
+    }
+    async spec(repoRoot, config) {
+        const path = join(repoRoot, config.specFile);
+        let text;
+        try {
+            text = await readFile(path, "utf8");
+        }
+        catch (error) {
+            throw configFailure("config-invalid", `spec_file is not readable: ${config.specFile}`, errorMessage(error), path);
+        }
+        return { path, blocks: specBlocks(text) };
+    }
+}
+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/refresh/adapters/outbound/SystemRefreshClock.d.ts

@@ -0,0 +1,4 @@
+import type { RefreshClockPort } from "../../ports/outbound/RefreshClockPort.js";
+export declare class SystemRefreshClock implements RefreshClockPort {
+    iso(): string;
+}

package/dist/features/refresh/adapters/outbound/SystemRefreshClock.js

@@ -0,0 +1,5 @@
+export class SystemRefreshClock {
+    iso() {
+        return new Date().toISOString();
+    }
+}

package/dist/features/refresh/application/BuildRefreshStubs.d.ts

@@ -0,0 +1,25 @@
+import { type Stub } from "../domain/DiffStubs.js";
+import type { RefreshClockPort } from "../ports/outbound/RefreshClockPort.js";
+import type { RefreshConfigPort } from "../ports/outbound/RefreshConfigPort.js";
+import type { RefreshGitPort } from "../ports/outbound/RefreshGitPort.js";
+import type { RefreshSpecPort } from "../ports/outbound/RefreshSpecPort.js";
+export type RefreshOutcome = {
+    kind: "json";
+    body: {
+        format_version: 1;
+        stubs: Stub[];
+    };
+} | {
+    kind: "human";
+    text: string;
+} | {
+    kind: "yaml";
+    text: string;
+};
+export interface BuildRefreshStubsPorts {
+    clock: RefreshClockPort;
+    config: RefreshConfigPort;
+    git: RefreshGitPort;
+    spec: RefreshSpecPort;
+}
+export declare function buildRefreshStubs(cwd: string, format: "human" | "json" | "yaml", ports: BuildRefreshStubsPorts): Promise<RefreshOutcome>;

package/dist/features/refresh/application/BuildRefreshStubs.js

@@ -0,0 +1,43 @@
+import { configFailure } from "../../../shared/domain/Errors.js";
+import { stringValue, typedBlock, } from "../../../shared/domain/SpecBlocks.js";
+import { humanStubText, stubs, yamlStubStream, } from "../domain/DiffStubs.js";
+import { footprint, impsMissingBinding } from "../domain/Footprint.js";
+export async function buildRefreshStubs(cwd, format, ports) {
+    const repoRoot = await ports.git.repoRoot(cwd);
+    await ports.git.headSha(repoRoot);
+    const config = await ports.config.config(repoRoot);
+    await assertGlobMatches(ports.git, repoRoot, config.discoveryScope);
+    const loadedSpec = await ports.spec.spec(repoRoot, config);
+    const missingBinding = impsMissingBinding(loadedSpec.blocks, config.footprint.bindingIdPrefix, config.footprint.bindingField);
+    if (missingBinding.length > 0) {
+        throw configFailure("config-invalid", `IMP block(s) missing ${config.footprint.bindingField}: ${missingBinding.join(", ")} (OQ-004 / BEH-051)`);
+    }
+    const recorded = baseline(loadedSpec.path, loadedSpec.blocks, config.baselineId);
+    const committedPaths = await ports.git.changedPaths(repoRoot, recorded.baselineCommitSha, config.discoveryScope);
+    const dirtyPaths = await ports.git.dirtyPaths(repoRoot, config.discoveryScope);
+    const changedPaths = [...new Set([...committedPaths, ...dirtyPaths])].sort();
+    const pathFootprint = footprint(loadedSpec.blocks, config.footprint.bindingIdPrefix, config.footprint.bindingField);
+    const emittedStubs = stubs(changedPaths, pathFootprint, ports.clock.iso());
+    if (format === "json") {
+        return { kind: "json", body: { format_version: 1, stubs: emittedStubs } };
+    }
+    if (format === "human") {
+        return { kind: "human", text: humanStubText(emittedStubs) };
+    }
+    return { kind: "yaml", text: yamlStubStream(emittedStubs) };
+}
+function baseline(specPath, blocks, baselineId) {
+    const block = typedBlock(blocks, baselineId, "BrownfieldBaseline", specPath);
+    return {
+        freshnessToken: stringValue(block, "freshness_token", specPath),
+        baselineCommitSha: stringValue(block, "baseline_commit_sha", specPath),
+    };
+}
+async function assertGlobMatches(git, repoRoot, scope) {
+    for (const entry of scope.filter((value) => /[*?[]/.test(value))) {
+        const paths = await git.treePaths(repoRoot, [entry]);
+        if (paths.length === 0) {
+            throw configFailure("config-invalid", `discovery_scope glob matched zero files: ${entry}`);
+        }
+    }
+}

package/dist/features/refresh/domain/DiffStubs.d.ts

@@ -0,0 +1,24 @@
+import type { Footprint } from "./Footprint.js";
+export type Stub = DeltaStub | OpenQStub;
+export interface DeltaStub {
+    kind: "Delta";
+    path: string;
+    target_imp_ids: string[];
+    target_ids: string[];
+    emitted_at: string;
+    compatibility_action: "TODO";
+    kind_of_change: "TODO";
+    tests_old_behavior: "TODO";
+    tests_new_behavior: "TODO";
+}
+export interface OpenQStub {
+    kind: "Open-Q";
+    path: string;
+    question: string;
+    options: string[];
+    blocking: "TODO";
+    emitted_at: string;
+}
+export declare function stubs(paths: readonly string[], footprint: Footprint, emittedAt: string): Stub[];
+export declare function yamlStubStream(stubs: readonly Stub[]): string;
+export declare function humanStubText(stubs: readonly Stub[]): string;

package/dist/features/refresh/domain/DiffStubs.js

@@ -0,0 +1,81 @@
+import { footprintEntriesForPath } from "./Footprint.js";
+export function stubs(paths, footprint, emittedAt) {
+    return [...new Set(paths)]
+        .sort((left, right) => left.localeCompare(right, "en"))
+        .map((path) => {
+        const entries = footprintEntriesForPath(footprint, path);
+        if (entries.length === 0) {
+            return openQStub(path, emittedAt);
+        }
+        const targetImpIds = entries.map((entry) => entry.impId).sort();
+        const targetIds = [
+            ...new Set(entries.flatMap((entry) => entry.targetIds)),
+        ].sort();
+        return {
+            kind: "Delta",
+            path,
+            target_imp_ids: targetImpIds,
+            target_ids: targetIds,
+            emitted_at: emittedAt,
+            compatibility_action: "TODO",
+            kind_of_change: "TODO",
+            tests_old_behavior: "TODO",
+            tests_new_behavior: "TODO",
+        };
+    });
+}
+export function yamlStubStream(stubs) {
+    if (stubs.length === 0) {
+        return "";
+    }
+    return stubs.map((stub) => `---\n${yamlStub(stub)}`).join("\n");
+}
+export function humanStubText(stubs) {
+    return stubs
+        .map((stub) => {
+        if (stub.kind === "Delta") {
+            return `Delta ${stub.path} -> ${stub.target_imp_ids.join(",")}`;
+        }
+        return `Open-Q ${stub.path} -> -`;
+    })
+        .join("\n");
+}
+function openQStub(path, emittedAt) {
+    return {
+        kind: "Open-Q",
+        path,
+        question: `Should ${path} be bound to a normative ID?`,
+        options: ["bind_to_existing_or_new_id", "leave_unmodeled"],
+        blocking: "TODO",
+        emitted_at: emittedAt,
+    };
+}
+function yamlStub(stub) {
+    if (stub.kind === "Delta") {
+        return [
+            "kind: Delta",
+            `path: ${quoted(stub.path)}`,
+            "target_imp_ids:",
+            ...stub.target_imp_ids.map((id) => `  - ${quoted(id)}`),
+            "target_ids:",
+            ...stub.target_ids.map((id) => `  - ${quoted(id)}`),
+            `emitted_at: ${quoted(stub.emitted_at)}`,
+            "compatibility_action: TODO",
+            "kind_of_change: TODO",
+            "tests_old_behavior: TODO",
+            "tests_new_behavior: TODO",
+        ].join("\n");
+    }
+    return [
+        "kind: Open-Q",
+        `path: ${quoted(stub.path)}`,
+        `question: ${quoted(stub.question)}`,
+        "options:",
+        ...stub.options.map((option) => `  - ${quoted(option)}`),
+        "blocking: TODO",
+        `emitted_at: ${quoted(stub.emitted_at)}`,
+    ].join("\n");
+}
+function quoted(value) {
+    return JSON.stringify(value);
+}

package/dist/features/refresh/domain/Footprint.d.ts

@@ -0,0 +1,14 @@
+import type { SpecBlock } from "../../../shared/domain/SpecBlocks.js";
+export interface FootprintEntry {
+    impId: string;
+    targetIds: string[];
+    paths: string[];
+}
+export interface Footprint {
+    entries: FootprintEntry[];
+}
+export declare function footprint(blocks: readonly SpecBlock[], bindingIdPrefix: string, bindingField: string): Footprint;
+/** ENF/OQ-004 — IDs of binding-prefixed (IMP-*) blocks that carry no
+ *  `bindingField`. An empty result means every such block declares a binding. */
+export declare function impsMissingBinding(blocks: readonly SpecBlock[], bindingIdPrefix: string, bindingField: string): string[];
+export declare function footprintEntriesForPath(footprint: Footprint, path: string): FootprintEntry[];

package/dist/features/refresh/domain/Footprint.js

@@ -0,0 +1,45 @@
+import { blocksByNeutralPrefix } from "../../../shared/domain/SpecBlocks.js";
+export function footprint(blocks, bindingIdPrefix, bindingField) {
+    const entries = blocksByNeutralPrefix(blocks, bindingIdPrefix).map((block) => {
+        return {
+            impId: block.id,
+            targetIds: stringArray(block.parsed.target_ids),
+            paths: stringLeaves(block.parsed[bindingField]),
+        };
+    });
+    return { entries };
+}
+/** ENF/OQ-004 — IDs of binding-prefixed (IMP-*) blocks that carry no
+ *  `bindingField`. An empty result means every such block declares a binding. */
+export function impsMissingBinding(blocks, bindingIdPrefix, bindingField) {
+    return blocksByNeutralPrefix(blocks, bindingIdPrefix)
+        .filter((block) => block.parsed[bindingField] === undefined)
+        .map((block) => block.id);
+}
+export function footprintEntriesForPath(footprint, path) {
+    return footprint.entries.filter((entry) => entry.paths.some((boundPath) => covers(boundPath, path)));
+}
+function covers(boundPath, path) {
+    return path === boundPath || path.startsWith(`${boundPath}/`);
+}
+function stringLeaves(value) {
+    if (typeof value === "string") {
+        return [value];
+    }
+    if (Array.isArray(value)) {
+        return value.flatMap((entry) => stringLeaves(entry));
+    }
+    if (isRecord(value)) {
+        return Object.values(value).flatMap((entry) => stringLeaves(entry));
+    }
+    return [];
+}
+function stringArray(value) {
+    if (!Array.isArray(value)) {
+        return [];
+    }
+    return value.filter((entry) => typeof entry === "string");
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}

package/dist/features/refresh/ports/inbound/RefreshCommand.d.ts

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

package/dist/features/refresh/ports/inbound/RefreshCommand.js

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

package/dist/features/refresh/ports/outbound/RefreshClockPort.d.ts

@@ -0,0 +1,3 @@
+export interface RefreshClockPort {
+    iso(): string;
+}

package/dist/features/refresh/ports/outbound/RefreshClockPort.js

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

package/dist/features/refresh/ports/outbound/RefreshConfigPort.d.ts

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

package/dist/features/refresh/ports/outbound/RefreshConfigPort.js

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

package/dist/features/refresh/ports/outbound/RefreshGitPort.d.ts

@@ -0,0 +1,7 @@
+export interface RefreshGitPort {
+    repoRoot(cwd: string): Promise<string>;
+    headSha(repoRoot: string): Promise<string>;
+    treePaths(repoRoot: string, scope: readonly string[]): Promise<string[]>;
+    dirtyPaths(repoRoot: string, scope: readonly string[]): Promise<string[]>;
+    changedPaths(repoRoot: string, baselineCommitSha: string, scope: readonly string[]): Promise<string[]>;
+}

package/dist/features/refresh/ports/outbound/RefreshGitPort.js

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

package/dist/features/refresh/ports/outbound/RefreshSpecPort.d.ts

@@ -0,0 +1,9 @@
+import type { SddConfig } from "../../../../shared/domain/Config.js";
+import type { SpecBlock } from "../../../../shared/domain/SpecBlocks.js";
+export interface RefreshSpec {
+    path: string;
+    blocks: SpecBlock[];
+}
+export interface RefreshSpecPort {
+    spec(repoRoot: string, config: SddConfig): Promise<RefreshSpec>;
+}

package/dist/features/refresh/ports/outbound/RefreshSpecPort.js

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

package/dist/features/report/adapters/inbound/CliReportHandler.d.ts

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

package/dist/features/report/adapters/inbound/CliReportHandler.js

@@ -0,0 +1,35 @@
+import { ok, } from "../../../../shared/domain/CliOutput.js";
+import { CliFailure } from "../../../../shared/domain/Errors.js";
+import { runReport } from "../../application/RunReport.js";
+export class CliReportHandler {
+    ports;
+    constructor(ports) {
+        this.ports = ports;
+    }
+    async execute(cwd, req, format) {
+        if (!req.prSummary) {
+            return {
+                exitCode: 2,
+                stdout: "",
+                stderr: "report: --pr-summary is required (no other modes implemented in v0.4)\n",
+            };
+        }
+        try {
+            const out = await runReport(cwd, { prSummary: true, against: req.against }, this.ports);
+            if (format === "json") {
+                return ok(JSON.stringify({
+                    format_version: 1,
+                    ok: true,
+                    markdown: out.markdown,
+                }));
+            }
+            return ok(out.markdown);
+        }
+        catch (error) {
+            if (error instanceof CliFailure) {
+                return { exitCode: 2, stdout: "", stderr: `${error.message}\n` };
+            }
+            throw error;
+        }
+    }
+}

package/dist/features/report/adapters/outbound/NodeReportFileSystem.d.ts

@@ -0,0 +1,7 @@
+import { type SddConfig } from "../../../../shared/domain/Config.js";
+import type { ReportConfigPort } from "../../ports/outbound/ReportConfigPort.js";
+import type { ReportFileReader, SpecFileEntry } from "../../ports/outbound/ReportFileReader.js";
+export declare class NodeReportFileSystem implements ReportConfigPort, ReportFileReader {
+    config(repoRoot: string): Promise<SddConfig>;
+    resolveSpecFiles(repoRoot: string, patterns: readonly string[]): Promise<SpecFileEntry[]>;
+}

package/dist/features/report/adapters/outbound/NodeReportFileSystem.js

@@ -0,0 +1,128 @@
+import { readFile, readdir, stat } from "node:fs/promises";
+import { join, relative, resolve } from "node:path";
+import { configFromJson, } from "../../../../shared/domain/Config.js";
+import { configFailure, errorMessage, } from "../../../../shared/domain/Errors.js";
+export class NodeReportFileSystem {
+    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);
+        }
+        return configFromJson(JSON.parse(text), 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 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);
+    return walk(baseDir, segments.slice(firstGlobIndex));
+}
+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 {
+        return (await stat(abs)).isFile();
+    }
+    catch {
+        return false;
+    }
+}

package/dist/features/report/application/RunReport.d.ts

@@ -0,0 +1,19 @@
+import type { ReportConfigPort } from "../ports/outbound/ReportConfigPort.js";
+import type { ReportFileReader } from "../ports/outbound/ReportFileReader.js";
+export interface RunReportPorts {
+    config: ReportConfigPort;
+    files: ReportFileReader;
+    /** Optional git-at-ref reader for the debt-budget delta section. When
+     *  omitted, debt-budget delta is rendered as "(--against not provided
+     *  or git unavailable)". */
+    readAtRef?: (repoRoot: string, ref: string, relativePath: string) => Promise<string | null>;
+    repoRoot?: (cwd: string) => Promise<string>;
+}
+export interface RunReportInput {
+    prSummary: boolean;
+    against?: string;
+}
+export interface RunReportOutput {
+    markdown: string;
+}
+export declare function runReport(cwd: string, input: RunReportInput, ports: RunReportPorts): Promise<RunReportOutput>;