argus-reviewer-e2e 0.3.0 → 0.4.0

package/dist/review/inline.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Inline review comment identity (plan KTD4, U6).
+ *
+ * The CLI renders each inline comment once and serializes its dedup key; the
+ * action poster rebuilds the same key from comments already on the PR. Both
+ * sides go through `inlineDedupKey`, and action/sticky-comment.cjs keeps a
+ * copy of this file's functions (KTD2), pinned equal by a parity test.
+ *
+ * Two body formats exist on real PRs:
+ *   legacy (before U6): `**argus-reviewer <sev>:** <message> \`<category>\``
+ *   Ocellus (U6):       `<!-- argus-reviewer:inline -->`
+ *                       `<glyph> **<severity word>** · <proof meter> <level>`
+ *                       `<message>`
+ * A comment posted in either format keys to the same value for the same
+ * finding, so upgrading never re-posts every inline comment.
+ */
+/** Hidden first line of every Ocellus inline comment: marks it as Argus's own. */
+export declare const INLINE_SENTINEL = "<!-- argus-reviewer:inline -->";
+/**
+ * Strip the prefix the review prompt asks the model for (`L42: <emoji> bug: `)
+ * in any order, so the rendered message line starts with the sentence.
+ */
+export declare function normalizeFindingMessage(message: string): string;
+/** Severity and message of an Argus inline comment in either format; undefined for any other body. */
+export declare function parseInlineBody(body: string): {
+    severity: string;
+    message: string;
+} | undefined;
+/** True when the body is an Argus inline comment (legacy prefix or the sentinel). */
+export declare function isArgusInlineBody(body: string): boolean;
+/** djb2 to 8 hex chars: dedup identity only, not a security boundary. */
+export declare function shortHash(s: string): string;
+/**
+ * The fenced suggestion block of a comment body. The CLI's fence is the
+ * longest backtick run plus one (min 4), so a run of exactly that length can
+ * only be the closing fence.
+ */
+export declare function extractSuggestion(body: string): string;
+/**
+ * KTD4 dedup key: `path:line:severity:normalizedMessage:hash8(suggestion)`.
+ * A changed suggestion changes the key, so a corrected fix re-posts. A body
+ * that parses as neither format keeps the pre-U6 first-line key.
+ */
+export declare function inlineDedupKey(path: string, line: number, body: string): string;

package/dist/review/inline.js

