balladeer 1.0.14 → 1.0.16

package/dist/risk/describe.js

@@ -0,0 +1,45 @@
+/**
+ * One reason as a person reads it: what in the change, and why it matters to
+ * the promise. Evidence only, never a verdict: a reason says where to look, and
+ * a judge says whether the promise still holds.
+ */
+export function describeReason(reason) {
+    const { file, symbol, resource, delta, caseId, detail } = reason.evidence;
+    const distance = detail?.startsWith("distance:") ? Number(detail.slice("distance:".length)) : NaN;
+    const steps = (count) => (count === 1 ? "1 step" : `${count} steps`);
+    const quoted = (text) => `"${text.length > 90 ? `${text.slice(0, 87)}...` : text}"`;
+    switch (reason.signal) {
+        case "symbol_hit":
+            return detail === "call_site"
+                ? `${file} changes a line that calls ${symbol}`
+                : `${symbol} ${detail === "added" ? "added" : detail === "deleted" ? "deleted" : "changed"} in ${file}`;
+        case "linked_test_changed":
+            if (detail === "deleted")
+                return `its test ${file} was deleted`;
+            if (detail === "assertion_removed")
+                return `its test ${file} lost an assertion`;
+            if (detail === "renamed")
+                return `its test moved to ${file}`;
+            return `its test ${file} changed`;
+        case "sink_reach":
+            return `${file} newly reaches ${resource}${caseId ? `, the effect ${caseId} forbids` : ""}`;
+        case "resource":
+            return `${file} ${detail === "added" ? "starts using" : detail === "removed" ? "stops using" : "touches"} ${resource}`;
+        case "graph_forward":
+            return distance === 0
+                ? `${file} is one of its mapped files`
+                : `its code imports ${file} (${steps(distance)} away)`;
+        case "graph_reverse":
+            return `${file} imports its code (${steps(distance)} away)`;
+        case "intent_clash":
+            return detail === "reverses_outcome"
+                ? `the change says it undoes the promised outcome: ${quoted(delta)}`
+                : `the change's stated intent meets a non-goal: ${quoted(delta)}`;
+        case "delta_similarity":
+            return `the change reads like ${caseId ?? "a failing case"}: ${quoted(delta)}`;
+        case "prior_break":
+            return "it has broken before";
+        case "churn":
+            return "its code changes often";
+    }
+}

package/dist/risk/diff.d.ts

@@ -0,0 +1,26 @@
+/**
+ * A zero-context unified diff, as `git diff -U0` prints it, read into files,
+ * hunks and the exact lines each hunk removed and added.
+ */
+export type DiffLine = Readonly<{
+    line: number;
+    text: string;
+}>;
+export type DiffHunk = Readonly<{
+    oldStart: number;
+    oldLines: number;
+    newStart: number;
+    newLines: number;
+    removed: readonly DiffLine[];
+    added: readonly DiffLine[];
+}>;
+export type DiffFile = Readonly<{
+    path: string;
+    oldPath: string | null;
+    status: "added" | "modified" | "deleted" | "renamed";
+    binary: boolean;
+    hunks: readonly DiffHunk[];
+}>;
+/** Undoes git's C-style quoting of a path: `"a\303\251.ts"` → `aé.ts`. */
+export declare function unquotePath(raw: string): string;
+export declare function parseUnifiedDiff(text: string): DiffFile[];

package/dist/risk/diff.js

