@stardustlc/dsh-review 0.0.0-stage → 0.3.0

package/lib/fingerprint.js

@@ -0,0 +1,14 @@
+/**
+ * finding 指纹：用"种类 + 文件 + 归一化代码行"生成稳定 id，
+ * 这样重排、rebase、加空行都不会让同一条 finding 变新，天然支持"不复报"。
+ *
+ * @module dsh-review/fingerprint
+ */
+import { createHash } from 'node:crypto';
+export function normalizeLine(text) {
+    return text.replace(/\s+/g, ' ').trim();
+}
+export function fingerprintOf(input) {
+    const payload = [input.kind.trim().toLowerCase(), input.file.replace(/\\/g, '/').trim(), normalizeLine(input.anchor)].join('\u0000');
+    return createHash('sha256').update(payload).digest('hex').slice(0, 16);
+}

package/lib/gate.d.ts

@@ -0,0 +1,81 @@
+import { type ReviewConfig } from './config.js';
+import type { HeadRecord, Ledger } from './ledger.js';
+import { type ReviewTarget } from './target.js';
+export declare const DROP_KINDS: string[];
+export interface Witness {
+    file: string;
+    line: number;
+    anchor: string;
+    side?: 'before' | 'after';
+}
+export interface CandidateFinding {
+    id?: string;
+    file: string;
+    line: number;
+    kind: string;
+    severity: 'blocker' | 'important' | 'nit';
+    message: string;
+    anchor: string;
+    evidence: string;
+    lens?: string;
+    classOfBug?: string;
+    side?: 'before' | 'after';
+    introducedBy?: Witness;
+    carried?: boolean;
+}
+export interface Vote {
+    candidateId: string;
+    decision: 'confirm' | 'reject' | 'pre-existing' | 'unverifiable';
+    reason: string;
+    witnesses: Witness[];
+    taskId: string;
+}
+export interface GatedFinding {
+    fingerprint: string;
+    file: string;
+    line: number;
+    kind: string;
+    lens: string;
+    severity: 'blocker' | 'important' | 'nit' | 'pre-existing';
+    message: string;
+    evidence: string;
+    preexisting: boolean;
+    anchor: string;
+    targetId: string;
+    verification: Vote[];
+    classOfBug?: string;
+}
+export interface GateResult {
+    postable: GatedFinding[];
+    suppressed: number;
+    suppressedFingerprints: string[];
+    dropped: number;
+    droppedDetail: Array<{
+        file: string;
+        reason: string;
+    }>;
+    unverified: number;
+    declined: unknown[];
+    rejected: Array<{
+        id: string;
+        reason: string;
+    }>;
+}
+export declare function candidateId(f: CandidateFinding, target: ReviewTarget): string;
+export declare function parseCandidate(raw: unknown, lens: string, target: ReviewTarget): CandidateFinding | null;
+export declare function parseVote(raw: unknown, taskId: string, expected: string, target: ReviewTarget): Vote;
+export declare function voteDecision(votes: Vote[], required: number): Vote['decision'];
+export declare function gateFindings(options: {
+    root: string;
+    head: string;
+    base: string;
+    mode: string;
+    findings: CandidateFinding[];
+    config: ReviewConfig;
+    rules: ReviewTarget['rules'];
+    record: HeadRecord;
+    ledger: Ledger;
+    target: ReviewTarget;
+    votes: Record<string, Vote[]>;
+    requiredVotes: number;
+}): GateResult;

package/lib/gate.js

