@expo/code-review-cli 0.12.1 → 0.12.3

package/build/core/review.js

@@ -18,7 +18,7 @@ import { errorMessage, sleep } from "./util.js";
 import { reviewSetupRefNotes } from "./config-refs.js";
 import { verifyFindings } from "./verify.js";
 import { applyInlineIgnores } from "./suppress.js";
-import { collectPlatformResearch } from "./research.js";
+import { boundResearchDecisions, createResearchMcpRuntime, formatResearchProgress, formatResearchUsefulness, groundResearchDecisions, groundResearchSources, mergeResearchSources, researchProvenanceFromAudit, renderResearchMarkdown, renderResearchUsefulnessMarkdown, summarizeResearchUsefulness, } from "./research.js";
 /**
  * Filter changed files down to an explicit include set (exact-path membership, not
  * globs — scope assignment already happened in resolveScopes). With no include set,
@@ -133,25 +133,8 @@ export async function runReview(source, options) {
         });
         return output;
     }
-    let researchText = "";
-    if (config.research.enabled) {
-        progress("Researching platform documentation from changed API identifiers…");
-        try {
-            const research = await collectPlatformResearch(kept, config.research);
-            researchText = research.promptText;
-            progress(research.queries.length === 0
-                ? "  research: no native platform identifiers found"
-                : `  research: ${research.evidence.length} passage(s) from ${research.queries.length} bounded query(s)`);
-            for (const warning of research.warnings) {
-                progress(`  research warning: ${warning}`);
-            }
-        }
-        catch (error) {
-            // Documentation is supporting evidence, not a prerequisite for reviewing the
-            // code. Fail open with a visible diagnostic; never weaken or skip the review.
-            progress(`  research unavailable; continuing without it (${errorMessage(error)})`);
-        }
-    }
+    let researchEvidence = [];
+    let researchRecord;
     // Materialize the PR-head tree (not the current checkout) when the source can, so
     // the agents' surrounding-source reads and the verifier's re-reads see the versions
     // that match the diff. Config is already fully loaded in memory, so the chdir below
@@ -208,6 +191,18 @@ export async function runReview(source, options) {
     for (const note of setupNotes) {
         progress(`  setup: ${note}`);
     }
+    let researchRuntime;
+    try {
+        researchRuntime = await createResearchMcpRuntime(config.research);
+        if (researchRuntime) {
+            progress(`Documentation MCP enabled for reviewer passes (${config.research.maxQueries} calls max; queries and results will be reported).`);
+        }
+    }
+    catch (error) {
+        await auth.cleanup();
+        await restoreCwd();
+        throw new Error(`Failed to prepare the documentation MCP: ${errorMessage(error)}`);
+    }
     const starting = [
         usesClaude ? "Claude Code engine" : null,
         usesOpencode ? "OpenCode server" : null,
@@ -221,23 +216,25 @@ export async function runReview(source, options) {
     let claudeHandle = null;
     try {
         if (usesOpencode) {
-            opencodeHandle = await startOpencode(buildOpencodeConfig(config));
+            opencodeHandle = await startOpencode(buildOpencodeConfig(config, researchRuntime));
         }
     }
     catch (error) {
         await auth.cleanup();
+        await researchRuntime?.cleanup();
         await restoreCwd();
         throw new Error(`Failed to start the OpenCode server. Ensure the \`opencode\` CLI is installed and ` +
             `model credentials are configured (\`ecr doctor\` checks both).\n${errorMessage(error)}`);
     }
     try {
         if (usesClaude) {
-            claudeHandle = await startClaudeCode(config);
+            claudeHandle = await startClaudeCode(config, researchRuntime);
         }
     }
     catch (error) {
         opencodeHandle?.close();
         await auth.cleanup();
+        await researchRuntime?.cleanup();
         await restoreCwd();
         throw new Error(`Failed to start the Claude Code engine. Ensure the \`claude\` CLI is installed and ` +
             `logged into a Max/Team subscription (\`ecr doctor\` checks both).\n${errorMessage(error)}`);
@@ -299,6 +296,7 @@ export async function runReview(source, options) {
     catch (error) {
         handle.close();
         await auth.cleanup();
+        await researchRuntime?.cleanup();
         await restoreCwd();
         throw error;
     }
@@ -309,6 +307,9 @@ export async function runReview(source, options) {
     // reviewers produced before the failure — partial findings are exactly what's
     // needed to debug a run that died mid-way.
     const agentFindings = {};
+    // Reviewer-declared, conclusion-only records of cases where documentation changed
+    // a concrete candidate decision. They remain inert until exact-source grounding.
+    const agentResearchDecisions = {};
     // Bounded, conclusion-only diagnostics for machine consumers of the hidden
     // comment state. These are deliberately separate from findings: they never reach
     // the coordinator, verification, policy, or decision paths.
@@ -319,6 +320,9 @@ export async function runReview(source, options) {
     // run log stay byte-identical (attribution is engine metadata, never sent to a model).
     // @ref LLP 0011#attribution-and-identity [constrained-by] — engine-set, excluded from fingerprintFinding, so attribution never re-keys a dismissal
     const agentByFp = new Map();
+    // Grounded source citations ride through coordinator rewrites by the same stable
+    // fingerprint. The model may select an injected source, but cannot invent its URL.
+    const sourcesByFp = new Map();
     // Every model request's usage lands in the run total AND its bucket, so the run
     // log can show cache effectiveness per pass and not just run-wide.
     const trackTokens = (bucket, tokens) => {
@@ -480,8 +484,8 @@ export async function runReview(source, options) {
         // smaller file set); a fallback task forbids tools and reviews the inlined diff.
         const buildTaskText = (task) => {
             const base = task.kind === "cross-cutting"
-                ? buildCrossCuttingTask(task.files, selectedAgents, filtered, { noTools: task.fallback }, options.contextText, researchText)
-                : buildReviewerTask(task.files, workspace.files, filtered, options.contextText, researchText);
+                ? buildCrossCuttingTask(task.files, selectedAgents, filtered, { noTools: task.fallback }, options.contextText, Boolean(researchRuntime) && !task.fallback)
+                : buildReviewerTask(task.files, workspace.files, filtered, options.contextText, Boolean(researchRuntime) && !task.fallback);
             return task.fallback ? `${base}\n\n${NO_TOOLS_INSTRUCTION}` : base;
         };
         const filesLabel = (files) => files.length === 1
@@ -520,6 +524,9 @@ export async function runReview(source, options) {
                 trackTokens(task.bucket, tokens);
                 trackModel(task.bucket, taskModel(task), model);
                 (agentFindings[task.bucket] ??= []).push(...value.findings);
+                if (value.researchDecisions) {
+                    (agentResearchDecisions[task.bucket] ??= []).push(...value.researchDecisions);
+                }
                 if (value.trace) {
                     mergeTraceNotes(agentTrace, task.bucket, value.trace);
                 }
@@ -616,6 +623,47 @@ export async function runReview(source, options) {
                 }
             }
         });
+        if (researchRuntime) {
+            try {
+                const audited = await researchProvenanceFromAudit(researchRuntime.auditPath);
+                researchRecord = audited.provenance;
+                researchEvidence = audited.evidence;
+                for (const line of formatResearchProgress(researchRecord))
+                    progress(line);
+                await appendStepSummary(renderResearchMarkdown(researchRecord));
+            }
+            catch (error) {
+                researchRecord = { queries: [], results: [], warnings: [], error: errorMessage(error) };
+                progress(`  research audit unavailable: ${researchRecord.error}`);
+            }
+        }
+        // Citations are accepted only when their exact canonical URL appeared in this
+        // run's MCP audit. This strips invented URLs even if a model copied a plausible
+        // official-looking address into its structured output.
+        for (const [bucket, findings] of Object.entries(agentFindings)) {
+            const grounded = groundResearchSources(findings, researchEvidence);
+            agentFindings[bucket] = grounded;
+            for (const finding of grounded) {
+                if (!finding.sources?.length)
+                    continue;
+                const fp = fingerprintFinding(finding);
+                sourcesByFp.set(fp, mergeResearchSources(sourcesByFp.get(fp), finding.sources));
+            }
+        }
+        if (researchRecord) {
+            const groundedDecisions = Object.entries(agentResearchDecisions).flatMap(([agent, records]) => groundResearchDecisions(records, researchEvidence, agent));
+            const { decisions, omitted } = boundResearchDecisions(groundedDecisions);
+            if (decisions.length > 0)
+                researchRecord = { ...researchRecord, decisions };
+            if (omitted > 0) {
+                const warning = `${omitted} grounded research decision(s) omitted by output bounds`;
+                researchRecord = {
+                    ...researchRecord,
+                    warnings: [...researchRecord.warnings, warning],
+                };
+                progress(`  research: ${warning}`);
+            }
+        }
         // A substituted model means the review did not run on the model this repo
         // configured — the findings may be from a weaker (or free-tier) model entirely.
         // Never silent: it goes to the log, the coverage notes, and the run log.
@@ -693,6 +741,12 @@ export async function runReview(source, options) {
                 : consolidated.decision;
             output = { ...consolidated, decision, incomplete: [...new Set(coverageNotes)] };
         }
+        // The coordinator remains model output. Revalidate every citation against the
+        // allowlisted prepass before verification, persistence, or rendering.
+        output = {
+            ...output,
+            findings: groundResearchSources(output.findings, researchEvidence),
+        };
         // Guard against hallucinated findings before surfacing: quote-ground every
         // finding against the real file, and adversarially verify criticals. This is
         // what stops a confident but wrong critical from shipping.
@@ -796,6 +850,17 @@ export async function runReview(source, options) {
         else if (output.decision !== decisionBeforeChecks) {
             output = { ...output, summary: reconcileRequalifiedSummary(output.summary) };
         }
+        // Carry a reviewer's grounded citations through a coordinator rewrite. A changed
+        // fingerprint fails closed, so the engine never guesses which source applies.
+        if (output.findings.length > 0) {
+            output = {
+                ...output,
+                findings: output.findings.map((finding) => {
+                    const sources = mergeResearchSources(finding.sources, sourcesByFp.get(fingerprintFinding(finding)));
+                    return sources.length > 0 ? { ...finding, sources } : finding;
+                }),
+            };
+        }
         // Attribution: carry each surviving finding's originating agent onto the output. The
         // coordinator merges and rewrites findings, so match by fingerprint and keep the
         // first agent that produced it; a finding the coordinator changed enough to break the
@@ -858,6 +923,15 @@ export async function runReview(source, options) {
                 progress(`Author-reply adjudication failed (${errorMessage(error)}); continuing without it.`);
             }
         }
+        // Measure utility only after verification, suppression, citation carry-through,
+        // and feedback adjudication have produced the final finding set. Counts use
+        // unique audited URLs, not passages, so duplicate search hits cannot inflate them.
+        if (researchRecord) {
+            const usefulness = summarizeResearchUsefulness(researchRecord, output.findings);
+            researchRecord = { ...researchRecord, usefulness };
+            progress(formatResearchUsefulness(usefulness));
+            await appendStepSummary(renderResearchUsefulnessMarkdown(researchRecord));
+        }
         // Surface provider throttling as a fact about the run: passes already waited or
         // backed off, but the operator should still SEE that it happened (a run that
         // was rate-limited is slower and may carry partial passes — that's the cause).
@@ -891,6 +965,7 @@ export async function runReview(source, options) {
         const reviewTrace = buildReviewTrace(agentTrace);
         await safeLog(logPath, {
             ...baseRecord,
+            ...(researchRecord ? { research: researchRecord } : {}),
             agentCosts,
             totalCost: sum(agentCosts),
             tokens: tokenTotals,
@@ -927,6 +1002,7 @@ export async function runReview(source, options) {
     catch (error) {
         await safeLog(logPath, {
             ...baseRecord,
+            ...(researchRecord ? { research: researchRecord } : {}),
             agentCosts,
             totalCost: sum(agentCosts),
             tokens: tokenTotals,
@@ -944,6 +1020,7 @@ export async function runReview(source, options) {
     finally {
         handle.close();
         await auth.cleanup();
+        await researchRuntime?.cleanup();
         await restoreCwd();
     }
 }

package/build/core/schema.js

@@ -1,4 +1,5 @@
 // @ref LLP 0005#finding-identity-fingerprints
+// @ref LLP 0013#research-provenance-and-citations [implements] — optional citations are annotations, not finding identity or decision inputs
 import { createHash } from "node:crypto";
 import { z } from "zod";
 import { normalizeCode } from "./util.js";
@@ -8,6 +9,25 @@ export const SEVERITIES = ["critical", "warning", "suggestion"];
 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 FindingSourceSchema = z.object({
+    title: z.string().min(1).max(240),
+    url: z
+        .string()
+        .url()
+        .max(2_000)
+        .refine((value) => new URL(value).protocol === "https:", "source URL must use HTTPS"),
+});
+export const RESEARCH_DECISION_OUTCOMES = ["supported-finding", "dismissed-candidate"];
+/**
+ * A reviewer-declared decision that documentation materially changed. Sources are
+ * later grounded against the MCP audit exactly like finding citations; an ungrounded
+ * record is discarded and can never inflate usefulness metrics.
+ */
+export const ResearchDecisionSchema = z.object({
+    outcome: z.enum(RESEARCH_DECISION_OUTCOMES),
+    summary: z.string().min(1).max(240),
+    sources: z.array(FindingSourceSchema).min(1).max(5),
+});
 export const FindingSchema = z.object({
     severity: z.enum(SEVERITIES),
     category: z.enum(CATEGORIES),
@@ -16,6 +36,11 @@ export const FindingSchema = z.object({
     title: z.string(),
     rationale: z.string(),
     suggestion: z.string().optional(),
+    sources: z
+        .array(FindingSourceSchema)
+        .max(5)
+        .optional()
+        .describe("Exact documentation sources used to support this finding; copy the returned title and canonical URL from this review's MCP results and omit when unused"),
     /**
      * 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,
@@ -111,6 +136,7 @@ export const ReviewerTraceNotesSchema = z.object({
 const ReviewerModelOutputSchema = z.object({
     findings: z.array(ModelFindingSchema).default([]),
     trace: ReviewerTraceNotesSchema.optional(),
+    researchDecisions: z.array(ResearchDecisionSchema).max(8).optional(),
 });
 /**
  * Local trust boundary for reviewer output. Findings stay strict, while diagnostics
@@ -121,12 +147,18 @@ export const ReviewerOutputSchema = z
     .object({
     findings: z.array(ModelFindingSchema).default([]),
     trace: z.unknown().optional(),
+    researchDecisions: z.unknown().optional(),
 })
     .transform((output) => {
     const trace = ReviewerTraceNotesSchema.safeParse(output.trace);
+    const researchDecisions = z
+        .array(ResearchDecisionSchema)
+        .max(8)
+        .safeParse(output.researchDecisions);
     return {
         findings: output.findings,
         ...(trace.success ? { trace: trace.data } : {}),
+        ...(researchDecisions.success ? { researchDecisions: researchDecisions.data } : {}),
     };
 });
 export const ReviewTraceSchema = z.object({

package/build/core/tools.js

@@ -1,5 +1,9 @@
 /** The OpenCode tool names the reviewer toggles. Single source of truth so the
  * agent and coordinator tool maps can't drift apart. */
+export const OPENCODE_RESEARCH_TOOLS = [
+    "platform_docs_search_platform_docs",
+    "platform_docs_fetch_platform_doc",
+];
 export const TOOL_NAMES = [
     "read",
     "grep",
@@ -9,6 +13,7 @@ export const TOOL_NAMES = [
     "write",
     "edit",
     "patch",
+    ...OPENCODE_RESEARCH_TOOLS,
 ];
 /** Build a full tool map with only the listed tools enabled. */
 export function toolMap(enabled) {

package/build/research-mcp/audit.js

@@ -0,0 +1,170 @@
+import { appendFile, mkdir, readFile, rmdir } from "node:fs/promises";
+import { randomUUID } from "node:crypto";
+const LOCK_RETRIES = 200;
+const LOCK_DELAY_MS = 10;
+const MAX_AUDITED_PASSAGE_CHARACTERS = 20_000;
+function delay(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+function boundedError(error) {
+    const message = error instanceof Error ? error.message : String(error);
+    // oxlint-disable-next-line no-control-regex -- audit lines must stay single-line JSONL
+    return message.replace(/[\r\n\u0000-\u001f\u007f]+/g, " ").slice(0, 500);
+}
+function boundedResult(result) {
+    return {
+        id: result.id.slice(0, 240),
+        platform: result.platform,
+        provider: result.provider,
+        sourceKind: result.sourceKind,
+        title: result.title.slice(0, 240),
+        url: result.url.slice(0, 2_000),
+        // This equals the direct-fetch document ceiling, so the artifact preserves the
+        // exact bounded text shown to the reviewer without ever storing the raw page.
+        passage: result.passage.slice(0, MAX_AUDITED_PASSAGE_CHARACTERS),
+        ...(result.availability?.length
+            ? { availability: result.availability.slice(0, 20).map((value) => value.slice(0, 240)) }
+            : {}),
+        ...(result.framework ? { framework: result.framework.slice(0, 240) } : {}),
+        ...(result.language ? { language: result.language } : {}),
+        ...(result.symbol ? { symbol: result.symbol.slice(0, 240) } : {}),
+        ...(result.previousPassageId
+            ? { previousPassageId: result.previousPassageId.slice(0, 240) }
+            : {}),
+        ...(result.nextPassageId ? { nextPassageId: result.nextPassageId.slice(0, 240) } : {}),
+    };
+}
+/** Shared append-only audit and global request budget for all MCP processes in one review. */
+export class ResearchAudit {
+    path;
+    maxCalls;
+    localReservations = 0;
+    constructor(path, maxCalls) {
+        this.path = path;
+        this.maxCalls = maxCalls;
+    }
+    async append(event) {
+        if (!this.path)
+            return;
+        await appendFile(this.path, `${JSON.stringify(event)}\n`, { encoding: "utf8", mode: 0o600 });
+    }
+    async withLock(callback) {
+        if (!this.path)
+            return callback();
+        const lockPath = `${this.path}.lock`;
+        for (let attempt = 0; attempt < LOCK_RETRIES; attempt++) {
+            try {
+                await mkdir(lockPath, { mode: 0o700 });
+                try {
+                    return await callback();
+                }
+                finally {
+                    await rmdir(lockPath).catch(() => { });
+                }
+            }
+            catch (error) {
+                if (error.code !== "EEXIST")
+                    throw error;
+                await delay(LOCK_DELAY_MS);
+            }
+        }
+        throw new Error("Documentation research audit lock timed out");
+    }
+    async reservationCount() {
+        if (!this.path)
+            return this.localReservations;
+        let contents = "";
+        try {
+            contents = await readFile(this.path, "utf8");
+        }
+        catch (error) {
+            if (error.code !== "ENOENT")
+                throw error;
+        }
+        return contents.split("\n").reduce((count, line) => {
+            if (!line)
+                return count;
+            try {
+                return JSON.parse(line).type === "reserved" ? count + 1 : count;
+            }
+            catch {
+                return count;
+            }
+        }, 0);
+    }
+    async reserve(tool, input) {
+        const requestId = randomUUID();
+        await this.withLock(async () => {
+            const used = await this.reservationCount();
+            if (used >= this.maxCalls) {
+                throw new Error(`Documentation research call budget exhausted (${this.maxCalls})`);
+            }
+            if (!this.path)
+                this.localReservations++;
+            await this.append({
+                type: "reserved",
+                requestId,
+                tool,
+                input,
+                timestamp: new Date().toISOString(),
+            });
+        });
+        return requestId;
+    }
+    async complete(requestId, tool, input, results, warnings = []) {
+        await this.append({
+            type: "completed",
+            requestId,
+            tool,
+            input,
+            results: results.map(boundedResult),
+            warnings: warnings.slice(0, 10).map((warning) => warning.slice(0, 500)),
+            timestamp: new Date().toISOString(),
+        });
+    }
+    async fail(requestId, tool, input, error) {
+        await this.append({
+            type: "failed",
+            requestId,
+            tool,
+            input,
+            error: boundedError(error),
+            timestamp: new Date().toISOString(),
+        });
+    }
+}
+export async function readResearchAudit(path) {
+    let contents = "";
+    try {
+        contents = await readFile(path, "utf8");
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return [];
+        throw error;
+    }
+    const records = [];
+    for (const line of contents.split("\n")) {
+        if (!line)
+            continue;
+        try {
+            const event = JSON.parse(line);
+            if (event.type === "completed")
+                records.push(event);
+            if (event.type === "failed") {
+                records.push({
+                    requestId: event.requestId,
+                    tool: event.tool,
+                    input: event.input,
+                    results: [],
+                    warnings: [],
+                    error: event.error,
+                });
+            }
+        }
+        catch {
+            // Ignore a partial final line from a process that was terminated mid-write.
+        }
+    }
+    return records;
+}

package/build/research-mcp/brave-search.js

@@ -1,4 +1,5 @@
 import { z } from "zod";
+import { sanitizeDocumentationQuery } from "./query-sanitizer.js";
 import { readBodyWithLimit } from "./response.js";
 const BRAVE_SEARCH_ENDPOINT = "https://api.search.brave.com/res/v1/web/search";
 const BRAVE_RESPONSE_LIMIT_BYTES = 1_000_000;
@@ -16,18 +17,8 @@ const braveResponseSchema = z.object({
     })
         .optional(),
 });
-function normalizeSearchText(value) {
-    return (value
-        // oxlint-disable-next-line no-control-regex -- outbound query sanitization
-        .replace(/[\u0000-\u001f\u007f]/g, " ")
-        .replace(/\s+/g, " ")
-        .trim());
-}
 export function buildScopedSearchQuery(query, scopes) {
-    const normalized = normalizeSearchText(query);
-    if (!normalized || normalized.length > 300) {
-        throw new Error("Query must contain between 1 and 300 visible characters");
-    }
+    const normalized = sanitizeDocumentationQuery(query);
     if (scopes.length === 0 || scopes.length > 8) {
         throw new Error("A documentation search requires between 1 and 8 fixed scopes");
     }

package/build/research-mcp/cli.js

@@ -16,10 +16,22 @@ Usage:
 
 The serve command uses BRAVE_SEARCH_API_KEY for scoped web discovery, fetches only
 allowlisted official pages, and optionally falls back to a local index. Expo-provider
-searches use Expo's public documentation index. The update command is an optional
-offline crawler for operator-managed fallback indexes.
+searches use Expo's public documentation index. Its fetch_platform_doc tool can fetch
+one exact allowlisted documentation URL without a search key and return focused,
+section, or bounded-document extracted context. The update command is
+an optional offline crawler for operator-managed fallback indexes.
 `);
 }
+function boundedInteger(name, fallback, minimum, maximum) {
+    const raw = process.env[name];
+    if (!raw)
+        return fallback;
+    const value = Number(raw);
+    if (!Number.isInteger(value) || value < minimum || value > maximum) {
+        throw new Error(`${name} must be an integer from ${minimum} to ${maximum}`);
+    }
+    return value;
+}
 async function main() {
     const [command = "serve", ...rest] = process.argv.slice(2);
     if (command === "--help" || command === "-h" || command === "help") {
@@ -41,6 +53,11 @@ async function main() {
         const indexPath = values.index ?? process.env.REVIEW_RESEARCH_INDEX_PATH;
         await runStdioServer({
             ...(indexPath ? { indexPath } : {}),
+            ...(process.env.REVIEW_RESEARCH_AUDIT_PATH
+                ? { auditPath: process.env.REVIEW_RESEARCH_AUDIT_PATH }
+                : {}),
+            maxCalls: boundedInteger("REVIEW_RESEARCH_MAX_CALLS", 8, 1, 20),
+            maxResultsPerCall: boundedInteger("REVIEW_RESEARCH_MAX_RESULTS", 3, 1, 3),
             ...(process.env.BRAVE_SEARCH_API_KEY
                 ? { braveApiKey: process.env.BRAVE_SEARCH_API_KEY }
                 : {}),