@expo/code-review-cli 0.1.0

package/build/core/schema.js

@@ -0,0 +1,107 @@
+import { createHash } from 'node:crypto';
+import { z } from 'zod';
+import { normalizeCode } from './util.js';
+/** Severity levels, ordered most→least severe for sorting/rendering. */
+export const SEVERITIES = ['critical', 'warning', 'suggestion'];
+/** Sort rank for severities (0 = most severe). Single source of truth. */
+export const SEVERITY_RANK = { critical: 0, warning: 1, suggestion: 2 };
+export const CATEGORIES = ['correctness', 'quality', 'security', 'secrets'];
+export const DECISIONS = ['approve', 'approve_with_comments', 'request_changes'];
+export const FindingSchema = z.object({
+    severity: z.enum(SEVERITIES),
+    category: z.enum(CATEGORIES),
+    file: z.string(),
+    line: z.number().int().nullable().optional().default(null),
+    title: z.string(),
+    rationale: z.string(),
+    suggestion: z.string().optional(),
+    /**
+     * Verbatim snippet of the flagged code, copied from the file. Used to
+     * quote-ground the finding: if this text isn't actually present in the file,
+     * the finding is treated as hallucinated and dropped.
+     */
+    evidence: z.string().optional(),
+});
+/** A verifier's verdict on whether a finding is real (adversarial refute pass). */
+export const VerdictSchema = z.object({
+    verified: z.boolean(),
+    reason: z.string().default(''),
+});
+export function parseVerdict(text) {
+    return VerdictSchema.parse(extractJsonObject(text));
+}
+/** Shape each sub-reviewer must emit. */
+export const ReviewerOutputSchema = z.object({
+    findings: z.array(FindingSchema).default([]),
+});
+/** Mode-agnostic coordinator result; each Reporter decides how to render it. */
+export const CoordinatorOutputSchema = z.object({
+    decision: z.enum(DECISIONS),
+    findings: z.array(FindingSchema).default([]),
+    summary: z.string(),
+    /**
+     * Human-readable notes about reduced coverage (e.g. a review pass that hit its
+     * time limit and returned partial findings, or was skipped). Populated by the
+     * engine after coordination, not by the model. Reporters surface these so a
+     * cut-short review is never presented as complete.
+     */
+    incomplete: z.array(z.string()).default([]),
+});
+/** Minimum normalized evidence length to key a fingerprint on the code (below
+ * this we fall back to the title). */
+const MIN_FP_EVIDENCE_LEN = 12;
+/**
+ * Stable identifier for a finding — dedupes across re-reviews and is the key for
+ * dismissals. Excludes the line number (which shifts as a PR grows). Keys on the
+ * verbatim `evidence` snippet (v2) rather than the LLM-written `title`, which
+ * varies run-to-run and would make a dismissal silently lapse. When the flagged
+ * code later changes, the hash changes and the dismissal lapses — which is correct
+ * (you dismissed that code, not a blank check). Falls back to `title` only when
+ * there's too little evidence to key on.
+ */
+export function fingerprintFinding(finding) {
+    const evidence = normalizeCode(finding.evidence ?? '');
+    const key = evidence.length >= MIN_FP_EVIDENCE_LEN ? evidence : normalizeCode(finding.title);
+    const normalized = ['v2', finding.file, finding.category, key].join('|');
+    return createHash('sha1').update(normalized).digest('hex').slice(0, 12);
+}
+/**
+ * Extract the JSON payload from an LLM response. Prefers the last fenced
+ * ```json block; falls back to the outermost {...} span. Throws if neither
+ * parses.
+ */
+export function extractJsonObject(text) {
+    const fenceMatches = [...text.matchAll(/```(?:json)?\s*\n([\s\S]*?)```/gi)];
+    const candidates = [];
+    if (fenceMatches.length > 0) {
+        candidates.push(fenceMatches[fenceMatches.length - 1][1].trim());
+    }
+    const firstBrace = text.indexOf('{');
+    const lastBrace = text.lastIndexOf('}');
+    if (firstBrace !== -1 && lastBrace > firstBrace) {
+        candidates.push(text.slice(firstBrace, lastBrace + 1));
+    }
+    let lastError;
+    for (const candidate of candidates) {
+        try {
+            return JSON.parse(candidate);
+        }
+        catch (error) {
+            lastError = error;
+        }
+    }
+    throw new Error(`Could not extract JSON from model response: ${lastError instanceof Error ? lastError.message : String(lastError)}`);
+}
+/** The router's choice of which agent ids to run. */
+export const RouteOutputSchema = z.object({
+    agents: z.array(z.string()).default([]),
+});
+export function parseRouteOutput(text) {
+    return RouteOutputSchema.parse(extractJsonObject(text));
+}
+export function parseReviewerOutput(text) {
+    return ReviewerOutputSchema.parse(extractJsonObject(text));
+}
+export function parseCoordinatorOutput(text) {
+    return CoordinatorOutputSchema.parse(extractJsonObject(text));
+}

