@expo/code-review-cli 0.12.3 → 0.12.5

package/build/core/research.js

@@ -1,4 +1,4 @@
-// @ref LLP 0013#query-and-prompt-boundary [implements] — derive identifiers only; validate, bound, and sanitize MCP evidence
+// @ref LLP 0013#query-and-prompt-boundary [implements] — validate, bound, and sanitize reviewer-requested 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";
@@ -6,9 +6,9 @@ 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";
+import { researchChildEnvironment } from "../research-mcp/child-env.js";
+import { totalResearchNetwork } from "../research-mcp/network.js";
 export { OPENCODE_RESEARCH_TOOLS } from "./tools.js";
 export const RESEARCH_DECISION_COUNT_LIMIT = 16;
 export const RESEARCH_DECISION_BYTES_LIMIT = 20_000;
@@ -17,388 +17,17 @@ 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;
-const QUERY_TOKEN = /[A-Za-z][A-Za-z0-9_.:-]{1,79}/g;
-const MAX_ANALYZED_PATCH_LINE_LENGTH = 4096;
-const TYPE_TOKEN = /\b[A-Z][A-Za-z0-9_]{2,}(?:\.[A-Za-z_][A-Za-z0-9_]*)*/g;
-const MEMBER_TOKEN = /\.([a-z][A-Za-z0-9_]{3,})\s*(?:\(|\b)/g;
-const ECOSYSTEM_CALL_TOKEN = /\b((?:create|enable|make|measure|run|schedule|scrollTo|use|with)[A-Z][A-Za-z0-9_]*)\s*\(/g;
-const IGNORED_TYPES = new Set([
-    "Array",
-    "Bool",
-    "Boolean",
-    "Class",
-    "Data",
-    "Double",
-    "Error",
-    "Exception",
-    "Float",
-    "Int",
-    "Integer",
-    "List",
-    "Long",
-    "Map",
-    "Object",
-    "Promise",
-    "Set",
-    "String",
-    "URL",
-    "Unit",
-]);
-const IGNORED_MEMBERS = new Set([
-    "apply",
-    "build",
-    "copy",
-    "equals",
-    "filter",
-    "first",
-    "get",
-    "hashCode",
-    "invoke",
-    "last",
-    "let",
-    "map",
-    "remove",
-    "run",
-    "set",
-    "toString",
-]);
-function startsModuleSpecifier(code) {
-    return /(?:\b(?:from|import)\s*|\brequire\s*\(\s*)$/.test(code);
-}
-function analyzePatchLine(source, state, collectProviderSignals, providerSignals) {
-    let code = "";
-    const finishModuleSpecifier = () => {
-        const value = state.moduleSpecifier;
-        if (value && /^[A-Za-z0-9@._/+~-]{1,200}$/.test(value))
-            providerSignals.push(value);
-        state.moduleSpecifier = null;
-    };
-    for (let index = 0; index < source.length;) {
-        if (state.mode === "block-comment") {
-            if (source.startsWith("*/", index)) {
-                state.mode = "code";
-                code += "  ";
-                index += 2;
-            }
-            else {
-                code += " ";
-                index++;
-            }
-            continue;
-        }
-        if (state.mode === "triple-single-quote" || state.mode === "triple-double-quote") {
-            const delimiter = state.mode === "triple-single-quote" ? "'''" : '"""';
-            if (source.startsWith(delimiter, index)) {
-                state.mode = "code";
-                code += "   ";
-                index += 3;
-            }
-            else {
-                code += " ";
-                index++;
-            }
-            continue;
-        }
-        if (state.mode === "single-quote" ||
-            state.mode === "double-quote" ||
-            state.mode === "template") {
-            const delimiter = state.mode === "single-quote" ? "'" : state.mode === "double-quote" ? '"' : "`";
-            const character = source[index];
-            if (state.escaped) {
-                if (state.moduleSpecifier !== null)
-                    state.moduleSpecifier += character;
-                state.escaped = false;
-                code += " ";
-                index++;
-            }
-            else if (character === "\\") {
-                state.escaped = true;
-                code += " ";
-                index++;
-            }
-            else if (character === delimiter) {
-                finishModuleSpecifier();
-                state.mode = "code";
-                code += " ";
-                index++;
-            }
-            else {
-                if (state.moduleSpecifier !== null)
-                    state.moduleSpecifier += character;
-                code += " ";
-                index++;
-            }
-            continue;
-        }
-        if (source.startsWith("//", index)) {
-            code += " ".repeat(source.length - index);
-            break;
-        }
-        if (source.startsWith("/*", index)) {
-            state.mode = "block-comment";
-            code += "  ";
-            index += 2;
-            continue;
-        }
-        if (source.startsWith("'''", index) || source.startsWith('"""', index)) {
-            state.mode = source.startsWith("'''", index) ? "triple-single-quote" : "triple-double-quote";
-            state.moduleSpecifier = null;
-            code += "   ";
-            index += 3;
-            continue;
-        }
-        const character = source[index];
-        if (character === "'" || character === '"' || character === "`") {
-            state.mode =
-                character === "'" ? "single-quote" : character === '"' ? "double-quote" : "template";
-            state.escaped = false;
-            state.moduleSpecifier =
-                collectProviderSignals && character !== "`" && startsModuleSpecifier(code) ? "" : null;
-            code += " ";
-            index++;
-            continue;
-        }
-        code += character;
-        index++;
-    }
-    // JavaScript/TypeScript, Swift, and Kotlin single/double-quoted strings do not
-    // continue onto the next physical line unless the final character escapes the
-    // newline. Reset malformed prose-like quotes (notably JSX apostrophes) here so
-    // they cannot invert how later patch lines are classified. Templates, triple
-    // quotes, and block comments intentionally retain their multiline state.
-    const continuesQuotedLine = (state.mode === "single-quote" || state.mode === "double-quote") && state.escaped;
-    if ((state.mode === "single-quote" || state.mode === "double-quote") && !continuesQuotedLine) {
-        state.mode = "code";
-        state.moduleSpecifier = null;
-    }
-    state.escaped = false;
-    return code.trim();
-}
-/**
- * Analyze the resulting side of a unified diff while keeping lexical state across
- * lines. Provider routing may retain only import/require module specifiers; those
- * strings are kept separate and can never become outbound query text.
- */
-function analyzeAddedPatch(patch) {
-    const codeLines = [];
-    const providerSignals = [];
-    const state = { mode: "code", escaped: false, moduleSpecifier: null };
-    for (const patchLine of patch.split("\n")) {
-        if (patchLine.startsWith("@@")) {
-            state.mode = "code";
-            state.escaped = false;
-            state.moduleSpecifier = null;
-            continue;
-        }
-        if (patchLine.startsWith("+++") || patchLine.startsWith("---"))
-            continue;
-        const isAdded = patchLine.startsWith("+");
-        const isContext = patchLine.startsWith(" ");
-        if (!isAdded && !isContext)
-            continue;
-        const source = patchLine.slice(1);
-        if (source.length > MAX_ANALYZED_PATCH_LINE_LENGTH) {
-            // A quote startsModuleSpecifier check examines the accumulated line prefix.
-            // Stop this file before an attacker-controlled giant line can turn that
-            // bounded research prepass into quadratic work. Abandoning later lines also
-            // avoids guessing whether the skipped input opened a multiline literal.
-            break;
-        }
-        const code = analyzePatchLine(source, state, isAdded, providerSignals);
-        if (isAdded && code)
-            codeLines.push(code);
-    }
-    return {
-        codeLines,
-        providerSignals: providerSignals.join("\n").slice(0, 256_000).toLowerCase(),
-    };
-}
-function normalizeQuery(parts) {
-    const tokens = parts.join(" ").match(QUERY_TOKEN) ?? [];
-    return [...new Set(tokens)].join(" ").slice(0, 120).trim();
-}
-function platformFor(file) {
-    const normalized = file.path.replace(/\\/g, "/");
-    if (APPLE_EXTENSIONS.test(normalized) || /(?:^|\/)ios(?:\/|$)/i.test(normalized)) {
-        return "apple";
-    }
-    if (ANDROID_EXTENSIONS.test(normalized) || /(?:^|\/)android(?:\/|$)/i.test(normalized)) {
-        return "android";
-    }
-    if (REACT_NATIVE_EXTENSIONS.test(normalized))
-        return "react-native";
-    return null;
-}
-const REACT_NATIVE_PROVIDERS = new Set([
-    "expo",
-    "react-native",
-    "react-native-reanimated",
-    "react-native-gesture-handler",
-    "react-native-screens",
-    "react-native-worklets",
-]);
-function providersFor(file, code, signals) {
-    const path = file.path.toLowerCase();
-    const text = code.toLowerCase();
-    const platform = platformFor(file);
-    const providers = [];
-    const add = (provider, matches) => {
-        if (matches && !providers.includes(provider))
-            providers.push(provider);
-    };
-    // Native source is owned by the native platform first. An Expo package path is
-    // repository ownership, not documentation ownership: packages/expo-image/ios
-    // must search Apple and SDWebImage contracts rather than Expo's JavaScript docs.
-    if (platform === "apple")
-        add("apple", true);
-    if (platform === "android")
-        add("android", true);
-    if (platform === "react-native") {
-        add("react-native-reanimated", /react-native-reanimated/.test(signals) || path.includes("react-native-reanimated"));
-        add("react-native-gesture-handler", /react-native-gesture-handler/.test(signals) || path.includes("react-native-gesture-handler"));
-        add("react-native-screens", /react-native-screens/.test(signals) || path.includes("react-native-screens"));
-        add("react-native-worklets", /react-native-worklets/.test(signals) || path.includes("react-native-worklets"));
-        add("expo", /(?:^|\n)(?:expo|expo-[a-z0-9-]+|@expo\/[a-z0-9-]+)(?:\n|$)/.test(signals) ||
-            /(?:^|\/)packages\/expo(?:-[^/]+)?(?:\/|$)/.test(path));
-        add("react-native", /(?:^|\n)react-native(?:\/[^\n]+)?(?:\n|$)/.test(signals));
-    }
-    // Explicit framework/dependency signals are additive. Keeping the platform
-    // provider alongside the dependency lets one pass check both the OS contract and
-    // the wrapper/library behavior without a package-path heuristic hiding either.
-    if (platform === "apple") {
-        add("sdwebimage", /\bsdwebimage(?:manager|options|context|cache|loader)?\b/.test(text));
-        add("expo", /\bexpomodulescore\b/.test(text));
-    }
-    if (platform === "android") {
-        add("media3", /androidx\.media3|mediasessionservice|\bexoplayer\b/.test(text));
-        add("glide", /com\.bumptech\.glide|\bglide\b/.test(text));
-        add("okhttp", /okhttp3|\bokhttpclient\b|\brequest\.builder\b/.test(text));
-        add("kotlin-coroutines", /kotlinx\.coroutines|\bcoroutinescope\b|\bmutable(?:state|shared)flow\b/.test(text));
-        const isGradle = /\.gradle(?:\.kts)?$/.test(path) || /(?:^|\/)build\.gradle/.test(path);
-        add("agp", isGradle && /com\.android|android\s*\{|compilesdk|targetsdk/.test(text));
-        add("gradle", isGradle);
-        add("expo", /\bexpo\.modules\.kotlin\b/.test(text));
-    }
-    return providers.length > 0 ? providers : ["react-native"];
-}
-function lineQuery(line) {
-    const declared = line.match(/\b(?:class|struct|enum|interface|protocol)\s+([A-Z][A-Za-z0-9_]*)/)?.[1];
-    const types = [...line.matchAll(TYPE_TOKEN)]
-        .map((match) => match[0])
-        .filter((value) => value !== declared && !IGNORED_TYPES.has(value.split(".")[0]));
-    if (types.length === 0) {
-        const call = [...line.matchAll(ECOSYSTEM_CALL_TOKEN)][0]?.[1];
-        return call ? normalizeQuery([call]) : null;
-    }
-    const members = [...line.matchAll(MEMBER_TOKEN)]
-        .map((match) => match[1])
-        .filter((value) => !IGNORED_MEMBERS.has(value));
-    const primary = types[0];
-    const member = members.find((value) => !primary.toLowerCase().includes(value.toLowerCase()));
-    return normalizeQuery(member ? [primary, member] : [primary]);
-}
-function addQuery(target, seen, platform, providers, query) {
-    const normalized = normalizeQuery([query]);
-    if (!normalized)
-        return;
-    const key = `${platform}|${providers.join(",")}|${normalized.toLowerCase()}`;
-    if (seen.has(key))
-        return;
-    seen.add(key);
-    target.push({ platform, providers, query: normalized });
-}
+export { researchChildEnvironment };
 /**
- * Derive bounded documentation searches from code identifiers only. String literals,
- * comments, removed lines, paths, and raw source snippets never become query text.
+ * The engine spawns the WRAPPER, not the server. Both Claude Code and OpenCode
+ * merge the config's `env` block onto their own environment instead of replacing
+ * it, so the block below cannot bound the child on its own; the wrapper rebuilds
+ * the environment from an explicit allowlist before the real server starts. See
+ * research-mcp/wrapper.ts.
  */
-export function deriveResearchQueries(files, maxQueries = 8) {
-    const queries = [];
-    const seen = new Set();
-    for (const file of files) {
-        const platform = platformFor(file);
-        if (!platform)
-            continue;
-        const { codeLines: lines, providerSignals } = analyzeAddedPatch(file.patch);
-        const code = lines.join("\n").slice(0, 256_000);
-        const providers = providersFor(file, code, providerSignals);
-        for (const provider of providers) {
-            let addedForProvider = 0;
-            for (const line of lines) {
-                const query = lineQuery(line);
-                if (!query)
-                    continue;
-                const before = queries.length;
-                addQuery(queries, seen, REACT_NATIVE_PROVIDERS.has(provider) ? "react-native" : platform, [provider], query);
-                if (queries.length > before && ++addedForProvider >= 2)
-                    break;
-                if (queries.length >= maxQueries)
-                    return queries;
-            }
-        }
-        if (platform === "apple" &&
-            /\b(?:actor|MainActor|Sendable|TaskGroup|Task\.sleep)\b/.test(code)) {
-            const concept = code.match(/\b(?:MainActor|Sendable|TaskGroup|actor|Task\.sleep)\b/)?.[0];
-            if (concept)
-                addQuery(queries, seen, "apple", ["swift-evolution"], concept);
-        }
-        if (platform === "android" && /\b(?:VERSION_CODES|SDK_INT|targetSdk|compileSdk)\b/.test(code)) {
-            const api = code.match(/\b(?:VERSION_CODES(?:\.[A-Z_]+)?|SDK_INT|targetSdk|compileSdk)\b/)?.[0];
-            if (api)
-                addQuery(queries, seen, "android", ["android-releases"], api);
-        }
-        if (queries.length >= maxQueries)
-            return queries.slice(0, maxQueries);
-    }
-    return queries.slice(0, maxQueries);
-}
-const ToolResultSchema = z.object({
-    content: z.array(z.object({
-        type: z.string(),
-        text: z.string().optional(),
-    })),
-});
-const SearchPayloadSchema = z.object({
-    warnings: z.array(z.string().max(500)).max(10).optional(),
-    results: z.array(z.object({
-        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 = [
-    "HTTP_PROXY",
-    "HTTPS_PROXY",
-    "NO_PROXY",
-    "http_proxy",
-    "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",
-        LC_ALL: "C.UTF-8",
-        ...(process.platform === "win32" && source.SystemRoot ? { SystemRoot: source.SystemRoot } : {}),
-    };
-    for (const key of RESEARCH_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;
-}
 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));
+    const builtEntry = fileURLToPath(new URL("../research-mcp/wrapper.js", import.meta.url));
+    const sourceEntry = fileURLToPath(new URL("../research-mcp/wrapper.ts", import.meta.url));
     return {
         command: process.execPath,
         args: [existsSync(builtEntry) ? builtEntry : sourceEntry],
@@ -406,8 +35,12 @@ export function bundledResearchServer() {
 }
 /**
  * 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.
+ * The model process receives only the config path.
+ *
+ * The `env` block below is a request the engine merges rather than applies — see
+ * bundledResearchServer. The wrapper it names is what actually bounds the server's
+ * environment, so the Brave credential and these limits are the only things the
+ * server can see, whatever the engine passed down.
  */
 export async function createResearchMcpRuntime(config) {
     if (!config.enabled)
@@ -427,6 +60,10 @@ export async function createResearchMcpRuntime(config) {
         REVIEW_RESEARCH_AUDIT_PATH: auditPath,
         REVIEW_RESEARCH_MAX_CALLS: String(config.maxQueries),
         REVIEW_RESEARCH_MAX_RESULTS: String(config.resultsPerQuery),
+        // The MCP enforces this itself as a per-call deadline. OpenCode's `timeout`
+        // only bounds tool DISCOVERY and Claude has no equivalent, so neither engine
+        // can bound how long a call actually runs — the server has to.
+        REVIEW_RESEARCH_TIMEOUT_MS: String(config.timeoutMs),
     }).flatMap(([key, value]) => (value === undefined ? [] : [[key, value]])));
     await writeFile(claudeConfigPath, `${JSON.stringify({
         mcpServers: {
@@ -448,7 +85,7 @@ export async function createResearchMcpRuntime(config) {
     };
 }
 export async function researchProvenanceFromAudit(auditPath) {
-    const records = await readResearchAudit(auditPath);
+    const { records, rejections } = await readResearchAudit(auditPath);
     const queries = [];
     const evidence = [];
     const warnings = [];
@@ -486,9 +123,25 @@ export async function researchProvenanceFromAudit(auditPath) {
         queries,
         evidence,
         warnings: [...new Set(warnings)].slice(0, 10),
-        promptText: "",
     };
-    return { provenance: toResearchProvenance(run), evidence };
+    const provenance = toResearchProvenance(run);
+    const ledgers = records.flatMap((record) => (record.network ? [record.network] : []));
+    if (ledgers.length > 0)
+        provenance.network = totalResearchNetwork(ledgers);
+    if (rejections.length > 0) {
+        const counts = new Map();
+        for (const rejection of rejections) {
+            const key = `${rejection.tool}\0${rejection.reason}`;
+            counts.set(key, (counts.get(key) ?? 0) + 1);
+        }
+        provenance.rejections = [...counts.entries()]
+            .map(([key, count]) => {
+            const [tool = "", reason = ""] = key.split("\0");
+            return { tool: cleanEvidenceText(tool, 80), reason: cleanEvidenceText(reason, 80), count };
+        })
+            .sort((left, right) => `${left.tool}${left.reason}`.localeCompare(`${right.tool}${right.reason}`));
+    }
+    return { provenance, evidence };
 }
 function cleanEvidenceText(value, maxLength) {
     return (value
@@ -500,25 +153,6 @@ function cleanEvidenceText(value, maxLength) {
         .slice(0, maxLength)
         .trim());
 }
-export function formatResearchEvidence(evidence) {
-    if (evidence.length === 0)
-        return "";
-    const body = evidence
-        .map((item) => {
-        const availability = item.availability?.length
-            ? `\nAvailability: ${cleanEvidenceText(item.availability.join(", "), 500)}`
-            : "";
-        return [
-            `Query: ${cleanEvidenceText(item.query.query, 120)}`,
-            `Provider: ${cleanEvidenceText(item.provider, 80)} (${cleanEvidenceText(item.sourceKind, 80)})`,
-            `Source: ${cleanEvidenceText(item.title, 240)} — ${item.url}${availability}`,
-            "Passage:",
-            cleanEvidenceText(item.passage, 1200),
-        ].join("\n");
-    })
-        .join("\n\n");
-    return cleanEvidenceText(body, 16_000);
-}
 function researchQueryKey(query) {
     return `${query.platform}\0${query.providers.join(",")}\0${query.query}`;
 }
@@ -562,6 +196,14 @@ export function formatResearchProgress(provenance) {
             lines.push(`    result: ${cleanEvidenceText(result.title, 160)} (${result.provider}/${result.sourceKind}) — ${result.url}`);
         }
     }
+    if (provenance.network) {
+        const { searchRequests, documentRequests, redirects, totalRequests } = provenance.network;
+        lines.push(`  research network: ${searchRequests} search request(s), ${documentRequests} page fetch(es), ` +
+            `${redirects} redirect(s) — ${totalRequests} HTTP request(s) total`);
+    }
+    for (const rejection of provenance.rejections ?? []) {
+        lines.push(`  research: ${rejection.count} ${rejection.tool} call(s) rejected before execution (${rejection.reason})`);
+    }
     for (const warning of provenance.warnings) {
         lines.push(`  research warning: ${cleanEvidenceText(warning, 500)}`);
     }
@@ -602,6 +244,15 @@ export function renderResearchMarkdown(provenance) {
             lines.push(`  - [${escapeMarkdownLabel(result.title)}](<${result.url}>) — ${escapeMarkdownLabel(result.provider)}/${escapeMarkdownLabel(result.sourceKind)}`);
         }
     }
+    if (provenance.network) {
+        const { searchRequests, documentRequests, redirects, totalRequests, elapsedMs } = provenance.network;
+        lines.push("", `Outbound: **${searchRequests}** search request(s), **${documentRequests}** page fetch(es), ` +
+            `**${redirects}** redirect(s) — **${totalRequests}** HTTP request(s) across ` +
+            `${(elapsedMs / 1000).toFixed(1)}s of call time.`);
+    }
+    for (const rejection of provenance.rejections ?? []) {
+        lines.push(`- ⚠️ ${rejection.count} \`${escapeMarkdownLabel(rejection.tool)}\` call(s) rejected before execution (${escapeMarkdownLabel(rejection.reason)}).`);
+    }
     for (const warning of provenance.warnings) {
         lines.push(`- ⚠️ ${escapeMarkdownLabel(warning)}`);
     }
@@ -622,16 +273,46 @@ export function mergeResearchSources(...groups) {
     })
         .slice(0, 5);
 }
-/** Keep only exact URLs returned by this review's MCP calls and restore canonical titles. */
+/**
+ * Fragment-insensitive lookup key. Models frequently normalize a copied URL by
+ * dropping its `#fragment`; the page identity is unchanged, so a fragment
+ * mismatch must not silently discard an otherwise exact citation. The audited
+ * URL (never the model's variant) is always what gets restored.
+ */
+function citationKey(url) {
+    try {
+        const parsed = new URL(url);
+        parsed.hash = "";
+        return parsed.href;
+    }
+    catch {
+        return url;
+    }
+}
+/** Exact-URL map plus a fragment-insensitive fallback; first audited entry wins. */
+function allowedSourceMaps(evidence) {
+    const exact = new Map();
+    const byKey = new Map();
+    for (const item of evidence) {
+        const canonical = { title: cleanEvidenceText(item.title, 240), url: item.url };
+        if (!exact.has(item.url))
+            exact.set(item.url, canonical);
+        const key = citationKey(item.url);
+        if (!byKey.has(key))
+            byKey.set(key, canonical);
+    }
+    return { exact, byKey };
+}
+function resolveClaimedSource(source, maps) {
+    return maps.exact.get(source.url) ?? maps.byKey.get(citationKey(source.url));
+}
+/** Keep only audited URLs from this review's MCP calls and restore canonical titles. */
 export function groundResearchSources(findings, evidence) {
-    const allowed = new Map(evidence.map((item) => [
-        item.url,
-        { title: cleanEvidenceText(item.title, 240), url: item.url },
-    ]));
+    const maps = allowedSourceMaps(evidence);
     return findings.map((finding) => {
         const { sources: claimed, ...withoutSources } = finding;
         const sources = mergeResearchSources(claimed?.flatMap((source) => {
-            const canonical = allowed.get(source.url);
+            const canonical = resolveClaimedSource(source, maps);
             return canonical ? [canonical] : [];
         }));
         return sources.length > 0 ? { ...withoutSources, sources } : withoutSources;
@@ -642,13 +323,10 @@ export function groundResearchSources(findings, evidence) {
  * An ungrounded declaration is discarded so model output cannot inflate usefulness.
  */
 export function groundResearchDecisions(decisions, evidence, agent) {
-    const allowed = new Map(evidence.map((item) => [
-        item.url,
-        { title: cleanEvidenceText(item.title, 240), url: item.url },
-    ]));
+    const maps = allowedSourceMaps(evidence);
     return decisions.flatMap((decision) => {
         const sources = mergeResearchSources(decision.sources.flatMap((source) => {
-            const canonical = allowed.get(source.url);
+            const canonical = resolveClaimedSource(source, maps);
             return canonical ? [canonical] : [];
         }));
         if (sources.length === 0)
@@ -682,6 +360,17 @@ export function boundResearchDecisions(decisions) {
     }
     return { decisions: kept, omitted };
 }
+/**
+ * Heuristic for external-behavior assertions: an OS-version or API-level claim,
+ * or documented-lifecycle wording. Deliberately narrow — it flags the claim
+ * shapes that most need documentation, not every mention of a platform.
+ */
+const EXTERNAL_CLAIM_PATTERN = /\b(?:iOS|iPadOS|macOS|watchOS|tvOS|visionOS|Android)\s?\d+(?:\.\d+)?\b|\bAPI level\s?\d+\b|\b(?:deprecated|introduced|available|removed)\s+(?:in|since|from|as of)\b|\brequires\s+(?:iOS|iPadOS|macOS|watchOS|tvOS|visionOS|Android|API level|SDK)\b/i;
+/** Final findings asserting external platform behavior with no grounded citation. */
+export function countUngroundedExternalClaims(findings) {
+    return findings.filter((finding) => !finding.sources?.length &&
+        EXTERNAL_CLAIM_PATTERN.test(`${finding.title}\n${finding.rationale}`)).length;
+}
 /** Count unique audited results that materially affected the final review. */
 export function summarizeResearchUsefulness(provenance, findings) {
     const resultUrls = new Set(provenance.results.map((result) => result.url));
@@ -698,15 +387,19 @@ export function summarizeResearchUsefulness(provenance, findings) {
         decisionResultCount: decisionUrls.size,
         utilizedResultCount: utilizedUrls.size,
         unusedResultCount: Math.max(0, resultUrls.size - utilizedUrls.size),
+        externalClaimFindingsWithoutSources: countUngroundedExternalClaims(findings),
     };
 }
 export function formatResearchUsefulness(usefulness) {
+    const ungrounded = usefulness.externalClaimFindingsWithoutSources > 0
+        ? `; ${usefulness.externalClaimFindingsWithoutSources} finding(s) assert external platform behavior without a citation`
+        : "";
     return (`  research usefulness: ${usefulness.finalFindingsWithSources} final finding(s) cited ` +
         `${usefulness.citedResultCount} unique result(s); ` +
         `${usefulness.supportedFindingCandidates} supported and ` +
         `${usefulness.dismissedCandidates} dismissed candidate(s); ` +
         `${usefulness.utilizedResultCount} result(s) materially used, ` +
-        `${usefulness.unusedResultCount} unused`);
+        `${usefulness.unusedResultCount} unused${ungrounded}`);
 }
 export function renderResearchUsefulnessMarkdown(provenance) {
     const usefulness = provenance.usefulness;
@@ -721,6 +414,9 @@ export function renderResearchUsefulnessMarkdown(provenance) {
         `- Candidate decisions: **${usefulness.supportedFindingCandidates} supported**, **${usefulness.dismissedCandidates} dismissed**`,
         `- Unique results materially used: **${usefulness.utilizedResultCount}/${totalUniqueResults}**`,
     ];
+    if (usefulness.externalClaimFindingsWithoutSources > 0) {
+        lines.push(`- ⚠️ Findings asserting external platform behavior without a citation: **${usefulness.externalClaimFindingsWithoutSources}**`);
+    }
     if (provenance.decisions?.length) {
         lines.push("", "Grounded candidate decisions:");
         for (const decision of provenance.decisions) {
@@ -732,93 +428,3 @@ export function renderResearchUsefulnessMarkdown(provenance) {
     }
     return lines.join("\n");
 }
-export async function collectPlatformResearch(files, config) {
-    const queries = deriveResearchQueries(files, config.maxQueries);
-    if (!config.enabled || queries.length === 0) {
-        return { queries, evidence: [], warnings: [], promptText: "" };
-    }
-    const calls = queries.map((query, index) => ({
-        jsonrpc: "2.0",
-        id: index + 2,
-        method: "tools/call",
-        params: {
-            name: "search_platform_docs",
-            arguments: {
-                platform: query.platform,
-                providers: query.providers,
-                query: query.query,
-                limit: config.resultsPerQuery,
-            },
-        },
-    }));
-    const messages = [
-        {
-            jsonrpc: "2.0",
-            id: 1,
-            method: "initialize",
-            params: {
-                protocolVersion: "2025-06-18",
-                capabilities: {},
-                clientInfo: { name: "expo-code-review-cli", version: "0.0.0" },
-            },
-        },
-        { jsonrpc: "2.0", method: "notifications/initialized", params: {} },
-        ...calls,
-    ];
-    const server = bundledResearchServer();
-    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(),
-        env: researchChildEnvironment(),
-        timeout: config.timeoutMs,
-        maxBuffer: 2 * 1024 * 1024,
-        check: false,
-    });
-    if (result.timedOut)
-        throw new Error("platform research MCP timed out");
-    if (result.overflowed)
-        throw new Error("platform research MCP output exceeded 2 MB");
-    if (result.code !== 0) {
-        throw new Error(`platform research MCP exited ${result.code}: ${result.stderr.slice(0, 500)}`);
-    }
-    const responses = new Map();
-    for (const line of result.stdout.split("\n")) {
-        if (!line.trim())
-            continue;
-        const parsed = JSON.parse(line);
-        if (typeof parsed.id === "number") {
-            if (parsed.error)
-                throw new Error(`platform research MCP error for request ${parsed.id}`);
-            responses.set(parsed.id, parsed.result);
-        }
-    }
-    if (!responses.has(1))
-        throw new Error("platform research MCP did not initialize");
-    const evidence = [];
-    const warnings = [];
-    for (let index = 0; index < queries.length; index++) {
-        const query = queries[index];
-        const toolResult = ToolResultSchema.parse(responses.get(index + 2));
-        const text = toolResult.content.find((block) => block.type === "text")?.text;
-        if (!text)
-            continue;
-        const payload = SearchPayloadSchema.parse(JSON.parse(text));
-        warnings.push(...(payload.warnings ?? []).map((warning) => cleanEvidenceText(warning, 500)).filter(Boolean));
-        for (const item of payload.results.slice(0, config.resultsPerQuery)) {
-            if (!item.url.startsWith("https://") || !query.providers.includes(item.provider))
-                continue;
-            evidence.push({ query, ...item });
-        }
-    }
-    return {
-        queries,
-        evidence,
-        warnings: [...new Set(warnings)].slice(0, 10),
-        promptText: formatResearchEvidence(evidence),
-    };
-}