@verevoir/review 0.2.0 → 0.3.0

package/dist/cli/review.js

@@ -0,0 +1,507 @@
+/// <reference types="node" />
+// The `aigency-review` command line: the v5 antagonistic panel, runnable from
+// any repository (including a public one) with `npx`.
+//
+// PORTED FROM verevoir/aigency-governance (src/cli/review.ts, src/cli/run.ts
+// and src/review/settings.ts), so a repository that cannot call governance's
+// private reusable workflow gets the same behaviour: settings are resolved
+// first, then the diff, then the lens set, and only then does anything reach
+// a model. Every failure before a verdict is `could_not_run` and red -- never
+// a pass. See the README's "Command line" section for what was deliberately
+// not ported.
+//
+// `main` takes everything that touches the world as an argument (`io`,
+// `deps`), so tests drive it with fakes and no process, disk, git or network.
+// The bin wrapper (bin.ts) is the only place real ones are constructed.
+//
+// BUNDLED DEFAULT LENSES: `lenses.default.json` at the package root is a copy
+// of aigency-governance's review/lenses.json at commit de238aa. It is a
+// snapshot, not a live read: refresh it deliberately when governance's set
+// changes.
+import { runReviewNode } from '../run-review.js';
+import { parseLensSet } from '../lensSet.js';
+import { buildPrompt, renderPrompt } from '../prompt.js';
+import { deriveLensSet, extractBar } from '../practice-lenses.js';
+import { buildFileContext, NO_FILE_CONTEXT_NOTE } from '../context-files.js';
+import { buildReferences } from '../references.js';
+import { renderFooter, tierLine, usageLines } from './footer.js';
+/** Governance's pinned default, sent to both routes. */
+export const DEFAULT_MODEL = 'claude-opus-5-5';
+/** Governance's default output-token budget (billed route only). */
+export const DEFAULT_MAX_TOKENS = 65536;
+/** What the prompt's "## The change" shows when no --description-file was given. */
+export const NO_DESCRIPTION_NOTE = 'No PR description was supplied; do not judge the description.';
+/** What the prompt's "## Checks on this change" shows when no --checks-file was given. */
+export const NO_CHECKS_NOTE = 'No check results were supplied; do not assume the tests pass.';
+/** Ends the checks section when --checks-file is given, so a red check is reported once. */
+export const RED_CI_NOTE = 'If a check fails, report it once, then review the rest of the change on its own merits, ' +
+    'as if that failure were fixed.';
+const USAGE = [
+    'Usage: aigency-review [--base <ref>] [--title <text>] [--lenses <path>]',
+    '',
+    '  --base <ref>     review `git diff --merge-base <ref> HEAD` (needs full history:',
+    '                   checkout with fetch-depth: 0). Without it the diff is read from stdin.',
+    '  --title <text>   the title shown at the top of the report (default: "this change")',
+    '  --lenses <path>  a lens set JSON file (else AIGENCY_REVIEW_LENSES, else the bundled set)',
+    '  --practices <dir>  derive one lens per `lens:` front-matter value from the practice',
+    '                   markdown files in <dir> (cannot be combined with --lenses)',
+    '  --print-lenses   with --practices: print the derived lenses as JSON and exit 0,',
+    '                   with no reviewer call and no diff',
+    '  --print-prompt <lens-id>  print the exact prompt that lens would be sent for the diff',
+    '                   (stdin or --base) and exit 0, with no reviewer call',
+    "  --context-root <dir>  a tree at the change's head: each file the diff touches is shown",
+    '                   in full (16 KB or smaller). Defaults to the current directory with --base;',
+    '                   with stdin and no --context-root there is no file context',
+    '  --description-file <path>  the PR description, shown under "## The change"; without it the',
+    '                   prompt says no description was supplied',
+    '  --checks-file <path>  CI check results, shown verbatim under "## Checks on this change";',
+    '                   without it the prompt says no check results were supplied',
+    '  --warm-first / --no-warm-first  run the first lens alone so the rest read the prompt cache',
+    '                   it wrote (default: on with 2 or more lenses; slower, cheaper)',
+    '  --no-dedup       skip the extra model call that merges findings describing the same',
+    '                   defect across lenses (default: on when 2 or more findings are raised)',
+    '  -h, --help       print this and exit 0',
+    '',
+    'Environment: ANTHROPIC_API_KEY, ANTHROPIC_API_KEY_FILE, AIGENCY_REVIEW_LENSES,',
+    'AIGENCY_REVIEW_MODEL, AIGENCY_REVIEW_MAX_TOKENS, GITHUB_STEP_SUMMARY.',
+].join('\n');
+function parseArgs(argv) {
+    let base;
+    let title = 'this change';
+    let lenses;
+    let help = false;
+    let practices;
+    let printLenses = false;
+    let printPrompt;
+    let contextRoot;
+    let descriptionFile;
+    let checksFile;
+    let warmFirst = true;
+    let dedup = true;
+    for (let i = 0; i < argv.length; i++) {
+        const raw = argv[i];
+        if (raw === '-h' || raw === '--help') {
+            help = true;
+            continue;
+        }
+        if (raw === '--print-lenses') {
+            printLenses = true;
+            continue;
+        }
+        if (raw === '--warm-first' || raw === '--no-warm-first') {
+            warmFirst = raw === '--warm-first';
+            continue;
+        }
+        if (raw === '--no-dedup') {
+            dedup = false;
+            continue;
+        }
+        const eq = raw.startsWith('--') ? raw.indexOf('=') : -1;
+        const name = eq === -1 ? raw : raw.slice(0, eq);
+        if (name !== '--base' &&
+            name !== '--title' &&
+            name !== '--lenses' &&
+            name !== '--practices' &&
+            name !== '--print-prompt' &&
+            name !== '--context-root' &&
+            name !== '--description-file' &&
+            name !== '--checks-file') {
+            return { error: `Unknown argument ${JSON.stringify(raw)}.` };
+        }
+        let value;
+        if (eq !== -1) {
+            value = raw.slice(eq + 1);
+        }
+        else {
+            value = argv[i + 1];
+            i++;
+        }
+        if (value === undefined || value === '') {
+            return { error: `${name} needs a value.` };
+        }
+        if (name === '--base')
+            base = value;
+        else if (name === '--title')
+            title = value;
+        else if (name === '--practices')
+            practices = value;
+        else if (name === '--print-prompt')
+            printPrompt = value;
+        else if (name === '--context-root')
+            contextRoot = value;
+        else if (name === '--description-file')
+            descriptionFile = value;
+        else if (name === '--checks-file')
+            checksFile = value;
+        else
+            lenses = value;
+    }
+    return {
+        ...(base === undefined ? {} : { base }),
+        title,
+        ...(lenses === undefined ? {} : { lenses }),
+        ...(practices === undefined ? {} : { practices }),
+        ...(contextRoot === undefined ? {} : { contextRoot }),
+        ...(descriptionFile === undefined ? {} : { descriptionFile }),
+        ...(checksFile === undefined ? {} : { checksFile }),
+        warmFirst,
+        dedup,
+        printLenses,
+        ...(printPrompt === undefined ? {} : { printPrompt }),
+        help,
+    };
+}
+function present(value) {
+    return value === undefined || value.trim() === '' ? undefined : value;
+}
+function defaultKeyFilePath(env) {
+    const xdg = present(env['XDG_CONFIG_HOME']);
+    if (xdg !== undefined)
+        return `${xdg}/verevoir/anthropic.key`;
+    const home = present(env['HOME']);
+    return home === undefined ? undefined : `${home}/.config/verevoir/anthropic.key`;
+}
+async function readKeyFile(io, path) {
+    try {
+        return { kind: 'text', text: await io.readFile(path) };
+    }
+    catch (cause) {
+        const code = cause.code;
+        if (code === 'ENOENT' || code === 'ENOTDIR')
+            return { kind: 'absent' };
+        // Names the failure, never any bytes: a key must not reach a log.
+        const message = cause instanceof Error ? cause.message : String(cause);
+        const label = typeof code === 'string' ? code : 'error';
+        return { kind: 'unreadable', reason: `${label}: ${message}` };
+    }
+}
+/**
+ * The key, in governance's order: ANTHROPIC_API_KEY (non-blank), then
+ * ANTHROPIC_API_KEY_FILE, then the conventional default key file; nothing
+ * configured selects the claude-cli route. A key file someone configured that
+ * is unreadable or blank -- or a NAMED file that is missing -- blocks rather
+ * than silently falling back to the keyless route.
+ */
+async function resolveAccount(env, io) {
+    const fromEnv = present(env['ANTHROPIC_API_KEY']);
+    if (fromEnv !== undefined) {
+        return { kind: 'ok', account: { kind: 'key', apiKey: fromEnv }, route: 'env' };
+    }
+    const named = present(env['ANTHROPIC_API_KEY_FILE']);
+    const path = named ?? defaultKeyFilePath(env);
+    if (path === undefined) {
+        return { kind: 'ok', account: { kind: 'subscription' }, route: 'claude-cli' };
+    }
+    const read = await readKeyFile(io, path);
+    if (read.kind === 'absent') {
+        if (named !== undefined) {
+            return {
+                kind: 'problem',
+                problem: `ANTHROPIC_API_KEY_FILE names ${path}, but no file exists there. Check the path, ` +
+                    'or unset ANTHROPIC_API_KEY_FILE to use the claude-cli route.',
+            };
+        }
+        return { kind: 'ok', account: { kind: 'subscription' }, route: 'claude-cli' };
+    }
+    if (read.kind === 'unreadable') {
+        return {
+            kind: 'problem',
+            problem: `the API key file at ${path} could not be read: ${read.reason}`,
+        };
+    }
+    const key = read.text.trim();
+    if (key === '') {
+        return {
+            kind: 'problem',
+            problem: `the API key file at ${path} exists but is blank; fill it in or remove it.`,
+        };
+    }
+    return { kind: 'ok', account: { kind: 'key', apiKey: key }, route: 'key-file' };
+}
+function couldNotRun(title, reason, source) {
+    return [
+        '## Review: Could not run',
+        '',
+        `**${title}**`,
+        '',
+        reason,
+        '',
+        'Nothing was reviewed. This is a red result and not a passing one.',
+        ...(source === undefined ? [] : ['', '---', '', `Lens set: \`${source}\`.`]),
+    ].join('\n');
+}
+/**
+ * Run the review. Returns the process exit code; never throws (anything
+ * unexpected is reported as could_not_run).
+ */
+export async function main(argv, env, io, deps) {
+    const parsed = parseArgs(argv);
+    if ('error' in parsed) {
+        const reason = `${parsed.error}\n\n${USAGE}`;
+        return finish(io, env, 'could_not_run', couldNotRun('this change', reason));
+    }
+    if (parsed.help) {
+        io.stdout(`${USAGE}\n`);
+        return 0;
+    }
+    const title = parsed.title;
+    const fail = (reason, source) => finish(io, env, 'could_not_run', couldNotRun(title, reason, source));
+    try {
+        // 0. Derived lenses (--practices), settled before settings or any diff.
+        if (parsed.practices !== undefined && parsed.lenses !== undefined) {
+            return await fail('--practices and --lenses cannot be used together; choose one lens source.');
+        }
+        if (parsed.printLenses && parsed.practices === undefined) {
+            return await fail('--print-lenses needs --practices <dir>.');
+        }
+        let derived;
+        let bar;
+        if (parsed.practices !== undefined) {
+            const dir = parsed.practices;
+            // The grading rules (README), read first so its failure has its own reason.
+            let readme;
+            try {
+                readme = await io.readFile(`${dir}/README.md`);
+            }
+            catch (cause) {
+                return await fail(`The practices README at ${dir}/README.md could not be read, so the review has no ` +
+                    'grading rules (reject / accept / expect): ' +
+                    `${cause instanceof Error ? cause.message : String(cause)}`);
+            }
+            try {
+                const names = (await io.readDir(dir)).filter((n) => n.endsWith('.md') && n.toLowerCase() !== 'readme.md');
+                const files = await Promise.all(names.map(async (name) => ({ name, text: await io.readFile(`${dir}/${name}`) })));
+                derived = deriveLensSet(files);
+            }
+            catch (cause) {
+                return await fail(`The practices under ${dir} could not be read: ` +
+                    `${cause instanceof Error ? cause.message : String(cause)}`);
+            }
+            if (derived.untagged.length > 0) {
+                io.stderr(`warning: ${String(derived.untagged.length)} practice(s) with no "lens:" tag are ` +
+                    `not reviewed: ${derived.untagged.join(', ')}\n`);
+            }
+            for (const [lensId, own] of Object.entries(derived.signals)) {
+                if (own.length === 0) {
+                    io.stderr(`warning: lens ${lensId} has no _Reject:_ / _Expect:_ signal lines, so every ` +
+                        'blocking finding it raises will be downgraded to a smell.\n');
+                }
+            }
+            if (derived.groups.length === 0) {
+                return await fail(`No practice under ${dir} carries a "lens:" front-matter value, so no lens could be ` +
+                    'derived. Refusing to review against nothing.');
+            }
+            const extracted = extractBar(readme);
+            if (!extracted.ok) {
+                return await fail(`The practices README at ${dir}/README.md cannot supply the grading rules: ` +
+                    `${extracted.reason}.`);
+            }
+            bar = extracted.text;
+            if (parsed.printLenses) {
+                const out = {
+                    barLength: bar.length,
+                    lenses: derived.lensSet.lenses.map((lens) => ({
+                        id: lens.id,
+                        practices: derived?.groups.find((g) => g.lensId === lens.id)?.practiceIds ?? [],
+                        focusLength: lens.focus.length,
+                    })),
+                    untagged: derived.untagged,
+                    missingSensor: derived.missingSensor,
+                };
+                io.stdout(`${JSON.stringify(out, null, 2)}\n`);
+                return 0;
+            }
+            if (derived.missingSensor.length > 0) {
+                return await fail(`Tagged practice(s) have no Sensor / Look for text, so a lens would check them ` +
+                    `against nothing: ${derived.missingSensor.join(', ')}.`);
+            }
+        }
+        // 1. Settings, before anything costs money.
+        const problems = [];
+        // --print-prompt makes no model call, so it needs no key.
+        const resolved = parsed.printPrompt
+            ? { kind: 'ok', account: { kind: 'subscription' }, route: 'claude-cli' }
+            : await resolveAccount(env, io);
+        if (resolved.kind === 'problem')
+            problems.push(resolved.problem);
+        const model = present(env['AIGENCY_REVIEW_MODEL']) ?? DEFAULT_MODEL;
+        let maxTokens = DEFAULT_MAX_TOKENS;
+        const rawMax = present(env['AIGENCY_REVIEW_MAX_TOKENS']);
+        if (rawMax !== undefined) {
+            const n = Number(rawMax);
+            if (!Number.isSafeInteger(n) || n <= 0) {
+                problems.push(`AIGENCY_REVIEW_MAX_TOKENS must be a positive whole number, got ${JSON.stringify(rawMax)}`);
+            }
+            else {
+                maxTokens = n;
+            }
+        }
+        if (resolved.kind === 'problem' || problems.length > 0) {
+            return await fail(`The configuration is present and wrong:\n\n${problems.map((p) => `- ${p}`).join('\n')}`);
+        }
+        const account = resolved.account;
+        const route = resolved.route;
+        // 2. The diff.
+        let diff;
+        if (parsed.base !== undefined) {
+            try {
+                diff = await deps.git(['diff', '--merge-base', parsed.base, 'HEAD']);
+            }
+            catch (cause) {
+                return await fail(`The diff could not be obtained from \`git diff --merge-base ${parsed.base} HEAD\`: ` +
+                    `${cause instanceof Error ? cause.message : String(cause)}\n\n` +
+                    'Check the ref exists and that the checkout has full history (fetch-depth: 0).');
+            }
+        }
+        else {
+            diff = await io.readStdin();
+        }
+        if (diff.trim() === '') {
+            return await fail('The diff was empty, so there was nothing to review.\n\n' +
+                'This is almost always a wiring problem rather than an empty change: a diff computed ' +
+                'against the wrong base, or a shallow clone with no merge base. Check how the diff was ' +
+                'produced before concluding the change is empty.');
+        }
+        // 2a. The PR description: --description-file, else a one-line note that
+        // none was supplied (so the lenses do not judge an empty description).
+        let description = NO_DESCRIPTION_NOTE;
+        if (parsed.descriptionFile !== undefined) {
+            let text;
+            try {
+                text = await io.readFile(parsed.descriptionFile);
+            }
+            catch (cause) {
+                return await fail(`The description file ${parsed.descriptionFile} could not be read: ` +
+                    `${cause instanceof Error ? cause.message : String(cause)}`);
+            }
+            if (text.trim() === '') {
+                return await fail(`The description file ${parsed.descriptionFile} is blank. Omit --description-file ` +
+                    'if there is no description.');
+            }
+            description = text.trim();
+        }
+        // 2a'. CI check results: --checks-file, else a one-line note that none were supplied.
+        let checks = NO_CHECKS_NOTE;
+        if (parsed.checksFile !== undefined) {
+            let text;
+            try {
+                text = await io.readFile(parsed.checksFile);
+            }
+            catch (cause) {
+                return await fail(`The checks file ${parsed.checksFile} could not be read: ` +
+                    `${cause instanceof Error ? cause.message : String(cause)}`);
+            }
+            if (text.trim() === '') {
+                return await fail(`The checks file ${parsed.checksFile} is blank. Omit --checks-file if there are no ` +
+                    'check results.');
+            }
+            checks = `${text.trim()}\n\n${RED_CI_NOTE}`;
+        }
+        // 2b. Whole-file context: --context-root, else the current directory in
+        // --base mode, else none (said in one line, not an error).
+        const contextRoot = parsed.contextRoot ?? (parsed.base !== undefined ? '.' : undefined);
+        let fileContext = NO_FILE_CONTEXT_NOTE;
+        let references;
+        if (contextRoot !== undefined) {
+            try {
+                const fs = {
+                    realpath: io.realpath,
+                    statFile: io.statFile,
+                    readFile: io.readFile,
+                };
+                fileContext = await buildFileContext(diff, contextRoot, fs);
+                references = await buildReferences(diff, contextRoot, {
+                    ...fs,
+                    ...(io.listDir === undefined ? {} : { listDir: io.listDir }),
+                });
+            }
+            catch (cause) {
+                return await fail(`The file context could not be built: ${cause instanceof Error ? cause.message : String(cause)}`);
+            }
+        }
+        const subject = {
+            title,
+            description,
+            diff,
+            fileContext,
+            checks,
+            ...(references === undefined ? {} : { references }),
+        };
+        // 3. The lens set: --lenses, else AIGENCY_REVIEW_LENSES, else bundled.
+        const lensPath = parsed.lenses ?? present(env['AIGENCY_REVIEW_LENSES']);
+        const source = derived !== undefined
+            ? `practices in ${parsed.practices ?? ''} (derived: one lens per lens: value)`
+            : (lensPath ?? 'bundled default lenses (aigency-governance review/lenses.json @ de238aa)');
+        let lensSet;
+        try {
+            if (derived !== undefined) {
+                lensSet = derived.lensSet;
+            }
+            else {
+                const text = lensPath === undefined ? await deps.defaultLenses() : await io.readFile(lensPath);
+                lensSet = parseLensSet(text);
+            }
+        }
+        catch (cause) {
+            return await fail(`The lens set could not be loaded: ${cause instanceof Error ? cause.message : String(cause)}`, source);
+        }
+        // 3b. --print-prompt: the exact prompt one lens would be sent; no reviewer call.
+        if (parsed.printPrompt !== undefined) {
+            const lens = lensSet.lenses.find((l) => l.id === parsed.printPrompt);
+            if (lens === undefined) {
+                return await fail(`--print-prompt names lens ${JSON.stringify(parsed.printPrompt)}, which is not in the ` +
+                    `lens set (${lensSet.lenses.map((l) => l.id).join(', ')}).`, source);
+            }
+            io.stdout(`${renderPrompt(buildPrompt(lens, subject, bar))}\n`);
+            return 0;
+        }
+        // 4. The panel.
+        const calls = [];
+        const result = await runReviewNode({
+            subject,
+            ...(bar === undefined ? {} : { practices: bar }),
+            lensSet,
+            lensSetSource: source,
+            account,
+            model,
+            maxTokens,
+            ...(deps.reviewer === undefined ? {} : { reviewer: deps.reviewer }),
+            warmFirst: parsed.warmFirst,
+            dedup: parsed.dedup,
+            ...(derived === undefined
+                ? {}
+                : { tierSignals: derived.signals, practiceNames: derived.practiceNames }),
+        }, (call) => void calls.push(call));
+        for (const line of usageLines(calls))
+            io.stderr(line);
+        const tier = tierLine(result.downgraded);
+        if (tier !== undefined)
+            io.stderr(`${tier}\n`);
+        const footer = `\n\n${renderFooter(model, route, calls, result.downgraded)}`;
+        const note = derived !== undefined && derived.untagged.length > 0
+            ? `\n\n> ${String(derived.untagged.length)} practice(s) had no "lens:" tag and were ` +
+                `not reviewed: ${derived.untagged.join(', ')}`
+            : '';
+        return await finish(io, env, result.verdict.outcome, result.report + note + footer, result.exitCode);
+    }
+    catch (cause) {
+        // Defect at the boundary, not a verdict about the change.
+        return fail(`Unexpected failure: ${cause instanceof Error ? cause.message : String(cause)}. ` +
+            'This is a defect in the runner, not a verdict about the change.');
+    }
+}
+async function finish(io, env, outcome, report, exitCode = 1) {
+    io.stdout(`${report}\n`);
+    const summary = present(env['GITHUB_STEP_SUMMARY']);
+    if (summary !== undefined) {
+        try {
+            await io.appendFile(summary, `${report}\n`);
+        }
+        catch (cause) {
+            // The verdict stands; a summary that could not be written is said, not hidden.
+            io.stderr(`warning: could not append to GITHUB_STEP_SUMMARY: ${cause instanceof Error ? cause.message : String(cause)}\n`);
+        }
+    }
+    io.stderr(`RESULT: ${outcome}\n`);
+    return exitCode;
+}