package/build/core/suppress.js

@@ -0,0 +1,60 @@
+import { readFile } from 'node:fs/promises';
+import path from 'node:path';
+const DIRECTIVE = 'expo-code-review-ignore';
+/**
+ * Deterministic backstop for the inline `expo-code-review-ignore` directive (which
+ * was previously prompt-only, i.e. honored only if the model chose to). Drops a
+ * finding when its flagged line — or the line just above it — carries the
+ * directive.
+ *
+ * Carve-out: NEVER suppress a `critical` or `secrets` finding this way. An author
+ * could otherwise hide a real vulnerability in their own PR by adding one comment
+ * line; those always surface, consistent with the shared-prompt invariant.
+ */
+export async function applyInlineIgnores(findings, cwd, onProgress) {
+    const kept = [];
+    const suppressed = [];
+    const cache = new Map();
+    for (const finding of findings) {
+        if (!(await hasDirectiveNear(finding, cwd, cache))) {
+            kept.push(finding);
+            continue;
+        }
+        if (finding.severity === 'critical' || finding.category === 'secrets') {
+            kept.push(finding);
+            onProgress?.(`  inline-ignore present but NOT honored for ${finding.severity}/${finding.category} "${finding.title}"`);
+        }
+        else {
+            suppressed.push(finding);
+            onProgress?.(`  suppressed "${finding.title}" via ${DIRECTIVE}`);
+        }
+    }
+    return { kept, suppressed };
+}
+async function hasDirectiveNear(finding, cwd, cache) {
+    if (finding.line == null) {
+        return false;
+    }
+    const lines = await readLines(finding.file, cwd, cache);
+    if (!lines) {
+        return false;
+    }
+    const idx = finding.line - 1; // 1-based → 0-based
+    const flagged = lines[idx] ?? '';
+    const above = idx > 0 ? (lines[idx - 1] ?? '') : '';
+    return flagged.includes(DIRECTIVE) || above.includes(DIRECTIVE);
+}
+async function readLines(file, cwd, cache) {
+    if (cache.has(file)) {
+        return cache.get(file);
+    }
+    let lines;
+    try {
+        lines = (await readFile(path.resolve(cwd, file), 'utf8')).split('\n');
+    }
+    catch {
+        lines = null;
+    }
+    cache.set(file, lines);
+    return lines;
+}

package/build/core/tools.js

@@ -0,0 +1,16 @@
+/** The OpenCode tool names the reviewer toggles. Single source of truth so the
+ * agent and coordinator tool maps can't drift apart. */
+export const TOOL_NAMES = [
+    'read',
+    'grep',
+    'glob',
+    'list',
+    'bash',
+    'write',
+    'edit',
+    'patch',
+];
+/** Build a full tool map with only the listed tools enabled. */
+export function toolMap(enabled) {
+    return Object.fromEntries(TOOL_NAMES.map(name => [name, enabled.includes(name)]));
+}

package/build/core/util.js

@@ -0,0 +1,11 @@
+export function sleep(ms) {
+    return new Promise(resolve => setTimeout(resolve, ms));
+}
+/** Extract a human-readable message from an unknown thrown value. */
+export function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+/** Collapse whitespace + lowercase — for tolerant code matching / fingerprinting. */
+export function normalizeCode(text) {
+    return text.replace(/\s+/g, ' ').trim().toLowerCase();
+}

package/build/core/verify.js

