@stardustlc/dsh-review 0.0.0-stage → 0.3.0

package/lib/run.js

@@ -0,0 +1,277 @@
+import { mkdirSync } from 'node:fs';
+import path from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { finderTask, verifierTask, arbiterTask, riskTask } from './lenses.js';
+import { planForMode, classifyRisk } from './modes.js';
+import { parseCandidate, parseVote, voteDecision, gateFindings } from './gate.js';
+import { captureTarget, targetArgs } from './target.js';
+import { prepareScope, inScope } from './scope.js';
+function inputFor(run, ledger, config) {
+    return { runId: run.id, target: run.target, mode: run.mode, outDir: path.join(ledger.directory, 'runs', run.id), snapshotFile: path.join(ledger.directory, 'runs', run.id, 'snapshot.json'), maxFindings: config.maxFindings };
+}
+export function startRun(target, mode, config, ledger, independent) {
+    const id = randomUUID(), now = new Date().toISOString();
+    const run = ledger.transaction(state => {
+        const prior = state.heads[target.series], pending = prior?.latestRunId ? state.runs[prior.latestRunId] : undefined;
+        if (pending?.lease)
+            throw new Error('A review is still executing; cancel it and wait for its workers to stop first');
+        if (pending && ['running', 'pending', 'incomplete'].includes(pending.status) && pending.targetId === target.id && pending.stage !== 'done')
+            throw new Error('Resume or explicitly abandon the existing review run ' + pending.id + ' instead of overlapping work');
+        if (pending && pending.targetId !== target.id && ['running', 'pending', 'incomplete'].includes(pending.status)) {
+            pending.status = 'stale';
+            pending.errors.push('Superseded by a changed target');
+        }
+        const round = prior?.round ?? 0;
+        if (round >= config.roundCap)
+            throw new Error('Review round cap reached. Stop and reconsider the approach.');
+        const record = prior ?? { head: target.head, round: 0, mode, posted: {}, reviewedFiles: [], dropped: 0, suppressed: 0, unverified: 0, updatedAt: now };
+        Object.assign(record, { round, head: target.head, base: target.base, targetId: target.id, series: target.series, latestRunId: id, mode });
+        state.heads[target.series] = record;
+        const created = { id, targetId: target.id, series: target.series, head: target.head, target, mode, status: 'pending', stage: 'find', tasks: [], results: {}, candidates: [], round: round + 1, calls: 0, errors: [], createdAt: now, postable: [], rejected: [], unverified: 0, independent };
+        const input = inputFor(created, ledger, config);
+        created.tasks = [...planForMode(mode).finders.map(lens => finderTask(input, lens)), riskTask(input, false), riskTask(input, true)];
+        state.runs[id] = created;
+        return created;
+    });
+    const input = inputFor(run, ledger, config);
+    mkdirSync(input.outDir, { recursive: true });
+    ledger.event('run-start', { runId: id, targetId: target.id, mode, independent });
+    return run;
+}
+export function parseTaskResult(task, text, target, maxFindings) {
+    if (Buffer.byteLength(text) > 1024 * 1024)
+        throw new Error('Worker output exceeds 1 MiB');
+    const value = JSON.parse(text.trim().replace(/^\x60{3}(?:json)?\s*\n([\s\S]*?)\n\x60{3}$/, '$1'));
+    if (!value || value.runId !== task.runId || value.targetId !== task.targetId || value.taskId !== task.id)
+        throw new Error('Wrong run, target or task identity');
+    if (task.role === 'find') {
+        if (!Array.isArray(value.findings) || !Array.isArray(value.declined) || value.findings.length > maxFindings)
+            throw new Error('Invalid or excessive finder output');
+        const parsed = value.findings.map((finding) => parseCandidate(finding, task.id, target));
+        return { runId: task.runId, targetId: task.targetId, taskId: task.id, findings: parsed.filter(Boolean), ignoredStyleCount: parsed.filter((finding) => finding === null).length, declined: value.declined };
+    }
+    if (task.role === 'verify')
+        return { runId: task.runId, targetId: task.targetId, ...parseVote(value, task.id, task.candidateId, target) };
+    if (task.role === 'risk') {
+        if (!['low', 'medium', 'high'].includes(value.tier) || typeof value.extraHuman !== 'boolean' || !Array.isArray(value.reasons) || !value.reasons.length || value.reasons.some((r) => typeof r !== 'string' || !r.trim()))
+            throw new Error('Invalid risk classification');
+        return { runId: task.runId, targetId: task.targetId, taskId: task.id, tier: value.tier, extraHuman: value.extraHuman, reasons: value.reasons };
+    }
+    if (!Array.isArray(value.orderedIds) || value.orderedIds.some((id) => typeof id !== 'string') || typeof value.summary !== 'string' || !value.summary.trim() || typeof value.needsHuman !== 'boolean')
+        throw new Error('Invalid arbiter output');
+    return { runId: task.runId, targetId: task.targetId, taskId: task.id, orderedIds: value.orderedIds, summary: value.summary, needsHuman: value.needsHuman };
+}
+export function submitResults(ledger, runId, targetId, values, config) {
+    ledger.transaction(state => {
+        const run = state.runs[runId];
+        if (!run || run.targetId !== targetId || run.stage === 'done' || ['failed', 'cancelled', 'stale'].includes(run.status))
+            throw new Error('Unknown, terminal or mismatched review run');
+        const pending = run.tasks.filter(task => !Object.hasOwn(run.results, task.id));
+        const parsed = values.map(value => {
+            const task = pending.find(task => task.id === value?.taskId);
+            if (!task)
+                throw new Error('Result duplicated or not a task in this stage');
+            return [task.id, parseTaskResult(task, JSON.stringify(value), run.target, config.maxFindings)];
+        });
+        if (new Set(parsed.map(([id]) => id)).size !== parsed.length)
+            throw new Error('Duplicate task result');
+        for (const [id, value] of parsed)
+            run.results[id] = value;
+        run.status = 'pending';
+    });
+}
+function votesFor(run) {
+    const votes = {};
+    for (const task of run.tasks.filter(task => task.role === 'verify')) {
+        const value = run.results[task.id];
+        if (value)
+            (votes[task.candidateId] ??= []).push(value);
+    }
+    return votes;
+}
+export function advance(ledger, runId, config) {
+    ledger.transaction(state => {
+        const run = state.runs[runId];
+        if (!run || run.stage === 'done' || ['failed', 'cancelled', 'stale'].includes(run.status) || run.tasks.some(task => !Object.hasOwn(run.results, task.id)))
+            return;
+        const input = inputFor(run, ledger, config), plan = planForMode(run.mode), record = state.heads[run.series];
+        if (run.stage === 'find') {
+            const floor = classifyRisk(run.target.allPaths, run.target.rules.sensitivePaths);
+            const classifiers = ['risk-classifier', 'risk-second'].map(id => run.results[id]);
+            const levels = ['low', 'medium', 'high'];
+            const tier = levels[Math.max(levels.indexOf(floor.tier), ...classifiers.map(c => levels.indexOf(c.tier)))];
+            run.risk = { tier, reasons: [...floor.reasons, ...classifiers.flatMap(c => c.reasons)], extraHuman: classifiers.some(c => c.extraHuman) };
+            if (tier === 'high' && run.mode !== 'deep') {
+                run.mode = 'deep';
+                const missing = planForMode('deep').finders.filter(lens => !run.tasks.some(task => task.id === 'find-' + lens.id));
+                run.tasks.push(...missing.map(lens => finderTask({ ...input, mode: 'deep' }, lens)));
+                return;
+            }
+            const candidates = new Map();
+            record.dropped += Object.values(run.results).reduce((n, value) => n + (value.ignoredStyleCount ?? 0), 0);
+            for (const value of Object.values(run.results))
+                for (const finding of value.findings ?? []) {
+                    if (!inScope(finding, run.scope, run.target))
+                        continue;
+                    const existing = candidates.get(finding.id), rank = { blocker: 3, important: 2, nit: 1 };
+                    if (!existing || rank[finding.severity] > rank[existing.severity])
+                        candidates.set(finding.id, finding);
+                }
+            for (const [id, former] of Object.entries(record.posted))
+                if (!former.disposition && former.severity !== 'pre-existing' && former.anchor && !candidates.has(id))
+                    candidates.set(id, { id, file: former.file, line: former.line, kind: former.kind, severity: former.severity, message: former.message, anchor: former.anchor, evidence: former.evidence, carried: true, ...(former.classOfBug ? { classOfBug: former.classOfBug } : {}), ...(former.lens ? { lens: former.lens } : {}) });
+            run.candidates = [...candidates.values()];
+            if (run.candidates.length > config.maxFindings) {
+                run.status = 'incomplete';
+                run.errors.push('Candidate budget exceeded; split the target');
+                return;
+            }
+            run.stage = 'verify';
+            run.tasks.push(...run.candidates.flatMap(finding => Array.from({ length: plan.verifiersPerFinding }, (_, i) => verifierTask(input, finding, i))));
+            if (run.tasks.some(task => !Object.hasOwn(run.results, task.id)))
+                return;
+        }
+        const votes = votesFor(run);
+        if (run.stage === 'verify' && plan.arbiter) {
+            const confirmed = run.candidates.filter(f => ['confirm', 'pre-existing'].includes(voteDecision(votes[f.id] ?? [], plan.verifiersPerFinding)));
+            run.stage = 'arbiter';
+            run.tasks.push(arbiterTask(input, confirmed, votes));
+            return;
+        }
+        const confirmedIds = run.candidates.filter(f => ['confirm', 'pre-existing'].includes(voteDecision(votes[f.id] ?? [], plan.verifiersPerFinding))).map(f => f.id);
+        if (run.stage === 'arbiter') {
+            const result = run.results.arbiter;
+            if (result.needsHuman || new Set(result.orderedIds).size !== confirmedIds.length || result.orderedIds.length !== confirmedIds.length || confirmedIds.some(id => !result.orderedIds.includes(id))) {
+                run.status = 'incomplete';
+                run.errors.push('Arbiter requires human attention or changed the accepted finding set');
+                return;
+            }
+        }
+        const gated = gateFindings({ root: run.target.root, head: run.head, base: run.target.base, mode: run.mode, findings: run.candidates, config, rules: run.target.rules, record, ledger, target: run.target, votes, requiredVotes: plan.verifiersPerFinding });
+        run.postable = gated.postable;
+        run.rejected = gated.rejected;
+        run.unverified = gated.unverified;
+        run.accepted = Object.values(record.posted).filter(f => f.targetId === run.targetId && !f.disposition).map(f => structuredClone(f));
+        run.summary = run.accepted.length + ' verified finding(s), ' + gated.unverified + ' unverified. ' + (run.accepted.length ? 'Resolve every finding with a fix or a specific reason.' : 'No verified defect to fix in the reviewed scope.');
+        run.stage = 'done';
+        run.status = gated.unverified ? 'incomplete' : 'complete';
+        run.completedAt = new Date().toISOString();
+        if (run.status === 'complete')
+            record.round = run.round;
+        record.updatedAt = new Date().toISOString();
+    });
+}
+export async function assertCurrent(run, ledger, config, signal) {
+    let current;
+    try {
+        current = await captureTarget(run.target.root, targetArgs(run.target), config.maxDiffBytes, config.stateDir, signal);
+    }
+    catch (error) {
+        ledger.transaction(state => { const r = state.runs[run.id]; r.status = signal?.aborted ? 'cancelled' : 'incomplete'; r.errors.push(error instanceof Error ? error.message : String(error)); });
+        throw error;
+    }
+    if (current.id !== run.targetId) {
+        ledger.transaction(state => { state.runs[run.id].status = 'stale'; state.runs[run.id].errors.push('Target changed; prior findings cannot approve this version'); });
+        throw new Error('Review target changed; prior approval is invalid');
+    }
+}
+async function executeStages(ledger, runId, config, dispatcher, signal) {
+    for (;;) {
+        const run = ledger.snapshot().runs[runId];
+        if (!run)
+            throw new Error('Unknown run');
+        if (['failed', 'cancelled', 'stale'].includes(run.status))
+            return run;
+        await assertCurrent(run, ledger, config, signal);
+        if (run.stage === 'done')
+            return run;
+        if (!run.scope) {
+            await prepareScope(run, ledger, config, signal);
+            continue;
+        }
+        const pending = run.tasks.filter(task => !Object.hasOwn(run.results, task.id));
+        if (!pending.length) {
+            advance(ledger, runId, config);
+            const updated = ledger.snapshot().runs[runId];
+            if (updated.status === 'incomplete' && updated.tasks.length === run.tasks.length)
+                return updated;
+            continue;
+        }
+        if (dispatcher.kind === 'external')
+            return run;
+        if (run.calls + pending.length > config.maxCalls) {
+            ledger.transaction(state => { state.runs[runId].status = 'incomplete'; state.runs[runId].errors.push('Actual model call budget exhausted'); });
+            return ledger.snapshot().runs[runId];
+        }
+        ledger.transaction(state => { state.runs[runId].status = 'running'; });
+        let next = 0, failed = false;
+        await Promise.all(Array.from({ length: Math.min(config.maxParallel, pending.length) }, async () => {
+            for (;;) {
+                const task = pending[next++];
+                if (!task)
+                    return;
+                try {
+                    signal.throwIfAborted();
+                    ledger.transaction(state => { state.runs[runId].calls++; });
+                    const result = await dispatcher.dispatch(task);
+                    if (!result.ok)
+                        throw new Error(result.reason ?? 'Worker failed');
+                    const text = result.output ?? '';
+                    const parsed = parseTaskResult(task, text, run.target, config.maxFindings);
+                    ledger.transaction(state => { state.runs[runId].results[task.id] = parsed; });
+                }
+                catch (error) {
+                    failed = true;
+                    ledger.transaction(state => { const r = state.runs[runId]; r.errors.push(task.id + ': ' + (error instanceof Error ? error.message : String(error))); r.status = signal.aborted ? 'cancelled' : 'incomplete'; });
+                }
+            }
+        }));
+        await dispatcher.settle();
+        if (failed)
+            return ledger.snapshot().runs[runId];
+        signal.throwIfAborted();
+        ledger.transaction(state => { state.runs[runId].status = 'pending'; });
+    }
+}
+export async function executeRun(ledger, runId, config, dispatcher, signal) {
+    const lease = randomUUID();
+    ledger.transaction(state => {
+        const run = state.runs[runId];
+        if (!run)
+            throw new Error('Unknown review run');
+        if (run.lease && run.leasePid) {
+            let alive = true;
+            try {
+                process.kill(run.leasePid, 0);
+            }
+            catch (error) {
+                if (error.code === 'ESRCH')
+                    alive = false;
+            }
+            if (!alive) {
+                delete run.lease;
+                delete run.leasePid;
+                run.status = 'incomplete';
+                run.errors.push('Recovered interrupted worker owner; no approval was preserved');
+            }
+        }
+        if (run.lease)
+            throw new Error('This review run is already executing');
+        run.lease = lease;
+        run.leasePid = process.pid;
+    });
+    try {
+        return await executeStages(ledger, runId, config, dispatcher, signal);
+    }
+    finally {
+        ledger.transaction(state => { const run = state.runs[runId]; if (run?.lease === lease) {
+            delete run.lease;
+            delete run.leasePid;
+        } });
+    }
+}
+export function runView(run) {
+    return { runId: run.id, targetId: run.targetId, head: run.head, mode: run.mode, status: run.status, stage: run.stage, independent: run.independent,
+        round: run.round, calls: run.calls, errors: run.errors, risk: run.risk ?? null, postable: run.postable, rejected: run.rejected, unverified: run.unverified, incremental: run.scope?.incremental ?? false, summary: run.summary ?? 'Review has not completed; no clean conclusion is available.',
+        missingOutputs: run.tasks.filter(task => !Object.hasOwn(run.results, task.id)).map(task => task.id), tasks: run.tasks.filter(task => !Object.hasOwn(run.results, task.id)) };
+}