package/dist/context-assembler.d.ts

@@ -0,0 +1,9 @@
+import type { SourceAccess } from './source-access.js';
+import type { SubjectContext } from './context-types.js';
+export interface ContextBudget {
+    /** Hard cap on how many symbols this run returns full bodies for. A
+     * diff touching more than this has the remainder named in `omitted`,
+     * never silently truncated. */
+    readonly maxSymbols?: number;
+}
+export declare function assembleSubjectContext(diff: string, source: SourceAccess, budget?: ContextBudget): Promise<SubjectContext>;

package/dist/context-assembler.js

@@ -0,0 +1,118 @@
+// Assembles CONTEXT about a diff's own touched symbols -- their full
+// bodies, and (name-based, approximate -- @verevoir/context's own
+// documented limit) callers/callees drawn from the rest of the checked-
+// out tree. The reviewer's SUBJECT stays the diff; this is read-only
+// evidence ABOUT it, never a second subject -- see the two-channel split
+// in prompt.ts (`citedContext` vs `subjectContext`) and this library's
+// README.
+//
+// Deliberately NOT called by run-review.ts itself -- that function stays
+// fs-free and unit-testable with a plain object. Every caller with a
+// source root (pump, preflight, eval, the CI Action checkout -- all of
+// them, per the operator's own confirmation) calls this FIRST, renders
+// the result with `renderSubjectContext`, and threads it into
+// `Subject.subjectContext` itself. The "option, off by default" this is
+// meant to sit behind is exactly that: whether a caller calls this
+// function at all. Every existing caller today does not, so every
+// existing caller's prompt output is byte-for-byte unchanged by this PR.
+//
+// SCOPE, deliberately narrow: callers and callees only. No "nearby"
+// definitions, no duplicate-candidate detection -- the latter is PR 4's
+// relational-kinds work (`breaks` / `duplicates` / `deviates`), not this
+// one's.
+import { createContextStore } from '@verevoir/context';
+import { detectLanguage, parseSymbols, edgesForItem } from '@verevoir/context/code';
+import { parseDiffHunks, touchedFiles, rangeTouchedByDiff } from './diff-hunks.js';
+const DEFAULT_MAX_SYMBOLS = 25;
+// A private, fixed (sourceId, version) pair -- this store is created and
+// discarded within one call, never shared across runs, so there is
+// nothing for these two constants to collide with.
+const SOURCE_ID = 'subject';
+const VERSION = '';
+export async function assembleSubjectContext(diff, source, budget = {}) {
+    const maxSymbols = budget.maxSymbols ?? DEFAULT_MAX_SYMBOLS;
+    const hunks = parseDiffHunks(diff);
+    const files = touchedFiles(diff);
+    const store = createContextStore();
+    const allFiles = await source.listFiles();
+    const codeFiles = [];
+    for (const path of allFiles) {
+        if (detectLanguage(path) === null)
+            continue; // never warm non-code files
+        const content = await source.readFile(path);
+        if (content === undefined)
+            continue;
+        store.setContent({ sourceId: SOURCE_ID, version: VERSION, itemId: path }, content);
+        codeFiles.push(path);
+    }
+    // One pass over every code file in the tree builds a global
+    // callee -> callers index, so resolving callers for a touched symbol
+    // never requires a second repo-wide scan per symbol.
+    const callerIndex = new Map();
+    for (const path of codeFiles) {
+        const edges = edgesForItem(store, SOURCE_ID, VERSION, path);
+        if (!edges)
+            continue;
+        for (const call of edges.calls) {
+            if (call.from === null)
+                continue;
+            const set = callerIndex.get(call.to) ?? new Set();
+            set.add(call.from);
+            callerIndex.set(call.to, set);
+        }
+    }
+    const entries = [];
+    const omitted = [];
+    const seen = new Set();
+    for (const path of files) {
+        if (detectLanguage(path) === null)
+            continue; // e.g. a changed README -- nothing to resolve
+        const content = store.getContent({ sourceId: SOURCE_ID, version: VERSION, itemId: path });
+        if (content === undefined) {
+            omitted.push({
+                symbol: path,
+                reason: 'file not present at head ref (deleted, or outside the source root)',
+            });
+            continue;
+        }
+        const language = detectLanguage(path);
+        let symbols;
+        try {
+            symbols = parseSymbols(language, content);
+        }
+        catch {
+            omitted.push({ symbol: path, reason: 'unparseable by tree-sitter' });
+            continue;
+        }
+        const ranges = hunks.get(path) ?? [];
+        const touchedSymbols = symbols.filter((s) => rangeTouchedByDiff(hunks, path, s.startLine, s.endLine));
+        if (touchedSymbols.length === 0 && ranges.length > 0) {
+            omitted.push({
+                symbol: path,
+                reason: "diff touches this file but no declared symbol's range overlaps a hunk",
+            });
+        }
+        const edges = edgesForItem(store, SOURCE_ID, VERSION, path);
+        const lines = content.split('\n');
+        for (const sym of touchedSymbols) {
+            const key = `${path}:${sym.name}`;
+            if (seen.has(key))
+                continue;
+            if (entries.length >= maxSymbols) {
+                omitted.push({
+                    symbol: sym.name,
+                    reason: `budget exhausted (max ${maxSymbols} symbols per run)`,
+                });
+                continue;
+            }
+            seen.add(key);
+            const definition = lines.slice(sym.startLine - 1, sym.endLine).join('\n');
+            const callees = edges
+                ? [...new Set(edges.calls.filter((c) => c.from === sym.name).map((c) => c.to))].sort()
+                : [];
+            const callers = [...(callerIndex.get(sym.name) ?? new Set())].sort();
+            entries.push({ symbol: sym.name, file: path, definition, callers, callees });
+        }
+    }
+    return { entries, omitted };
+}