@@ -0,0 +1,93 @@
+import { readFile } from 'node:fs/promises';
+import path from 'node:path';
+import { parseVerdict } from './schema.js';
+import { addTokenUsage, promptAndParse, VERIFIER_AGENT } from './opencode.js';
+import { buildVerifierSystem, buildVerifierTask } from './prompts.js';
+import { errorMessage, normalizeCode } from './util.js';
+// Verification runs after coordination (a serial tail step); keep it short. It
+// runs criticals in parallel, so this bounds the added latency regardless of count.
+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.
+ */
+async function evidencePresence(finding, cwd) {
+    const evidence = normalizeCode(finding.evidence ?? '');
+    if (evidence.length < MIN_EVIDENCE_LEN) {
+        return 'unknown';
+    }
+    let content;
+    try {
+        content = await readFile(path.resolve(cwd, finding.file), 'utf8');
+    }
+    catch {
+        return 'unknown';
+    }
+    return normalizeCode(content).includes(evidence) ? 'present' : 'absent';
+}
+/**
+ * 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).
+ */
+export async function verifyFindings(handle, findings, cwd, onProgress) {
+    const dropped = [];
+    let cost = 0;
+    const tokens = {};
+    // Phase 1 — quote-grounding for every finding.
+    const checked = await Promise.all(findings.map(async (finding) => ({ finding, presence: await evidencePresence(finding, cwd) })));
+    const survivors = [];
+    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}`);
+        }
+        else {
+            survivors.push(finding);
+        }
+    }
+    // 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) => {
+        try {
+            const { value, cost: verifyCost, tokens: verifyTokens } = await promptAndParse(handle, {
+                agent: VERIFIER_AGENT,
+                system: buildVerifierSystem(),
+                text: buildVerifierTask(finding),
+                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'}`);
+            }
+        }
+        catch (error) {
+            // Fail open: keep the critical if verification itself failed.
+            onProgress?.(`  verify: could not verify critical "${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);
+        }
+    }
+    return { kept, dropped, cost, tokens };
+}

package/build/reporters/github.js

@@ -0,0 +1,166 @@
+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 { fingerprintFinding } from '../core/schema.js';
+const MAINTAINER_ASSOCIATIONS = new Set(['OWNER', 'MEMBER', 'COLLABORATOR']);
+/**
+ * Maintains exactly one PR comment, updating it in place across re-reviews (and
+ * cleaning up duplicates) so the review converges instead of churning. Runs the
+ * break-glass check first. Comment-only: never calls the review-state APIs.
+ */
+export class GitHubReporter {
+    options;
+    marker;
+    constructor(options) {
+        this.options = options;
+        this.marker = commentMarker(options.commentTag);
+    }
+    async checkBreakGlass() {
+        const comments = await this.fetchAllComments();
+        return comments.some(comment => typeof comment.body === 'string' &&
+            comment.body.includes(this.options.breakGlassMarker) &&
+            MAINTAINER_ASSOCIATIONS.has(comment.author_association ?? ''));
+    }
+    async postSkipNote() {
+        await this.upsertComment(`${this.marker}\n🤖 AI review skipped via \`${this.options.breakGlassMarker}\`.`);
+    }
+    async report(review) {
+        // Carry forward any per-PR dismissals recorded in the existing comment so they
+        // survive re-reviews (a dismissed finding stays in the collapsed section).
+        const existing = await this.findExistingComment();
+        const dismissed = existing
+            ? (parseReviewState(existing.body, this.options.commentTag)?.dismissed ?? [])
+            : [];
+        await this.upsertComment(renderMarkdown(review, this.options.commentTag, dismissed, this.linkContext()));
+    }
+    /** PR context for turning finding locations into diff-line links. */
+    linkContext() {
+        return { repo: this.options.repo, prNumber: this.options.prNumber };
+    }
+    /**
+     * Add or remove per-PR finding dismissals in the reviewer's comment and re-render
+     * it in place — no re-review needed (the comment embeds the full review state).
+     */
+    async applyDismissal(add, remove, by, reason) {
+        const existing = await this.findExistingComment();
+        if (!existing) {
+            throw new Error('No reviewer comment found on this PR yet — run a review first.');
+        }
+        const state = parseReviewState(existing.body, this.options.commentTag);
+        if (!state) {
+            throw new Error('The reviewer comment has no embedded state (posted before dismissals existed); re-run a review first.');
+        }
+        const validFps = new Set(state.review.findings.map(fingerprintFinding));
+        const matched = add.filter(fp => validFps.has(fp));
+        const unmatched = add.filter(fp => !validFps.has(fp));
+        let dismissed = state.dismissed.filter(record => !remove.includes(record.fp));
+        for (const fp of matched) {
+            if (!dismissed.some(record => record.fp === fp)) {
+                dismissed.push({ fp, by, reason });
+            }
+        }
+        await this.patchComment(existing.id, renderMarkdown(state.review, this.options.commentTag, dismissed, this.linkContext()));
+        return { dismissedCount: dismissed.length, matched, unmatched };
+    }
+    /** Newest reviewer-tagged comment (id + body), or null if none posted yet. */
+    async findExistingComment() {
+        const marked = (await this.fetchAllComments()).filter(comment => comment.body?.includes(this.marker));
+        const keep = marked[marked.length - 1];
+        return keep ? { id: keep.id, body: keep.body ?? '' } : null;
+    }
+    // Safety cap on pagination (100/page): 30 pages = 3000 comments. Bounds a
+    // pathological PR; virtually every real PR exits far earlier.
+    static MAX_COMMENT_PAGES = 30;
+    /**
+     * Fetch ALL issue comments, paginating manually (a single page's array is valid
+     * JSON; `--paginate` concatenates arrays into invalid JSON). The issue-comments
+     * endpoint does NOT honor `sort`/`direction`, so results come back oldest-first
+     * — we must page to the end to see the newest comments (our own prior comment or
+     * a recent `/skip-review` can otherwise fall outside a single 100-comment window,
+     * causing duplicate comments and missed break-glass).
+     */
+    async fetchAllComments() {
+        const all = [];
+        for (let page = 1; page <= GitHubReporter.MAX_COMMENT_PAGES; page++) {
+            const { stdout } = await run('gh', [
+                'api',
+                '-X',
+                'GET',
+                `repos/${this.options.repo}/issues/${this.options.prNumber}/comments`,
+                '-f',
+                'per_page=100',
+                '-f',
+                `page=${page}`,
+            ], { cwd: this.options.cwd });
+            let batch;
+            try {
+                batch = JSON.parse(stdout);
+            }
+            catch {
+                break;
+            }
+            if (!Array.isArray(batch) || batch.length === 0) {
+                break;
+            }
+            all.push(...batch);
+            if (batch.length < 100) {
+                break;
+            }
+        }
+        return all;
+    }
+    /**
+     * Update the reviewer's existing comment if present (deleting older duplicates),
+     * otherwise create it. Comments come back oldest-first, so the LAST marked one
+     * is the newest and is the keeper.
+     */
+    async upsertComment(body) {
+        const marked = (await this.fetchAllComments()).filter(comment => comment.body?.includes(this.marker));
+        if (marked.length === 0) {
+            await this.createComment(body);
+            return;
+        }
+        const keep = marked[marked.length - 1];
+        const duplicates = marked.slice(0, -1);
+        await this.patchComment(keep.id, body);
+        for (const duplicate of duplicates) {
+            await this.deleteComment(duplicate.id);
+        }
+    }
+    async withBodyFile(body, fn) {
+        const dir = await mkdtemp(path.join(tmpdir(), 'ecr-'));
+        const jsonPath = path.join(dir, 'comment.json');
+        try {
+            await writeFile(jsonPath, JSON.stringify({ body }), 'utf8');
+            return await fn(jsonPath);
+        }
+        finally {
+            await rm(dir, { recursive: true, force: true });
+        }
+    }
+    async createComment(body) {
+        await this.withBodyFile(body, jsonPath => run('gh', [
+            'api',
+            '-X',
+            'POST',
+            `repos/${this.options.repo}/issues/${this.options.prNumber}/comments`,
+            '--input',
+            jsonPath,
+        ], { cwd: this.options.cwd }));
+    }
+    async patchComment(commentId, body) {
+        await this.withBodyFile(body, jsonPath => run('gh', [
+            'api',
+            '-X',
+            'PATCH',
+            `repos/${this.options.repo}/issues/comments/${commentId}`,
+            '--input',
+            jsonPath,
+        ], { cwd: this.options.cwd }));
+    }
+    async deleteComment(commentId) {
+        await run('gh', ['api', '-X', 'DELETE', `repos/${this.options.repo}/issues/comments/${commentId}`], { cwd: this.options.cwd });
+    }
+}