@@ -0,0 +1,95 @@
+import { SEVERITIES, SEVERITY_LABEL } from '../report/viewmodel.js';
+/**
+ * Inline review comment identity (plan KTD4, U6).
+ *
+ * The CLI renders each inline comment once and serializes its dedup key; the
+ * action poster rebuilds the same key from comments already on the PR. Both
+ * sides go through `inlineDedupKey`, and action/sticky-comment.cjs keeps a
+ * copy of this file's functions (KTD2), pinned equal by a parity test.
+ *
+ * Two body formats exist on real PRs:
+ *   legacy (before U6): `**argus-reviewer <sev>:** <message> \`<category>\``
+ *   Ocellus (U6):       `<!-- argus-reviewer:inline -->`
+ *                       `<glyph> **<severity word>** · <proof meter> <level>`
+ *                       `<message>`
+ * A comment posted in either format keys to the same value for the same
+ * finding, so upgrading never re-posts every inline comment.
+ */
+/** Hidden first line of every Ocellus inline comment: marks it as Argus's own. */
+export const INLINE_SENTINEL = '<!-- argus-reviewer:inline -->';
+const LEGACY_PREFIX = '**argus-reviewer';
+const LEGACY_LINE = /^\*\*argus-reviewer ([^:*]+):\*\* ?(.*)$/;
+const SEVERITY_LINE = /^(?:\S+ )?\*\*([^*]+)\*\* · /;
+/** The category code span the legacy renderer appended to the message. */
+const CATEGORY_SUFFIX = /\s*`(?:correctness|security|performance|usability|convention|other)`$/;
+/** One model-message prefix: `L<n>[-<m>]:`, a leading emoji, or a `<severity>:` keyword. */
+const MESSAGE_PREFIX = /^(?:L\d+(?:-\d+)?:|\p{Extended_Pictographic}\u{FE0F}?|(?:bug|risk|nit|q|question):)\s*/iu;
+/**
+ * Strip the prefix the review prompt asks the model for (`L42: <emoji> bug: `)
+ * in any order, so the rendered message line starts with the sentence.
+ */
+export function normalizeFindingMessage(message) {
+    let out = message.trim();
+    for (let i = 0; i < 4; i++) {
+        const next = out.replace(MESSAGE_PREFIX, '');
+        if (next === out)
+            break;
+        out = next;
+    }
+    return out;
+}
+/** The message as the dedup key sees it: normalized, no category span, one-spaced. */
+function keyMessage(message) {
+    return normalizeFindingMessage(message.replace(CATEGORY_SUFFIX, '')).replace(/\s+/g, ' ').trim();
+}
+const LABEL_TO_SEVERITY = new Map(SEVERITIES.map((s) => [SEVERITY_LABEL[s], s]));
+/** Severity and message of an Argus inline comment in either format; undefined for any other body. */
+export function parseInlineBody(body) {
+    const lines = body.split(/\r?\n/);
+    if (body.startsWith(LEGACY_PREFIX)) {
+        const m = LEGACY_LINE.exec(lines[0] ?? '');
+        if (m === null)
+            return undefined;
+        return { severity: (m[1] ?? '').trim(), message: keyMessage(m[2] ?? '') };
+    }
+    if (lines[0] === INLINE_SENTINEL) {
+        const m = SEVERITY_LINE.exec(lines[1] ?? '');
+        if (m === null)
+            return undefined;
+        const word = (m[1] ?? '').trim();
+        return { severity: LABEL_TO_SEVERITY.get(word) ?? word, message: keyMessage(lines[2] ?? '') };
+    }
+    return undefined;
+}
+/** True when the body is an Argus inline comment (legacy prefix or the sentinel). */
+export function isArgusInlineBody(body) {
+    return body.startsWith(LEGACY_PREFIX) || body.startsWith(INLINE_SENTINEL);
+}
+/** djb2 to 8 hex chars: dedup identity only, not a security boundary. */
+export function shortHash(s) {
+    let h = 5381;
+    for (let i = 0; i < s.length; i++)
+        h = ((h << 5) + h + s.charCodeAt(i)) | 0;
+    return (h >>> 0).toString(16).padStart(8, '0');
+}
+/**
+ * The fenced suggestion block of a comment body. The CLI's fence is the
+ * longest backtick run plus one (min 4), so a run of exactly that length can
+ * only be the closing fence.
+ */
+export function extractSuggestion(body) {
+    const m = /\r?\n(`{4,})suggestion\r?\n([\s\S]*?)\r?\n\1/.exec(body);
+    return m?.[2] ?? '';
+}
+/**
+ * KTD4 dedup key: `path:line:severity:normalizedMessage:hash8(suggestion)`.
+ * A changed suggestion changes the key, so a corrected fix re-posts. A body
+ * that parses as neither format keeps the pre-U6 first-line key.
+ */
+export function inlineDedupKey(path, line, body) {
+    const parsed = parseInlineBody(body);
+    const hash = shortHash(extractSuggestion(body));
+    if (parsed === undefined)
+        return `${path}:${line}:${body.split('\n')[0]}:${hash}`;
+    return `${path}:${line}:${parsed.severity}:${parsed.message}:${hash}`;
+}

package/dist/review/packs.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Review prompt packs (roadmap E1.U2): named rubric blocks appended to the
+ * code-review prompt. Packs shape the rubric only — findings still flow
+ * through the same severity gate, dedup, adjudication, and cap path, so a
+ * pack can shift recall but cannot bypass posting policy.
+ *
+ * The `security` pack's deterministic half is the secrets lane
+ * (`src/review/secrets.ts`) — regex candidates over the local merge-base
+ * diff, adjudicated by the confidence model, masked in every output. It runs regardless of
+ * profile selection; the rubric below additionally tunes the model toward
+ * security-shaped defects.
+ */
+export declare const REVIEW_PROFILES: readonly ["security", "perf", "debloat"];
+export type ReviewProfile = (typeof REVIEW_PROFILES)[number];
+export declare function isReviewProfile(value: string): value is ReviewProfile;
+/**
+ * Render the rubric section for the configured profiles. Returns undefined
+ * when no valid profile is configured so the prompt stays byte-identical to
+ * the no-packs form.
+ */
+export declare function packRubric(profiles: readonly string[] | undefined): string | undefined;

package/dist/review/packs.js

@@ -0,0 +1,47 @@
+/**
+ * Review prompt packs (roadmap E1.U2): named rubric blocks appended to the
+ * code-review prompt. Packs shape the rubric only — findings still flow
+ * through the same severity gate, dedup, adjudication, and cap path, so a
+ * pack can shift recall but cannot bypass posting policy.
+ *
+ * The `security` pack's deterministic half is the secrets lane
+ * (`src/review/secrets.ts`) — regex candidates over the local merge-base
+ * diff, adjudicated by the confidence model, masked in every output. It runs regardless of
+ * profile selection; the rubric below additionally tunes the model toward
+ * security-shaped defects.
+ */
+export const REVIEW_PROFILES = ['security', 'perf', 'debloat'];
+export function isReviewProfile(value) {
+    return REVIEW_PROFILES.includes(value);
+}
+const RUBRICS = {
+    security: 'Security lens – additionally weigh: injection (SQL, shell, template, prompt), ' +
+        'missing or bypassable authorization checks, unsafe deserialization, secret-shaped ' +
+        'literals committed in the diff (report file/line and pattern class only – never ' +
+        'reproduce the literal), weak or misused crypto, path traversal, SSRF, and ' +
+        'unsanitized input reaching HTML or a shell. Only report a path actually ' +
+        'exploitable from the changed code.',
+    perf: 'Performance lens – additionally weigh: N+1 or per-item queries, work repeated ' +
+        'inside loops that could hoist, accidental O(n^2) or worse on unbounded inputs, ' +
+        'sync or blocking calls on hot paths, unnecessary copies or allocations of large ' +
+        'structures, and missing pagination or bounds on data fetched. Cite the scaling ' +
+        'input the cost depends on.',
+    debloat: 'Debloat lens – additionally weigh: dead code added but never reachable, logic ' +
+        'duplicating an existing helper visible in the diff or index context, dependencies ' +
+        'or abstractions introduced for a single trivial use, commented-out code, and ' +
+        'params/exports added without a caller. Do not flag removal opportunities that ' +
+        'the diff itself already deletes.',
+};
+/**
+ * Render the rubric section for the configured profiles. Returns undefined
+ * when no valid profile is configured so the prompt stays byte-identical to
+ * the no-packs form.
+ */
+export function packRubric(profiles) {
+    if (profiles === undefined || profiles.length === 0)
+        return undefined;
+    const blocks = profiles.filter(isReviewProfile).map((p) => `- ${RUBRICS[p]}`);
+    if (blocks.length === 0)
+        return undefined;
+    return `Active review lenses:\n${blocks.join('\n')}`;
+}

package/dist/review/scope.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Review scope: which changed files reach the review model.
+ *
+ * Generated, fixture, golden and vendored paths carry content that reads
+ * like code (sample manifests, rendered comments, lockfiles). Fed to the
+ * model it produced findings about files that do not exist, so these
+ * paths are excluded by default. `review.exclude` replaces the list.
+ */
+export declare const DEFAULT_REVIEW_EXCLUDE: readonly string[];
+export declare function globMatch(glob: string, path: string): boolean;
+export declare function partitionByExclude<T extends {
+    filename: string;
+}>(files: T[], exclude: readonly string[]): {
+    kept: T[];
+    excluded: T[];
+};

package/dist/review/scope.js

@@ -0,0 +1,74 @@
+/**
+ * Review scope: which changed files reach the review model.
+ *
+ * Generated, fixture, golden and vendored paths carry content that reads
+ * like code (sample manifests, rendered comments, lockfiles). Fed to the
+ * model it produced findings about files that do not exist, so these
+ * paths are excluded by default. `review.exclude` replaces the list.
+ */
+export const DEFAULT_REVIEW_EXCLUDE = [
+    'dist/**',
+    'fixtures/**',
+    'tests/goldens/**',
+    '**/package-lock.json',
+    '**/npm-shrinkwrap.json',
+    '**/yarn.lock',
+    '**/pnpm-lock.yaml',
+    '**/bun.lock',
+    '**/Cargo.lock',
+    '**/poetry.lock',
+    '**/Gemfile.lock',
+    '**/composer.lock',
+    '**/go.sum',
+    '**/*.generated.*',
+    'assets/brand/export/**',
+];
+const globCache = new Map();
+function globToRegExp(glob) {
+    const cached = globCache.get(glob);
+    if (cached !== undefined)
+        return cached;
+    let re = '';
+    for (let i = 0; i < glob.length; i++) {
+        const c = glob[i];
+        if (c === '*') {
+            if (glob[i + 1] === '*') {
+                // `**/` matches zero or more directories; a bare `**` matches anything.
+                if (glob[i + 2] === '/') {
+                    re += '(?:.*/)?';
+                    i += 2;
+                }
+                else {
+                    re += '.*';
+                    i += 1;
+                }
+            }
+            else {
+                re += '[^/]*';
+            }
+        }
+        else if (c === '?') {
+            re += '[^/]';
+        }
+        else {
+            re += c.replace(/[.+^${}()|[\]\\]/g, '\\$&');
+        }
+    }
+    const out = new RegExp(`^${re}$`);
+    globCache.set(glob, out);
+    return out;
+}
+export function globMatch(glob, path) {
+    return globToRegExp(glob).test(path);
+}
+export function partitionByExclude(files, exclude) {
+    const kept = [];
+    const excluded = [];
+    for (const f of files) {
+        if (exclude.some((g) => globMatch(g, f.filename)))
+            excluded.push(f);
+        else
+            kept.push(f);
+    }
+    return { kept, excluded };
+}

package/dist/review/secrets.d.ts

@@ -2,12 +2,12 @@ import { type ExecFn } from '../detect.js';
 import { DecisionClient } from '../vision/decisions.js';
 /**
  * Deterministic secrets scan over the PR's local merge-base diff,
- * optionally adjudicated by the Decisions API (Jev). The lane is
+ * optionally adjudicated by the Decisions API (the confidence model). The lane is
  * additive-only: findings are unioned into the review AFTER model
  * synthesis so a prompt-injected synthesis can never erase them, and a
- * Jev outage degrades to regex-only findings rather than silence.
+ * A confidence-model outage degrades to regex-only findings rather than silence.
  *
- * Masking contract: raw literals transit to Jev inside `state` (KTD9 —
+ * Masking contract: raw literals transit to the confidence model inside `state` (KTD9 —
  * adjudication needs the shape, and the full diff already crosses to
  * OpenRouter in the review call) and appear NOWHERE else — not in
  * findings, comments, the report, or logs.
@@ -19,19 +19,19 @@ export interface SecretCandidate {
     patternClass: string;
     /** Diff line text with every occurrence of the literal replaced by `***`. */
     contextExcerpt: string;
-    /** Raw literal — Jev `state` only, never emitted. */
+    /** Raw literal — confidence-model `state` only, never emitted. */
     literal: string;
-    /** Full raw added-line text — Jev `state` only, never emitted. */
+    /** Full raw added-line text — confidence-model `state` only, never emitted. */
     rawText: string;
 }
 export interface SecretScanRecord {
     file: string;
     line: number;
     patternClass: string;
-    /** True when Jev answered for this candidate. */
+    /** True when the confidence model answered for this candidate. */
     adjudicated: boolean;
     pLive?: number;
-    /** Jev scored below threshold — recorded for audit, not a finding. */
+    /** The confidence model scored below threshold — recorded for audit, not a finding. */
     suppressed?: boolean;
 }
 export interface SecretsScanResult {
@@ -42,12 +42,12 @@ export interface SecretsScanResult {
         severity: string;
         category?: string;
         message: string;
-        /** Jev P(live) carried through adjudication — feeds the review gate. */
+        /** Confidence-model P(live) carried through adjudication — feeds the review gate. */
         p?: number;
     }[];
     /** Audit records for report.secretsScan — literals never included. */
     records: SecretScanRecord[];
-    /** Candidates past MAX_CANDIDATES — reported count-only, never sent to Jev. */
+    /** Candidates past MAX_CANDIDATES — reported count-only, never sent to the confidence model. */
     overflow: number;
     /** Why the lane produced nothing (e.g. base unfetchable). */
     skipped?: string;
@@ -77,7 +77,7 @@ export declare function materializeMergeBaseDiff(opts: {
     skipped: string;
 }>;
 /**
- * Full lane: scan candidates (capped), Jev-adjudicate when a client and
+ * Full lane: scan candidates (capped), adjudicate with the confidence model when a client and
  * threshold are available, and emit masked findings + audit records.
  * `client === undefined` (decisionModel unset) or any DecisionError →
  * every candidate unadjudicated — regex-only mode, never silence.

package/dist/review/secrets.js

@@ -87,8 +87,8 @@ export function scanDiffForSecrets(diffText) {
 function maskFindingMessage(c, adjudicated) {
     const verdict = adjudicated
         ? 'live-looking credential'
-        : 'secret-shaped literal (unadjudicated — decision model unavailable)';
-    return (`L${c.line}: ${adjudicated ? '🔴' : '🟡'} ${adjudicated ? 'bug' : 'risk'}: ` +
+        : 'secret-shaped literal (unadjudicated: decision model unavailable)';
+    return (`L${c.line}: ${adjudicated ? 'bug' : 'risk'}: ` +
         `${verdict} (${c.patternClass}) added in this PR at \`${c.file}\`. ` +
         `Rotate it and purge it from history.`);
 }
