@garygentry/system1-core 0.1.0

package/dist/sources/read.js

@@ -0,0 +1,294 @@
+import { execFileSync } from "node:child_process";
+import { existsSync, readFileSync, realpathSync, statSync } from "node:fs";
+import { isAbsolute, relative, resolve } from "node:path";
+import { glob } from "tinyglobby";
+import { DecisionsError } from "../errors.js";
+function resolvePath(cwd, path) {
+    const absolute = resolve(cwd, path);
+    let realAbsolute = absolute;
+    try {
+        realAbsolute = realpathSync(absolute);
+    }
+    catch {
+        // Missing files are reported by the caller.
+    }
+    const real = toRel(cwd, realAbsolute);
+    return {
+        absolute,
+        display: toRel(cwd, absolute),
+        real,
+        outside: isAbsolute(real) || real.startsWith(".."),
+    };
+}
+const DEFAULT_MAX_FILE_BYTES = 2_000_000;
+const GIT_TIMEOUT_MS = 10_000;
+/** Never content: dependencies, git internals, and our own state (config, fixtures, ledger). */
+const ALWAYS_IGNORED = ["**/node_modules/**", "**/.git/**", "**/.system1/**"];
+export async function readSources(specs, options) {
+    const documents = [];
+    const skipped = [];
+    for (const spec of specs) {
+        const result = await readSource(spec, options);
+        documents.push(...result.documents);
+        skipped.push(...result.skipped);
+    }
+    return { documents, skipped };
+}
+async function readSource(spec, options) {
+    switch (spec.kind) {
+        case "text":
+            return { documents: [{ id: spec.id ?? "text", kind: "text", text: spec.text }], skipped: [] };
+        case "stdin":
+            return { documents: [{ id: "stdin", kind: "text", text: spec.text }], skipped: [] };
+        case "file":
+            return readFiles([spec.path], options, spec.range);
+        case "glob":
+            return readGlob(spec.patterns, options);
+        case "jsonl":
+            return readJsonl(spec.path, options);
+        case "diff":
+            return readDiff(spec, options);
+    }
+}
+/**
+ * Parse `path`, `path:12` or `path:12-40` (1-based, inclusive). A bare `:`
+ * suffix that isn't a line spec stays part of the path.
+ */
+export function parseFileRef(ref) {
+    const match = /^(.*?):(\d+)(?:-(\d+))?$/.exec(ref);
+    if (!match?.[1])
+        return { path: ref };
+    const start = Number(match[2]);
+    const end = match[3] === undefined ? start : Number(match[3]);
+    if (start < 1 || end < start) {
+        throw new DecisionsError("invalid-request", `Invalid line range in "${ref}" (use path:START-END, 1-based)`);
+    }
+    return { path: match[1], range: { start, end } };
+}
+function readFiles(paths, options, range) {
+    const documents = [];
+    const skipped = [];
+    const limit = options.maxFileBytes ?? DEFAULT_MAX_FILE_BYTES;
+    for (const path of paths) {
+        const { absolute, display: rel, real, outside } = resolvePath(options.cwd, path);
+        if (!existsSync(absolute) || !statSync(absolute).isFile()) {
+            throw new DecisionsError("source-error", `No such file: ${rel}`, { path: rel });
+        }
+        if (outside && !options.allowOutside) {
+            skipped.push({ path: rel, reason: "outside-repo", detail: real });
+            continue;
+        }
+        if (statSync(absolute).size > limit) {
+            skipped.push({ path: rel, reason: "too-large", detail: `> ${limit} bytes` });
+            continue;
+        }
+        const buffer = readFileSync(absolute);
+        if (buffer.subarray(0, 8000).includes(0)) {
+            skipped.push({ path: rel, reason: "binary" });
+            continue;
+        }
+        let text = buffer.toString("utf8");
+        let startLine = 1;
+        if (range) {
+            const lines = text.split("\n");
+            if (range.start > lines.length) {
+                throw new DecisionsError("source-error", `${rel} has ${lines.length} lines; range starts at ${range.start}`);
+            }
+            text = lines.slice(range.start - 1, range.end).join("\n");
+            startLine = range.start;
+        }
+        const id = range
+            ? `${rel}:${range.start}-${Math.min(range.end, startLine + text.split("\n").length - 1)}`
+            : rel;
+        documents.push({
+            id,
+            kind: "file",
+            path: rel,
+            ...(real !== rel ? { realPath: real } : {}),
+            text,
+            startLine,
+        });
+    }
+    return { documents, skipped };
+}
+async function readGlob(patterns, options) {
+    const matches = await glob([...patterns], {
+        cwd: options.cwd,
+        ignore: ALWAYS_IGNORED,
+        dot: true,
+        onlyFiles: true,
+    });
+    matches.sort();
+    const ignored = new Set(gitIgnored(options.cwd, matches));
+    const kept = matches.filter((m) => !ignored.has(m));
+    const result = readFiles(kept, options);
+    return {
+        documents: result.documents,
+        skipped: [
+            ...[...ignored].map((path) => ({ path, reason: "gitignored" })),
+            ...result.skipped,
+        ],
+    };
+}
+/**
+ * The subset of `paths` git would ignore, when `cwd` is inside a work tree.
+ * Outside one, nothing is filtered (and `node_modules`/`.git` are still skipped).
+ */
+export function gitIgnored(cwd, paths) {
+    if (paths.length === 0 || !insideGitWorkTree(cwd))
+        return [];
+    try {
+        const out = execFileSync("git", ["-C", cwd, "check-ignore", "-z", "--stdin"], {
+            input: paths.join("\0"),
+            encoding: "utf8",
+            stdio: ["pipe", "pipe", "ignore"],
+            // Bounded: a git that never answers must not hang the run. Some
+            // sandboxes make a piped child hang indefinitely.
+            timeout: GIT_TIMEOUT_MS,
+            killSignal: "SIGKILL",
+        });
+        return out.split("\0").filter(Boolean);
+    }
+    catch (error) {
+        // Exit 1 means "none ignored", which is not an error.
+        if (error.status === 1)
+            return [];
+        if (error.signal === "SIGKILL") {
+            throw new DecisionsError("source-error", `git check-ignore did not answer within ${GIT_TIMEOUT_MS} ms. Name the files with --file, or run where git works.`);
+        }
+        throw new DecisionsError("source-error", `git check-ignore failed: ${String(error)}`);
+    }
+}
+function insideGitWorkTree(cwd) {
+    try {
+        return (execFileSync("git", ["-C", cwd, "rev-parse", "--is-inside-work-tree"], {
+            encoding: "utf8",
+            stdio: ["ignore", "pipe", "ignore"],
+        }).trim() === "true");
+    }
+    catch {
+        return false;
+    }
+}
+function readJsonl(path, options) {
+    const { absolute, display: rel, real, outside } = resolvePath(options.cwd, path);
+    if (!existsSync(absolute))
+        throw new DecisionsError("source-error", `No such file: ${rel}`, { path: rel });
+    if (outside && !options.allowOutside) {
+        return { documents: [], skipped: [{ path: rel, reason: "outside-repo", detail: real }] };
+    }
+    const documents = [];
+    readFileSync(absolute, "utf8")
+        .split("\n")
+        .forEach((line, index) => {
+        if (line.trim() === "")
+            return;
+        let data;
+        try {
+            data = JSON.parse(line);
+        }
+        catch {
+            throw new DecisionsError("source-error", `${rel}:${index + 1} is not valid JSON`, {
+                path: rel,
+                line: index + 1,
+            });
+        }
+        documents.push({
+            id: `${rel}:row${index + 1}`,
+            kind: "row",
+            path: rel,
+            ...(real !== rel ? { realPath: real } : {}),
+            data,
+            startLine: index + 1,
+        });
+    });
+    return { documents, skipped: [] };
+}
+/** One document per file in the diff, text starting at its `diff --git` header. */
+function readDiff(spec, options) {
+    if (spec.range?.startsWith("-")) {
+        throw new DecisionsError("invalid-request", `Invalid diff range "${spec.range}"`);
+    }
+    const args = ["-C", options.cwd, "diff", "--no-color", "--no-ext-diff", "--unified=3"];
+    if (spec.staged)
+        args.push("--cached");
+    args.push(spec.range ?? "HEAD", "--", ...(spec.paths ?? []));
+    let out;
+    try {
+        out = execFileSync("git", args, {
+            encoding: "utf8",
+            maxBuffer: 64 * 1024 * 1024,
+            stdio: ["ignore", "pipe", "pipe"],
+        });
+    }
+    catch (error) {
+        const stderr = String(error.stderr ?? error).trim();
+        throw new DecisionsError("source-error", `git diff failed: ${stderr}`);
+    }
+    return splitDiffByFile(out);
+}
+export function splitDiffByFile(diff) {
+    const sections = diff.split(/^(?=diff --git )/m).filter((s) => s.startsWith("diff --git "));
+    const documents = [];
+    const skipped = [];
+    for (const text of sections) {
+        const raw = /^\+\+\+ (?:b\/)?(.+)$/m.exec(text)?.[1] ?? /^diff --git a\/.+ b\/(.+)$/m.exec(text)?.[1];
+        // Git quotes the whole side, including its `b/` prefix: "b/secrets/é.txt".
+        const decoded = raw === undefined ? undefined : unquoteGitPath(raw.trim());
+        const path = decoded?.replace(/^b\//, "");
+        if (path === undefined || path === "/dev/null") {
+            // Without a path, excludes cannot be applied, so it is never sent.
+            skipped.push({
+                path: raw?.trim() ?? "(unnamed)",
+                reason: "excluded",
+                detail: "unreadable diff path",
+            });
+            continue;
+        }
+        documents.push({ id: `${path}#diff`, kind: "diff", path, text: text.replace(/\n$/, "") });
+    }
+    return { documents, skipped };
+}
+/**
+ * Git quotes paths with unusual bytes (`"secrets/\303\251.txt"`). Left quoted,
+ * the path never matches an exclude, so it is decoded here.
+ */
+export function unquoteGitPath(path) {
+    if (!path.startsWith('"'))
+        return path;
+    if (!path.endsWith('"') || path.length < 2)
+        return undefined;
+    const body = path.slice(1, -1);
+    const bytes = [];
+    for (let i = 0; i < body.length; i++) {
+        if (body[i] !== "\\") {
+            bytes.push(...Buffer.from(body[i], "utf8"));
+            continue;
+        }
+        const next = body[++i];
+        if (next === undefined)
+            return undefined;
+        const simple = { n: 10, t: 9, r: 13, '"': 34, "\\": 92 };
+        if (next in simple) {
+            bytes.push(simple[next]);
+        }
+        else if (/[0-7]/.test(next)) {
+            const octal = body.slice(i, i + 3);
+            if (!/^[0-7]{3}$/.test(octal))
+                return undefined;
+            bytes.push(Number.parseInt(octal, 8));
+            i += 2;
+        }
+        else {
+            return undefined;
+        }
+    }
+    return Buffer.from(bytes).toString("utf8");
+}
+function toRel(cwd, absolute) {
+    const rel = relative(cwd, absolute);
+    return rel === "" || isAbsolute(rel) || rel.startsWith("..")
+        ? absolute
+        : rel.split("\\").join("/");
+}
+//# sourceMappingURL=read.js.map

package/dist/sources/read.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"read.js","sourceRoot":"","sources":["../../src/sources/read.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAA;AACjD,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,YAAY,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAA;AAC1E,OAAO,EAAE,UAAU,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,WAAW,CAAA;AACzD,OAAO,EAAE,IAAI,EAAE,MAAM,YAAY,CAAA;AACjC,OAAO,EAAE,cAAc,EAAE,MAAM,cAAc,CAAA;AA4B7C,SAAS,WAAW,CAAC,GAAW,EAAE,IAAY;IAC5C,MAAM,QAAQ,GAAG,OAAO,CAAC,GAAG,EAAE,IAAI,CAAC,CAAA;IACnC,IAAI,YAAY,GAAG,QAAQ,CAAA;IAC3B,IAAI,CAAC;QACH,YAAY,GAAG,YAAY,CAAC,QAAQ,CAAC,CAAA;IACvC,CAAC;IAAC,MAAM,CAAC;QACP,4CAA4C;IAC9C,CAAC;IACD,MAAM,IAAI,GAAG,KAAK,CAAC,GAAG,EAAE,YAAY,CAAC,CAAA;IACrC,OAAO;QACL,QAAQ;QACR,OAAO,EAAE,KAAK,CAAC,GAAG,EAAE,QAAQ,CAAC;QAC7B,IAAI;QACJ,OAAO,EAAE,UAAU,CAAC,IAAI,CAAC,IAAI,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC;KACnD,CAAA;AACH,CAAC;AAOD,MAAM,sBAAsB,GAAG,SAAS,CAAA;AACxC,MAAM,cAAc,GAAG,MAAM,CAAA;AAE7B,gGAAgG;AAChG,MAAM,cAAc,GAAG,CAAC,oBAAoB,EAAE,YAAY,EAAE,gBAAgB,CAAC,CAAA;AAE7E,MAAM,CAAC,KAAK,UAAU,WAAW,CAC/B,KAA4B,EAC5B,OAAoB;IAEpB,MAAM,SAAS,GAAe,EAAE,CAAA;IAChC,MAAM,OAAO,GAAc,EAAE,CAAA;IAC7B,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,MAAM,MAAM,GAAG,MAAM,UAAU,CAAC,IAAI,EAAE,OAAO,CAAC,CAAA;QAC9C,SAAS,CAAC,IAAI,CAAC,GAAG,MAAM,CAAC,SAAS,CAAC,CAAA;QACnC,OAAO,CAAC,IAAI,CAAC,GAAG,MAAM,CAAC,OAAO,CAAC,CAAA;IACjC,CAAC;IACD,OAAO,EAAE,SAAS,EAAE,OAAO,EAAE,CAAA;AAC/B,CAAC;AAED,KAAK,UAAU,UAAU,CAAC,IAAgB,EAAE,OAAoB;IAC9D,QAAQ,IAAI,CAAC,IAAI,EAAE,CAAC;QAClB,KAAK,MAAM;YACT,OAAO,EAAE,SAAS,EAAE,CAAC,EAAE,EAAE,EAAE,IAAI,CAAC,EAAE,IAAI,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,CAAC,EAAE,OAAO,EAAE,EAAE,EAAE,CAAA;QAC/F,KAAK,OAAO;YACV,OAAO,EAAE,SAAS,EAAE,CAAC,EAAE,EAAE,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,CAAC,EAAE,OAAO,EAAE,EAAE,EAAE,CAAA;QACrF,KAAK,MAAM;YACT,OAAO,SAAS,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,OAAO,EAAE,IAAI,CAAC,KAAK,CAAC,CAAA;QACpD,KAAK,MAAM;YACT,OAAO,QAAQ,CAAC,IAAI,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAA;QACzC,KAAK,OAAO;YACV,OAAO,SAAS,CAAC,IAAI,CAAC,IAAI,EAAE,OAAO,CAAC,CAAA;QACtC,KAAK,MAAM;YACT,OAAO,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC,CAAA;IAClC,CAAC;AACH,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,YAAY,CAAC,GAAW;IACtC,MAAM,KAAK,GAAG,0BAA0B,CAAC,IAAI,CAAC,GAAG,CAAC,CAAA;IAClD,IAAI,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC;QAAE,OAAO,EAAE,IAAI,EAAE,GAAG,EAAE,CAAA;IACrC,MAAM,KAAK,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAA;IAC9B,MAAM,GAAG,GAAG,KAAK,CAAC,CAAC,CAAC,KAAK,SAAS,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAA;IAC7D,IAAI,KAAK,GAAG,CAAC,IAAI,GAAG,GAAG,KAAK,EAAE,CAAC;QAC7B,MAAM,IAAI,cAAc,CACtB,iBAAiB,EACjB,0BAA0B,GAAG,iCAAiC,CAC/D,CAAA;IACH,CAAC;IACD,OAAO,EAAE,IAAI,EAAE,KAAK,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,EAAE,KAAK,EAAE,GAAG,EAAE,EAAE,CAAA;AAClD,CAAC;AAED,SAAS,SAAS,CAAC,KAAwB,EAAE,OAAoB,EAAE,KAAiB;IAClF,MAAM,SAAS,GAAe,EAAE,CAAA;IAChC,MAAM,OAAO,GAAc,EAAE,CAAA;IAC7B,MAAM,KAAK,GAAG,OAAO,CAAC,YAAY,IAAI,sBAAsB,CAAA;IAC5D,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,MAAM,EAAE,QAAQ,EAAE,OAAO,EAAE,GAAG,EAAE,IAAI,EAAE,OAAO,EAAE,GAAG,WAAW,CAAC,OAAO,CAAC,GAAG,EAAE,IAAI,CAAC,CAAA;QAChF,IAAI,CAAC,UAAU,CAAC,QAAQ,CAAC,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC;YAC1D,MAAM,IAAI,cAAc,CAAC,cAAc,EAAE,iBAAiB,GAAG,EAAE,EAAE,EAAE,IAAI,EAAE,GAAG,EAAE,CAAC,CAAA;QACjF,CAAC;QACD,IAAI,OAAO,IAAI,CAAC,OAAO,CAAC,YAAY,EAAE,CAAC;YACrC,OAAO,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,GAAG,EAAE,MAAM,EAAE,cAAc,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,CAAA;YACjE,SAAQ;QACV,CAAC;QACD,IAAI,QAAQ,CAAC,QAAQ,CAAC,CAAC,IAAI,GAAG,KAAK,EAAE,CAAC;YACpC,OAAO,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,GAAG,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,KAAK,KAAK,QAAQ,EAAE,CAAC,CAAA;YAC5E,SAAQ;QACV,CAAC;QACD,MAAM,MAAM,GAAG,YAAY,CAAC,QAAQ,CAAC,CAAA;QACrC,IAAI,MAAM,CAAC,QAAQ,CAAC,CAAC,EAAE,IAAI,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,CAAC;YACzC,OAAO,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC,CAAA;YAC7C,SAAQ;QACV,CAAC;QACD,IAAI,IAAI,GAAG,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAA;QAClC,IAAI,SAAS,GAAG,CAAC,CAAA;QACjB,IAAI,KAAK,EAAE,CAAC;YACV,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAA;YAC9B,IAAI,KAAK,CAAC,KAAK,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC;gBAC/B,MAAM,IAAI,cAAc,CACtB,cAAc,EACd,GAAG,GAAG,QAAQ,KAAK,CAAC,MAAM,2BAA2B,KAAK,CAAC,KAAK,EAAE,CACnE,CAAA;YACH,CAAC;YACD,IAAI,GAAG,KAAK,CAAC,KAAK,CAAC,KAAK,CAAC,KAAK,GAAG,CAAC,EAAE,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;YACzD,SAAS,GAAG,KAAK,CAAC,KAAK,CAAA;QACzB,CAAC;QACD,MAAM,EAAE,GAAG,KAAK;YACd,CAAC,CAAC,GAAG,GAAG,IAAI,KAAK,CAAC,KAAK,IAAI,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,GAAG,EAAE,SAAS,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,EAAE;YACzF,CAAC,CAAC,GAAG,CAAA;QACP,SAAS,CAAC,IAAI,CAAC;YACb,EAAE;YACF,IAAI,EAAE,MAAM;YACZ,IAAI,EAAE,GAAG;YACT,GAAG,CAAC,IAAI,KAAK,GAAG,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YAC3C,IAAI;YACJ,SAAS;SACV,CAAC,CAAA;IACJ,CAAC;IACD,OAAO,EAAE,SAAS,EAAE,OAAO,EAAE,CAAA;AAC/B,CAAC;AAED,KAAK,UAAU,QAAQ,CAAC,QAA2B,EAAE,OAAoB;IACvE,MAAM,OAAO,GAAG,MAAM,IAAI,CAAC,CAAC,GAAG,QAAQ,CAAC,EAAE;QACxC,GAAG,EAAE,OAAO,CAAC,GAAG;QAChB,MAAM,EAAE,cAAc;QACtB,GAAG,EAAE,IAAI;QACT,SAAS,EAAE,IAAI;KAChB,CAAC,CAAA;IACF,OAAO,CAAC,IAAI,EAAE,CAAA;IACd,MAAM,OAAO,GAAG,IAAI,GAAG,CAAC,UAAU,CAAC,OAAO,CAAC,GAAG,EAAE,OAAO,CAAC,CAAC,CAAA;IACzD,MAAM,IAAI,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAA;IACnD,MAAM,MAAM,GAAG,SAAS,CAAC,IAAI,EAAE,OAAO,CAAC,CAAA;IACvC,OAAO;QACL,SAAS,EAAE,MAAM,CAAC,SAAS;QAC3B,OAAO,EAAE;YACP,GAAG,CAAC,GAAG,OAAO,CAAC,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,YAAqB,EAAE,CAAC,CAAC;YACxE,GAAG,MAAM,CAAC,OAAO;SAClB;KACF,CAAA;AACH,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,UAAU,CAAC,GAAW,EAAE,KAAwB;IAC9D,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,IAAI,CAAC,iBAAiB,CAAC,GAAG,CAAC;QAAE,OAAO,EAAE,CAAA;IAC5D,IAAI,CAAC;QACH,MAAM,GAAG,GAAG,YAAY,CAAC,KAAK,EAAE,CAAC,IAAI,EAAE,GAAG,EAAE,cAAc,EAAE,IAAI,EAAE,SAAS,CAAC,EAAE;YAC5E,KAAK,EAAE,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC;YACvB,QAAQ,EAAE,MAAM;YAChB,KAAK,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,CAAC;YACjC,gEAAgE;YAChE,kDAAkD;YAClD,OAAO,EAAE,cAAc;YACvB,UAAU,EAAE,SAAS;SACtB,CAAC,CAAA;QACF,OAAO,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAA;IACxC,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,sDAAsD;QACtD,IAAK,KAA6B,CAAC,MAAM,KAAK,CAAC;YAAE,OAAO,EAAE,CAAA;QAC1D,IAAK,KAA6B,CAAC,MAAM,KAAK,SAAS,EAAE,CAAC;YACxD,MAAM,IAAI,cAAc,CACtB,cAAc,EACd,0CAA0C,cAAc,0DAA0D,CACnH,CAAA;QACH,CAAC;QACD,MAAM,IAAI,cAAc,CAAC,cAAc,EAAE,4BAA4B,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC,CAAA;IACvF,CAAC;AACH,CAAC;AAED,SAAS,iBAAiB,CAAC,GAAW;IACpC,IAAI,CAAC;QACH,OAAO,CACL,YAAY,CAAC,KAAK,EAAE,CAAC,IAAI,EAAE,GAAG,EAAE,WAAW,EAAE,uBAAuB,CAAC,EAAE;YACrE,QAAQ,EAAE,MAAM;YAChB,KAAK,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,CAAC;SACpC,CAAC,CAAC,IAAI,EAAE,KAAK,MAAM,CACrB,CAAA;IACH,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAA;IACd,CAAC;AACH,CAAC;AAED,SAAS,SAAS,CAAC,IAAY,EAAE,OAAoB;IACnD,MAAM,EAAE,QAAQ,EAAE,OAAO,EAAE,GAAG,EAAE,IAAI,EAAE,OAAO,EAAE,GAAG,WAAW,CAAC,OAAO,CAAC,GAAG,EAAE,IAAI,CAAC,CAAA;IAChF,IAAI,CAAC,UAAU,CAAC,QAAQ,CAAC;QACvB,MAAM,IAAI,cAAc,CAAC,cAAc,EAAE,iBAAiB,GAAG,EAAE,EAAE,EAAE,IAAI,EAAE,GAAG,EAAE,CAAC,CAAA;IACjF,IAAI,OAAO,IAAI,CAAC,OAAO,CAAC,YAAY,EAAE,CAAC;QACrC,OAAO,EAAE,SAAS,EAAE,EAAE,EAAE,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,GAAG,EAAE,MAAM,EAAE,cAAc,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,EAAE,CAAA;IAC1F,CAAC;IACD,MAAM,SAAS,GAAe,EAAE,CAAA;IAChC,YAAY,CAAC,QAAQ,EAAE,MAAM,CAAC;SAC3B,KAAK,CAAC,IAAI,CAAC;SACX,OAAO,CAAC,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE;QACvB,IAAI,IAAI,CAAC,IAAI,EAAE,KAAK,EAAE;YAAE,OAAM;QAC9B,IAAI,IAAa,CAAA;QACjB,IAAI,CAAC;YACH,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAA;QACzB,CAAC;QAAC,MAAM,CAAC;YACP,MAAM,IAAI,cAAc,CAAC,cAAc,EAAE,GAAG,GAAG,IAAI,KAAK,GAAG,CAAC,oBAAoB,EAAE;gBAChF,IAAI,EAAE,GAAG;gBACT,IAAI,EAAE,KAAK,GAAG,CAAC;aAChB,CAAC,CAAA;QACJ,CAAC;QACD,SAAS,CAAC,IAAI,CAAC;YACb,EAAE,EAAE,GAAG,GAAG,OAAO,KAAK,GAAG,CAAC,EAAE;YAC5B,IAAI,EAAE,KAAK;YACX,IAAI,EAAE,GAAG;YACT,GAAG,CAAC,IAAI,KAAK,GAAG,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YAC3C,IAAI;YACJ,SAAS,EAAE,KAAK,GAAG,CAAC;SACrB,CAAC,CAAA;IACJ,CAAC,CAAC,CAAA;IACJ,OAAO,EAAE,SAAS,EAAE,OAAO,EAAE,EAAE,EAAE,CAAA;AACnC,CAAC;AAED,mFAAmF;AACnF,SAAS,QAAQ,CACf,IAA2C,EAC3C,OAAoB;IAEpB,IAAI,IAAI,CAAC,KAAK,EAAE,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC;QAChC,MAAM,IAAI,cAAc,CAAC,iBAAiB,EAAE,uBAAuB,IAAI,CAAC,KAAK,GAAG,CAAC,CAAA;IACnF,CAAC;IACD,MAAM,IAAI,GAAG,CAAC,IAAI,EAAE,OAAO,CAAC,GAAG,EAAE,MAAM,EAAE,YAAY,EAAE,eAAe,EAAE,aAAa,CAAC,CAAA;IACtF,IAAI,IAAI,CAAC,MAAM;QAAE,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC,CAAA;IACtC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK,IAAI,MAAM,EAAE,IAAI,EAAE,GAAG,CAAC,IAAI,CAAC,KAAK,IAAI,EAAE,CAAC,CAAC,CAAA;IAC5D,IAAI,GAAW,CAAA;IACf,IAAI,CAAC;QACH,GAAG,GAAG,YAAY,CAAC,KAAK,EAAE,IAAI,EAAE;YAC9B,QAAQ,EAAE,MAAM;YAChB,SAAS,EAAE,EAAE,GAAG,IAAI,GAAG,IAAI;YAC3B,KAAK,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,CAAC;SAClC,CAAC,CAAA;IACJ,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,MAAM,GAAG,MAAM,CAAE,KAA8B,CAAC,MAAM,IAAI,KAAK,CAAC,CAAC,IAAI,EAAE,CAAA;QAC7E,MAAM,IAAI,cAAc,CAAC,cAAc,EAAE,oBAAoB,MAAM,EAAE,CAAC,CAAA;IACxE,CAAC;IACD,OAAO,eAAe,CAAC,GAAG,CAAC,CAAA;AAC7B,CAAC;AAED,MAAM,UAAU,eAAe,CAAC,IAAY;IAC1C,MAAM,QAAQ,GAAG,IAAI,CAAC,KAAK,CAAC,mBAAmB,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,UAAU,CAAC,aAAa,CAAC,CAAC,CAAA;IAC3F,MAAM,SAAS,GAAe,EAAE,CAAA;IAChC,MAAM,OAAO,GAAc,EAAE,CAAA;IAC7B,KAAK,MAAM,IAAI,IAAI,QAAQ,EAAE,CAAC;QAC5B,MAAM,GAAG,GACP,wBAAwB,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,6BAA6B,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC,CAAA;QAC3F,2EAA2E;QAC3E,MAAM,OAAO,GAAG,GAAG,KAAK,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,cAAc,CAAC,GAAG,CAAC,IAAI,EAAE,CAAC,CAAA;QAC1E,MAAM,IAAI,GAAG,OAAO,EAAE,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAA;QACzC,IAAI,IAAI,KAAK,SAAS,IAAI,IAAI,KAAK,WAAW,EAAE,CAAC;YAC/C,mEAAmE;YACnE,OAAO,CAAC,IAAI,CAAC;gBACX,IAAI,EAAE,GAAG,EAAE,IAAI,EAAE,IAAI,WAAW;gBAChC,MAAM,EAAE,UAAU;gBAClB,MAAM,EAAE,sBAAsB;aAC/B,CAAC,CAAA;YACF,SAAQ;QACV,CAAC;QACD,SAAS,CAAC,IAAI,CAAC,EAAE,EAAE,EAAE,GAAG,IAAI,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,EAAE,CAAC,CAAA;IAC3F,CAAC;IACD,OAAO,EAAE,SAAS,EAAE,OAAO,EAAE,CAAA;AAC/B,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,cAAc,CAAC,IAAY;IACzC,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC;QAAE,OAAO,IAAI,CAAA;IACtC,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,IAAI,CAAC,MAAM,GAAG,CAAC;QAAE,OAAO,SAAS,CAAA;IAC5D,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAA;IAC9B,MAAM,KAAK,GAAa,EAAE,CAAA;IAC1B,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACrC,IAAI,IAAI,CAAC,CAAC,CAAC,KAAK,IAAI,EAAE,CAAC;YACrB,KAAK,CAAC,IAAI,CAAC,GAAG,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAW,EAAE,MAAM,CAAC,CAAC,CAAA;YACrD,SAAQ;QACV,CAAC;QACD,MAAM,IAAI,GAAG,IAAI,CAAC,EAAE,CAAC,CAAC,CAAA;QACtB,IAAI,IAAI,KAAK,SAAS;YAAE,OAAO,SAAS,CAAA;QACxC,MAAM,MAAM,GAA2B,EAAE,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,EAAE,EAAE,GAAG,EAAE,EAAE,EAAE,IAAI,EAAE,EAAE,EAAE,CAAA;QAChF,IAAI,IAAI,IAAI,MAAM,EAAE,CAAC;YACnB,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,IAAI,CAAW,CAAC,CAAA;QACpC,CAAC;aAAM,IAAI,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;YAC9B,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,GAAG,CAAC,CAAC,CAAA;YAClC,IAAI,CAAC,YAAY,CAAC,IAAI,CAAC,KAAK,CAAC;gBAAE,OAAO,SAAS,CAAA;YAC/C,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,CAAA;YACrC,CAAC,IAAI,CAAC,CAAA;QACR,CAAC;aAAM,CAAC;YACN,OAAO,SAAS,CAAA;QAClB,CAAC;IACH,CAAC;IACD,OAAO,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAA;AAC5C,CAAC;AAED,SAAS,KAAK,CAAC,GAAW,EAAE,QAAgB;IAC1C,MAAM,GAAG,GAAG,QAAQ,CAAC,GAAG,EAAE,QAAQ,CAAC,CAAA;IACnC,OAAO,GAAG,KAAK,EAAE,IAAI,UAAU,CAAC,GAAG,CAAC,IAAI,GAAG,CAAC,UAAU,CAAC,IAAI,CAAC;QAC1D,CAAC,CAAC,QAAQ;QACV,CAAC,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAA;AAC/B,CAAC"}

package/dist/sources/types.d.ts

@@ -0,0 +1,79 @@
+import type { State } from "../model/types.js";
+/**
+ * Where the content to judge comes from. The agent names a source and the
+ * engine reads it, so the agent never pastes content into a command (charter
+ * principle 1: state by reference, not by value).
+ *
+ * There is deliberately no `command` source (decision 0014): pipe command
+ * output into `stdin` instead.
+ */
+export type SourceSpec = {
+    kind: "text";
+    text: string;
+    id?: string;
+}
+/** Content the caller already read from stdin. */
+ | {
+    kind: "stdin";
+    text: string;
+} | {
+    kind: "file";
+    path: string;
+    range?: LineRange;
+} | {
+    kind: "glob";
+    patterns: string[];
+} | {
+    kind: "jsonl";
+    path: string;
+}
+/**
+ * `git diff`. With no `range`, working tree changes against `HEAD`; `staged`
+ * means the index against `HEAD`. `paths` limits the diff.
+ */
+ | {
+    kind: "diff";
+    range?: string;
+    staged?: boolean;
+    paths?: string[];
+};
+/** 1-based and inclusive, as editors show them. */
+export interface LineRange {
+    start: number;
+    end: number;
+}
+/** One unit of read content, before splitting. */
+export interface Document {
+    id: string;
+    kind: "text" | "file" | "row" | "diff";
+    /** Repo-relative path, when the content came from a file. */
+    path?: string;
+    /**
+     * The path with symlinks resolved, when it differs from `path`. Excludes are
+     * matched against this, so `innocent.txt -> .env` is still withheld.
+     */
+    realPath?: string;
+    /** Text content (every kind except structured JSONL rows). */
+    text?: string;
+    /** Parsed value of a JSONL row. */
+    data?: unknown;
+    /** Line number of the first line of `text` in its file (1-based). */
+    startLine?: number;
+}
+export interface Skipped {
+    path: string;
+    reason: "binary" | "too-large" | "gitignored" | "excluded" | "outside-repo";
+    /** For `excluded`: the pattern that matched. */
+    detail?: string;
+}
+/** One thing to send: a state, labelled with where it came from. */
+export interface Item {
+    id: string;
+    state: State;
+    path?: string;
+    /** See `Document.realPath`. */
+    realPath?: string;
+    /** 1-based inclusive line span in `path`, when known. */
+    lines?: LineRange;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/sources/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/sources/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,mBAAmB,CAAA;AAE9C;;;;;;;GAOG;AACH,MAAM,MAAM,UAAU,GAClB;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,EAAE,CAAC,EAAE,MAAM,CAAA;CAAE;AAC7C,kDAAkD;GAChD;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAC/B;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,SAAS,CAAA;CAAE,GACjD;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,EAAE,CAAA;CAAE,GACpC;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE;AACjC;;;GAGG;GACD;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,OAAO,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,EAAE,CAAA;CAAE,CAAA;AAExE,mDAAmD;AACnD,MAAM,WAAW,SAAS;IACxB,KAAK,EAAE,MAAM,CAAA;IACb,GAAG,EAAE,MAAM,CAAA;CACZ;AAED,kDAAkD;AAClD,MAAM,WAAW,QAAQ;IACvB,EAAE,EAAE,MAAM,CAAA;IACV,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,KAAK,GAAG,MAAM,CAAA;IACtC,6DAA6D;IAC7D,IAAI,CAAC,EAAE,MAAM,CAAA;IACb;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,8DAA8D;IAC9D,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,mCAAmC;IACnC,IAAI,CAAC,EAAE,OAAO,CAAA;IACd,qEAAqE;IACrE,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB;AAED,MAAM,WAAW,OAAO;IACtB,IAAI,EAAE,MAAM,CAAA;IACZ,MAAM,EAAE,QAAQ,GAAG,WAAW,GAAG,YAAY,GAAG,UAAU,GAAG,cAAc,CAAA;IAC3E,gDAAgD;IAChD,MAAM,CAAC,EAAE,MAAM,CAAA;CAChB;AAED,oEAAoE;AACpE,MAAM,WAAW,IAAI;IACnB,EAAE,EAAE,MAAM,CAAA;IACV,KAAK,EAAE,KAAK,CAAA;IACZ,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,+BAA+B;IAC/B,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,yDAAyD;IACzD,KAAK,CAAC,EAAE,SAAS,CAAA;CAClB"}

package/dist/sources/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/sources/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/sources/types.ts"],"names":[],"mappings":""}

package/dist/spec/expect.d.ts

@@ -0,0 +1,39 @@
+import type { Answer, QuestionSet } from "../model/types.js";
+import { type Filter } from "../project/project.js";
+/**
+ * What an example expects of one question. Written in a spec's
+ * `examples[].expect`:
+ *
+ *   noul:    true | false          compared at 0.5
+ *   choice:  <option key>          compared with the winner
+ *   score:   <level> | [lo, hi]    the weighted mean rounds to the level, or lies in the range
+ *   any:     ">=0.7", "in a,b" …   the `--keep` shorthand, applied to this question
+ *   any:     undecided             the answer should be too flat to act on
+ */
+export type Expectation = {
+    kind: "noul";
+    value: boolean;
+} | {
+    kind: "choice";
+    value: string;
+} | {
+    kind: "level";
+    value: number;
+} | {
+    kind: "range";
+    lo: number;
+    hi: number;
+} | {
+    kind: "filter";
+    filter: Filter;
+    text: string;
+} | {
+    kind: "undecided";
+};
+/** Parse one example's `expect` map against its questions, collecting every problem. */
+export declare function parseExpect(expect: Record<string, unknown>, questions: QuestionSet, where: string): Record<string, Expectation>;
+/** Whether an answer meets an expectation. Undecided answers are handled by the caller. */
+export declare function meets(name: string, answer: Answer, expectation: Expectation): boolean;
+/** The expectation as written, for reports. */
+export declare function describeExpectation(expectation: Expectation): string;
+//# sourceMappingURL=expect.d.ts.map

package/dist/spec/expect.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"expect.d.ts","sourceRoot":"","sources":["../../src/spec/expect.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,MAAM,EAAY,WAAW,EAAE,MAAM,mBAAmB,CAAA;AACtE,OAAO,EAAE,KAAK,MAAM,EAAwB,MAAM,uBAAuB,CAAA;AAEzE;;;;;;;;;GASG;AACH,MAAM,MAAM,WAAW,GACnB;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,OAAO,CAAA;CAAE,GAChC;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GACjC;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GAChC;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,EAAE,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,MAAM,CAAA;CAAE,GACzC;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAChD;IAAE,IAAI,EAAE,WAAW,CAAA;CAAE,CAAA;AAIzB,wFAAwF;AACxF,wBAAgB,WAAW,CACzB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC/B,SAAS,EAAE,WAAW,EACtB,KAAK,EAAE,MAAM,GACZ,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,CAmB7B;AA4CD,2FAA2F;AAC3F,wBAAgB,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,WAAW,EAAE,WAAW,GAAG,OAAO,CAiBrF;AAED,+CAA+C;AAC/C,wBAAgB,mBAAmB,CAAC,WAAW,EAAE,WAAW,GAAG,MAAM,CAWpE"}

package/dist/spec/expect.js

@@ -0,0 +1,95 @@
+import { DecisionsError } from "../errors.js";
+import { matches, parseFilter } from "../project/project.js";
+const OPERATOR = /^\s*(>=|<=|!=|>|<|=|in\s)/;
+/** Parse one example's `expect` map against its questions, collecting every problem. */
+export function parseExpect(expect, questions, where) {
+    const out = {};
+    const problems = [];
+    for (const [name, raw] of Object.entries(expect)) {
+        const question = questions[name];
+        if (!question) {
+            problems.push(`${where}: expects "${name}", which is not a question in this spec`);
+            continue;
+        }
+        try {
+            out[name] = parseOne(name, question, raw);
+        }
+        catch (error) {
+            problems.push(`${where}: ${error.message}`);
+        }
+    }
+    if (problems.length > 0) {
+        throw new DecisionsError("invalid-request", problems.join("\n"), { problems });
+    }
+    return out;
+}
+function parseOne(name, question, raw) {
+    if (raw === "undecided")
+        return { kind: "undecided" };
+    if (typeof raw === "string" && OPERATOR.test(raw)) {
+        return {
+            kind: "filter",
+            filter: parseFilter(`${name}${raw.startsWith("in") ? " " : ""}${raw}`, { [name]: question }),
+            text: raw.trim(),
+        };
+    }
+    switch (question.type) {
+        case "noul":
+            if (typeof raw === "boolean")
+                return { kind: "noul", value: raw };
+            break;
+        case "choice":
+            if (typeof raw === "string") {
+                if (!(raw in question.criteria)) {
+                    throw new Error(`expects "${name}" to be "${raw}", which is not one of its options (${Object.keys(question.criteria).join(", ")})`);
+                }
+                return { kind: "choice", value: raw };
+            }
+            break;
+        case "score": {
+            const top = question.criteria.length - 1;
+            if (Number.isInteger(raw) && raw >= 0 && raw <= top) {
+                return { kind: "level", value: raw };
+            }
+            if (Array.isArray(raw) && raw.length === 2) {
+                const [lo, hi] = raw;
+                if (typeof lo === "number" && typeof hi === "number" && lo <= hi) {
+                    return { kind: "range", lo, hi };
+                }
+            }
+            throw new Error(`expects "${name}" to be a level 0–${top} or a [lo, hi] range`);
+        }
+    }
+    throw new Error(`expects "${name}" to be ${JSON.stringify(raw)}; a ${question.type} takes ${question.type === "noul" ? "true or false" : "an option key"}, "undecided", or a filter such as ">=0.7"`);
+}
+/** Whether an answer meets an expectation. Undecided answers are handled by the caller. */
+export function meets(name, answer, expectation) {
+    switch (expectation.kind) {
+        case "undecided":
+            return false;
+        case "filter":
+            return matches({ [name]: answer }, expectation.filter);
+        case "noul":
+            return answer.type === "noul" && answer.noul >= 0.5 === expectation.value;
+        case "choice":
+            return answer.type === "choice" && answer.choice === expectation.value;
+        case "level":
+            return answer.type === "score" && Math.round(answer.score) === expectation.value;
+        case "range":
+            return (answer.type === "score" && answer.score >= expectation.lo && answer.score <= expectation.hi);
+    }
+}
+/** The expectation as written, for reports. */
+export function describeExpectation(expectation) {
+    switch (expectation.kind) {
+        case "undecided":
+            return "undecided";
+        case "filter":
+            return expectation.text;
+        case "range":
+            return `[${expectation.lo}, ${expectation.hi}]`;
+        default:
+            return String(expectation.value);
+    }
+}
+//# sourceMappingURL=expect.js.map

package/dist/spec/expect.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"expect.js","sourceRoot":"","sources":["../../src/spec/expect.ts"],"names":[],"mappings":"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"}

package/dist/spec/spec.d.ts

@@ -0,0 +1,90 @@
+import { type Static, Type } from "typebox";
+import type { QuestionSet } from "../model/types.js";
+export declare const SPEC_FORMAT = 1;
+export declare const SpecSchema: Type.TObject<{
+    /** Spec file format. Absent means 1; a newer one is refused, not guessed. */
+    version: Type.TOptional<Type.TInteger>;
+    description: Type.TString;
+    questions: Type.TRecord<"^.*$", Type.TUnknown>;
+    keep: Type.TOptional<Type.TArray<Type.TString>>;
+    sort: Type.TOptional<Type.TString>;
+    policy: Type.TOptional<Type.TObject<{
+        thresholds: Type.TOptional<Type.TRecord<"^.*$", Type.TObject<{
+            value: Type.TNumber;
+            why: Type.TString;
+        }>>>;
+    }>>;
+    source: Type.TOptional<Type.TObject<{
+        glob: Type.TOptional<Type.TArray<Type.TString>>;
+        file: Type.TOptional<Type.TString>;
+        jsonl: Type.TOptional<Type.TString>;
+        diff: Type.TOptional<Type.TString>;
+        split: Type.TOptional<Type.TString>;
+    }>>;
+    examples: Type.TOptional<Type.TArray<Type.TObject<{
+        id: Type.TString;
+        /** The text (or a JSON value, sent as its JSON text) to judge. Give this or `file`. */
+        state: Type.TOptional<Type.TUnknown>;
+        /** A repo file to judge, `path` or `path:START-END`. Give this or `state`. */
+        file: Type.TOptional<Type.TString>;
+        expect: Type.TOptional<Type.TRecord<"^.*$", Type.TUnknown>>;
+    }>>>;
+    provenance: Type.TOptional<Type.TRecord<"^.*$", Type.TUnknown>>;
+    /** Anything else a team wants to carry, ignored by the engine. */
+    meta: Type.TOptional<Type.TRecord<"^.*$", Type.TUnknown>>;
+}>;
+export type SpecFile = Static<typeof SpecSchema>;
+export interface Spec extends Omit<SpecFile, "questions"> {
+    /** File stem; also the fixture namespace. */
+    name: string;
+    questions: QuestionSet;
+    /** Where it was loaded from. */
+    file: string;
+    /** Which lookup layer it came from. */
+    origin: "repo" | "user" | "bundled" | "path";
+}
+export interface SpecDirs {
+    repo: string;
+    user: string;
+    bundled?: string;
+}
+/** Parse and validate spec text. Collects every problem before failing. */
+export declare function parseSpec(text: string, file: string, origin: Spec["origin"]): Spec;
+/**
+ * Problems with a spec's examples. Checked by `spec validate` and `spec check`
+ * only, so a bad example never stops `ask` or `many` from using the spec.
+ * With `repoRoot`, each example `file` must also exist inside the repo.
+ */
+export declare function exampleProblems(spec: Spec, repoRoot?: string): string[];
+/**
+ * Why an example's `file` can't be used, or undefined. Only files inside the
+ * repo: a committed spec must not be able to read (and send) anything else.
+ */
+export declare function exampleFileProblem(ref: string, repoRoot: string): string | undefined;
+/** @throws DecisionsError `invalid-request` listing every example problem. */
+export declare function assertExamples(spec: Spec, repoRoot?: string): void;
+/**
+ * Parse a question set given on its own (`--questions`): YAML or JSON, in the
+ * same shape as a spec's `questions:`.
+ */
+export declare function parseQuestionSet(text: string, from: string): QuestionSet;
+/** The default spec directories for a repo. */
+export declare function specDirs(repoRoot: string, userConfigDir: string, bundled?: string): SpecDirs;
+/**
+ * Resolve a spec by name (repo → user → bundled) or by path.
+ *
+ * @throws DecisionsError `invalid-request` when nothing matches, listing what exists.
+ */
+export declare function loadSpec(ref: string, dirs: SpecDirs, cwd: string): Spec;
+export interface SpecListing {
+    name: string;
+    origin: Spec["origin"];
+    file: string;
+    description?: string;
+    /** Set when the file does not validate. */
+    error?: string;
+    /** A higher-priority layer defines the same name. */
+    shadowed?: boolean;
+}
+export declare function listSpecs(dirs: SpecDirs): SpecListing[];
+//# sourceMappingURL=spec.d.ts.map

package/dist/spec/spec.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"spec.d.ts","sourceRoot":"","sources":["../../src/spec/spec.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,KAAK,MAAM,EAAE,IAAI,EAAE,MAAM,SAAS,CAAA;AAI3C,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAA;AAcpD,eAAO,MAAM,WAAW,IAAI,CAAA;AAE5B,eAAO,MAAM,UAAU;IAEnB,6EAA6E;;;;;;;;;;;;;;;;;;;;;QAsBvE,uFAAuF;;QAEvF,8EAA8E;;;;;IAOpF,kEAAkE;;EAMrE,CAAA;AAED,MAAM,MAAM,QAAQ,GAAG,MAAM,CAAC,OAAO,UAAU,CAAC,CAAA;AAEhD,MAAM,WAAW,IAAK,SAAQ,IAAI,CAAC,QAAQ,EAAE,WAAW,CAAC;IACvD,6CAA6C;IAC7C,IAAI,EAAE,MAAM,CAAA;IACZ,SAAS,EAAE,WAAW,CAAA;IACtB,gCAAgC;IAChC,IAAI,EAAE,MAAM,CAAA;IACZ,uCAAuC;IACvC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,GAAG,MAAM,CAAA;CAC7C;AAED,MAAM,WAAW,QAAQ;IACvB,IAAI,EAAE,MAAM,CAAA;IACZ,IAAI,EAAE,MAAM,CAAA;IACZ,OAAO,CAAC,EAAE,MAAM,CAAA;CACjB;AAID,2EAA2E;AAC3E,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,CAAC,QAAQ,CAAC,GAAG,IAAI,CA6ClF;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,IAAI,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAuBvE;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAOpF;AAED,8EAA8E;AAC9E,wBAAgB,cAAc,CAAC,IAAI,EAAE,IAAI,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CASlE;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,WAAW,CAqBxE;AAMD,+CAA+C;AAC/C,wBAAgB,QAAQ,CAAC,QAAQ,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,QAAQ,CAM5F;AAED;;;;GAIG;AACH,wBAAgB,QAAQ,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,QAAQ,EAAE,GAAG,EAAE,MAAM,GAAG,IAAI,CAkBvE;AAED,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAA;IACZ,MAAM,EAAE,IAAI,CAAC,QAAQ,CAAC,CAAA;IACtB,IAAI,EAAE,MAAM,CAAA;IACZ,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,2CAA2C;IAC3C,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,qDAAqD;IACrD,QAAQ,CAAC,EAAE,OAAO,CAAA;CACnB;AAED,wBAAgB,SAAS,CAAC,IAAI,EAAE,QAAQ,GAAG,WAAW,EAAE,CAgCvD"}