@@ -0,0 +1,135 @@
+import { severityRank } from './config.js';
+import { fingerprintOf } from './fingerprint.js';
+import { sourceMatches } from './target.js';
+export const DROP_KINDS = ['style', 'formatting', 'format', 'diagnostics', 'diagnostic', 'cleanup', 'nitpick', 'naming', 'whitespace'];
+export function candidateId(f, target) {
+    const file = target.files.find(item => (f.side === 'before' ? item.oldPath : item.path) === f.file);
+    const lines = ((f.side === 'before' ? file?.before : file?.after) ?? '').split(/\r?\n/);
+    const occurrence = lines.slice(0, f.line).filter(line => line === f.anchor).length;
+    return fingerprintOf({ kind: f.kind + ':' + (f.classOfBug ?? '') + ':' + occurrence, file: f.file, anchor: f.anchor });
+}
+export function parseCandidate(raw, lens, target) {
+    const item = raw;
+    if (!item || typeof item !== 'object' || typeof item.kind !== 'string')
+        throw new Error('Invalid finding shape');
+    if (DROP_KINDS.includes(item.kind.toLowerCase()))
+        return null;
+    if (!['correctness', 'state', 'breaking', 'security'].includes(item.kind))
+        throw new Error('Unknown finding kind');
+    for (const key of ['file', 'anchor', 'message'])
+        if (typeof item[key] !== 'string' || !item[key].trim())
+            throw new Error('Finding requires ' + key);
+    if (!['blocker', 'important', 'nit'].includes(item.severity))
+        throw new Error('Invalid finding severity');
+    if (item.side !== undefined && !['before', 'after'].includes(item.side))
+        throw new Error('Invalid finding side');
+    const side = item.side === 'before' ? 'before' : 'after';
+    if (!sourceMatches(target, item.file, item.line, item.anchor, side))
+        throw new Error('Finding does not quote exact snapshot source');
+    const introducedBy = item.introducedBy ?? { file: item.file, line: item.line, anchor: item.anchor, side };
+    if (introducedBy.side !== undefined && !['before', 'after'].includes(introducedBy.side))
+        throw new Error('Invalid introducing side');
+    if (!sourceMatches(target, introducedBy.file, introducedBy.line, introducedBy.anchor, introducedBy.side ?? 'after'))
+        throw new Error('Invalid introducing evidence');
+    const changed = target.files.find(file => (introducedBy.side === 'before' ? file.oldPath : file.path) === introducedBy.file);
+    if (!(introducedBy.side === 'before' ? changed?.removedLines : changed?.addedLines)?.includes(introducedBy.line))
+        throw new Error('Finding is not linked to a changed introducing line');
+    const finding = { file: item.file, line: item.line, kind: item.kind, severity: item.severity, message: item.message, anchor: item.anchor, evidence: typeof item.evidence === 'string' ? item.evidence : '', lens, side, introducedBy,
+        ...(typeof item.classOfBug === 'string' && item.classOfBug.trim() ? { classOfBug: item.classOfBug.trim() } : {}) };
+    finding.id = candidateId(finding, target);
+    return finding;
+}
+export function parseVote(raw, taskId, expected, target) {
+    const item = raw;
+    if (!item || item.candidateId !== expected || !['confirm', 'reject', 'pre-existing', 'unverifiable'].includes(item.decision) || typeof item.reason !== 'string' || item.reason.trim().length < 12 || !Array.isArray(item.witnesses))
+        throw new Error('Invalid independent verification');
+    for (const witness of item.witnesses)
+        if (!witness || (witness.side !== undefined && !['before', 'after'].includes(witness.side)) || !sourceMatches(target, witness.file, witness.line, witness.anchor, witness.side ?? 'after'))
+            throw new Error('Verifier cited source outside the immutable snapshot');
+    if (item.decision !== 'unverifiable' && item.witnesses.length === 0)
+        throw new Error('Verifier supplied no checkable source witness');
+    if (item.decision === 'pre-existing' && !item.witnesses.some(witness => witness.side === 'before'))
+        throw new Error('Pre-existing verdict requires base evidence');
+    return { candidateId: expected, decision: item.decision, reason: item.reason.trim(), witnesses: item.witnesses, taskId };
+}
+export function voteDecision(votes, required) {
+    if (votes.length !== required)
+        return 'unverifiable';
+    const majority = Math.floor(required / 2) + 1;
+    for (const decision of ['confirm', 'reject', 'pre-existing'])
+        if (votes.filter(vote => vote.decision === decision).length >= majority)
+            return decision;
+    return 'unverifiable';
+}
+export function gateFindings(options) {
+    const { record, target, config, rules } = options;
+    const result = { postable: [], suppressed: 0, suppressedFingerprints: [], dropped: 0, droppedDetail: [], unverified: 0, declined: [], rejected: [] };
+    let nits = 0;
+    const unique = new Map();
+    for (const finding of options.findings) {
+        if (DROP_KINDS.includes(finding.kind.toLowerCase())) {
+            result.dropped++;
+            continue;
+        }
+        const id = finding.id ?? candidateId(finding, target), prior = unique.get(id);
+        if (!prior || severityRank(finding.severity) > severityRank(prior.severity))
+            unique.set(id, { ...finding, id });
+    }
+    for (const finding of [...unique.values()].sort((a, b) => severityRank(b.severity) - severityRank(a.severity))) {
+        const id = finding.id, votes = options.votes[id] ?? [], decision = voteDecision(votes, options.requiredVotes);
+        if (decision === 'unverifiable') {
+            result.unverified++;
+            continue;
+        }
+        if (decision === 'reject') {
+            result.rejected.push({ id, reason: votes.map(v => v.reason).join('\n') });
+            const prior = record.posted[id];
+            if (prior && !prior.disposition) {
+                prior.disposition = prior.targetId === target.id ? 'wrong' : 'fixed';
+                prior.note = 'Independent re-verification rejects the former finding on target ' + target.id;
+                prior.verification = votes;
+                prior.targetId = target.id;
+            }
+            continue;
+        }
+        if (decision !== 'pre-existing' && severityRank(finding.severity) < severityRank(rules.severityFloor ?? config.severityFloor)) {
+            result.dropped++;
+            continue;
+        }
+        if (finding.severity === 'nit' && nits++ >= (rules.maxNits ?? config.maxNits)) {
+            result.dropped++;
+            continue;
+        }
+        if (result.postable.length >= config.maxFindings) {
+            result.unverified++;
+            continue;
+        }
+        const entry = { fingerprint: id, file: finding.file, line: finding.line, kind: finding.kind, lens: finding.lens ?? 'unknown', severity: decision === 'pre-existing' ? 'pre-existing' : finding.severity,
+            message: finding.message, evidence: votes.map(v => v.reason).join('\n'), preexisting: decision === 'pre-existing', anchor: finding.anchor, targetId: target.id, verification: votes,
+            ...(finding.classOfBug ? { classOfBug: finding.classOfBug } : {}) };
+        const prior = record.posted[id];
+        if (prior && prior.targetId === target.id) {
+            prior.repeats++;
+            result.suppressed++;
+            result.suppressedFingerprints.push(id);
+            prior.verification = votes;
+            prior.evidence = entry.evidence;
+            if (severityRank(entry.severity) > severityRank(prior.severity)) {
+                prior.severity = entry.severity;
+                prior.message = entry.message;
+            }
+            continue;
+        }
+        if (prior && !prior.disposition) {
+            result.suppressed++;
+            result.suppressedFingerprints.push(id);
+        }
+        else
+            result.postable.push(entry);
+        options.ledger.remember(record, { ...entry, at: new Date().toISOString(), repeats: prior?.repeats ?? 0 });
+    }
+    record.unverified = result.unverified;
+    record.dropped += result.dropped;
+    record.reviewedFiles = target.files.map(file => file.path);
+    return result;
+}