@@ -0,0 +1,174 @@
+/**
+ * A zero-context unified diff, as `git diff -U0` prints it, read into files,
+ * hunks and the exact lines each hunk removed and added.
+ */
+/** Undoes git's C-style quoting of a path: `"a\303\251.ts"` → `aé.ts`. */
+export function unquotePath(raw) {
+    if (!raw.startsWith('"') || !raw.endsWith('"'))
+        return raw;
+    const bytes = [];
+    const body = raw.slice(1, -1);
+    for (let i = 0; i < body.length; i += 1) {
+        const char = body[i];
+        if (char !== "\\") {
+            bytes.push(...Buffer.from(char, "utf8"));
+            continue;
+        }
+        const next = body[i + 1] ?? "";
+        if (/[0-7]/.test(next)) {
+            bytes.push(parseInt(body.slice(i + 1, i + 4), 8));
+            i += 3;
+            continue;
+        }
+        const escapes = {
+            n: 10,
+            t: 9,
+            r: 13,
+            '"': 34,
+            "\\": 92,
+            a: 7,
+            b: 8,
+            f: 12,
+            v: 11,
+        };
+        bytes.push(escapes[next] ?? next.charCodeAt(0));
+        i += 1;
+    }
+    return Buffer.from(bytes).toString("utf8");
+}
+function stripPrefix(path, prefix) {
+    const unquoted = unquotePath(path.trim());
+    return unquoted.startsWith(prefix) ? unquoted.slice(prefix.length) : unquoted;
+}
+/** `diff --git a/x b/x` with an unchanged path, which is the only form this line carries alone. */
+function pathFromHeader(header) {
+    const rest = header.slice("diff --git ".length);
+    if (rest.startsWith('"')) {
+        const end = rest.indexOf('" ', 1);
+        return end < 0 ? undefined : stripPrefix(rest.slice(0, end + 1), "a/");
+    }
+    for (let at = rest.indexOf(" b/"); at >= 0; at = rest.indexOf(" b/", at + 1)) {
+        const left = rest.slice(0, at);
+        const right = rest.slice(at + 1);
+        if (left.slice(2) === right.slice(2))
+            return left.slice(2);
+    }
+    return undefined;
+}
+export function parseUnifiedDiff(text) {
+    const files = [];
+    let current;
+    let hunk;
+    const finishHunk = () => {
+        if (current !== undefined && hunk !== undefined) {
+            current.hunks.push({
+                oldStart: hunk.oldStart,
+                oldLines: hunk.oldLines,
+                newStart: hunk.newStart,
+                newLines: hunk.newLines,
+                removed: hunk.removed,
+                added: hunk.added,
+            });
+        }
+        hunk = undefined;
+    };
+    const finishFile = () => {
+        finishHunk();
+        if (current === undefined)
+            return;
+        let path = current.path;
+        let oldPath = current.oldPath;
+        if (current.minus !== undefined &&
+            current.minus !== "/dev/null" &&
+            oldPath === null &&
+            current.status !== "added")
+            oldPath = current.minus;
+        if (current.plus !== undefined && current.plus !== "/dev/null")
+            path = current.plus;
+        else if (current.status === "deleted" && current.minus !== undefined)
+            path = current.minus;
+        if (current.status !== "renamed")
+            oldPath = null;
+        files.push({
+            path,
+            oldPath,
+            status: current.status,
+            binary: current.binary,
+            hunks: current.hunks,
+        });
+        current = undefined;
+    };
+    for (const line of text.split("\n")) {
+        if (line.startsWith("diff --git ")) {
+            finishFile();
+            current = {
+                path: pathFromHeader(line) ?? "",
+                oldPath: null,
+                status: "modified",
+                binary: false,
+                hunks: [],
+            };
+            continue;
+        }
+        if (current === undefined)
+            continue;
+        if (hunk !== undefined) {
+            if (line.startsWith("-")) {
+                hunk.removed.push({ line: hunk.oldAt, text: line.slice(1) });
+                hunk.oldAt += 1;
+                continue;
+            }
+            if (line.startsWith("+")) {
+                hunk.added.push({ line: hunk.newAt, text: line.slice(1) });
+                hunk.newAt += 1;
+                continue;
+            }
+            if (line.startsWith("\\"))
+                continue;
+            if (line.startsWith(" ")) {
+                hunk.oldAt += 1;
+                hunk.newAt += 1;
+                continue;
+            }
+        }
+        const header = /^@@ -(\d+)(?:,(\d+))? \+(\d+)(?:,(\d+))? @@/.exec(line);
+        if (header) {
+            finishHunk();
+            const oldStart = Number(header[1]);
+            const newStart = Number(header[3]);
+            hunk = {
+                oldStart,
+                oldLines: header[2] === undefined ? 1 : Number(header[2]),
+                newStart,
+                newLines: header[4] === undefined ? 1 : Number(header[4]),
+                removed: [],
+                added: [],
+                oldAt: oldStart,
+                newAt: newStart,
+            };
+            continue;
+        }
+        if (line.startsWith("new file mode"))
+            current.status = "added";
+        else if (line.startsWith("deleted file mode"))
+            current.status = "deleted";
+        else if (line.startsWith("rename from ")) {
+            current.status = "renamed";
+            current.oldPath = unquotePath(line.slice("rename from ".length));
+        }
+        else if (line.startsWith("rename to "))
+            current.path = unquotePath(line.slice("rename to ".length));
+        else if (line.startsWith("copy to ")) {
+            current.status = "added";
+            current.path = unquotePath(line.slice("copy to ".length));
+        }
+        else if (line.startsWith("--- "))
+            current.minus = line === "--- /dev/null" ? "/dev/null" : stripPrefix(line.slice(4), "a/");
+        else if (line.startsWith("+++ "))
+            current.plus = line === "+++ /dev/null" ? "/dev/null" : stripPrefix(line.slice(4), "b/");
+        else if (line.startsWith("Binary files ") || line.startsWith("GIT binary patch"))
+            current.binary = true;
+    }
+    finishFile();
+    return files.filter((file) => file.path.length > 0);
+}