package/build/reporters/reporter.js

@@ -0,0 +1 @@
+export {};

package/build/reporters/terminal.js

@@ -0,0 +1,93 @@
+import { decisionExitCode, decisionLabel, groupBySeverity, sortFindings, } from '../core/render.js';
+import { SEVERITIES } from '../core/schema.js';
+const ESC = '';
+const RESET = `${ESC}[0m`;
+const BOLD = `${ESC}[1m`;
+const DIM = `${ESC}[2m`;
+const COLORS = {
+    critical: `${ESC}[31m`,
+    warning: `${ESC}[33m`,
+    suggestion: `${ESC}[36m`,
+};
+const SEVERITY_LABEL = {
+    critical: 'CRITICAL',
+    warning: 'WARNING',
+    suggestion: 'SUGGESTION',
+};
+/**
+ * Prints a human-readable summary grouped by severity; honors --json; never
+ * contacts GitHub. Maps the decision to a process exit code so it works as a
+ * pre-push/pre-commit gate.
+ */
+export class TerminalReporter {
+    options;
+    color;
+    constructor(options = {}) {
+        this.options = options;
+        this.color = !options.json && Boolean(process.stdout.isTTY);
+    }
+    async report(review) {
+        if (this.options.json) {
+            process.stdout.write(`${JSON.stringify(review, null, 2)}\n`);
+        }
+        else {
+            // The review is the primary artifact → stdout (progress goes to stderr), so
+            // `ecr review > out.txt` captures the report and redirection works.
+            process.stdout.write(this.renderPretty(review));
+        }
+        process.exitCode = this.options.noFail ? 0 : decisionExitCode(review.decision);
+    }
+    renderPretty(review) {
+        const out = [''];
+        out.push(this.paint(BOLD, `AI code review — ${decisionLabel(review.decision)}`));
+        out.push(this.tally(review.findings), '');
+        out.push(review.summary, '');
+        if (review.incomplete.length > 0) {
+            out.push(this.paint(BOLD, '⏱️  Coverage note: some passes did not finish (partial coverage):'));
+            for (const note of review.incomplete) {
+                out.push(this.paint(DIM, `  - ${note}`));
+            }
+            out.push('');
+        }
+        if (review.findings.length === 0) {
+            out.push(this.paint(DIM, 'No findings.'), '');
+        }
+        else {
+            const groups = groupBySeverity(sortFindings(review.findings));
+            for (const severity of SEVERITIES) {
+                const findings = groups[severity];
+                if (findings.length === 0) {
+                    continue;
+                }
+                out.push(this.paint(`${BOLD}${COLORS[severity]}`, `${SEVERITY_LABEL[severity]} (${findings.length})`), '');
+                for (const finding of findings) {
+                    out.push(this.renderFinding(finding));
+                }
+            }
+        }
+        return `${out.join('\n')}\n`;
+    }
+    /** One-line count headline, e.g. "2 critical · 5 warning". */
+    tally(findings) {
+        const parts = SEVERITIES.map(severity => {
+            const n = findings.filter(finding => finding.severity === severity).length;
+            return n > 0 ? this.paint(COLORS[severity], `${n} ${severity}`) : null;
+        }).filter((part) => part !== null);
+        return parts.length > 0 ? parts.join(this.paint(DIM, ' · ')) : this.paint(DIM, 'no findings');
+    }
+    renderFinding(finding) {
+        const loc = finding.line != null ? `${finding.file}:${finding.line}` : finding.file;
+        const lines = [
+            `  ${finding.title} ${this.paint(DIM, `(${finding.category})`)}`,
+            `  ${this.paint(DIM, loc)}`,
+            `  ${finding.rationale}`,
+        ];
+        if (finding.suggestion) {
+            lines.push(`  ${this.paint(DIM, 'Suggestion:')} ${finding.suggestion}`);
+        }
+        return `${lines.join('\n')}\n`;
+    }
+    paint(codes, text) {
+        return this.color ? `${codes}${text}${RESET}` : text;
+    }
+}

