@stardustlc/dsh-review 0.0.0-stage → 0.3.0

package/lib/config.d.ts

@@ -0,0 +1,33 @@
+/**
+ * dsh-review 配置：审阅轮次、证据门槛、噪音上限。
+ *
+ * @module dsh-review/config
+ */
+export type Severity = 'blocker' | 'important' | 'nit' | 'pre-existing';
+export interface ReviewConfig {
+    /** @profile 按仓库隔离，或显式指定仓库内子目录。 */
+    stateDir: string;
+    /** 每个审阅系列的完成轮次上限，超过后停止。 */
+    roundCap: number;
+    /** 超过这轮后，新问题限定到相对上轮的增量行。 */
+    diffOnlyAfterRound: number;
+    /** 单轮最多发多少条 finding。 */
+    maxFindings: number;
+    /** 单轮最多发多少条 nit（0 表示不发 nit）。 */
+    maxNits: number;
+    /** 低于该严重度的 finding 不发。 */
+    severityFloor: Exclude<Severity, 'pre-existing'>;
+    /** 旧配置兼容项；不能关闭独立验证或以文字断言替代证据。 */
+    evidenceRequired: boolean;
+    /** 证据命令超时。 */
+    commandTimeoutMs: number;
+    /** 补丁与源码快照上限；超出则保持未完成。 */
+    maxDiffBytes: number;
+    maxCalls: number;
+    runTimeoutMs: number;
+    subagentProvider: string;
+    maxParallel: number;
+}
+export declare const DEFAULT_CONFIG: ReviewConfig;
+export declare function severityRank(value: Severity): number;
+export declare function resolveConfig(raw?: Partial<ReviewConfig> | null): ReviewConfig;

package/lib/config.js

@@ -0,0 +1,69 @@
+/**
+ * dsh-review 配置：审阅轮次、证据门槛、噪音上限。
+ *
+ * @module dsh-review/config
+ */
+export const DEFAULT_CONFIG = {
+    stateDir: '@profile',
+    roundCap: 3,
+    diffOnlyAfterRound: 2,
+    maxFindings: 20,
+    maxNits: 2,
+    severityFloor: 'important',
+    evidenceRequired: true,
+    commandTimeoutMs: 120000,
+    maxDiffBytes: 4 * 1024 * 1024,
+    maxCalls: 80,
+    runTimeoutMs: 600000,
+    subagentProvider: 'spawn',
+    maxParallel: 3,
+};
+const SEVERITY_RANK = { blocker: 3, important: 2, nit: 1, 'pre-existing': 0 };
+export function severityRank(value) {
+    return SEVERITY_RANK[value] ?? 0;
+}
+function intIn(value, fallback, min, max, label) {
+    if (value === undefined || value === null)
+        return fallback;
+    if (typeof value !== 'number' || !Number.isFinite(value))
+        throw new Error(label + ' 必须是数字');
+    const n = Math.trunc(value);
+    if (n < min || n > max)
+        throw new Error(label + ' 必须在 ' + min + ' 到 ' + max + ' 之间');
+    return n;
+}
+export function resolveConfig(raw) {
+    const input = (raw ?? {});
+    const config = { ...DEFAULT_CONFIG };
+    if (input.stateDir !== undefined) {
+        if (typeof input.stateDir !== 'string' || input.stateDir.trim() === '')
+            throw new Error('stateDir 必须是非空字符串');
+        config.stateDir = input.stateDir.trim();
+    }
+    config.roundCap = intIn(input.roundCap, config.roundCap, 1, 20, 'roundCap');
+    config.diffOnlyAfterRound = intIn(input.diffOnlyAfterRound, config.diffOnlyAfterRound, 1, 20, 'diffOnlyAfterRound');
+    config.maxFindings = intIn(input.maxFindings, config.maxFindings, 1, 200, 'maxFindings');
+    config.maxNits = intIn(input.maxNits, config.maxNits, 0, 100, 'maxNits');
+    config.commandTimeoutMs = intIn(input.commandTimeoutMs, config.commandTimeoutMs, 1000, 600000, 'commandTimeoutMs');
+    config.maxDiffBytes = intIn(input.maxDiffBytes, config.maxDiffBytes, 1024, 64 * 1024 * 1024, 'maxDiffBytes');
+    config.maxCalls = intIn(input.maxCalls, config.maxCalls, 1, 1000, 'maxCalls');
+    config.maxParallel = intIn(input.maxParallel, config.maxParallel, 1, 8, 'maxParallel');
+    config.runTimeoutMs = intIn(input.runTimeoutMs, config.runTimeoutMs, 1000, 3600000, 'runTimeoutMs');
+    if (input.subagentProvider !== undefined) {
+        if (typeof input.subagentProvider !== 'string' || !/^[\w-]+$/.test(input.subagentProvider))
+            throw new Error('Invalid subagentProvider');
+        config.subagentProvider = input.subagentProvider;
+    }
+    if (input.severityFloor !== undefined) {
+        const floor = String(input.severityFloor);
+        if (!['blocker', 'important', 'nit'].includes(floor))
+            throw new Error('severityFloor 只能是 blocker | important | nit');
+        config.severityFloor = floor;
+    }
+    if (input.evidenceRequired !== undefined) {
+        if (typeof input.evidenceRequired !== 'boolean')
+            throw new Error('evidenceRequired 必须是布尔值');
+        config.evidenceRequired = input.evidenceRequired;
+    }
+    return config;
+}