package/dist/risk/extract.d.ts

@@ -0,0 +1,43 @@
+import { type DiffFile } from "./diff.js";
+import { type LineContext, type ResourceRef } from "./resources.js";
+import { type ChangedFile, type ChangeExtraction, type Intent } from "./contract.js";
+/** Per line of a SQL file: the table the surrounding statement names, and whether it is a CREATE body. */
+export declare function sqlLineContexts(path: string, text: string): LineContext[];
+export type FileChangeInput = Readonly<{
+    diff: DiffFile;
+    /** The file at the merge base (its old path for a rename), absent for an added file. */
+    baseText: string | undefined;
+    /** The file at head, absent for a deleted file. */
+    headText: string | undefined;
+    /** Resources the behavior maps name, looked for directly. */
+    watch?: readonly ResourceRef[];
+    /** Where the repository is, so its own TypeScript compiler can be found. */
+    root?: string;
+}>;
+/** The contract's per-file reading of one changed file. Pure: no git, no disk. */
+export declare function analyzeFileChange(input: FileChangeInput): ChangedFile;
+export type ExtractChangeOptions = Readonly<{
+    root: string;
+    /** Any ref or full sha. The diff is `base...head`: against their merge base. */
+    base: string;
+    head: string;
+    /** Resources the behavior maps name, looked for directly in the change. */
+    watch?: readonly ResourceRef[];
+}>;
+/**
+ * Runs `git diff base...head` and reads each changed file at head and at the
+ * merge base, then reads each one with `analyzeFileChange`. The extraction's
+ * `base` is the merge base, because that is what the diff and any judge compare
+ * against.
+ */
+export declare function extractChange(options: ExtractChangeOptions): Promise<ChangeExtraction>;
+/**
+ * The change's stated intent from its commit messages, with trailers removed:
+ * the model-free `intent` (`source: "commits"`). Absent when there are no
+ * commits between the two.
+ */
+export declare function readCommitIntent(options: Readonly<{
+    root: string;
+    base: string;
+    head: string;
+}>): Intent | undefined;

package/dist/risk/extract.js