@@ -128,7 +128,7 @@ export async function materializeMergeBaseDiff(opts) {
     return { diff: diff.stdout };
 }
 /**
- * Full lane: scan candidates (capped), Jev-adjudicate when a client and
+ * Full lane: scan candidates (capped), adjudicate with the confidence model when a client and
  * threshold are available, and emit masked findings + audit records.
  * `client === undefined` (decisionModel unset) or any DecisionError →
  * every candidate unadjudicated — regex-only mode, never silence.
@@ -169,7 +169,7 @@ export async function scanSecrets(opts) {
         }
         catch (e) {
             adjudicationFailed = true;
-            debug('secrets', `adjudication failed — degrading to regex-only: ${describeDecisionError(e)}`);
+            debug('secrets', `adjudication failed, degrading to regex-only: ${describeDecisionError(e)}`);
         }
     }
     const findings = [];
@@ -194,7 +194,7 @@ export async function scanSecrets(opts) {
             severity: adjudicated ? 'bug' : 'risk',
             category: 'security',
             message: maskFindingMessage(c, adjudicated),
-            // A Jev-confirmed live secret counts as proven for the review-event
+            // A confidence-model-confirmed live secret counts as proven for the review-event
             // gate — pLive IS the true-positive probability for this finding.
             // Unadjudicated findings carry no p (degrade-open, like U8).
             ...(adjudicated && pLive !== undefined ? { p: pLive } : {}),
@@ -215,8 +215,8 @@ export async function scanSecrets(opts) {
             line: 0,
             severity: 'risk',
             category: 'security',
-            message: `L0: 🟡 risk: ${overflow} secret-shaped literal(s) exceeded the ` +
-                `${MAX_CANDIDATES}-candidate adjudication cap and were not evaluated — ` +
+            message: `L0: risk: ${overflow} secret-shaped literal(s) exceeded the ` +
+                `${MAX_CANDIDATES}-candidate adjudication cap and were not evaluated; ` +
                 'review the diff for secrets manually.',
         });
     }

package/dist/review/testfiles.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Test files describe expected behavior: a finding that restates an
+ * assertion is almost never a defect. Findings anchored in a test file
+ * are capped at `nit` unless they cite a non-test file from the diff
+ * (the real bug is elsewhere) or carry reproduced evidence.
+ */
+export declare function isTestPath(path: string): boolean;
+export declare function capTestFindings<T extends {
+    file: string;
+    severity: string;
+    message: string;
+    evidence?: {
+        status?: string;
+    };
+}>(findings: T[], diffFiles: string[]): {
+    findings: T[];
+    capped: number;
+};

