@expo/code-review-cli 0.12.3 → 0.12.5

package/build/core/review.js

@@ -754,25 +754,43 @@ export async function runReview(source, options) {
         const findingCountBeforeChecks = output.findings.length;
         const decisionBeforeChecks = output.decision;
         let verifierDropped = [];
+        // Citations the verifier stripped from kept findings, persisted to the run
+        // log so the removal reason stays auditable — mirrors verifierDropped.
+        let citationStrips = [];
         // Stripped requalifications (finding + reason), persisted to the run log so the
         // stack-aware decision trail is auditable after the fact — mirrors verifierDropped.
         const requalificationStrips = [];
         if (output.findings.length > 0) {
             progress("Verifying findings…");
-            const verification = await verifyFindings(handle, output.findings, process.cwd(), progress);
+            const verification = await verifyFindings(handle, output.findings, process.cwd(), progress, researchEvidence);
             agentCosts["verifier"] = verification.cost;
             trackTokens("verifier", verification.tokens);
             // Mirrors buildOpencodeConfig, which gives the verifier the first agent's model.
             trackModel("verifier", config.agents[0]?.model ?? config.coordinator.model, verification.model);
             verifierDropped = verification.dropped;
-            if (verification.dropped.length > 0) {
-                progress(`Verification dropped ${verification.dropped.length} unverified finding(s).`);
+            citationStrips = verification.citationStripped;
+            if (verification.dropped.length > 0 || verification.citationStripped.length > 0) {
+                if (verification.dropped.length > 0) {
+                    progress(`Verification dropped ${verification.dropped.length} unverified finding(s).`);
+                }
                 output = {
                     ...output,
                     findings: verification.kept,
-                    decision: decisionAfterVerification(output.decision, verification.kept),
+                    // Re-derive the decision ONLY when findings were dropped. A citation
+                    // strip keeps every finding, and decisionAfterVerification would
+                    // downgrade a criticals-free request_changes to approve_with_comments —
+                    // a blocking review must not stop blocking because a link was removed.
+                    decision: verification.dropped.length > 0
+                        ? decisionAfterVerification(output.decision, verification.kept)
+                        : output.decision,
                 };
             }
+            // The verifier judged these citations unsupportive. Remove the
+            // fingerprint-carried copies too, or the post-coordination merge below
+            // would silently restore the stripped sources.
+            for (const stripped of verification.citationStripped) {
+                sourcesByFp.delete(fingerprintFinding(stripped.finding));
+            }
         }
         // Stack-aware requalification grounding (deterministic, zero LLM): strip any
         // `requalifiedBy` the coordinator wrote that is forged, hallucinated, or touches a
@@ -976,6 +994,7 @@ export async function runReview(source, options) {
             coverageNotes,
             verifierDropped,
             requalificationStrips,
+            citationStrips,
             ...(rlTotal > 0
                 ? {
                     rateLimitEvents: rlTotal,

package/build/core/schema.js

@@ -90,6 +90,12 @@ export function isOverallRiskHandoff(finding) {
 export const VerdictSchema = z.object({
     verified: z.boolean(),
     reason: z.string().default(""),
+    /**
+     * Only requested when the finding cites research: whether the cited passages
+     * genuinely support the finding's external-behavior claim. `false` strips the
+     * citation while the finding itself stands or falls on `verified`.
+     */
+    citationSupported: z.boolean().optional(),
 });
 /**
  * A stack verifier's verdict on whether a later stacked PR's patch actually

package/build/core/verify.js

@@ -12,6 +12,17 @@ import { errorMessage, normalizeCode } from "./util.js";
 const VERIFY_TIMEOUT_MS = 3 * 60 * 1000;
 // Evidence shorter than this (normalized) is too weak to conclude "hallucinated".
 const MIN_EVIDENCE_LEN = 12;
+/** The audited passages behind a finding's grounded citations, bounded per source. */
+function citedSourcesFor(finding, evidence) {
+    if (!finding.sources?.length || evidence.length === 0)
+        return undefined;
+    const byUrl = new Map(evidence.map((item) => [item.url, item]));
+    const cited = finding.sources.flatMap((source) => {
+        const match = byUrl.get(source.url);
+        return match ? [{ title: match.title, url: match.url, passage: match.passage }] : [];
+    });
+    return cited.length > 0 ? cited : undefined;
+}
 // @ref LLP 0005#evidence-grounding-escalate-never-hard-drop [implements] — exact-substring is a good positive but poor negative signal (33a970a revert)
 /**
  * Break `evidence` into normalized, substantive fragments for fuzzy matching:
@@ -95,31 +106,43 @@ async function evidencePresence(finding, cwd) {
  * real findings whose natural evidence (a structural/absence bug, a cross-line
  * quote, a slightly-wrong location) wasn't a verbatim substring.
  */
-export async function verifyFindings(handle, findings, cwd, onProgress) {
+export async function verifyFindings(handle, findings, cwd, onProgress, 
+/** This run's audited research evidence, for findings that cite documentation. */
+researchEvidence = []) {
     const dropped = [];
+    const citationStripped = [];
+    // Kept findings the verifier rewrote (currently only citation removal).
+    const replacements = new Map();
     let cost = 0;
     let model;
     const tokens = {};
     // Phase 1 — deterministic quote-grounding for every finding.
     const checked = await Promise.all(findings.map(async (finding) => ({ finding, presence: await evidencePresence(finding, cwd) })));
-    // Decide which findings need an LLM check vs. can be kept directly.
+    // Decide which findings need an LLM check vs. can be kept directly. A finding
+    // that cites documentation always gets an LLM check: the repo alone cannot
+    // confirm an external-behavior claim, and the verifier must judge whether the
+    // cited passages support it rather than fall back to model memory.
     const verdicts = new Map();
     const toVerify = [];
     for (const { finding, presence } of checked) {
-        if (presence === "absent" || finding.severity === "critical") {
-            toVerify.push({ finding, presence });
+        const citedSources = citedSourcesFor(finding, researchEvidence);
+        if (presence === "absent" || finding.severity === "critical" || citedSources) {
+            toVerify.push({ finding, presence, ...(citedSources ? { citedSources } : {}) });
         }
         else {
             verdicts.set(finding, "keep"); // grounded (or uncheckable) non-critical
         }
     }
     // Phase 2 — LLM verify (parallel). Refuted → drop; verified or errored → keep.
-    await Promise.all(toVerify.map(async ({ finding, presence }, index) => {
+    await Promise.all(toVerify.map(async ({ finding, presence, citedSources }, index) => {
         try {
             const { value, cost: verifyCost, tokens: verifyTokens, model: verifyModel, } = await promptAndParse(handle, {
                 agent: VERIFIER_AGENT,
                 system: buildVerifierSystem(),
-                text: buildVerifierTask(finding, { evidenceUngrounded: presence === "absent" }),
+                text: buildVerifierTask(finding, {
+                    evidenceUngrounded: presence === "absent",
+                    ...(citedSources ? { citedSources } : {}),
+                }),
                 title: `verify-${index}`,
                 maxWaitMs: VERIFY_TIMEOUT_MS,
                 finalizeOnTimeout: true,
@@ -130,6 +153,17 @@ export async function verifyFindings(handle, findings, cwd, onProgress) {
             model = verifyModel ?? model;
             if (value.verified) {
                 verdicts.set(finding, "keep");
+                // An explicit false strips the citation; the finding itself stands.
+                // Absent or true leaves the grounded sources untouched (fail open).
+                if (citedSources && value.citationSupported === false) {
+                    const { sources: _sources, ...withoutSources } = finding;
+                    replacements.set(finding, withoutSources);
+                    citationStripped.push({
+                        finding,
+                        reason: "the verifier judged the cited passages unsupportive of the claim",
+                    });
+                    onProgress?.(`  verify: kept "${finding.title}" but removed its citation — the cited passages do not support the claim`);
+                }
             }
             else {
                 verdicts.set(finding, "drop");
@@ -144,6 +178,8 @@ export async function verifyFindings(handle, findings, cwd, onProgress) {
         }
     }));
     // Preserve original order.
-    const kept = findings.filter((finding) => verdicts.get(finding) === "keep");
-    return { kept, dropped, cost, tokens, model };
+    const kept = findings
+        .filter((finding) => verdicts.get(finding) === "keep")
+        .map((finding) => replacements.get(finding) ?? finding);
+    return { kept, dropped, citationStripped, cost, tokens, model };
 }

package/build/research-mcp/audit.js

@@ -1,5 +1,15 @@
 import { appendFile, mkdir, readFile, rmdir } from "node:fs/promises";
 import { randomUUID } from "node:crypto";
+/**
+ * Why a call was refused before it executed. Recorded WITHOUT the offending
+ * input: a rejected query or URL may contain exactly the sensitive material
+ * the sanitizer refused to send, so only the reason class is audited.
+ */
+export const RESEARCH_REJECTION_REASONS = [
+    "query-rejected",
+    "url-rejected",
+    "budget-exhausted",
+];
 const LOCK_RETRIES = 200;
 const LOCK_DELAY_MS = 10;
 const MAX_AUDITED_PASSAGE_CHARACTERS = 20_000;
@@ -97,6 +107,14 @@ export class ResearchAudit {
         await this.withLock(async () => {
             const used = await this.reservationCount();
             if (used >= this.maxCalls) {
+                // Rejected events do not count as reservations, so recording the refusal
+                // cannot itself consume (or extend) the budget.
+                await this.append({
+                    type: "rejected",
+                    tool,
+                    reason: "budget-exhausted",
+                    timestamp: new Date().toISOString(),
+                });
                 throw new Error(`Documentation research call budget exhausted (${this.maxCalls})`);
             }
             if (!this.path)
@@ -111,7 +129,7 @@ export class ResearchAudit {
         });
         return requestId;
     }
-    async complete(requestId, tool, input, results, warnings = []) {
+    async complete(requestId, tool, input, results, warnings = [], network) {
         await this.append({
             type: "completed",
             requestId,
@@ -119,6 +137,7 @@ export class ResearchAudit {
             input,
             results: results.map(boundedResult),
             warnings: warnings.slice(0, 10).map((warning) => warning.slice(0, 500)),
+            ...(network ? { network } : {}),
             timestamp: new Date().toISOString(),
         });
     }
@@ -132,6 +151,15 @@ export class ResearchAudit {
             timestamp: new Date().toISOString(),
         });
     }
+    /** Record a call refused before execution — reason class only, never the input. */
+    async rejected(tool, reason) {
+        await this.append({
+            type: "rejected",
+            tool,
+            reason,
+            timestamp: new Date().toISOString(),
+        });
+    }
 }
 export async function readResearchAudit(path) {
     let contents = "";
@@ -140,10 +168,11 @@ export async function readResearchAudit(path) {
     }
     catch (error) {
         if (error.code === "ENOENT")
-            return [];
+            return { records: [], rejections: [] };
         throw error;
     }
     const records = [];
+    const rejections = [];
     for (const line of contents.split("\n")) {
         if (!line)
             continue;
@@ -161,10 +190,14 @@ export async function readResearchAudit(path) {
                     error: event.error,
                 });
             }
+            if (event.type === "rejected" &&
+                RESEARCH_REJECTION_REASONS.includes(event.reason)) {
+                rejections.push({ tool: event.tool, reason: event.reason });
+            }
         }
         catch {
             // Ignore a partial final line from a process that was terminated mid-write.
         }
     }
-    return records;
+    return { records, rejections };
 }

package/build/research-mcp/child-env.js

@@ -0,0 +1,74 @@
+// @ref LLP 0013#one-package-two-binaries [implements] — the bounded MCP's environment is constructed, never inherited
+/**
+ * The single definition of what the bounded documentation MCP is allowed to see
+ * in its environment.
+ *
+ * Two callers share it, and they need it for different reasons:
+ *
+ *  - `createResearchMcpRuntime` writes `researchChildEnvironment()` into the
+ *    engine's MCP configuration. That block is a REQUEST, not a guarantee: both
+ *    Claude Code and OpenCode merge it onto the environment the engine already
+ *    has rather than replacing it, so the declared allowlist alone never bounds
+ *    the child.
+ *  - `wrapper.ts` applies `researchWrapperEnvironment()` when it spawns the real
+ *    server. That IS the guarantee — the server process is handed a constructed
+ *    environment, so whatever the engine merged in stops at the wrapper.
+ *
+ * Nothing here imports a parser, a network client, or the config schema: the
+ * wrapper must stay loadable without pulling untrusted-content machinery into
+ * the one process that still holds the engine's credentials.
+ */
+const PROXY_ENV_KEYS = [
+    "HTTP_PROXY",
+    "HTTPS_PROXY",
+    "NO_PROXY",
+    "http_proxy",
+    "https_proxy",
+    "no_proxy",
+];
+export const RESEARCH_SEARCH_API_KEY = "BRAVE_SEARCH_API_KEY";
+/**
+ * Bounds ECR sets on the child through the config env block. These are inputs to
+ * the server, so the wrapper must forward them; every one is a number, a path ECR
+ * itself chose, or both, and none is a credential.
+ */
+export const RESEARCH_RUNTIME_ENV_KEYS = [
+    "REVIEW_RESEARCH_AUDIT_PATH",
+    "REVIEW_RESEARCH_INDEX_PATH",
+    "REVIEW_RESEARCH_MAX_CALLS",
+    "REVIEW_RESEARCH_MAX_RESULTS",
+    "REVIEW_RESEARCH_TIMEOUT_MS",
+];
+/**
+ * Locale, proxy configuration, and the search-only credential — the environment
+ * the MCP actually needs to do its job.
+ *
+ * NODE_OPTIONS is deliberately absent: it is arbitrary code injection into the
+ * process that parses untrusted remote documents. So are PATH and HOME — the
+ * wrapper spawns the server by absolute path and the server writes only to the
+ * audit path it is given.
+ */
+export function researchChildEnvironment(source = process.env) {
+    const environment = {
+        LANG: "C.UTF-8",
+        LC_ALL: "C.UTF-8",
+        ...(process.platform === "win32" && source.SystemRoot ? { SystemRoot: source.SystemRoot } : {}),
+    };
+    for (const key of PROXY_ENV_KEYS) {
+        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;
+}
+/** The child environment plus the bounds ECR passes through the config block. */
+export function researchWrapperEnvironment(source = process.env) {
+    const environment = researchChildEnvironment(source);
+    for (const key of RESEARCH_RUNTIME_ENV_KEYS) {
+        if (source[key] !== undefined)
+            environment[key] = source[key];
+    }
+    return environment;
+}

package/build/research-mcp/cli.js

@@ -58,6 +58,7 @@ async function main() {
                 : {}),
             maxCalls: boundedInteger("REVIEW_RESEARCH_MAX_CALLS", 8, 1, 20),
             maxResultsPerCall: boundedInteger("REVIEW_RESEARCH_MAX_RESULTS", 3, 1, 3),
+            timeoutMs: boundedInteger("REVIEW_RESEARCH_TIMEOUT_MS", 30_000, 1_000, 60_000),
             ...(process.env.BRAVE_SEARCH_API_KEY
                 ? { braveApiKey: process.env.BRAVE_SEARCH_API_KEY }
                 : {}),

package/build/research-mcp/expo-algolia.js

@@ -53,8 +53,8 @@ export function extractExpoAlgoliaDocuments(json) {
     }
     return documents;
 }
-async function fetchExpoAlgolia(query, limit, timeoutMs, maxResponseBytes) {
-    const response = await fetch(EXPO_ALGOLIA_ENDPOINT, {
+async function fetchExpoAlgolia(query, limit, timeoutMs, maxResponseBytes, fetchImplementation) {
+    const response = await fetchImplementation(EXPO_ALGOLIA_ENDPOINT, {
         method: "POST",
         redirect: "error",
         signal: AbortSignal.timeout(timeoutMs),
@@ -83,7 +83,7 @@ async function fetchExpoAlgolia(query, limit, timeoutMs, maxResponseBytes) {
     const body = await readBodyWithLimit(response, maxResponseBytes);
     return extractExpoAlgoliaDocuments(body);
 }
-export async function searchExpoAlgolia(query, limit) {
+export async function searchExpoAlgolia(query, limit, fetchImplementation = fetch) {
     const normalized = query.replace(/\s+/g, " ").trim();
     if (!normalized || normalized.length > 300) {
         throw new Error("Expo Algolia query must contain between 1 and 300 characters");
@@ -91,5 +91,5 @@ export async function searchExpoAlgolia(query, limit) {
     if (!Number.isInteger(limit) || limit < 1 || limit > 10) {
         throw new Error("Expo Algolia result limit must be between 1 and 10");
     }
-    return fetchExpoAlgolia(normalized, limit, 5000, 1_000_000);
+    return fetchExpoAlgolia(normalized, limit, 5000, 1_000_000, fetchImplementation);
 }

package/build/research-mcp/network.js

@@ -0,0 +1,75 @@
+/** Discovery endpoints. Everything else is a documentation page or asset. */
+const SEARCH_ENDPOINTS = [
+    "https://api.search.brave.com/",
+    "https://qex7pb7d46-dsn.algolia.net/",
+    "https://lysine.dev/okhttp/search/search_index.json",
+];
+export class ResearchDeadlineError extends Error {
+    constructor(timeoutMs) {
+        super(`Documentation research call exceeded its ${timeoutMs}ms deadline`);
+        this.name = "ResearchDeadlineError";
+    }
+}
+export function createResearchNetwork(base, timeoutMs) {
+    const startedAt = Date.now();
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(new ResearchDeadlineError(timeoutMs)), timeoutMs);
+    // The MCP is a short-lived stdio process; never hold the loop open for this.
+    timer.unref?.();
+    let searchRequests = 0;
+    let documentRequests = 0;
+    let redirects = 0;
+    let totalRequests = 0;
+    const wrapped = async (input, init) => {
+        if (controller.signal.aborted)
+            throw new ResearchDeadlineError(timeoutMs);
+        const href = typeof input === "string" ? input : input instanceof URL ? input.href : input.url;
+        const isSearch = SEARCH_ENDPOINTS.some((endpoint) => href.startsWith(endpoint));
+        totalRequests++;
+        if (isSearch)
+            searchRequests++;
+        else
+            documentRequests++;
+        // Keep the caller's own per-attempt timeout AND add the call deadline, so a
+        // single slow hop still fails fast while the whole call stays bounded.
+        const signal = init?.signal
+            ? AbortSignal.any([init.signal, controller.signal])
+            : controller.signal;
+        const response = await base(input, { ...init, signal });
+        if (response.status >= 300 && response.status < 400) {
+            redirects++;
+            // A redirect hop is a round trip, not a distinct resource, so undo the
+            // classification count. It has to be the SAME counter that was
+            // incremented: the search backends use `redirect: "manual"` too and treat
+            // a 3xx as an error, so unconditionally decrementing documentRequests
+            // drives it negative the first time a discovery endpoint redirects.
+            if (isSearch)
+                searchRequests--;
+            else
+                documentRequests--;
+        }
+        return response;
+    };
+    return {
+        fetch: wrapped,
+        signal: controller.signal,
+        expired: () => controller.signal.aborted,
+        counts: () => ({
+            searchRequests,
+            documentRequests,
+            redirects,
+            totalRequests,
+            elapsedMs: Date.now() - startedAt,
+        }),
+    };
+}
+/** Sum per-call ledgers into one review-wide total. */
+export function totalResearchNetwork(counts) {
+    return counts.reduce((total, entry) => ({
+        searchRequests: total.searchRequests + entry.searchRequests,
+        documentRequests: total.documentRequests + entry.documentRequests,
+        redirects: total.redirects + entry.redirects,
+        totalRequests: total.totalRequests + entry.totalRequests,
+        elapsedMs: total.elapsedMs + entry.elapsedMs,
+    }), { searchRequests: 0, documentRequests: 0, redirects: 0, totalRequests: 0, elapsedMs: 0 });
+}

package/build/research-mcp/query-sanitizer.js

@@ -71,7 +71,20 @@ function isApiAnchor(value) {
     return (/[a-z][A-Z]/.test(value) ||
         /[A-Z][A-Za-z0-9_]{1,}/.test(value) ||
         /[._:$#()]/.test(value) ||
-        /_[A-Z0-9]/.test(value));
+        /_[A-Z0-9]/.test(value) ||
+        // Hyphenated package and module names (expo-camera, react-native-screens).
+        /[a-z0-9]-[a-z]/.test(value));
+}
+/**
+ * A short, all-lowercase concept phrase ("gradle configuration cache",
+ * "coroutine cancellation cooperative"). Guide, release-note, and Expo
+ * documentation topics frequently have no CamelCase symbol; two or more plain
+ * dictionary-shaped words carry no more outbound capacity than a symbol query
+ * (same token, length, entropy, and secret checks apply) and are accepted.
+ * A single generic word still fails closed.
+ */
+function isPlainConceptPhrase(tokens) {
+    return tokens.length >= 2 && tokens.every((token) => /^[a-z][a-z0-9]{2,23}$/.test(token));
 }
 /**
  * Convert an agent-authored search into a short API-symbol query. Dangerous shapes
@@ -100,8 +113,8 @@ export function sanitizeDocumentationQuery(rawQuery) {
         return !PROSE_STOP_WORDS.has(token.toLowerCase());
     });
     const unique = [...new Set(candidates)].slice(0, MAX_QUERY_TOKENS);
-    if (!unique.some(isApiAnchor)) {
-        throw new Error("Query must include an API-like symbol or member name");
+    if (!unique.some(isApiAnchor) && !isPlainConceptPhrase(unique)) {
+        throw new Error("Query must include an API-like symbol or a multi-word concept phrase");
     }
     const sanitized = unique.join(" ").slice(0, MAX_QUERY_CHARACTERS).trim();
     if (!sanitized)

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

@@ -136,7 +136,7 @@ export async function searchRemoteDocumentation(providerId, query, limit, option
     }
     const warnings = [];
     const indexedAt = new Date().toISOString();
-    const fetched = await Promise.all(candidates.map(async ({ url, position }) => {
+    const fetchCandidate = async ({ url, position, }) => {
         try {
             const document = await fetchDocumentationDocument(provider, url.href, definition.sourceKind, fetchImplementation);
             if (!document || (options.language && document.language !== options.language))
@@ -168,12 +168,24 @@ export async function searchRemoteDocumentation(providerId, query, limit, option
             warnings.push(`${provider.displayName} fetch failed for ${url.href}: ${message}`);
             return null;
         }
-    }));
+    };
+    // Brave ranking is discovery order. Fetch only enough pages to satisfy the
+    // caller, advancing to later candidates when a page is rejected or unavailable.
+    // Batching the outstanding result count preserves parallelism without eagerly
+    // downloading every discovery candidate.
+    const fetched = [];
+    let candidateIndex = 0;
+    while (fetched.length < limit &&
+        candidateIndex < candidates.length &&
+        !options.deadline?.aborted) {
+        const outstanding = limit - fetched.length;
+        const batch = candidates.slice(candidateIndex, candidateIndex + outstanding);
+        candidateIndex += batch.length;
+        const batchResults = await Promise.all(batch.map(fetchCandidate));
+        fetched.push(...batchResults.flatMap((result) => (result ? [result] : [])));
+    }
     return {
-        results: fetched
-            .flatMap((result) => (result ? [result] : []))
-            .sort((left, right) => right.score - left.score)
-            .slice(0, limit),
+        results: fetched.sort((left, right) => right.score - left.score).slice(0, limit),
         warnings: warnings.slice(0, 5),
     };
 }