package/lib/github.d.ts

@@ -0,0 +1,2 @@
+import type { PullRequestEvidence } from './policy.js';
+export declare function githubEvidence(repository: string, number: number, token: string, expectedHead: string, expectedBase: string, fetcher?: typeof fetch): Promise<PullRequestEvidence>;

package/lib/github.js

@@ -0,0 +1,53 @@
+export async function githubEvidence(repository, number, token, expectedHead, expectedBase, fetcher = fetch) {
+    if (!/^[\w.-]+\/[\w.-]+$/.test(repository) || !Number.isSafeInteger(number) || number < 1 || [expectedHead, expectedBase].some(sha => !/^[a-f0-9]{40,64}$/.test(sha)))
+        throw new Error('Invalid GitHub repository, pull request or commit');
+    const request = async (route, body) => {
+        const response = await fetcher('https://api.github.com' + route, { method: body ? 'POST' : 'GET', redirect: 'error', signal: AbortSignal.timeout(15000),
+            headers: { accept: 'application/vnd.github+json', 'content-type': 'application/json', authorization: 'Bearer ' + token, 'X-GitHub-Api-Version': '2026-03-10', 'user-agent': 'dsh-review-gate' }, ...(body ? { body: JSON.stringify(body) } : {}) });
+        if (!response.ok)
+            throw new Error('GitHub evidence unavailable (HTTP ' + response.status + '); gate remains blocked');
+        return response.json();
+    };
+    const prefix = '/repos/' + repository, pr = await request(prefix + '/pulls/' + number);
+    if (pr.head?.sha !== expectedHead || pr.base?.sha !== expectedBase || pr.base?.repo?.full_name?.toLowerCase() !== repository.toLowerCase())
+        throw new Error('GitHub PR head/base changed or repository mismatch');
+    const paged = async (route, field) => {
+        const values = [];
+        for (let page = 1; page <= 30; page++) {
+            const data = await request(route + (route.includes('?') ? '&' : '?') + 'per_page=100&page=' + page), rows = field ? data[field] : data;
+            if (!Array.isArray(rows))
+                throw new Error('Malformed GitHub evidence');
+            values.push(...rows);
+            if (rows.length < 100)
+                return values;
+        }
+        throw new Error('GitHub evidence pagination exceeds coverage limit');
+    };
+    const [reviews, checks, files] = await Promise.all([
+        paged(prefix + '/pulls/' + number + '/reviews'),
+        paged(prefix + '/commits/' + expectedHead + '/check-runs?filter=all', 'check_runs'),
+        paged(prefix + '/pulls/' + number + '/files'),
+    ]);
+    if (files.length !== pr.changed_files || files.some(f => typeof f.filename !== 'string'))
+        throw new Error('Incomplete GitHub changed-file inventory');
+    const [owner, repo] = repository.split('/');
+    let cursor = null, unresolvedThreads = 0;
+    for (let page = 0;; page++) {
+        if (page >= 30)
+            throw new Error('Review-thread coverage limit exceeded');
+        const result = await request('/graphql', { query: 'query($owner:String!,$repo:String!,$number:Int!,$cursor:String){repository(owner:$owner,name:$repo){pullRequest(number:$number){headRefOid reviewThreads(first:100,after:$cursor){nodes{isResolved} pageInfo{hasNextPage endCursor}}}}}', variables: { owner, repo, number, cursor } });
+        const pull = result.data?.repository?.pullRequest, threads = pull?.reviewThreads;
+        if (result.errors || pull?.headRefOid !== expectedHead || !Array.isArray(threads?.nodes) || !threads.pageInfo || threads.nodes.some((t) => typeof t?.isResolved !== 'boolean'))
+            throw new Error('Review-thread evidence unavailable or changed');
+        unresolvedThreads += threads.nodes.filter((t) => !t.isResolved).length;
+        if (threads.pageInfo.hasNextPage === false)
+            break;
+        if (threads.pageInfo.hasNextPage !== true || typeof threads.pageInfo.endCursor !== 'string' || threads.pageInfo.endCursor === cursor)
+            throw new Error('Invalid thread pagination');
+        cursor = threads.pageInfo.endCursor;
+    }
+    const current = await request(prefix + '/pulls/' + number);
+    if (current.head?.sha !== expectedHead || current.base?.sha !== expectedBase)
+        throw new Error('PR changed while reading approval evidence');
+    return { head: expectedHead, author: pr.user, paths: files.flatMap(f => f.previous_filename ? [f.filename, f.previous_filename] : [f.filename]), draft: pr.draft, reviews, checks, unresolvedThreads };
+}