package/lib/scope.d.ts

@@ -0,0 +1,23 @@
+import type { ReviewTarget } from './target.js';
+import type { Ledger, StoredRun } from './ledger.js';
+import type { ReviewConfig } from './config.js';
+export interface ReviewScope {
+    incremental: boolean;
+    fromRunId?: string;
+    files: Array<{
+        file: string;
+        addedLines: number[];
+        removedLines: number[];
+    }>;
+}
+export declare function prepareScope(run: StoredRun, ledger: Ledger, config: ReviewConfig, signal: AbortSignal): Promise<void>;
+export declare function inScope(finding: {
+    introducedBy?: {
+        file: string;
+        line: number;
+        side?: string;
+    };
+    file: string;
+    line: number;
+    side?: string;
+}, scope: ReviewScope | undefined, target: ReviewTarget): boolean;

package/lib/scope.js

@@ -0,0 +1,50 @@
+import { mkdirSync, writeFileSync, readFileSync, existsSync } from 'node:fs';
+import path from 'node:path';
+import { git } from './exec.js';
+import { parseDiff } from './diff.js';
+export async function prepareScope(run, ledger, config, signal) {
+    if (run.scope)
+        return;
+    const directory = path.join(ledger.directory, 'runs', run.id), snapshot = path.join(directory, 'snapshot.json');
+    const earlier = Object.values(ledger.snapshot().runs).filter(r => r.id !== run.id && r.series === run.series && r.status === 'complete' && r.completedAt).sort((a, b) => b.completedAt.localeCompare(a.completedAt))[0];
+    const incremental = run.round > config.diffOnlyAfterRound && !!earlier;
+    const scope = { incremental, ...(incremental ? { fromRunId: earlier.id } : {}), files: [] };
+    mkdirSync(directory, { recursive: true });
+    for (let i = 0; i < run.target.files.length; i++) {
+        const file = run.target.files[i], previous = earlier?.target.files.find(f => f.path === file.path);
+        if (!incremental || !previous) {
+            scope.files.push({ file: file.path, addedLines: file.addedLines, removedLines: file.removedLines });
+            continue;
+        }
+        if (previous.after === file.after && previous.before === file.before)
+            continue;
+        const oldPath = path.join(directory, 'scope-' + i + '-old'), newPath = path.join(directory, 'scope-' + i + '-new');
+        writeFileSync(oldPath, previous.after ?? '');
+        writeFileSync(newPath, file.after ?? '');
+        const diff = await git(run.target.root, ['diff', '--no-index', '--no-ext-diff', '--no-textconv', '--unified=0', '--', oldPath, newPath], 30000, config.maxDiffBytes, signal);
+        if ((diff.code !== 0 && diff.code !== 1) || diff.truncated || diff.timedOut || signal.aborted)
+            throw new Error('Incremental comparison did not complete');
+        // Only hunk line numbers are used: temp-file paths are not project paths.
+        const parsed = parseDiff(diff.stdout);
+        if (!parsed.complete)
+            throw new Error('Incremental comparison has an unsupported diff header');
+        const addedLines = parsed.files.flatMap(f => f.hunks.flatMap(h => h.lines.filter(l => l.type === 'add').map(l => l.newNo)));
+        const removedLines = previous.before === file.before ? file.removedLines.filter(n => !previous.removedLines.includes(n)) : file.removedLines;
+        scope.files.push({ file: file.path, addedLines, removedLines });
+    }
+    const document = JSON.stringify({ ...run.target, reviewScope: scope }, null, 2);
+    if (existsSync(snapshot)) {
+        if (readFileSync(snapshot, 'utf8') !== document)
+            throw new Error('Immutable run snapshot already exists with different content');
+    }
+    else
+        writeFileSync(snapshot, document, { flag: 'wx' });
+    ledger.transaction(state => { state.runs[run.id].scope = scope; });
+}
+export function inScope(finding, scope, target) {
+    if (!scope?.incremental)
+        return true;
+    const anchor = finding.introducedBy ?? finding, file = target.files.find(f => (anchor.side === 'before' ? f.oldPath : f.path) === anchor.file);
+    const entry = scope.files.find(f => f.file === file?.path);
+    return !!entry && (anchor.side === 'before' ? entry.removedLines : entry.addedLines).includes(anchor.line);
+}