package/dist/context-files.d.ts

@@ -0,0 +1,33 @@
+/** Files larger than this (bytes) are skipped, with the reason named. */
+export declare const MAX_CONTEXT_FILE_BYTES: number;
+/** The one line used when there is no context root (diff read from stdin). */
+export declare const NO_FILE_CONTEXT_NOTE: string;
+export interface ContextFs {
+    /** Resolve symlinks. Rejects with an fs-style `code` (ENOENT...) if absent. */
+    readonly realpath: (path: string) => Promise<string>;
+    readonly statFile: (path: string) => Promise<{
+        readonly size: number;
+        readonly isFile: boolean;
+    }>;
+    readonly readFile: (path: string) => Promise<string>;
+}
+export interface DiffPath {
+    readonly path: string;
+    /** True when the file is deleted by the change (`+++ /dev/null`). */
+    readonly deleted: boolean;
+}
+/**
+ * The files a unified diff touches, from its `--- ` / `+++ ` header pairs
+ * (a `+++` only counts when the line before it is a `--- `). A path git had
+ * to quote with escapes is reported with `unreadable: true` via an empty
+ * path so the caller can say it was skipped.
+ */
+export declare function diffPaths(diff: string): DiffPath[];
+/** Why a diff-supplied path must not be read, or undefined if it is acceptable. */
+export declare function unsafePathReason(path: string): string | undefined;
+/**
+ * Build the body of the "Changed files in full" section for `diff`, reading
+ * from `root`. Throws only when the root itself cannot be resolved; every
+ * per-file problem becomes a "skipped" line naming the reason.
+ */
+export declare function buildFileContext(diff: string, root: string, fs: ContextFs): Promise<string>;