package/dist/review/testfiles.js

@@ -0,0 +1,26 @@
+/**
+ * Test files describe expected behavior: a finding that restates an
+ * assertion is almost never a defect. Findings anchored in a test file
+ * are capped at `nit` unless they cite a non-test file from the diff
+ * (the real bug is elsewhere) or carry reproduced evidence.
+ */
+const TEST_PATH = /(^|\/)(tests?|__tests__|__mocks__|spec|e2e)\/|\.(test|spec)\.[^/]+$|_test\.(go|py|rb)$|(^|\/)test_[^/]+\.py$/;
+export function isTestPath(path) {
+    return TEST_PATH.test(path.replace(/^\.\//, ''));
+}
+const CAPPED = new Set(['bug', 'risk']);
+export function capTestFindings(findings, diffFiles) {
+    const sourceFiles = diffFiles.filter((p) => !isTestPath(p));
+    let capped = 0;
+    const out = findings.map((f) => {
+        if (!isTestPath(f.file) || !CAPPED.has(f.severity))
+            return f;
+        if (f.evidence?.status === 'reproduced')
+            return f;
+        if (sourceFiles.some((p) => f.message.includes(p)))
+            return f;
+        capped++;
+        return { ...f, severity: 'nit' };
+    });
+    return { findings: out, capped };
+}

package/dist/review/triage.d.ts

@@ -17,7 +17,7 @@ export interface TriageRecord {
     topRiskArea?: TriageArea;
     /** Choice-answer confidence when the API provides one. */
     topRiskAreaConfidence?: number;
-    /** Chars of diff evidence Jev saw — route mode won't downgrade on 0. */
+    /** Chars of diff evidence the confidence model saw — route mode won't downgrade on 0. */
     diffExcerptChars?: number;
     /** decide() failed or answers failed validation — degrade-open marker. */
     unadjudicated?: boolean;

package/dist/review/triage.js

@@ -1,12 +1,12 @@
 /**
  * U7 PR triage lane — one batched `decide` call before chunk review
  * produces a typed-probability triage record (the pace two-round
- * pattern). Jev routes and annotates, never gates: every chunk is still
+ * pattern). The confidence model routes and annotates, never gates: every chunk is still
  * reviewed by a code model and the deterministic verdict stays
  * authoritative. `decide` failure degrades open — the record lands with
  * `unadjudicated` and routing keeps the configured (strong) model.
  *
- * PR title/body in `state` are untrusted text — Jev is the only
+ * PR title/body in `state` are untrusted text — the confidence model is the only
  * consumer; they never reach the verdict path.
  */
 import { debug } from '../debug.js';
@@ -60,13 +60,13 @@ function buildTriageQuestions() {
         },
         [Q.risk]: {
             type: 'score',
-            instructions: 'blast radius if this PR merges broken — pick the closest rubric level.',
+            instructions: 'blast radius if this PR merges broken – pick the closest rubric level.',
             criteria: [
-                'cosmetic only — docs, comments, formatting, metadata',
-                'minor — internal-only paths, limited blast radius',
-                'moderate — user-visible defects plausible',
-                'high — security-sensitive or data-handling paths touched',
-                'severe — auth, billing, or data-loss surface',
+                'cosmetic only – docs, comments, formatting, metadata',
+                'minor – internal-only paths, limited blast radius',
+                'moderate – user-visible defects plausible',
+                'high – security-sensitive or data-handling paths touched',
+                'severe – auth, billing, or data-loss surface',
             ],
         },
         [Q.area]: {
@@ -111,7 +111,7 @@ export async function triagePr(opts) {
         return rec;
     }
     catch (e) {
-        debug('triage', `adjudication failed — degrading to annotate: ${describeDecisionError(e)}`);
+        debug('triage', `adjudication failed – degrading to annotate: ${describeDecisionError(e)}`);
         return { mode: opts.mode, model: opts.model ?? JEV_DEFAULT_MODEL, unadjudicated: true };
     }
 }
@@ -137,7 +137,7 @@ export function routeModel(opts) {
     if (rec.risk <= 2 && rec.needsDeepReview < 0.5) {
         return {
             model: opts.lowRiskModel,
-            reason: `low risk — risk=${rec.risk}, needsDeepReview=${rec.needsDeepReview.toFixed(2)}`,
+            reason: `low risk – risk=${rec.risk}, needsDeepReview=${rec.needsDeepReview.toFixed(2)}`,
         };
     }
     return {

package/dist/review/validate.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Deterministic finding validation (no model). A finding must point at a
+ * file that is in the reviewed diff and at a line inside the diff's
+ * changed hunks (plus a small context tolerance). Anything else is a
+ * hallucinated or stale anchor; it is dropped here and counted in the
+ * report so the drop is never silent.
+ */
+export type DropReason = 'file_not_in_diff' | 'file_excluded' | 'file_deleted' | 'line_beyond_file' | 'line_outside_diff';
+export interface DroppedFinding {
+    file: string;
+    line?: number;
+    reason: DropReason;
+}
+export interface ValidationAudit {
+    dropped: number;
+    byReason: Partial<Record<DropReason, number>>;
+    /** Up to 10 dropped anchors, for the Diagnostics fold. */
+    examples: DroppedFinding[];
+}
+/** Lines of slack around a hunk: models are often off by a line or two. */
+export declare const HUNK_TOLERANCE = 2;
+export interface ParsedHunks {
+    /** Inclusive new-side [start, end] line ranges, one per hunk with new lines. */
+    ranges: [number, number][];
+    /** Set when the patch creates the file: its exact line count. */
+    newFileLength?: number;
+    /** True when no new-side lines survive (file deleted at head). */
+    deleted: boolean;
+}
+export declare function parseHunks(patch: string): ParsedHunks;
+export declare function validateFindings<T extends {
+    file: string;
+    line?: number;
+}>(findings: T[], files: {
+    filename: string;
+    patch?: string;
+}[], excluded?: ReadonlySet<string>): {
+    kept: T[];
+    dropped: DroppedFinding[];
+};
+export declare function auditOf(dropped: DroppedFinding[]): ValidationAudit;

package/dist/review/validate.js

@@ -0,0 +1,76 @@
+/**
+ * Deterministic finding validation (no model). A finding must point at a
+ * file that is in the reviewed diff and at a line inside the diff's
+ * changed hunks (plus a small context tolerance). Anything else is a
+ * hallucinated or stale anchor; it is dropped here and counted in the
+ * report so the drop is never silent.
+ */
+/** Lines of slack around a hunk: models are often off by a line or two. */
+export const HUNK_TOLERANCE = 2;
+const MAX_EXAMPLES = 10;
+const HUNK_HEADER = /^@@ -(\d+)(?:,(\d+))? \+(\d+)(?:,(\d+))? @@/;
+export function parseHunks(patch) {
+    const ranges = [];
+    let newFileLength;
+    let sawHunk = false;
+    for (const line of patch.split('\n')) {
+        const m = HUNK_HEADER.exec(line);
+        if (m === null)
+            continue;
+        sawHunk = true;
+        const oldStart = Number(m[1]);
+        const oldCount = m[2] === undefined ? 1 : Number(m[2]);
+        const start = Number(m[3]);
+        const count = m[4] === undefined ? 1 : Number(m[4]);
+        if (count > 0)
+            ranges.push([start, start + count - 1]);
+        if (oldStart === 0 && oldCount === 0)
+            newFileLength = count;
+    }
+    return {
+        ranges,
+        ...(newFileLength !== undefined ? { newFileLength } : {}),
+        deleted: sawHunk && ranges.length === 0,
+    };
+}
+const norm = (p) => p.replace(/^\.\//, '');
+export function validateFindings(findings, files, excluded = new Set()) {
+    const byName = new Map();
+    for (const f of files)
+        byName.set(f.filename, parseHunks(f.patch ?? ''));
+    const kept = [];
+    const dropped = [];
+    for (const f of findings) {
+        const file = norm(String(f.file ?? ''));
+        const hunks = byName.get(file);
+        const hasLine = typeof f.line === 'number' && Number.isFinite(f.line);
+        const drop = (reason) => {
+            dropped.push({ file: String(f.file), ...(hasLine ? { line: f.line } : {}), reason });
+        };
+        if (hunks === undefined) {
+            drop(excluded.has(file) ? 'file_excluded' : 'file_not_in_diff');
+        }
+        else if (hunks.deleted) {
+            drop('file_deleted');
+        }
+        else if (!hasLine) {
+            kept.push(f);
+        }
+        else if (hunks.newFileLength !== undefined && f.line > hunks.newFileLength) {
+            drop('line_beyond_file');
+        }
+        else if (!hunks.ranges.some(([s, e]) => f.line >= s - HUNK_TOLERANCE && f.line <= e + HUNK_TOLERANCE)) {
+            drop('line_outside_diff');
+        }
+        else {
+            kept.push(f);
+        }
+    }
+    return { kept, dropped };
+}
+export function auditOf(dropped) {
+    const byReason = {};
+    for (const d of dropped)
+        byReason[d.reason] = (byReason[d.reason] ?? 0) + 1;
+    return { dropped: dropped.length, byReason, examples: dropped.slice(0, MAX_EXAMPLES) };
+}