@expo/code-review-cli 0.12.1 → 0.12.2

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 { createResearchMcpRuntime, formatResearchProgress, groundResearchSources, mergeResearchSources, researchProvenanceFromAudit, renderResearchMarkdown, } 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;
     }
@@ -319,6 +317,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 +481,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
@@ -616,6 +617,33 @@ 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));
+            }
+        }
         // 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 +721,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 +830,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
@@ -891,6 +936,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 +973,7 @@ export async function runReview(source, options) {
     catch (error) {
         await safeLog(logPath, {
             ...baseRecord,
+            ...(researchRecord ? { research: researchRecord } : {}),
             agentCosts,
             totalCost: sum(agentCosts),
             tokens: tokenTotals,
@@ -944,6 +991,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,14 @@ 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 FindingSchema = z.object({
     severity: z.enum(SEVERITIES),
     category: z.enum(CATEGORIES),
@@ -16,6 +25,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 title and URL from the injected research evidence 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,

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,163 @@
+import { appendFile, mkdir, readFile, rmdir } from "node:fs/promises";
+import { randomUUID } from "node:crypto";
+const LOCK_RETRIES = 200;
+const LOCK_DELAY_MS = 10;
+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),
+        passage: result.passage.slice(0, 1_400),
+        ...(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) } : {}),
+    };
+}
+/** 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,21 @@ 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. 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 +52,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 }
                 : {}),

package/build/research-mcp/direct-fetch.js

@@ -0,0 +1,100 @@
+import { fetchDocumentationDocument } from "./fetch-document.js";
+import { chunkDocument } from "./html.js";
+import { getProvider, resolveAllowedUrl } from "./providers.js";
+import { assertSafeDocumentationUrlShape } from "./query-sanitizer.js";
+import { buildSearchIndex, searchDocumentation } from "./search-index.js";
+/** Specific corpora precede their broader host/path parents during URL inference. */
+const DIRECT_PROVIDER_ORDER = [
+    "apple-releases",
+    "apple",
+    "swift-evolution",
+    "android-releases",
+    "media3",
+    "agp",
+    "android",
+    "glide",
+    "okhttp",
+    "kotlin-coroutines",
+    "gradle",
+    "jetbrains-issues",
+    "react-native-reanimated",
+    "react-native-gesture-handler",
+    "react-native-screens",
+    "react-native-worklets",
+    "react-native",
+    "expo",
+];
+const DIRECT_SOURCE_KIND = {
+    apple: "official-api",
+    "apple-releases": "release-notes",
+    "swift-evolution": "official-guide",
+    android: "official-api",
+    "android-releases": "release-notes",
+    media3: "official-guide",
+    glide: "official-guide",
+    okhttp: "official-guide",
+    "kotlin-coroutines": "official-guide",
+    gradle: "official-guide",
+    agp: "release-notes",
+    "jetbrains-issues": "issue-tracker",
+    expo: "official-api",
+    "react-native": "official-api",
+    "react-native-reanimated": "official-guide",
+    "react-native-gesture-handler": "official-guide",
+    "react-native-screens": "official-guide",
+    "react-native-worklets": "official-guide",
+};
+/** Resolve a caller-supplied URL against the fixed provider allowlist. */
+export function resolveDirectDocumentationTarget(rawUrl, providerHint) {
+    assertSafeDocumentationUrlShape(rawUrl);
+    const candidates = providerHint ? [providerHint] : DIRECT_PROVIDER_ORDER;
+    for (const providerId of candidates) {
+        const provider = getProvider(providerId);
+        try {
+            return {
+                provider: providerId,
+                sourceKind: DIRECT_SOURCE_KIND[providerId],
+                url: resolveAllowedUrl(provider, rawUrl),
+            };
+        }
+        catch {
+            // Try the next fixed provider. No caller-controlled host is ever admitted.
+        }
+    }
+    throw new Error(providerHint
+        ? `URL is outside the ${providerHint} documentation allowlist`
+        : "URL is outside the supported documentation allowlist");
+}
+/** Fetch one allowlisted documentation URL and return bounded extracted passages. */
+export async function fetchDocumentationUrl(rawUrl, options = {}) {
+    const target = resolveDirectDocumentationTarget(rawUrl, options.provider);
+    const provider = getProvider(target.provider);
+    const document = await fetchDocumentationDocument(provider, target.url.href, target.sourceKind, options.fetchImplementation ?? fetch);
+    if (!document) {
+        throw new Error(`No readable documentation content at ${target.url.href}`);
+    }
+    const indexedAt = new Date().toISOString();
+    const chunks = chunkDocument(document, indexedAt);
+    const limit = Math.min(5, Math.max(1, options.limit ?? 3));
+    let results;
+    if (options.query?.trim()) {
+        const index = buildSearchIndex(chunks, 1, indexedAt);
+        results = searchDocumentation(index, options.query, {
+            platform: document.platform,
+            providers: [target.provider],
+            limit,
+        });
+        if (results.length === 0) {
+            results = chunks.slice(0, limit).map((chunk) => ({ ...chunk, score: 0 }));
+        }
+    }
+    else {
+        results = chunks.slice(0, limit).map((chunk) => ({ ...chunk, score: 0 }));
+    }
+    return {
+        provider: target.provider,
+        sourceKind: target.sourceKind,
+        canonicalUrl: target.url.href,
+        results,
+    };
+}