package/build/sources/github-pr.js

@@ -0,0 +1,36 @@
+import { run } from '../core/exec.js';
+import { parseUnifiedDiff } from '../core/diff.js';
+/**
+ * Pulls PR diff + metadata through the `gh` CLI, which is preinstalled and
+ * authenticated on GitHub Actions runners via GH_TOKEN.
+ */
+export class GitHubPRSource {
+    options;
+    constructor(options) {
+        this.options = options;
+    }
+    repoArgs() {
+        return this.options.repo ? ['--repo', this.options.repo] : [];
+    }
+    async getMetadata() {
+        const { stdout } = await run('gh', [
+            'pr',
+            'view',
+            String(this.options.prNumber),
+            ...this.repoArgs(),
+            '--json',
+            'title,body,baseRefName,headRefName',
+        ], { cwd: this.options.cwd });
+        const parsed = JSON.parse(stdout);
+        return {
+            title: parsed.title ?? '',
+            body: parsed.body ?? '',
+            baseRef: parsed.baseRefName ?? '',
+            headRef: parsed.headRefName ?? '',
+        };
+    }
+    async getChangedFiles() {
+        const { stdout } = await run('gh', ['pr', 'diff', String(this.options.prNumber), ...this.repoArgs()], { cwd: this.options.cwd });
+        return parseUnifiedDiff(stdout);
+    }
+}