@expo/code-review-cli 0.2.0 → 0.2.2

package/README.md

@@ -68,6 +68,26 @@ ecr review --pr 4057
 ecr review --pr 4057 --post
 ```
 
+Options (most to least common):
+
+| Flag | What it does |
+| --- | --- |
+| `--pr <n>` | Review GitHub PR #n by number (diff fetched via `gh`, no checkout); not combinable with `--base`/`--head`/`--staged`. |
+| `--post` | With `--pr`, also post the result as the PR comment (needs `gh` auth). Omit to preview only; re-run with `--post` to publish. |
+| `--staged` | Review only staged changes. |
+| `--base <ref>` | Base ref to diff against (default: merge-base with the default branch). |
+| `--head <ref>` | Head ref to diff (default: working tree, incl. uncommitted changes). |
+| `--agents <a,b>` | Run only these agents (comma-separated ids); default: all. |
+| `--route` | Let an LLM router pick the relevant agents from the diff. |
+| `--repo <owner/repo>` | Repo for `--pr` (default: inferred from the current checkout). |
+| `--json` | Emit machine-readable JSON on stdout. |
+| `--no-fail` | Always exit 0 (otherwise a `request_changes` decision exits non-zero). |
+| `-h`, `--help` | Show help. |
+
+`--pr` uses the PR's diff (authoritative) but reads your checked-out files for
+surrounding context; for full fidelity, `gh pr checkout <n>` first and run a plain
+`ecr review`.
+
 In CI it runs automatically from the scaffolded workflows — by label or a `/review`
 comment (see **CI usage**). From Claude Code (or another agent), add a slash command
 that runs it; eas-cli's
@@ -113,31 +133,6 @@ and applies Anthropic prompt caching automatically.
 
 </details>
 
-<details>
-<summary><b><code>ecr review</code> options</b></summary>
-
-```
---base <ref>       Base ref to diff against (default: merge-base with default branch)
---head <ref>       Head ref to diff (default: working tree, incl. uncommitted changes)
---staged           Review only staged changes
---pr <n>           Review GitHub PR #n by number (diff fetched via gh, no checkout);
-                   not combinable with --base/--head/--staged
---repo <owner/repo>  Repo for --pr (default: inferred from the current checkout)
---post             With --pr: also post the result as the PR comment (needs gh auth).
-                   Omit to preview only; re-run with --post to publish.
---agents <a,b>     Run only these agents (comma-separated ids); default: all
---route            Let an LLM router pick the relevant agents from the diff
---json             Emit machine-readable JSON on stdout
---no-fail          Always exit 0 (otherwise a request_changes decision exits non-zero)
--h, --help         Show help
-```
-
-`--pr` uses the PR's diff (authoritative) but reads your checked-out files for
-surrounding context; for full fidelity, `gh pr checkout <n>` first and run a plain
-`ecr review`.
-
-</details>
-
 <details>
 <summary><b>Configuration — <code>.expo-code-review/</code></b></summary>
 

package/build/core/prompts.js

@@ -182,25 +182,34 @@ export function buildCrossCuttingTask(allFiles, filtered = []) {
 export function buildVerifierSystem() {
     return [
         'You are a skeptical verifier of a single code-review finding. Your default is',
-        'DISTRUST. Using your read/grep tools, open the cited file, locate the code, and',
-        'confirm the finding against what the source ACTUALLY says.',
+        'DISTRUST. Using your read/grep tools, open the cited file (search nearby files',
+        'if the code is not exactly there), locate the relevant code, and judge whether',
+        'the described PROBLEM is actually present in the source.',
+        '',
+        'Judge the SUBSTANCE, not the wording. The finding\'s quoted "evidence" may be',
+        'paraphrased, abbreviated, quoted across non-adjacent lines, or slightly',
+        'misquoted, and its file/line may be approximate. None of that alone makes the',
+        'finding false — verify against what the code actually does. Do NOT reject merely',
+        'because the quoted snippet is not a verbatim match; reject only if the',
+        'underlying problem is not real.',
         '',
         'Mark verified=false (reject) if any of these hold:',
-        '- the code the finding describes or quotes is not actually present as claimed',
-        '  (it misread or invented the code),',
-        '- the described failure/exploit cannot actually occur,',
+        '- the described problem does not actually occur in the code (it misread or',
+        '  invented the behavior),',
+        '- the described failure/exploit cannot actually happen,',
         "- the claim is internally contradictory (e.g. asserts a type error in code that",
         '  compiles), or',
-        '- you cannot substantiate it after reading the file.',
+        '- you cannot substantiate the underlying issue after reading the file.',
         '',
-        'Only mark verified=true when you have CONFIRMED, from the real source, that the',
-        'flagged code exists as described and the problem is genuine. When unsure, reject.',
+        'Mark verified=true when you have CONFIRMED, from the real source, that the',
+        'described problem genuinely exists. When genuinely unsure whether it is real,',
+        'reject.',
         '',
         'Return ONLY this JSON object and nothing else:',
         '{"verified": true|false, "reason": "one concise sentence grounded in the file"}',
     ].join('\n');
 }
-export function buildVerifierTask(finding) {
+export function buildVerifierTask(finding, opts = {}) {
     const lines = [
         'Verify this finding by reading the real source (do not trust its wording):',
         '',
@@ -214,6 +223,9 @@ export function buildVerifierTask(finding) {
     if (finding.evidence) {
         lines.push('- code the finding claims is present (UNTRUSTED — verify it against the file):', '<<<EVIDENCE', finding.evidence, 'EVIDENCE');
     }
+    if (opts.evidenceUngrounded) {
+        lines.push('', 'NOTE: the quoted evidence could NOT be located verbatim in the file. It may be', 'a paraphrase, an elision, or a slightly wrong location — do not reject on that', 'basis alone. Read the file (and nearby files) and judge whether the described', 'problem is genuinely present.');
+    }
     lines.push('', 'Open the file, find the relevant code, and return the single verdict JSON object.');
     return lines.join('\n');
 }

package/build/core/render.js

@@ -1,5 +1,41 @@
 import { createHash } from 'node:crypto';
 import { fingerprintFinding, SEVERITIES, SEVERITY_RANK } from './schema.js';
+/**
+ * Build the file → right-side-line-numbers index from changed files' patch text,
+ * by walking each unified-diff hunk (`@@ -a,b +c,d @@`) and collecting the new-tree
+ * line number of every added (`+`) and context (` `) line. Deleted (`-`) lines have
+ * no right-side line and are skipped.
+ */
+export function buildDiffLineIndex(files) {
+    const index = new Map();
+    const hunkRe = /^@@ -\d+(?:,\d+)? \+(\d+)(?:,\d+)? @@/;
+    for (const file of files) {
+        const lines = new Set();
+        let right = 0;
+        let inHunk = false;
+        for (const raw of file.patch.split('\n')) {
+            const hunk = hunkRe.exec(raw);
+            if (hunk) {
+                right = parseInt(hunk[1], 10);
+                inHunk = true;
+                continue;
+            }
+            if (!inHunk || raw.startsWith('+++') || raw.startsWith('---') || raw.startsWith('\\')) {
+                continue;
+            }
+            const marker = raw[0];
+            if (marker === '+' || marker === ' ') {
+                lines.add(right);
+                right++;
+            }
+            // '-' is left-side only (no new-tree line); anything else is ignored.
+        }
+        if (lines.size > 0) {
+            index.set(file.path, lines);
+        }
+    }
+    return index;
+}
 const DECISION_LABEL = {
     approve: 'Approve',
     approve_with_comments: 'Approve with comments',
@@ -30,19 +66,36 @@ function locationText(finding) {
     return finding.line != null ? `${finding.file}:${finding.line}` : finding.file;
 }
 /**
- * Render a finding's location as inline code, linked to the exact diff line in the
- * PR's "Files changed" tab when PR context is available. GitHub anchors each file's
- * diff as `diff-<sha256(path)>` and each right-hand (added/context) line as `…R<n>`.
+ * Render a finding's location as inline code, linked to the code it points at:
+ *  - in the diff (file+line shown in a hunk) → the PR's "Files changed" tab at that
+ *    line (`#diff-<sha256(path)>R<n>`), so the reader lands in the review diff;
+ *  - not in the diff (unchanged code the PR references, e.g. a caller/helper) → the
+ *    source blob on the PR base at that line (`/blob/<baseSha>/<path>#L<n>`);
+ *  - if neither is possible (no link context / no base SHA) → plain inline code.
+ * Never emits a dead diff anchor for a line that isn't in the diff.
  */
 function location(finding, link) {
     const text = locationText(finding);
     if (!link) {
         return `\`${text}\``;
     }
-    const fileHash = createHash('sha256').update(finding.file).digest('hex');
-    const anchor = finding.line != null ? `diff-${fileHash}R${finding.line}` : `diff-${fileHash}`;
-    const url = `https://github.com/${link.repo}/pull/${link.prNumber}/files#${anchor}`;
-    return `[\`${text}\`](${url})`;
+    const fileLines = link.diffLines?.get(finding.file);
+    // In the diff when the file is present and (if the finding names a line) that line
+    // is one of the diff's right-side lines. A file-level finding (no line) counts as
+    // in-diff as long as the file appears in the diff.
+    const inDiff = fileLines != null && (finding.line == null || fileLines.has(finding.line));
+    if (inDiff) {
+        const fileHash = createHash('sha256').update(finding.file).digest('hex');
+        const anchor = finding.line != null ? `diff-${fileHash}R${finding.line}` : `diff-${fileHash}`;
+        const url = `https://github.com/${link.repo}/pull/${link.prNumber}/files#${anchor}`;
+        return `[\`${text}\`](${url})`;
+    }
+    if (link.baseSha) {
+        const lineAnchor = finding.line != null ? `#L${finding.line}` : '';
+        const url = `https://github.com/${link.repo}/blob/${link.baseSha}/${finding.file}${lineAnchor}`;
+        return `[\`${text}\`](${url})`;
+    }
+    return `\`${text}\``;
 }
 /**
  * GitHub comment body. The marker + embedded state enable in-place updates and

package/build/core/verify.js

@@ -10,16 +10,46 @@ const VERIFY_TIMEOUT_MS = 3 * 60 * 1000;
 // Evidence shorter than this (normalized) is too weak to conclude "hallucinated".
 const MIN_EVIDENCE_LEN = 12;
 /**
- * Deterministic quote-grounding: does the finding's `evidence` snippet actually
- * appear in the file? Returns `unknown` (don't judge) when there's too little
- * evidence or the file can't be read (e.g. a base-ref checkout that lacks a
- * PR-added file), so we never drop a finding we couldn't actually check.
+ * Break `evidence` into normalized, substantive fragments for fuzzy matching:
+ * split on newlines AND ellipses (the model often elides with `…`/`...`), strip
+ * leading diff markers (`+`/`-`) and comment markers (`//`, `#`, `*`) it may have
+ * copied along, normalize, and keep only fragments long enough to be meaningful.
  */