package/lib/index.d.ts

@@ -0,0 +1,36 @@
+import { type ReviewConfig } from './config.js';
+import { type ReviewToolDefinition } from './tools.js';
+import { type SubagentService } from './dispatch.js';
+export declare const name = "review";
+export declare const inject: string[];
+interface HostResult {
+    isError?: boolean;
+    value?: any;
+    error?: {
+        message?: string;
+    };
+}
+export interface ReviewPluginContext {
+    effect?(effect: () => () => void): unknown;
+    tools: {
+        register(definition: ReviewToolDefinition): () => void;
+        execute(call: Record<string, unknown>): Promise<HostResult>;
+        get?(name: string, agent: unknown): unknown;
+    };
+    subagents: SubagentService;
+    permissionPresets: {
+        current(session: unknown): string;
+        resolve(name: string): {
+            sandbox: string;
+        };
+    };
+    jobs: {
+        kill(id: string, caller?: string, reason?: string): unknown;
+        wait(id: string, timeoutMs: number, caller?: string): Promise<{
+            status: string;
+        }>;
+    };
+}
+export declare function apply(ctx: ReviewPluginContext, config?: Partial<ReviewConfig> | null): void;
+export { resolveConfig, DEFAULT_CONFIG } from './config.js';
+export type { ReviewConfig } from './config.js';