package/lib/diff.d.ts

@@ -0,0 +1,38 @@
+/**
+ * 统一 diff 解析：把 git diff 拆成文件 / hunk / 行，并保留新文件行号。
+ *
+ * @module dsh-review/diff
+ */
+export type LineType = 'add' | 'del' | 'ctx';
+export interface DiffLine {
+    type: LineType;
+    oldNo: number | null;
+    newNo: number | null;
+    text: string;
+}
+export interface Hunk {
+    header: string;
+    oldStart: number;
+    newStart: number;
+    lines: DiffLine[];
+}
+export type FileStatus = 'added' | 'modified' | 'deleted' | 'renamed' | 'copied';
+export interface FileDiff {
+    path: string;
+    oldPath: string | null;
+    status: FileStatus;
+    binary: boolean;
+    hunks: Hunk[];
+    added: number;
+    removed: number;
+}
+export interface ParsedDiff {
+    files: FileDiff[];
+    added: number;
+    removed: number;
+    complete: boolean;
+}
+export declare function gitPath(value: string): string;
+export declare function parseDiff(raw: string): ParsedDiff;
+/** 取某个新行号附近的上下文（用于给 finding 定位）。 */
+export declare function contextAround(file: FileDiff, line: number, radius?: number): DiffLine[];

package/lib/diff.js