-async function evidencePresence(finding, cwd) {
-    const evidence = normalizeCode(finding.evidence ?? '');
-    if (evidence.length < MIN_EVIDENCE_LEN) {
+export function evidenceFragments(evidence) {
+    return evidence
+        .split(/\r?\n|…|\.\.\./)
+        .map(line => line.replace(/^[+\-\s]*/, '').replace(/^(\/\/+|#+|\*+|\/\*)\s?/, ''))
+        .map(normalizeCode)
+        .filter(fragment => fragment.length >= MIN_EVIDENCE_LEN);
+}
+/**
+ * Does the finding's `evidence` correspond to code in the file?
+ *  - exact (whitespace-normalized) substring → 'present'
+ *  - else any substantive line/fragment present verbatim → 'present' (fuzzy: this
+ *    rescues cross-line quotes, ellipsis elisions, and copied comment/diff markers)
+ *  - a real quote that matches nothing → 'absent'
+ * Returns 'unknown' (don't judge) when evidence is too short to conclude anything
+ * or the file can't be read, so we never drop a finding we couldn't actually check.
+ * NOTE: 'absent' is NOT terminal — the caller escalates it to the LLM verifier
+ * rather than dropping, because an imperfect quote does not mean a false finding.
+ */
+export function matchEvidence(evidence, content) {
+    const normEvidence = normalizeCode(evidence);
+    if (normEvidence.length < MIN_EVIDENCE_LEN) {
+        return 'unknown';
+    }
+    const normContent = normalizeCode(content);
+    if (normContent.includes(normEvidence)) {
+        return 'present';
+    }
+    const fragments = evidenceFragments(evidence);
+    if (fragments.length === 0) {
         return 'unknown';
     }
+    return fragments.some(fragment => normContent.includes(fragment)) ? 'present' : 'absent';
+}
+/** Read the cited file and grade the evidence against it (see matchEvidence). */
+async function evidencePresence(finding, cwd) {
     let content;
     try {
         content = await readFile(path.resolve(cwd, finding.file), 'utf8');
@@ -27,67 +57,73 @@ async function evidencePresence(finding, cwd) {
     catch {
         return 'unknown';
     }
-    return normalizeCode(content).includes(evidence) ? 'present' : 'absent';
+    return matchEvidence(finding.evidence ?? '', content);
 }
 /**
- * Guard against hallucinated findings before they're surfaced:
- *  1. Quote-grounding (deterministic, all findings): drop any whose quoted
- *     `evidence` is definitively not in the file.
- *  2. Adversarial verify (LLM, criticals only): a skeptical pass re-reads the real
- *     file and must confirm the critical is genuine; refuted criticals are dropped.
- * Fails OPEN — if a verify call itself errors, the critical is kept (better a
- * possible false positive than hiding a real critical on an infra hiccup).
+ * Guard against hallucinated findings before they're surfaced, WITHOUT silently
+ * dropping real ones on an imperfect quote:
+ *  1. Quote-grounding (deterministic, all findings): grade each finding's `evidence`
+ *     against the file (exact + fuzzy — see matchEvidence).
+ *  2. LLM verify (adversarial, in parallel) runs for a finding when EITHER:
+ *       - its evidence is `absent` (any severity) — the quote isn't grounded, but
+ *         that alone doesn't make the finding false, so the verifier re-reads the
+ *         real file (and nearby files) and judges the underlying problem; or
+ *       - it's a `critical` (even if grounded) — a skeptical double-check.
+ *     A finding is dropped ONLY when the verifier refutes it. `present`/`unknown`
+ *     non-criticals are kept without an LLM call (the fast, cheap path).
+ * Fails OPEN — if a verify call itself errors, the finding is kept (better a
+ * possible false positive than hiding a real finding on an infra hiccup).
+ *
+ * This replaces the old "absent evidence → hard drop" rule, which was suppressing
+ * real findings whose natural evidence (a structural/absence bug, a cross-line
+ * quote, a slightly-wrong location) wasn't a verbatim substring.
  */
 export async function verifyFindings(handle, findings, cwd, onProgress) {
     const dropped = [];
     let cost = 0;
     const tokens = {};
-    // Phase 1 — quote-grounding for every finding.
+    // Phase 1 — deterministic quote-grounding for every finding.
     const checked = await Promise.all(findings.map(async (finding) => ({ finding, presence: await evidencePresence(finding, cwd) })));
-    const survivors = [];
+    // Decide which findings need an LLM check vs. can be kept directly.
+    const verdicts = new Map();
+    const toVerify = [];
     for (const { finding, presence } of checked) {
-        if (presence === 'absent') {
-            dropped.push({ finding, reason: 'quoted code not found in file (likely hallucinated)' });
-            onProgress?.(`  verify: dropped ${finding.severity} "${finding.title}" — quoted code not in ${finding.file}`);
+        if (presence === 'absent' || finding.severity === 'critical') {
+            toVerify.push({ finding, presence });
         }
         else {
-            survivors.push(finding);
+            verdicts.set(finding, 'keep'); // grounded (or uncheckable) non-critical
         }
     }
-    // Phase 2 — adversarial verify for surviving criticals, in parallel.
-    const refuted = new Set();
-    await Promise.all(survivors
-        .filter(finding => finding.severity === 'critical')
-        .map(async (finding, index) => {
+    // Phase 2 — LLM verify (parallel). Refuted → drop; verified or errored → keep.
+    await Promise.all(toVerify.map(async ({ finding, presence }, index) => {
         try {
             const { value, cost: verifyCost, tokens: verifyTokens } = await promptAndParse(handle, {
                 agent: VERIFIER_AGENT,
                 system: buildVerifierSystem(),
-                text: buildVerifierTask(finding),
+                text: buildVerifierTask(finding, { evidenceUngrounded: presence === 'absent' }),
                 title: `verify-${index}`,
                 maxWaitMs: VERIFY_TIMEOUT_MS,
                 finalizeOnTimeout: true,
             }, parseVerdict);
             cost += verifyCost;
             addTokenUsage(tokens, verifyTokens);
-            if (!value.verified) {
-                refuted.add(finding);
-                onProgress?.(`  verify: dropped critical "${finding.title}" — ${value.reason || 'refuted by verifier'}`);
+            if (value.verified) {
+                verdicts.set(finding, 'keep');
+            }
+            else {
+                verdicts.set(finding, 'drop');
+                dropped.push({ finding, reason: value.reason || 'refuted by verifier' });
+                onProgress?.(`  verify: dropped ${finding.severity} "${finding.title}" — ${value.reason || 'refuted by verifier'}`);
             }
         }
         catch (error) {
-            // Fail open: keep the critical if verification itself failed.
-            onProgress?.(`  verify: could not verify critical "${finding.title}" (${errorMessage(error)}); keeping it`);
+            // Fail open: keep the finding if verification itself failed.
+            verdicts.set(finding, 'keep');
+            onProgress?.(`  verify: could not verify "${finding.title}" (${errorMessage(error)}); keeping it`);
         }
     }));
-    const kept = [];
-    for (const finding of survivors) {
-        if (refuted.has(finding)) {
-            dropped.push({ finding, reason: 'refuted by verifier' });
-        }
-        else {
-            kept.push(finding);
-        }
-    }
+    // Preserve original order.
+    const kept = findings.filter(finding => verdicts.get(finding) === 'keep');
     return { kept, dropped, cost, tokens };
 }

package/build/reporters/github.js

@@ -2,7 +2,8 @@ import { writeFile, mkdtemp, rm } from 'node:fs/promises';
 import { tmpdir } from 'node:os';
 import path from 'node:path';
 import { run } from '../core/exec.js';
-import { commentMarker, parseReviewState, renderMarkdown } from '../core/render.js';
+import { parseUnifiedDiff } from '../core/diff.js';
+import { buildDiffLineIndex, commentMarker, parseReviewState, renderMarkdown } from '../core/render.js';
 import { fingerprintFinding } from '../core/schema.js';
 const MAINTAINER_ASSOCIATIONS = new Set(['OWNER', 'MEMBER', 'COLLABORATOR']);
 /**
@@ -33,11 +34,43 @@ export class GitHubReporter {
         const dismissed = existing
             ? (parseReviewState(existing.body, this.options.commentTag)?.dismissed ?? [])
             : [];
-        await this.upsertComment(renderMarkdown(review, this.options.commentTag, dismissed, this.linkContext()));
+        const link = await this.linkContextAsync();
+        await this.upsertComment(renderMarkdown(review, this.options.commentTag, dismissed, link));
     }
-    /** PR context for turning finding locations into diff-line links. */
-    linkContext() {
-        return { repo: this.options.repo, prNumber: this.options.prNumber };
+    /**
+     * PR context for turning finding locations into links: the set of lines actually
+     * in the diff (for in-diff findings → diff-anchor links) and the base commit SHA
+     * (for out-of-diff findings → source-blob links on the base). Both fetches fail
+     * soft — a missing piece just degrades to a plain-text location, never a dead link.
+     */
+    async linkContextAsync() {
+        const link = { repo: this.options.repo, prNumber: this.options.prNumber };
+        const prArgs = [String(this.options.prNumber), '--repo', this.options.repo];
+        const cwd = this.options.cwd;
+        await Promise.all([
+            (async () => {
+                try {
+                    const { stdout } = await run('gh', ['pr', 'diff', ...prArgs], { cwd });
+                    link.diffLines = buildDiffLineIndex(parseUnifiedDiff(stdout));
+                }
+                catch {
+                    // leave diffLines unset → in-diff findings degrade to plain text
+                }
+            })(),
+            (async () => {
+                try {
+                    const { stdout } = await run('gh', ['pr', 'view', ...prArgs, '--json', 'baseRefOid'], { cwd });
+                    const oid = JSON.parse(stdout).baseRefOid;
+                    if (oid) {
+                        link.baseSha = oid;
+                    }
+                }
+                catch {
+                    // leave baseSha unset → out-of-diff findings degrade to plain text
+                }
+            })(),
+        ]);
+        return link;
     }
     /**
      * Add or remove per-PR finding dismissals in the reviewer's comment and re-render
@@ -61,7 +94,8 @@ export class GitHubReporter {
                 dismissed.push({ fp, by, reason });
             }
         }
-        await this.patchComment(existing.id, renderMarkdown(state.review, this.options.commentTag, dismissed, this.linkContext()));
+        const link = await this.linkContextAsync();
+        await this.patchComment(existing.id, renderMarkdown(state.review, this.options.commentTag, dismissed, link));
         return { dismissedCount: dismissed.length, matched, unmatched };
     }
     /** Newest reviewer-tagged comment (id + body), or null if none posted yet. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@expo/code-review-cli",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "description": "Generic, config-driven AI code reviewer engine. Repos supply their agents via .expo-code-review/.",
   "license": "MIT",
   "repository": {

package/templates/shared.md

@@ -65,7 +65,7 @@ Return **only** a single fenced ```json code block, an object of this shape:
       "line": 142,
       "title": "short one-line summary",
       "rationale": "why this is a problem, with the concrete failure/exploit path",
-      "evidence": "the exact line(s) of code you are flagging, copied VERBATIM",
+      "evidence": "one contiguous line of the flagged code, copied VERBATIM",
       "suggestion": "optional concrete fix, or omit"
     }
   ]
@@ -73,7 +73,9 @@ Return **only** a single fenced ```json code block, an object of this shape:
 ```
 
 `line` is the start line in the new version of the file, or `null` if not
-line-specific. `evidence` MUST be the flagged code copied **verbatim** from the
-file — it is used to verify the finding, and a finding whose evidence isn't found
-in the file is discarded (don't paraphrase or invent it). If you have nothing to
-report, return `{ "findings": [] }`. Emit no prose outside the JSON block.
+line-specific. `evidence` is used to help verify the finding, so make it easy to
+locate: copy **one contiguous line** of the flagged code **verbatim** (not spanning
+multiple lines, no `…` elisions, no paraphrasing). For a structural/"missing" issue,
+quote the single most relevant real line (e.g. the early `return` that skips the
+handling). If you have nothing to report, return `{ "findings": [] }`. Emit no prose
+outside the JSON block.