package/lib/target.d.ts

@@ -0,0 +1,40 @@
+import { type FileDiff } from './diff.js';
+import { type ReviewRules } from './rules.js';
+export interface TargetFile {
+    path: string;
+    oldPath: string | null;
+    status: string;
+    binary: boolean;
+    before: string | null;
+    after: string | null;
+    addedLines: number[];
+    removedLines: number[];
+}
+export interface ReviewTarget {
+    id: string;
+    series: string;
+    root: string;
+    head: string;
+    base: string;
+    baseRef: string;
+    kind: 'worktree' | 'staged' | 'commit';
+    includeUntracked: boolean;
+    patch: string;
+    files: TargetFile[];
+    allPaths: string[];
+    instructions: string;
+    skipped: string[];
+    rules: ReviewRules;
+    diff: FileDiff[];
+}
+export declare function captureTarget(root: string, args: {
+    base?: unknown;
+    staged?: unknown;
+    includeUntracked?: unknown;
+}, maxBytes: number, stateDir: string, signal?: AbortSignal): Promise<ReviewTarget>;
+export declare function targetArgs(target: ReviewTarget): {
+    base: string;
+    staged: boolean;
+    includeUntracked: boolean;
+};
+export declare function sourceMatches(target: ReviewTarget, file: string, line: number, anchor: string, side?: 'before' | 'after'): boolean;