package/lib/index.js

@@ -0,0 +1,56 @@
+import { resolveConfig } from './config.js';
+import { buildReviewTools } from './tools.js';
+import { createDispatcher } from './dispatch.js';
+import { randomUUID } from 'node:crypto';
+import { existsSync } from 'node:fs';
+import path from 'node:path';
+export const name = 'review';
+export const inject = ['tools', 'subagents', 'permissionPresets', 'jobs'];
+export function apply(ctx, config) {
+    const resolved = resolveConfig(config);
+    const runner = async (input) => {
+        const agent = input.exec.agent;
+        if (!agent)
+            throw new Error('Evidence execution requires the live calling agent');
+        const preset = ctx.permissionPresets.current(agent.session);
+        if (ctx.permissionPresets.resolve(preset).sandbox === 'read-only')
+            throw new Error('Evidence command denied in a read-only session; use static source evidence or request the normal workspace permission');
+        const tools = agent.ctx?.get?.('tools') ?? ctx.tools;
+        let toolName = 'bash', command = input.command;
+        if (process.platform === 'win32' && !tools.get?.('bash', agent) && tools.get?.('pwsh', agent)) {
+            const bash = [path.join(process.env.ProgramFiles ?? 'C:\\Program Files', 'Git', 'bin', 'bash.exe'), path.join(process.env.LOCALAPPDATA ?? '', 'Programs', 'Git', 'bin', 'bash.exe')].find(file => existsSync(file));
+            if (!bash)
+                throw new Error('This Windows preset exposes pwsh only. Install Git Bash or enable the controlled Bash tool; no direct process fallback is allowed.');
+            // The official Windows preset exposes pwsh. It remains the policy/cancellation
+            // boundary; use Git Bash underneath, preserving the original visible command.
+            const quote = (s) => "'" + s.replaceAll("'", "''") + "'";
+            command = "if ($PSVersionTable.PSVersion -lt [version]'7.3') { throw 'Git Bash bridging requires PowerShell 7.3+' }; $PSNativeCommandArgumentPassing = 'Standard'; & " + quote(bash) + ' -lc ' + quote(input.command) + '; exit $LASTEXITCODE';
+            toolName = 'pwsh';
+        }
+        const result = await tools.execute({ callId: 'review-check-' + randomUUID(), name: toolName, arguments: { command, description: 'Run review evidence in Git Bash', workdir: input.cwd, timeoutMs: 600000 }, agent, signal: input.signal });
+        if (result.isError || !result.value)
+            throw new Error(result.error?.message ?? 'Controlled Bash execution failed');
+        const value = result.value;
+        if (value.kind === 'promoted' || value.kind === 'background') {
+            ctx.jobs.kill(value.jobId, agent.id, 'Review checks cannot continue in the background');
+            for (;;) {
+                const view = await ctx.jobs.wait(value.jobId, 5000, agent.id);
+                if (!['running', 'stopping'].includes(view.status))
+                    break;
+            }
+            throw new Error('Evidence command exceeded the foreground budget and was stopped');
+        }
+        const truncated = value.stdout?.truncated === true || value.stderr?.truncated === true;
+        return { ok: value.exitCode === 0 && !value.timedOut && !value.aborted && !value.sandbox?.denied && !truncated,
+            exitCode: value.exitCode ?? null, timedOut: !!value.timedOut, aborted: !!value.aborted, truncated,
+            output: String(value.stdout?.text ?? '') + (value.stderr?.text ? '\n' + value.stderr.text : '') };
+    };
+    const dispatcher = (exec, root, signal) => createDispatcher({ subagents: ctx.subagents, parent: exec.agent, provider: resolved.subagentProvider, signal, cwd: root });
+    for (const definition of buildReviewTools(resolved, { runner, dispatcher })) {
+        if (ctx.effect)
+            ctx.effect(() => ctx.tools.register(definition));
+        else
+            ctx.tools.register(definition);
+    }
+}
+export { resolveConfig, DEFAULT_CONFIG } from './config.js';

