@expo/code-review-cli 0.12.0 → 0.12.2

package/build/core/research.js

@@ -1,10 +1,20 @@
 // @ref LLP 0013#query-and-prompt-boundary [implements] — derive identifiers only; validate, bound, and sanitize MCP evidence
 // @ref LLP 0013#one-package-two-binaries [implements] — resolve the package-relative MCP entry instead of PATH/configured commands
+// @ref LLP 0013#research-provenance-and-citations [implements] — bounded query/result audit records plus exact citation grounding
 import { existsSync } from "node:fs";
+import { mkdtemp, rm, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
+import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { z } from "zod";
+import { readResearchAudit } from "../research-mcp/audit.js";
 import { run } from "./exec.js";
+export { OPENCODE_RESEARCH_TOOLS } from "./tools.js";
+export const RESEARCH_MCP_SERVER_NAME = "platform_docs";
+export const CLAUDE_RESEARCH_TOOLS = [
+    `mcp__${RESEARCH_MCP_SERVER_NAME}__search_platform_docs`,
+    `mcp__${RESEARCH_MCP_SERVER_NAME}__fetch_platform_doc`,
+];
 const APPLE_EXTENSIONS = /\.(?:swift|m|mm)$/i;
 const ANDROID_EXTENSIONS = /\.(?:kt|java|gradle|gradle\.kts)$/i;
 const REACT_NATIVE_EXTENSIONS = /\.(?:[cm]?[jt]sx?)$/i;
@@ -345,12 +355,13 @@ const ToolResultSchema = z.object({
 const SearchPayloadSchema = z.object({
     warnings: z.array(z.string().max(500)).max(10).optional(),
     results: z.array(z.object({
-        provider: z.string(),
-        sourceKind: z.string(),
-        title: z.string(),
-        url: z.string().url(),
-        passage: z.string(),
-        availability: z.array(z.string()).optional(),
+        id: z.string().min(1).max(240).optional(),
+        provider: z.string().min(1).max(80),
+        sourceKind: z.string().min(1).max(80),
+        title: z.string().min(1).max(500),
+        url: z.string().url().max(2_000),
+        passage: z.string().max(5_000),
+        availability: z.array(z.string().max(240)).max(20).optional(),
     })),
 });
 const RESEARCH_PROXY_ENV_KEYS = [
@@ -361,6 +372,7 @@ const RESEARCH_PROXY_ENV_KEYS = [
     "https_proxy",
     "no_proxy",
 ];
+const RESEARCH_SEARCH_API_KEY = "BRAVE_SEARCH_API_KEY";
 export function researchChildEnvironment(source = process.env) {
     const environment = {
         LANG: "C.UTF-8",
@@ -371,9 +383,12 @@ export function researchChildEnvironment(source = process.env) {
         if (source[key])
             environment[key] = source[key];
     }
+    if (source[RESEARCH_SEARCH_API_KEY]) {
+        environment[RESEARCH_SEARCH_API_KEY] = source[RESEARCH_SEARCH_API_KEY];
+    }
     return environment;
 }
-function bundledResearchServer() {
+export function bundledResearchServer() {
     const builtEntry = fileURLToPath(new URL("../research-mcp/cli.js", import.meta.url));
     const sourceEntry = fileURLToPath(new URL("../research-mcp/cli.ts", import.meta.url));
     return {
@@ -381,6 +396,92 @@ function bundledResearchServer() {
         args: [existsSync(builtEntry) ? builtEntry : sourceEntry],
     };
 }
+/**
+ * Create one owner-only MCP configuration and append-only audit for a review run.
+ * The model process receives only the config path; the Brave credential is passed
+ * directly to the bounded MCP child and never added to the model process env.
+ */
+export async function createResearchMcpRuntime(config) {
+    if (!config.enabled)
+        return undefined;
+    const directory = await mkdtemp(path.join(tmpdir(), "ecr-research-"));
+    const auditPath = path.join(directory, "audit.jsonl");
+    const claudeConfigPath = path.join(directory, "mcp.json");
+    const server = bundledResearchServer();
+    const args = [
+        ...server.args,
+        "serve",
+        ...(config.indexPath ? ["--index", config.indexPath] : []),
+    ];
+    const child = researchChildEnvironment();
+    const environment = Object.fromEntries(Object.entries({
+        ...child,
+        REVIEW_RESEARCH_AUDIT_PATH: auditPath,
+        REVIEW_RESEARCH_MAX_CALLS: String(config.maxQueries),
+        REVIEW_RESEARCH_MAX_RESULTS: String(config.resultsPerQuery),
+    }).flatMap(([key, value]) => (value === undefined ? [] : [[key, value]])));
+    await writeFile(claudeConfigPath, `${JSON.stringify({
+        mcpServers: {
+            [RESEARCH_MCP_SERVER_NAME]: {
+                type: "stdio",
+                command: server.command,
+                args,
+                env: environment,
+            },
+        },
+    })}\n`, { encoding: "utf8", mode: 0o600 });
+    return {
+        auditPath,
+        claudeConfigPath,
+        command: server.command,
+        args,
+        environment,
+        cleanup: () => rm(directory, { recursive: true, force: true }),
+    };
+}
+export async function researchProvenanceFromAudit(auditPath) {
+    const records = await readResearchAudit(auditPath);
+    const queries = [];
+    const evidence = [];
+    const warnings = [];
+    for (const record of records) {
+        const firstResult = record.results[0];
+        const platformValue = record.input.platform ?? firstResult?.platform ?? "react-native";
+        const platform = platformValue === "apple" || platformValue === "android" ? platformValue : "react-native";
+        const providers = record.input.providers ??
+            record.results.flatMap((result) => (result.provider ? [result.provider] : []));
+        const query = {
+            platform,
+            providers: [...new Set(providers)],
+            query: record.input.query ?? record.input.url ?? record.tool,
+        };
+        queries.push(query);
+        warnings.push(...record.warnings);
+        if (record.error)
+            warnings.push(`${record.tool}: ${record.error}`);
+        for (const result of record.results) {
+            if (!result.provider || !result.sourceKind)
+                continue;
+            evidence.push({
+                id: result.id,
+                query,
+                provider: result.provider,
+                sourceKind: result.sourceKind,
+                title: result.title,
+                url: result.url,
+                passage: result.passage,
+                ...(result.availability ? { availability: result.availability } : {}),
+            });
+        }
+    }
+    const run = {
+        queries,
+        evidence,
+        warnings: [...new Set(warnings)].slice(0, 10),
+        promptText: "",
+    };
+    return { provenance: toResearchProvenance(run), evidence };
+}
 function cleanEvidenceText(value, maxLength) {
     return (value
         .replace(/^\s*-{3,}\s*(?:BEGIN|END)\s+PLATFORM RESEARCH.*$/gim, "")
@@ -410,9 +511,127 @@ export function formatResearchEvidence(evidence) {
         .join("\n\n");
     return cleanEvidenceText(body, 16_000);
 }
+function researchQueryKey(query) {
+    return `${query.platform}\0${query.providers.join(",")}\0${query.query}`;
+}
+export function toResearchProvenance(run) {
+    return {
+        queries: run.queries,
+        results: run.evidence.map((item) => ({
+            ...(item.id ? { id: cleanEvidenceText(item.id, 240) } : {}),
+            query: item.query,
+            provider: cleanEvidenceText(item.provider, 80),
+            sourceKind: cleanEvidenceText(item.sourceKind, 80),
+            title: cleanEvidenceText(item.title, 240),
+            url: item.url,
+            passage: cleanEvidenceText(item.passage, 1_200),
+            ...(item.availability?.length
+                ? { availability: item.availability.map((value) => cleanEvidenceText(value, 240)) }
+                : {}),
+        })),
+        warnings: run.warnings.map((warning) => cleanEvidenceText(warning, 500)),
+    };
+}
+export function formatResearchProgress(provenance) {
+    const lines = [
+        `  research: ${provenance.results.length} result(s) from ${provenance.queries.length} bounded query(s)`,
+    ];
+    const byQuery = new Map();
+    for (const result of provenance.results) {
+        const key = researchQueryKey(result.query);
+        const bucket = byQuery.get(key) ?? [];
+        bucket.push(result);
+        byQuery.set(key, bucket);
+    }
+    for (const [index, query] of provenance.queries.entries()) {
+        lines.push(`  research query ${index + 1}/${provenance.queries.length} — ${query.platform} [${query.providers.join(", ")}]: ${cleanEvidenceText(query.query, 120)}`);
+        const results = byQuery.get(researchQueryKey(query)) ?? [];
+        if (results.length === 0) {
+            lines.push("    result: none");
+            continue;
+        }
+        for (const result of results) {
+            lines.push(`    result: ${cleanEvidenceText(result.title, 160)} (${result.provider}/${result.sourceKind}) — ${result.url}`);
+        }
+    }
+    for (const warning of provenance.warnings) {
+        lines.push(`  research warning: ${cleanEvidenceText(warning, 500)}`);
+    }
+    if (provenance.error) {
+        lines.push(`  research error: ${cleanEvidenceText(provenance.error, 500)}`);
+    }
+    return lines;
+}
+function escapeMarkdownLabel(value) {
+    return cleanEvidenceText(value, 240)
+        .replace(/&/g, "&")
+        .replace(/</g, "&lt;")
+        .replace(/>/g, "&gt;")
+        .replace(/([\\[\]])/g, "\\$1");
+}
+export function renderResearchMarkdown(provenance) {
+    const lines = [
+        "### 🔎 Documentation research",
+        "",
+        `${provenance.results.length} result(s) from ${provenance.queries.length} bounded query(s).`,
+        "",
+    ];
+    const byQuery = new Map();
+    for (const result of provenance.results) {
+        const key = researchQueryKey(result.query);
+        const bucket = byQuery.get(key) ?? [];
+        bucket.push(result);
+        byQuery.set(key, bucket);
+    }
+    for (const query of provenance.queries) {
+        lines.push(`- \`${cleanEvidenceText(query.query, 120)}\` — ${query.platform}; ${query.providers.join(", ")}`);
+        const results = byQuery.get(researchQueryKey(query)) ?? [];
+        if (results.length === 0) {
+            lines.push("  - _No allowlisted result._");
+            continue;
+        }
+        for (const result of results) {
+            lines.push(`  - [${escapeMarkdownLabel(result.title)}](<${result.url}>) — ${escapeMarkdownLabel(result.provider)}/${escapeMarkdownLabel(result.sourceKind)}`);
+        }
+    }
+    for (const warning of provenance.warnings) {
+        lines.push(`- ⚠️ ${escapeMarkdownLabel(warning)}`);
+    }
+    if (provenance.error) {
+        lines.push(`- ⚠️ Research failed: ${escapeMarkdownLabel(provenance.error)}`);
+    }
+    return lines.join("\n");
+}
+export function mergeResearchSources(...groups) {
+    const seen = new Set();
+    return groups
+        .flatMap((group) => group ?? [])
+        .filter((source) => {
+        if (seen.has(source.url))
+            return false;
+        seen.add(source.url);
+        return true;
+    })
+        .slice(0, 5);
+}
+/** Keep only exact URLs returned by the trusted research prepass and restore their canonical titles. */
+export function groundResearchSources(findings, evidence) {
+    const allowed = new Map(evidence.map((item) => [
+        item.url,
+        { title: cleanEvidenceText(item.title, 240), url: item.url },
+    ]));
+    return findings.map((finding) => {
+        const { sources: claimed, ...withoutSources } = finding;
+        const sources = mergeResearchSources(claimed?.flatMap((source) => {
+            const canonical = allowed.get(source.url);
+            return canonical ? [canonical] : [];
+        }));
+        return sources.length > 0 ? { ...withoutSources, sources } : withoutSources;
+    });
+}
 export async function collectPlatformResearch(files, config) {
     const queries = deriveResearchQueries(files, config.maxQueries);
-    if (!config.enabled || !config.indexPath || queries.length === 0) {
+    if (!config.enabled || queries.length === 0) {
         return { queries, evidence: [], warnings: [], promptText: "" };
     }
     const calls = queries.map((query, index) => ({
@@ -444,7 +663,11 @@ export async function collectPlatformResearch(files, config) {
         ...calls,
     ];
     const server = bundledResearchServer();
-    const serverArgs = [...server.args, "serve", "--index", config.indexPath];
+    const serverArgs = [
+        ...server.args,
+        "serve",
+        ...(config.indexPath ? ["--index", config.indexPath] : []),
+    ];
     const result = await run(server.command, serverArgs, {
         input: `${messages.map((message) => JSON.stringify(message)).join("\n")}\n`,
         cwd: tmpdir(),

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) {