@@ -0,0 +1,136 @@
+/**
+ * 统一 diff 解析：把 git diff 拆成文件 / hunk / 行，并保留新文件行号。
+ *
+ * @module dsh-review/diff
+ */
+const HEADER = /^diff --git a\/(.+?) b\/(.+)$/;
+export function gitPath(value) {
+    if (!value.startsWith('"'))
+        return value;
+    if (!value.endsWith('"'))
+        throw new Error('Incomplete quoted Git path');
+    const bytes = [];
+    for (let i = 1; i < value.length - 1; i++) {
+        if (value[i] !== '\\') {
+            bytes.push(...Buffer.from(value[i]));
+            continue;
+        }
+        const octal = /^[0-7]{1,3}/.exec(value.slice(i + 1));
+        if (octal) {
+            bytes.push(parseInt(octal[0], 8));
+            i += octal[0].length;
+            continue;
+        }
+        const ch = value[++i];
+        const escaped = { t: '\t', n: '\n', r: '\r', b: '\b', f: '\f', v: '\v', a: '\x07', '\\': '\\', '"': '"' };
+        if (!(ch in escaped))
+            throw new Error('Invalid Git path escape');
+        bytes.push(...Buffer.from(escaped[ch]));
+    }
+    return Buffer.from(bytes).toString('utf8');
+}
+export function parseDiff(raw) {
+    const files = [];
+    let current = null;
+    let hunk = null;
+    let oldNo = 0;
+    let newNo = 0;
+    let complete = true;
+    const push = () => {
+        if (current !== null)
+            files.push(current);
+        current = null;
+        hunk = null;
+    };
+    for (const line of raw.split(/\r?\n/)) {
+        const quoted = /^diff --git ("(?:[^"\\]|\\.)*") ("(?:[^"\\]|\\.)*")$/.exec(line);
+        const header = HEADER.exec(line)
+            ?? (quoted ? [line, gitPath(quoted[1]).replace(/^a\//, ''), gitPath(quoted[2]).replace(/^b\//, '')] : null);
+        if (line.startsWith('diff --git ') && header === null)
+            complete = false;
+        if (header !== null) {
+            push();
+            current = { path: header[2], oldPath: header[1], status: 'modified', binary: false, hunks: [], added: 0, removed: 0 };
+            continue;
+        }
+        if (current === null)
+            continue;
+        if (line.startsWith('new file mode')) {
+            current.status = 'added';
+            continue;
+        }
+        if (line.startsWith('deleted file mode')) {
+            current.status = 'deleted';
+            continue;
+        }
+        if (line.startsWith('rename from')) {
+            current.status = 'renamed';
+            current.oldPath = line.slice(12).trim();
+            continue;
+        }
+        if (line.startsWith('copy from')) {
+            current.status = 'copied';
+            current.oldPath = line.slice(10).trim();
+            continue;
+        }
+        if (line.startsWith('Binary files ') || line === 'GIT binary patch') {
+            current.binary = true;
+            continue;
+        }
+        if (hunk === null && line.startsWith('--- ')) {
+            const target = line.slice(4).trim();
+            if (current.status !== 'added' && target !== '/dev/null')
+                current.oldPath = gitPath(target).replace(/^a\//, '');
+            continue;
+        }
+        if (hunk === null && line.startsWith('+++ ')) {
+            const target = line.slice(4).trim();
+            if (target !== '/dev/null')
+                current.path = gitPath(target).replace(/^b\//, '');
+            continue;
+        }
+        const hunkHeader = /^@@ -(\d+)(?:,(\d+))? \+(\d+)(?:,(\d+))? @@/.exec(line);
+        if (hunkHeader !== null) {
+            oldNo = Number(hunkHeader[1]);
+            newNo = Number(hunkHeader[3]);
+            hunk = { header: line, oldStart: oldNo, newStart: newNo, lines: [] };
+            current.hunks.push(hunk);
+            continue;
+        }
+        if (hunk === null)
+            continue;
+        if (line.startsWith('\\'))
+            continue;
+        const marker = line.slice(0, 1);
+        const text = line.slice(1);
+        if (marker === '+') {
+            hunk.lines.push({ type: 'add', oldNo: null, newNo, text });
+            current.added++;
+            newNo++;
+        }
+        else if (marker === '-') {
+            hunk.lines.push({ type: 'del', oldNo, newNo: null, text });
+            current.removed++;
+            oldNo++;
+        }
+        else if (marker === ' ') {
+            hunk.lines.push({ type: 'ctx', oldNo, newNo, text });
+            oldNo++;
+            newNo++;
+        }
+    }
+    push();
+    const added = files.reduce((n, f) => n + f.added, 0);
+    const removed = files.reduce((n, f) => n + f.removed, 0);
+    return { files, added, removed, complete };
+}
+/** 取某个新行号附近的上下文（用于给 finding 定位）。 */
+export function contextAround(file, line, radius = 3) {
+    for (const hunk of file.hunks) {
+        const index = hunk.lines.findIndex(l => l.newNo === line);
+        if (index < 0)
+            continue;
+        return hunk.lines.slice(Math.max(0, index - radius), index + radius + 1);
+    }
+    return [];
+}

package/lib/dispatch.d.ts

@@ -0,0 +1,58 @@
+import type { LensTask } from './lenses.js';
+export interface TaskResult {
+    ok: boolean;
+    reason?: string;
+    output?: string;
+    childId?: string;
+}
+export interface Dispatcher {
+    kind: 'subagents' | 'external';
+    reason?: string;
+    dispatch(task: LensTask): Promise<TaskResult>;
+    settle(): Promise<void>;
+}
+export interface Activation {
+    childId: string;
+    result: Promise<{
+        output?: Array<{
+            type: string;
+            text?: string;
+        }>;
+        stopReason?: unknown;
+    }>;
+    dispose(): Promise<void>;
+}
+export interface SubagentService {
+    startActivation(input: {
+        provider: string;
+        label: string;
+        delivery: 'caller';
+        request: {
+            prompt: Array<{
+                type: 'text';
+                text: string;
+            }>;
+            parent: unknown;
+            cwd: string;
+            maxDepth: number;
+        };
+        signal: AbortSignal;
+    }): Promise<Activation>;
+    getProvider?(name: string): {
+        inheritsParentContext?: boolean;
+        capabilities?: {
+            depthLimit?: boolean;
+        };
+    } | undefined;
+    resolveMaxDepth?(configured?: number): number | undefined;
+}
+export interface DispatcherOptions {
+    subagents?: SubagentService;
+    parent?: unknown;
+    provider?: string;
+    signal?: AbortSignal;
+    cwd?: string;
+    maxDepth?: number;
+}
+export declare function externalDispatcher(reason?: string): Dispatcher;
+export declare function createDispatcher(options: DispatcherOptions): Dispatcher;

package/lib/dispatch.js

@@ -0,0 +1,50 @@
+export function externalDispatcher(reason = 'Subagent service or live parent unavailable. Execute the returned tasks and submit their identity-bound JSON with review_report.') {
+    return { kind: 'external', reason, async dispatch() { return { ok: false, reason: 'external' }; }, async settle() { } };
+}
+export function createDispatcher(options) {
+    const svc = options.subagents;
+    if (!svc || !options.parent || !options.signal || !options.cwd)
+        return externalDispatcher();
+    const provider = options.provider ?? 'spawn', signal = options.signal;
+    return {
+        kind: 'subagents',
+        async dispatch(task) {
+            let activation;
+            try {
+                signal.throwIfAborted();
+                if (svc.getProvider?.(provider)?.inheritsParentContext !== false)
+                    throw new Error('Review workers require a provider that explicitly guarantees fresh context, not a fork or unknown backend');
+                const maxDepth = svc.resolveMaxDepth?.(options.maxDepth) ?? options.maxDepth ?? 1;
+                activation = await svc.startActivation({ provider, label: task.id, delivery: 'caller', signal,
+                    request: { prompt: [{ type: 'text', text: task.prompt }], parent: options.parent, cwd: options.cwd, maxDepth } });
+                const onAbort = () => { void activation?.dispose().catch(() => { }); };
+                signal.addEventListener('abort', onAbort, { once: true });
+                try {
+                    if (signal.aborted) {
+                        await activation.dispose();
+                        signal.throwIfAborted();
+                    }
+                    const result = await activation.result;
+                    signal.throwIfAborted();
+                    if (result.stopReason !== 'completed')
+                        return { ok: false, reason: 'Child did not complete: ' + String(result.stopReason), childId: activation.childId };
+                    const output = result.output?.filter(block => block.type === 'text').map(block => block.text ?? '').join('\n') ?? '';
+                    if (!output.trim())
+                        return { ok: false, reason: 'Child finished without JSON output', childId: activation.childId };
+                    return { ok: true, output, childId: activation.childId };
+                }
+                finally {
+                    signal.removeEventListener('abort', onAbort);
+                }
+            }
+            catch (error) {
+                return { ok: false, reason: error instanceof Error ? error.message : String(error) };
+            }
+            finally {
+                if (activation)
+                    await activation.dispose();
+            }
+        },
+        async settle() { },
+    };
+}

package/lib/eval.d.ts

@@ -0,0 +1,71 @@
+import { Ledger } from './ledger.js';
+export declare function evaluation(ledger: Ledger, root: string, args: Record<string, any>): Promise<{
+    action: any;
+    count: number;
+    entries?: undefined;
+    results?: undefined;
+    tasks?: undefined;
+    recorded?: undefined;
+    registeredCases?: undefined;
+    cohorts?: undefined;
+    metric?: undefined;
+} | {
+    action: any;
+    entries: unknown[];
+    results: unknown[];
+    count?: undefined;
+    tasks?: undefined;
+    recorded?: undefined;
+    registeredCases?: undefined;
+    cohorts?: undefined;
+    metric?: undefined;
+} | {
+    action: any;
+    tasks: {
+        caseId: string;
+        head: string;
+        base: string;
+        instructions: string;
+    }[];
+    count?: undefined;
+    entries?: undefined;
+    results?: undefined;
+    recorded?: undefined;
+    registeredCases?: undefined;
+    cohorts?: undefined;
+    metric?: undefined;
+} | {
+    action: any;
+    recorded: boolean;
+    count?: undefined;
+    entries?: undefined;
+    results?: undefined;
+    tasks?: undefined;
+    registeredCases?: undefined;
+    cohorts?: undefined;
+    metric?: undefined;
+} | {
+    action: any;
+    registeredCases: number;
+    cohorts: {
+        cohort: string;
+        tested: number;
+        unrun: string[];
+        coverage: number;
+        truePositives: number;
+        falseNegatives: number;
+        falsePositives: number;
+        strictRecall: number | null;
+        precision: number | null;
+        cleanCases: number;
+        cleanCaseFalsePositiveRate: number | null;
+        completeEvaluation: boolean;
+        matchedRunIds: string[];
+    }[];
+    metric: string;
+    count?: undefined;
+    entries?: undefined;
+    results?: undefined;
+    tasks?: undefined;
+    recorded?: undefined;
+}>;

package/lib/eval.js

@@ -0,0 +1,83 @@
+import { git } from './exec.js';
+export async function evaluation(ledger, root, args) {
+    const action = args.action;
+    const store = () => ledger.snapshot().evaluations ?? { cases: {}, results: {} };
+    if (action === 'register') {
+        if (!Array.isArray(args.entries))
+            throw new Error('register requires entries');
+        const prepared = [];
+        for (const entry of args.entries) {
+            if (!entry || typeof entry.id !== 'string' || !/^[\w.-]{1,64}$/.test(entry.id) || !Array.isArray(entry.expected))
+                throw new Error('Each case needs id and human-curated expected bugs; [] is a known-clean case');
+            const commits = [];
+            for (const ref of [entry.sha, entry.base]) {
+                if (typeof ref !== 'string' || !/^[a-f0-9]{7,40}$/.test(ref))
+                    throw new Error('Evaluation sha/base must be immutable commit ids');
+                const result = await git(root, ['rev-parse', '--verify', '--end-of-options', ref + '^{commit}']);
+                if (!result.ok)
+                    throw new Error('Evaluation commit does not exist');
+                commits.push(result.stdout.trim());
+            }
+            for (const bug of entry.expected)
+                if (['bugId', 'file', 'kind', 'classOfBug', 'anchor'].some(key => typeof bug[key] !== 'string' || !bug[key].trim()))
+                    throw new Error('Ground truth requires bugId, file, kind, classOfBug and exact anchor');
+            if (new Set(entry.expected.map((bug) => bug.bugId)).size !== entry.expected.length)
+                throw new Error('Duplicate ground-truth bug ids');
+            prepared.push({ id: entry.id, sha: commits[0], base: commits[1], expected: entry.expected.map((bug) => ({ bugId: bug.bugId, file: bug.file, kind: bug.kind, classOfBug: bug.classOfBug, anchor: bug.anchor })), note: typeof entry.note === 'string' ? entry.note : '' });
+        }
+        ledger.transaction(state => {
+            const db = state.evaluations ??= { cases: {}, results: {} };
+            for (const item of prepared) {
+                if (db.cases[item.id])
+                    throw new Error('Case id already registered; ground truth is immutable');
+                db.cases[item.id] = item;
+            }
+        });
+        return { action, count: Object.keys(store().cases).length };
+    }
+    if (action === 'list')
+        return { action, entries: Object.values(store().cases), results: Object.values(store().results) };
+    if (action === 'prompts') {
+        // Labels and incident notes deliberately stay out of the reviewer prompt.
+        return { action, tasks: Object.values(store().cases).map(value => {
+                const entry = value;
+                return { caseId: entry.id, head: entry.sha, base: entry.base, instructions: 'Use an isolated checkout of this exact head and base, without future commits or incident labels. Run the normal review pipeline, then record its native runId. Do not inspect the evaluation ground truth.' };
+            }) };
+    }
+    if (action === 'record') {
+        if (typeof args.caseId !== 'string' || typeof args.runId !== 'string' || typeof args.cohort !== 'string' || !args.cohort.trim())
+            throw new Error('record requires caseId, runId and cohort');
+        ledger.transaction(state => {
+            const db = state.evaluations ??= { cases: {}, results: {} }, entry = db.cases[args.caseId], run = state.runs[args.runId];
+            if (!entry || !run || run.status !== 'complete' || !run.independent || run.target.kind !== 'commit' || run.head !== entry.sha || run.target.base !== entry.base)
+                throw new Error('Evaluation requires a completed native commit review of the exact case head/base');
+            const findings = (run.accepted ?? []).filter(f => f.severity !== 'pre-existing');
+            const unmatched = new Set(entry.expected.map(bug => bug.bugId)), matched = [];
+            let fp = 0;
+            for (const f of findings) {
+                const bug = entry.expected.find(bug => unmatched.has(bug.bugId) && f.file === bug.file && f.kind === bug.kind && f.classOfBug === bug.classOfBug && f.anchor === bug.anchor);
+                if (bug) {
+                    matched.push(bug);
+                    unmatched.delete(bug.bugId);
+                }
+                else
+                    fp++;
+            }
+            const key = args.caseId + ':' + args.cohort;
+            if (db.results[key])
+                throw new Error('A case/cohort result already exists; use a new cohort for a new reviewer');
+            db.results[key] = { caseId: entry.id, runId: run.id, cohort: args.cohort, truePositives: matched.map(b => b.bugId), falseNegatives: entry.expected.filter(b => !matched.includes(b)).map(b => b.bugId), falsePositives: fp, predictions: findings.length, at: new Date().toISOString() };
+        });
+        return { action, recorded: true };
+    }
+    if (action !== 'score')
+        throw new Error('Unknown evaluation action');
+    const db = store(), cases = Object.keys(db.cases), results = Object.values(db.results).map(r => r).filter(r => !args.cohort || r.cohort === args.cohort);
+    const cohorts = [...new Set(results.map(r => r.cohort))];
+    return { action, registeredCases: cases.length, cohorts: cohorts.map(cohort => {
+            const rows = results.filter(r => r.cohort === cohort), tp = rows.reduce((n, r) => n + r.truePositives.length, 0), fn = rows.reduce((n, r) => n + r.falseNegatives.length, 0), fp = rows.reduce((n, r) => n + r.falsePositives, 0);
+            const tested = new Set(rows.map(r => r.caseId)), clean = rows.filter(r => db.cases[r.caseId].expected.length === 0);
+            return { cohort, tested: tested.size, unrun: cases.filter(id => !tested.has(id)), coverage: cases.length ? tested.size / cases.length : 0, truePositives: tp, falseNegatives: fn, falsePositives: fp, strictRecall: tp + fn ? tp / (tp + fn) : null, precision: tp + fp ? tp / (tp + fp) : null, cleanCases: clean.length, cleanCaseFalsePositiveRate: clean.length ? clean.filter(r => r.falsePositives > 0).length / clean.length : null,
+                completeEvaluation: tested.size === cases.length && cases.length > 0, matchedRunIds: rows.map(r => r.runId) };
+        }), metric: 'Strict human-curated location/category/anchor matching; not a semantic-quality claim. Unrun cases are reported separately.' };
+}

package/lib/exec.d.ts

@@ -0,0 +1,26 @@
+/**
+ * 受信任的结构化 Git 读取。证据命令由宿主 Bash 工具执行。
+ *
+ * @module dsh-review/exec
+ */
+export interface RunResult {
+    ok: boolean;
+    code: number | null;
+    stdout: string;
+    stderr: string;
+    timedOut: boolean;
+    durationMs: number;
+    truncated: boolean;
+}
+export interface RunOptions {
+    cwd: string;
+    timeoutMs: number;
+    maxOutputBytes?: number;
+    input?: string;
+    env?: NodeJS.ProcessEnv;
+    signal?: AbortSignal;
+}
+export declare function run(command: string, args: string[], options: RunOptions): Promise<RunResult>;
+export declare function git(cwd: string, args: string[], timeoutMs?: number, maxOutputBytes?: number, signal?: AbortSignal): Promise<RunResult>;
+/** 输出裁剪：保留头部与尾部，中间省略。 */
+export declare function excerpt(text: string, maxLines?: number, maxChars?: number): string;

package/lib/exec.js

@@ -0,0 +1,82 @@
+/**
+ * 受信任的结构化 Git 读取。证据命令由宿主 Bash 工具执行。
+ *
+ * @module dsh-review/exec
+ */
+import { spawn } from 'node:child_process';
+import { StringDecoder } from 'node:string_decoder';
+const DEFAULT_OUTPUT_LIMIT = 256 * 1024;
+export function run(command, args, options) {
+    const started = Date.now();
+    const limit = options.maxOutputBytes ?? DEFAULT_OUTPUT_LIMIT;
+    return new Promise(resolve => {
+        let settled = false;
+        const child = spawn(command, args, {
+            cwd: options.cwd,
+            env: options.env ?? process.env,
+            windowsHide: true,
+            shell: false,
+            stdio: ['pipe', 'pipe', 'pipe'],
+        });
+        let stdout = '';
+        let stderr = '';
+        let timedOut = false;
+        let truncated = false;
+        let bytes = 0;
+        const decoders = { stdout: new StringDecoder('utf8'), stderr: new StringDecoder('utf8') };
+        const abort = () => child.kill('SIGKILL');
+        options.signal?.addEventListener('abort', abort, { once: true });
+        if (options.signal?.aborted)
+            abort();
+        const timer = setTimeout(() => {
+            timedOut = true;
+            child.kill('SIGKILL');
+        }, options.timeoutMs);
+        const finish = (code) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            options.signal?.removeEventListener('abort', abort);
+            stdout += decoders.stdout.end();
+            stderr += decoders.stderr.end();
+            resolve({ ok: code === 0 && !timedOut && !options.signal?.aborted && !truncated, code, stdout, stderr, timedOut, truncated, durationMs: Date.now() - started });
+        };
+        const collect = (stream, chunk) => {
+            const available = Math.max(0, limit - bytes);
+            const accepted = chunk.subarray(0, available);
+            bytes += accepted.length;
+            const value = decoders[stream].write(accepted);
+            if (stream === 'stdout')
+                stdout += value;
+            else
+                stderr += value;
+            if (accepted.length < chunk.length)
+                truncated = true;
+        };
+        child.stdout?.on('data', (chunk) => collect('stdout', chunk));
+        child.stderr?.on('data', (chunk) => collect('stderr', chunk));
+        child.on('error', (error) => { stderr += error.message; finish(null); });
+        child.on('close', (code) => finish(code));
+        if (options.input !== undefined) {
+            child.stdin?.end(options.input);
+        }
+        else {
+            child.stdin?.end();
+        }
+    });
+}
+export async function git(cwd, args, timeoutMs = 30000, maxOutputBytes = DEFAULT_OUTPUT_LIMIT, signal) {
+    return run('git', ['-c', 'core.quotepath=false', '-c', 'color.ui=false', '-c', 'core.fsmonitor=false', ...args], { cwd, timeoutMs, maxOutputBytes, signal });
+}
+/** 输出裁剪：保留头部与尾部，中间省略。 */
+export function excerpt(text, maxLines = 40, maxChars = 4000) {
+    const trimmed = text.trimEnd();
+    if (trimmed === '')
+        return '';
+    const lines = trimmed.split(/\r?\n/);
+    let out = lines.length > maxLines ? [...lines.slice(0, maxLines), '… (' + (lines.length - maxLines) + ' 行省略)'].join('\n') : trimmed;
+    if (out.length > maxChars)
+        out = out.slice(0, maxChars) + '…';
+    return out;
+}

package/lib/fingerprint.d.ts

@@ -0,0 +1,12 @@
+/**
+ * finding 指纹：用"种类 + 文件 + 归一化代码行"生成稳定 id，
+ * 这样重排、rebase、加空行都不会让同一条 finding 变新，天然支持"不复报"。
+ *
+ * @module dsh-review/fingerprint
+ */
+export declare function normalizeLine(text: string): string;
+export declare function fingerprintOf(input: {
+    kind: string;
+    file: string;
+    anchor: string;
+}): string;