package/lib/ledger.d.ts

@@ -0,0 +1,140 @@
+import type { Mode } from './modes.js';
+import type { ReviewTarget } from './target.js';
+import type { LensTask } from './lenses.js';
+import type { CandidateFinding } from './gate.js';
+import type { ReviewScope } from './scope.js';
+export type Disposition = 'fixed' | 'wrong' | 'intentional' | 'wontfix';
+export type RunStatus = 'pending' | 'running' | 'complete' | 'incomplete' | 'failed' | 'cancelled' | 'stale';
+export interface LedgerFinding {
+    fingerprint: string;
+    file: string;
+    line: number;
+    kind: string;
+    lens?: string;
+    severity: 'blocker' | 'important' | 'nit' | 'pre-existing';
+    message: string;
+    evidence: string;
+    at: string;
+    disposition?: Disposition;
+    note?: string;
+    repeats: number;
+    targetId?: string;
+    anchor?: string;
+    classOfBug?: string;
+    verification?: unknown;
+}
+export interface HeadRecord {
+    head: string;
+    base?: string;
+    targetId?: string;
+    series?: string;
+    latestRunId?: string;
+    round: number;
+    mode: Mode;
+    posted: Record<string, LedgerFinding>;
+    reviewedFiles: string[];
+    dropped: number;
+    suppressed: number;
+    unverified: number;
+    updatedAt: string;
+}
+export interface StoredRun {
+    id: string;
+    targetId: string;
+    series: string;
+    head: string;
+    target: ReviewTarget;
+    mode: Mode;
+    status: RunStatus;
+    stage: 'find' | 'verify' | 'arbiter' | 'done';
+    tasks: LensTask[];
+    results: Record<string, unknown>;
+    candidates: CandidateFinding[];
+    round: number;
+    calls: number;
+    errors: string[];
+    createdAt: string;
+    completedAt?: string;
+    postable: unknown[];
+    rejected: unknown[];
+    unverified: number;
+    accepted?: LedgerFinding[];
+    independent: boolean;
+    scope?: ReviewScope;
+    lease?: string;
+    leasePid?: number;
+    summary?: string;
+    risk?: {
+        tier: 'low' | 'medium' | 'high';
+        extraHuman: boolean;
+        reasons: string[];
+    };
+}
+export interface Receipt {
+    id: string;
+    runId: string;
+    targetId: string;
+    command: string;
+    cwd: string;
+    exitCode: number | null;
+    timedOut: boolean;
+    aborted: boolean;
+    truncated: boolean;
+    output: string;
+    at: string;
+}
+export interface LedgerState {
+    version: 2;
+    revision: number;
+    heads: Record<string, HeadRecord>;
+    runs: Record<string, StoredRun>;
+    receipts: Record<string, Receipt>;
+    legacy?: unknown;
+    evaluations?: {
+        cases: Record<string, unknown>;
+        results: Record<string, unknown>;
+    };
+}
+export declare function stateDirectory(root: string, stateDir: string): string;
+export declare class Ledger {
+    private readonly root;
+    readonly directory: string;
+    private readonly file;
+    private state;
+    constructor(root: string, stateDir: string);
+    private read;
+    private locked;
+    private write;
+    transaction<T>(work: (state: LedgerState) => T): T;
+    save(): void;
+    event(type: string, payload: Record<string, unknown>): void;
+    snapshot(): LedgerState;
+    head(head: string): HeadRecord | undefined;
+    ensureHead(head: string, mode: Mode): HeadRecord;
+    beginRound(head: string, mode: Mode): HeadRecord;
+    remember(record: HeadRecord, finding: LedgerFinding): void;
+    respond(head: string, fingerprint: string, disposition: Disposition, note?: string): LedgerFinding | undefined;
+    status(head?: string): {
+        heads: number;
+        round: number;
+        posted: number;
+        byDisposition: Record<string, number>;
+        noiseRate: number | null;
+        repeatRate: number | null;
+        unverified: number;
+        dropped: number;
+        topKinds: {
+            kind: string;
+            count: number;
+        }[];
+        runs: {
+            id: string;
+            targetId: string;
+            status: RunStatus;
+            stage: "find" | "verify" | "arbiter" | "done";
+            calls: number;
+            errors: string[];
+        }[];
+        legacyPresent: boolean;
+    };
+}