package/lib/target.js

@@ -0,0 +1,134 @@
+import { createHash } from 'node:crypto';
+import { readFileSync, realpathSync, lstatSync } from 'node:fs';
+import path from 'node:path';
+import { git } from './exec.js';
+import { parseDiff } from './diff.js';
+import { loadRules, parseRules, RULE_PATHS, isSkipped } from './rules.js';
+const hash = (value) => createHash('sha256').update(value).digest('hex');
+export async function captureTarget(root, args, maxBytes, stateDir, signal) {
+    root = realpathSync(root);
+    const query = async (argv) => {
+        const r = await git(root, argv, 30000, maxBytes, signal);
+        if (!r.ok)
+            throw new Error(r.truncated ? 'Review incomplete: diff or source exceeds maxDiffBytes' : 'Git read failed: ' + r.stderr.slice(0, 300));
+        return r.stdout;
+    };
+    const head = (await query(['rev-parse', '--verify', 'HEAD'])).trim();
+    const baseRef = typeof args.base === 'string' && args.base.trim() ? args.base.trim() : 'HEAD';
+    if (baseRef.startsWith('-') || /[\s\x00-\x1f]/.test(baseRef))
+        throw new Error('Invalid base ref');
+    const kind = args.staged === true ? 'staged' : baseRef !== 'HEAD' ? 'commit' : 'worktree';
+    if (args.staged === true && baseRef !== 'HEAD')
+        throw new Error('staged and base are mutually exclusive');
+    const requestedBase = (await query(['rev-parse', '--verify', '--end-of-options', baseRef + '^{commit}'])).trim();
+    const base = kind === 'commit' ? (await query(['merge-base', requestedBase, head])).trim() : head;
+    const selector = kind === 'staged' ? ['--cached', head] : kind === 'commit' ? [base, head] : [head];
+    const common = ['diff', '--no-ext-diff', '--no-textconv', '--no-color'];
+    const names = await query([...common, '--name-status', '-z', ...selector, '--']);
+    const patch = await query([...common, '--unified=3', ...selector, '--']);
+    const parsed = parseDiff(patch);
+    if (!parsed.complete)
+        throw new Error('Review incomplete: unsupported Git diff header');
+    const fields = names.split('\0');
+    if (fields.at(-1) === '')
+        fields.pop();
+    const entries = [];
+    for (let i = 0; i < fields.length;) {
+        const code = fields[i++], first = fields[i++];
+        if (!first || !/^[AMDTRC][0-9]*$/.test(code))
+            throw new Error('Review incomplete: unsupported name-status entry');
+        const renamed = /^[RC]/.test(code), next = renamed ? fields[i++] : first;
+        if (!next)
+            throw new Error('Review incomplete: truncated file inventory');
+        entries.push({ path: next, oldPath: code[0] === 'A' ? null : first, code });
+    }
+    const includeUntracked = kind === 'worktree' && args.includeUntracked !== false;
+    if (includeUntracked) {
+        const extra = (await query(['ls-files', '--others', '--exclude-standard', '-z'])).split('\0').filter(Boolean);
+        for (const file of extra)
+            if (!entries.some(e => e.path === file))
+                entries.push({ path: file, oldPath: null, code: 'A' });
+    }
+    let rules;
+    if (kind === 'commit') {
+        const entries = (await query(['ls-tree', '-z', base, '--', ...RULE_PATHS])).split('\0').filter(Boolean);
+        const source = RULE_PATHS.find(file => entries.some(e => e.split('\t')[1] === file));
+        if (source) {
+            if (!entries.find(e => e.split('\t')[1] === source)?.startsWith('100'))
+                throw new Error('Committed review guidance must be a regular file');
+            rules = parseRules(await query(['show', '--no-ext-diff', '--no-textconv', base + ':' + source]), source);
+        }
+        else
+            rules = parseRules('', null);
+    }
+    else
+        rules = loadRules(root);
+    const skipped = [], files = [];
+    const internal = path.isAbsolute(stateDir) ? path.relative(root, stateDir).replaceAll('\\', '/') : stateDir;
+    const inState = (file) => file === internal || file.startsWith(internal + '/') || file === '.dsh-review' || file.startsWith('.dsh-review/');
+    let total = Buffer.byteLength(patch);
+    const blob = async (spec) => query(['show', '--no-ext-diff', '--no-textconv', spec]);
+    for (const entry of entries) {
+        if (inState(entry.path) || isSkipped(entry.path, rules.skip)) {
+            skipped.push(entry.path);
+            continue;
+        }
+        const diff = parsed.files.find(f => f.path === entry.path);
+        if (!diff && entry.oldPath !== null)
+            throw new Error('Review incomplete: file missing from patch: ' + entry.path);
+        const before = entry.oldPath === null ? null : await blob(base + ':' + entry.oldPath);
+        let after = null;
+        if (entry.code[0] !== 'D') {
+            if (kind === 'worktree') {
+                const file = path.resolve(root, entry.path), relative = path.relative(root, realpathSync(file));
+                if (relative.startsWith('..') || path.isAbsolute(relative) || lstatSync(file).isSymbolicLink())
+                    throw new Error('Review incomplete: symlink or out-of-root path');
+                after = readFileSync(file, 'utf8');
+            }
+            else
+                after = await blob((kind === 'staged' ? '' : head) + ':' + entry.path);
+        }
+        total += Buffer.byteLength(before ?? '') + Buffer.byteLength(after ?? '');
+        if (total > maxBytes)
+            throw new Error('Review incomplete: snapshot exceeds maxDiffBytes');
+        files.push({ path: entry.path, oldPath: entry.oldPath, status: diff?.status ?? 'added', binary: diff?.binary ?? (after?.includes('\0') ?? false), before, after,
+            addedLines: diff ? diff.hunks.flatMap(h => h.lines.filter(l => l.type === 'add').map(l => l.newNo)) : (after ?? '').split('\n').map((_, n) => n + 1),
+            removedLines: diff?.hunks.flatMap(h => h.lines.filter(l => l.type === 'del').map(l => l.oldNo)) ?? [] });
+    }
+    if ((await query(['rev-parse', 'HEAD'])).trim() !== head || await query([...common, '--name-status', '-z', ...selector, '--']) !== names || await query([...common, '--unified=3', ...selector, '--']) !== patch)
+        throw new Error('Review target changed while reading; retry');
+    const branchResult = await git(root, ['symbolic-ref', '--short', 'HEAD']);
+    const series = hash(JSON.stringify([root, branchResult.ok ? branchResult.stdout.trim() : head, kind, base, kind === 'commit' ? null : head]));
+    const instructions = ['AGENTS.md', 'CLAUDE.md'].map(file => {
+        try {
+            const absolute = path.join(root, file), relative = path.relative(root, realpathSync(absolute));
+            if (lstatSync(absolute).isSymbolicLink() || relative.startsWith('..') || path.isAbsolute(relative))
+                throw new Error('Project guidance must be a regular workspace file');
+            const content = readFileSync(absolute, 'utf8');
+            if (Buffer.byteLength(content) > 16384)
+                throw new Error('Project instruction file exceeds 16 KiB');
+            return file + '\n' + content;
+        }
+        catch (error) {
+            if (error.code === 'ENOENT')
+                return '';
+            throw error;
+        }
+    }).filter(Boolean).join('\n');
+    const allPaths = entries.filter(entry => !inState(entry.path)).map(entry => entry.path);
+    if (includeUntracked) {
+        const now = (await query(['ls-files', '--others', '--exclude-standard', '-z'])).split('\0').filter(file => file && !inState(file) && !isSkipped(file, rules.skip));
+        const then = entries.filter(e => e.oldPath === null && !parsed.files.some(f => f.path === e.path) && !inState(e.path) && !isSkipped(e.path, rules.skip)).map(e => e.path);
+        if (JSON.stringify(now.sort()) !== JSON.stringify(then.sort()))
+            throw new Error('Untracked file inventory changed while reading; retry');
+        for (const file of files.filter(f => f.oldPath === null && !parsed.files.some(d => d.path === f.path)))
+            if (readFileSync(path.resolve(root, file.path), 'utf8') !== file.after)
+                throw new Error('Untracked source changed while reading; retry');
+    }
+    return { id: hash(JSON.stringify([root, kind, head, base, patch, files, rules, instructions, allPaths])), series, root, head, base, baseRef, kind, includeUntracked, patch, files, allPaths, instructions, skipped, rules, diff: parsed.files.filter(f => files.some(item => item.path === f.path)) };
+}
+export function targetArgs(target) { return { base: target.baseRef, staged: target.kind === 'staged', includeUntracked: target.includeUntracked }; }
+export function sourceMatches(target, file, line, anchor, side = 'after') {
+    const item = target.files.find(f => (side === 'before' ? f.oldPath : f.path) === file);
+    return !!item && Number.isInteger(line) && line > 0 && item[side]?.split(/\r?\n/)[line - 1] === anchor;
+}

package/lib/tools.d.ts

@@ -0,0 +1,28 @@
+import { type CommandRunner, type ToolExecutionContext } from './check.js';
+import { type Dispatcher } from './dispatch.js';
+import type { ReviewConfig } from './config.js';
+export interface ContentBlock {
+    type: 'text';
+    text: string;
+}
+export interface ReviewToolDefinition {
+    name: string;
+    description: string;
+    parameters: {
+        type: 'object';
+        properties: Record<string, unknown>;
+        required?: string[];
+        additionalProperties?: boolean;
+    };
+    output: {
+        schema: Record<string, unknown>;
+        render(args: unknown, value: unknown): ContentBlock[];
+    };
+    execute(args: unknown, exec?: unknown): Promise<unknown>;
+    timeoutMs?: number;
+}
+export interface BuildOptions {
+    runner?: CommandRunner;
+    dispatcher?: (exec: ToolExecutionContext, root: string, signal: AbortSignal) => Dispatcher;
+}
+export declare function buildReviewTools(config: ReviewConfig, options?: BuildOptions): ReviewToolDefinition[];