@@ -0,0 +1,336 @@
+import { parseUnifiedDiff } from "./diff.js";
+import { commitMessages, git, mergeBase, readBlobs, resolveCommit } from "./git.js";
+import { isTestPath, languageOf } from "./paths.js";
+import { isSqlPath, mentionsResource, resourceKey, resourcesInLine, routeFromPath, } from "./resources.js";
+import { CHANGE_EXTRACTION_SCHEMA_VERSION, } from "./contract.js";
+import { declaredSymbols, symbolsAtLines } from "./symbols.js";
+import { identifierTokens } from "./text.js";
+/**
+ * One structural reading of a change, shared by every promise it is scored
+ * against. No model is involved: symbols come from the TypeScript compiler or a
+ * declaration regex, resources and guards from regular expressions, constants
+ * from pairing removed and added lines. The optional `deltas` and `intent` are
+ * left for a model to add; `readCommitIntent` supplies an intent from commit
+ * messages without one.
+ */
+const MAX_IDENTIFIERS = 500;
+const MAX_SYMBOLS = 200;
+const MAX_ANALYZED_BYTES = 1_500_000;
+const MAX_BODY_LINES = 300;
+const GUARD = /\b(?:if|elif|unless|throw|raise|return|assert\w*|guard|invariant|panic|abort|require|ensure|precondition|check\w*|validate\w*|verify\w*|reject|deny|forbid\w*)\b|\bexpect\s*\(|\.should\b|\?\?\s*throw/;
+const TEST_CASE = /\b(?:it|test|describe|specify|scenario)(?:\.\w+)?\s*\(|^\s*def\s+test_|^\s*func\s+Test\w*\(/;
+/** Per line of a SQL file: the table the surrounding statement names, and whether it is a CREATE body. */
+export function sqlLineContexts(path, text) {
+    const contexts = [];
+    let table;
+    let creating = false;
+    let depth = 0;
+    for (const line of text.split("\n")) {
+        const statement = /\b(create|alter)\s+table\s+(?:if\s+(?:not\s+)?exists\s+)?(?:only\s+)?[`"]?([A-Za-z_][\w.]*)[`"]?/i.exec(line);
+        if (statement) {
+            table = (statement[2] ?? "").toLowerCase();
+            creating = (statement[1] ?? "").toLowerCase() === "create";
+            depth = 0;
+            contexts.push({ path, currentTable: table, inCreateTable: false });
+        }
+        else
+            contexts.push({ path, currentTable: table, inCreateTable: creating && depth > 0 });
+        if (creating) {
+            for (const char of line) {
+                if (char === "(")
+                    depth += 1;
+                else if (char === ")")
+                    depth -= 1;
+            }
+        }
+        if (line.includes(";")) {
+            table = undefined;
+            creating = false;
+            depth = 0;
+        }
+    }
+    return contexts;
+}
+function lineContexts(path, text) {
+    if (text === undefined || !isSqlPath(path))
+        return () => ({ path });
+    const contexts = sqlLineContexts(path, text);
+    return (line) => contexts[line - 1] ?? { path };
+}
+function mentionsIn(lines, context, watch) {
+    const resources = new Map();
+    for (const { line, text } of lines) {
+        const lineContext = context(line);
+        for (const ref of resourcesInLine(text, lineContext))
+            resources.set(resourceKey(ref), ref);
+        for (const ref of watch) {
+            if (mentionsResource(text, ref, lineContext))
+                resources.set(resourceKey(ref), ref);
+        }
+    }
+    return { resources, keys: new Set(resources.keys()) };
+}
+function numbered(text) {
+    if (text === undefined)
+        return [];
+    return text.split("\n").map((line, index) => ({ line: index + 1, text: line }));
+}
+/** Whether a symbol encloses the gap between two adjacent lines, where a pure deletion or insertion sits. */
+function enclosingGap(symbols, after) {
+    return symbols.filter((symbol) => symbol.startLine <= after && symbol.endLine >= after + 1);
+}
+/** Literal values on a line, and the line with each literal replaced by a placeholder. */
+function literalShape(line) {
+    const literals = [];
+    const shape = line
+        .trim()
+        .replace(/(["'`])(?:\\.|(?!\1)[^\\])*\1|\b0x[0-9a-fA-F]+\b|(?<![\w.])-?\d+(?:\.\d+)?(?:e[+-]?\d+)?(?:_\d+)*[nLfd]?\b|\b(?:true|false|True|False|null|None|nil)\b/g, (literal) => {
+        literals.push(literal);
+        return "\u0000";
+    });
+    return { shape, literals };
+}
+/**
+ * What a changed literal belongs to: the key or name it is assigned to, else
+ * the function around it, else the call it is passed to, else the line itself.
+ */
+function constantName(line, enclosing) {
+    const quotedKey = /^\s*["']([^"']+)["']\s*:/.exec(line);
+    if (quotedKey?.[1] !== undefined)
+        return quotedKey[1];
+    const assignment = /(?:^|[\s,{(])([A-Za-z_$][\w$.]*)\s*(?::\s*[\w<>[\]|, ]+)?\s*(?:=(?!=)|:(?!:)|:=)/.exec(line.trim());
+    if (assignment?.[1] !== undefined)
+        return assignment[1];
+    if (enclosing !== undefined)
+        return enclosing;
+    const call = /([A-Za-z_$][\w$.]*)\s*\(/.exec(line.trim());
+    if (call?.[1] !== undefined)
+        return call[1];
+    return line.trim().slice(0, 80);
+}
+/** The narrowest symbol around a line. */
+function innermost(symbols, line) {
+    let best;
+    for (const symbol of symbols) {
+        if (line < symbol.startLine || line > symbol.endLine)
+            continue;
+        if (best === undefined || symbol.endLine - symbol.startLine < best.endLine - best.startLine)
+            best = symbol;
+    }
+    return best?.name;
+}
+/** The contract's per-file reading of one changed file. Pure: no git, no disk. */
+export function analyzeFileChange(input) {
+    const { diff } = input;
+    const watch = input.watch ?? [];
+    const path = diff.path;
+    const oldPath = diff.status === "renamed" ? diff.oldPath : null;
+    const basePath = oldPath ?? path;
+    const tooLarge = (text) => text !== undefined && text.length > MAX_ANALYZED_BYTES;
+    const baseText = diff.binary || tooLarge(input.baseText) ? undefined : input.baseText;
+    const headText = diff.binary || tooLarge(input.headText) ? undefined : input.headText;
+    const removed = diff.hunks.flatMap((hunk) => hunk.removed);
+    const added = diff.hunks.flatMap((hunk) => hunk.added);
+    // Symbols, from both sides.
+    const headRead = headText === undefined ? undefined : declaredSymbols(path, headText, input.root);
+    const baseRead = baseText === undefined ? undefined : declaredSymbols(basePath, baseText, input.root);
+    const headSymbols = headRead?.symbols ?? [];
+    const baseSymbols = baseRead?.symbols ?? [];
+    const symbolExtractor = (headRead ?? baseRead)?.extractor;
+    const headTouched = new Set(symbolsAtLines(headSymbols, new Set(added.map((line) => line.line))));
+    const baseTouched = new Set(symbolsAtLines(baseSymbols, new Set(removed.map((line) => line.line))));
+    for (const hunk of diff.hunks) {
+        if (hunk.newLines === 0)
+            for (const s of enclosingGap(headSymbols, hunk.newStart))
+                headTouched.add(s);
+        if (hunk.oldLines === 0)
+            for (const s of enclosingGap(baseSymbols, hunk.oldStart))
+                baseTouched.add(s);
+    }
+    const headNames = new Set(headSymbols.map((symbol) => symbol.name));
+    const baseNames = new Set(baseSymbols.map((symbol) => symbol.name));
+    const symbolsChanged = new Map();
+    for (const symbol of [...headTouched, ...baseTouched]) {
+        if (symbolsChanged.has(symbol.name))
+            continue;
+        const change = headNames.has(symbol.name) && !baseNames.has(symbol.name)
+            ? "added"
+            : baseNames.has(symbol.name) && !headNames.has(symbol.name)
+                ? "deleted"
+                : "modified";
+        symbolsChanged.set(symbol.name, { name: symbol.name, kind: symbol.kind, change });
+        if (symbolsChanged.size >= MAX_SYMBOLS)
+            break;
+    }
+    // Identifiers.
+    const identifiersAdded = identifierTokens(added.map((line) => line.text).join("\n")).slice(0, MAX_IDENTIFIERS);
+    const identifiersRemoved = identifierTokens(removed.map((line) => line.text).join("\n")).slice(0, MAX_IDENTIFIERS);
+    // Resources: changed lines, the bodies of changed functions, and each side whole.
+    const headContext = lineContexts(path, headText);
+    const baseContext = lineContexts(basePath, baseText);
+    const inAdded = mentionsIn(added, headContext, watch);
+    const inRemoved = mentionsIn(removed, baseContext, watch);
+    const bodyLines = (text, symbols) => {
+        const lines = numbered(text);
+        const picked = [];
+        for (const symbol of symbols) {
+            if (symbol.kind !== "function" && symbol.kind !== "method")
+                continue;
+            if (symbol.endLine - symbol.startLine > MAX_BODY_LINES)
+                continue;
+            picked.push(...lines.slice(symbol.startLine - 1, symbol.endLine));
+        }
+        return picked;
+    };
+    const inBodies = mentionsIn([...bodyLines(headText, headTouched), ...bodyLines(baseText, baseTouched)], headContext, watch);
+    // Whether each side reaches a resource anywhere, asked only of the resources found above.
+    const found = new Set([...inAdded.keys, ...inRemoved.keys, ...inBodies.keys]);
+    const watched = watch.filter((ref) => found.has(resourceKey(ref)));
+    const everywhereHead = mentionsIn(numbered(headText), headContext, watched).keys;
+    const everywhereBase = mentionsIn(numbered(baseText), baseContext, watched).keys;
+    const resources = new Map();
+    const classify = (key) => {
+        const onAddedSide = inAdded.keys.has(key) || (headText !== undefined && inBodies.keys.has(key));
+        if (onAddedSide && !everywhereBase.has(key))
+            return "added";
+        if (inRemoved.keys.has(key) && !everywhereHead.has(key))
+            return "removed";
+        return "touched";
+    };
+    for (const source of [inAdded, inRemoved, inBodies]) {
+        for (const [key, ref] of source.resources) {
+            if (!resources.has(key))
+                resources.set(key, { ...ref, change: classify(key) });
+        }
+    }
+    const served = routeFromPath(path) ?? (oldPath === null ? undefined : routeFromPath(oldPath));
+    if (served !== undefined && !resources.has(`route:${served}`)) {
+        resources.set(`route:${served}`, {
+            kind: "route",
+            name: served,
+            change: diff.status === "added" ? "added" : diff.status === "deleted" ? "removed" : "touched",
+        });
+    }
+    // Guards and test cases taken out: removed lines that do not come back verbatim.
+    const readded = new Set(added.map((line) => line.text.trim()));
+    const test = isTestPath(path) || (oldPath !== null && isTestPath(oldPath));
+    const guardDeletions = removed
+        .filter((line) => {
+        const text = line.text.trim();
+        if (text.length === 0 || readded.has(text))
+            return false;
+        if (/^(?:\/\/|#|\*|\/\*)/.test(text))
+            return false;
+        return GUARD.test(text) || (test && TEST_CASE.test(text));
+    })
+        .map((line) => ({ line: line.line, text: line.text.trim().slice(0, 200) }));
+    // Constants: a removed and an added line with the same shape and different literals.
+    const constantChanges = [];
+    for (const hunk of diff.hunks) {
+        if (hunk.removed.length === 0 || hunk.added.length === 0)
+            continue;
+        if (hunk.removed.length > 40 || hunk.added.length > 40)
+            continue;
+        const used = new Set();
+        for (const before of hunk.removed) {
+            const a = literalShape(before.text);
+            if (a.literals.length === 0)
+                continue;
+            for (let index = 0; index < hunk.added.length; index += 1) {
+                if (used.has(index))
+                    continue;
+                const after = hunk.added[index];
+                const b = literalShape(after.text);
+                if (a.shape !== b.shape || a.literals.length !== b.literals.length)
+                    continue;
+                const differing = a.literals
+                    .map((literal, position) => [literal, b.literals[position] ?? ""])
+                    .filter(([from, to]) => from !== to);
+                if (differing.length === 0)
+                    continue;
+                used.add(index);
+                constantChanges.push({
+                    name: constantName(after.text, innermost(headSymbols, after.line)),
+                    from: differing.map(([from]) => from).join(", "),
+                    to: differing.map(([, to]) => to).join(", "),
+                });
+                break;
+            }
+        }
+    }
+    return {
+        path,
+        status: diff.status,
+        oldPath,
+        language: languageOf(path),
+        isTest: test,
+        hunks: diff.hunks.map((hunk) => ({
+            oldStart: hunk.oldStart,
+            oldLines: hunk.oldLines,
+            newStart: hunk.newStart,
+            newLines: hunk.newLines,
+        })),
+        symbolsChanged: [...symbolsChanged.values()],
+        identifiersAdded,
+        identifiersRemoved,
+        resources: [...resources.values()].sort((a, b) => resourceKey(a).localeCompare(resourceKey(b))),
+        guardDeletions,
+        constantChanges,
+        ...(symbolExtractor === undefined ? {} : { symbolExtractor }),
+    };
+}
+/**
+ * Runs `git diff base...head` and reads each changed file at head and at the
+ * merge base, then reads each one with `analyzeFileChange`. The extraction's
+ * `base` is the merge base, because that is what the diff and any judge compare
+ * against.
+ */
+export async function extractChange(options) {
+    const { root } = options;
+    const head = resolveCommit(root, options.head);
+    const base = mergeBase(root, resolveCommit(root, options.base), head);
+    const text = git(root, [
+        "diff",
+        "--no-color",
+        "--no-ext-diff",
+        "--no-textconv",
+        "-M",
+        "-U0",
+        "--src-prefix=a/",
+        "--dst-prefix=b/",
+        `${base}...${head}`,
+    ]);
+    const diffs = parseUnifiedDiff(text);
+    const headBlobs = readBlobs(root, head, diffs.filter((diff) => diff.status !== "deleted" && !diff.binary).map((diff) => diff.path));
+    const baseBlobs = readBlobs(root, base, diffs
+        .filter((diff) => diff.status !== "added" && !diff.binary)
+        .map((diff) => diff.oldPath ?? diff.path));
+    const files = diffs.map((diff) => analyzeFileChange({
+        diff,
+        baseText: diff.status === "added" ? undefined : baseBlobs.get(diff.oldPath ?? diff.path),
+        headText: diff.status === "deleted" ? undefined : headBlobs.get(diff.path),
+        root,
+        ...(options.watch === undefined ? {} : { watch: options.watch }),
+    }));
+    return { schemaVersion: CHANGE_EXTRACTION_SCHEMA_VERSION, base, head, files };
+}
+const TRAILER = /^(?:[A-Z][\w-]*-by|Balladeer-Session|Change-Id|Signed-off-by|Co-authored-by):/i;
+/**
+ * The change's stated intent from its commit messages, with trailers removed:
+ * the model-free `intent` (`source: "commits"`). Absent when there are no
+ * commits between the two.
+ */
+export function readCommitIntent(options) {
+    const head = resolveCommit(options.root, options.head);
+    const base = mergeBase(options.root, resolveCommit(options.root, options.base), head);
+    const messages = commitMessages(options.root, base, head)
+        .map((message) => message
+        .split("\n")
+        .filter((line) => !TRAILER.test(line.trim()))
+        .join("\n")
+        .trim())
+        .filter((message) => message.length > 0);
+    if (messages.length === 0)
+        return undefined;
+    return { summary: messages.join("\n\n").slice(0, 20_000), source: "commits" };
+}

package/dist/risk/git.d.ts

@@ -0,0 +1,30 @@
+/**
+ * The few git reads the extraction needs, each one process with an argument
+ * array and never a shell. Paths are read unquoted and without the reader's own
+ * diff settings (external diff tools, text conversion, no-prefix), so the
+ * output parses the same on every machine.
+ */
+export declare class GitReadError extends Error {
+    readonly args: readonly string[];
+    constructor(args: readonly string[], message: string);
+}
+export declare function git(root: string, args: readonly string[]): string;
+/** A git answer, or undefined when git refuses. */
+export declare function tryGit(root: string, args: readonly string[]): string | undefined;
+/** The full commit sha a ref names. Throws a GitReadError when it names no commit. */
+export declare function resolveCommit(root: string, ref: string): string;
+/** The merge base `git diff base...head` compares against. */
+export declare function mergeBase(root: string, base: string, head: string): string;
+export type TreeEntry = Readonly<{
+    path: string;
+    size: number;
+}>;
+/** Every blob in a commit's tree, with its size. */
+export declare function listTree(root: string, rev: string): TreeEntry[];
+/**
+ * The contents of many files at one commit, in one `git cat-file --batch`.
+ * A path missing at that commit maps to undefined.
+ */
+export declare function readBlobs(root: string, rev: string, paths: readonly string[]): Map<string, string | undefined>;
+/** The commit messages from base (exclusive) to head, oldest first. */
+export declare function commitMessages(root: string, base: string, head: string): string[];