package/lib/ledger.js

@@ -0,0 +1,125 @@
+import { appendFileSync, existsSync, mkdirSync, readFileSync, renameSync, writeFileSync, rmdirSync, unlinkSync, copyFileSync, constants, realpathSync } from 'node:fs';
+import path from 'node:path';
+import { homedir } from 'node:os';
+import { createHash, randomUUID } from 'node:crypto';
+export function stateDirectory(root, stateDir) {
+    const configuredHome = process.env.DSH_HOME || path.join(homedir(), '.dsh');
+    let profileBase = configuredHome;
+    if (stateDir === '@profile') {
+        let ancestor = path.resolve(configuredHome);
+        while (!existsSync(ancestor))
+            ancestor = path.dirname(ancestor);
+        profileBase = path.join(realpathSync(ancestor), path.relative(ancestor, path.resolve(configuredHome)));
+    }
+    const dir = stateDir === '@profile'
+        ? path.join(profileBase, 'plugins', 'dsh-review', createHash('sha256').update(realpathSync(root)).digest('hex').slice(0, 24))
+        : path.resolve(root, stateDir);
+    if (stateDir !== '@profile') {
+        const relative = path.relative(root, dir);
+        if (relative.startsWith('..') || path.isAbsolute(relative) || relative === '')
+            throw new Error('stateDir must be a child directory of the workspace, or @profile');
+    }
+    let current = dir;
+    while (!existsSync(current))
+        current = path.dirname(current);
+    if (path.resolve(realpathSync(current)).toLowerCase() !== path.resolve(current).toLowerCase())
+        throw new Error('Review state path may not traverse a symlink');
+    return dir;
+}
+export class Ledger {
+    root;
+    directory;
+    file;
+    state;
+    constructor(root, stateDir) {
+        this.root = root;
+        this.directory = stateDirectory(root, stateDir);
+        this.file = path.join(this.directory, 'state.json');
+        this.state = this.read();
+    }
+    read() {
+        if (!existsSync(this.file))
+            return { version: 2, revision: 0, heads: {}, runs: {}, receipts: {} };
+        let parsed;
+        try {
+            parsed = JSON.parse(readFileSync(this.file, 'utf8'));
+        }
+        catch {
+            throw new Error('Review ledger is corrupt; original file preserved. Gate remains blocked.');
+        }
+        if (parsed?.version === 1 && parsed.heads && typeof parsed.heads === 'object' && !Array.isArray(parsed.heads))
+            return { version: 2, revision: 0, heads: {}, runs: {}, receipts: {}, legacy: parsed };
+        if (parsed?.version !== 2 || !Number.isInteger(parsed.revision) || !parsed.heads || !parsed.runs || !parsed.receipts || [parsed.heads, parsed.runs, parsed.receipts].some(value => typeof value !== 'object' || Array.isArray(value)))
+            throw new Error('Unsupported or invalid review ledger; gate remains blocked');
+        return parsed;
+    }
+    locked(work) {
+        mkdirSync(this.directory, { recursive: true });
+        const lock = path.join(this.directory, 'write.lock');
+        try {
+            mkdirSync(lock);
+        }
+        catch {
+            throw new Error('Review ledger is busy; retry after the current update finishes');
+        }
+        try {
+            return work();
+        }
+        finally {
+            rmdirSync(lock);
+        }
+    }
+    write() {
+        if (this.state.legacy && !existsSync(this.file + '.v1.backup') && existsSync(this.file))
+            copyFileSync(this.file, this.file + '.v1.backup', constants.COPYFILE_EXCL);
+        const tmp = this.file + '.tmp-' + process.pid + '-' + randomUUID();
+        const text = JSON.stringify({ ...this.state, revision: this.state.revision + 1 }, null, 2) + '\n';
+        try {
+            writeFileSync(tmp, text, { flag: 'wx' });
+            renameSync(tmp, this.file);
+            this.state.revision++;
+        }
+        finally {
+            if (existsSync(tmp))
+                unlinkSync(tmp);
+        }
+    }
+    transaction(work) {
+        return this.locked(() => { this.state = this.read(); const value = work(this.state); this.write(); return value; });
+    }
+    save() { this.locked(() => { const current = this.read(); if (current.revision !== this.state.revision)
+        throw new Error('Review ledger changed; refusing a stale write'); this.write(); }); }
+    event(type, payload) {
+        mkdirSync(this.directory, { recursive: true });
+        appendFileSync(path.join(this.directory, 'ledger.jsonl'), JSON.stringify({ at: new Date().toISOString(), type, ...payload }) + '\n');
+    }
+    snapshot() { return this.read(); }
+    head(head) { return this.state.heads[head]; }
+    ensureHead(head, mode) { return this.state.heads[head] ??= { head, round: 0, mode, posted: {}, reviewedFiles: [], dropped: 0, suppressed: 0, unverified: 0, updatedAt: new Date().toISOString() }; }
+    beginRound(head, mode) { const record = this.ensureHead(head, mode); record.round++; return record; }
+    remember(record, finding) { record.posted[finding.fingerprint] = finding; record.updatedAt = new Date().toISOString(); }
+    respond(head, fingerprint, disposition, note) {
+        const finding = this.state.heads[head]?.posted[fingerprint];
+        if (!finding)
+            return undefined;
+        finding.disposition = disposition;
+        if (note)
+            finding.note = note;
+        return finding;
+    }
+    status(head) {
+        const state = this.read(), records = Object.entries(state.heads).filter(([key, value]) => !head || key === head || value.head === head).map(([, value]) => value);
+        const findings = records.flatMap(record => Object.values(record.posted)), byDisposition = { fixed: 0, wrong: 0, intentional: 0, wontfix: 0, unanswered: 0 };
+        for (const finding of findings)
+            byDisposition[finding.disposition ?? 'unanswered']++;
+        const answered = findings.filter(f => f.disposition).length, kinds = new Map();
+        for (const f of findings)
+            kinds.set(f.kind, (kinds.get(f.kind) ?? 0) + 1);
+        return { heads: records.length, round: Math.max(0, ...records.map(r => r.round)), posted: findings.length, byDisposition,
+            noiseRate: answered ? ((byDisposition.wrong + byDisposition.intentional) / answered) : null,
+            repeatRate: findings.length ? findings.reduce((n, f) => n + f.repeats, 0) / findings.length : null,
+            unverified: records.reduce((n, r) => n + r.unverified, 0), dropped: records.reduce((n, r) => n + r.dropped, 0),
+            topKinds: [...kinds].map(([kind, count]) => ({ kind, count })).sort((a, b) => b.count - a.count).slice(0, 8),
+            runs: Object.values(state.runs).filter(r => !head || r.head === head || r.targetId === head).map(r => ({ id: r.id, targetId: r.targetId, status: r.status, stage: r.stage, calls: r.calls, errors: r.errors })), legacyPresent: !!state.legacy };
+    }
+}