@expo/code-review-cli 0.12.1 → 0.12.3

package/build/core/research.js

@@ -1,10 +1,22 @@
 // @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_DECISION_COUNT_LIMIT = 16;
+export const RESEARCH_DECISION_BYTES_LIMIT = 20_000;
+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;
@@ -231,40 +243,46 @@ const REACT_NATIVE_PROVIDERS = new Set([
 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);
     };
-    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));
-    if (providers.length > 0)
-        return providers;
-    if (/androidx\.media3|mediasessionservice|\bexoplayer\b/.test(text))
-        return ["media3"];
-    if (/com\.bumptech\.glide|\bglide\b/.test(text))
-        return ["glide"];
-    if (/okhttp3|\bokhttpclient\b|\brequest\.builder\b/.test(text))
-        return ["okhttp"];
-    if (/kotlinx\.coroutines|\bcoroutinescope\b|\bmutable(?:state|shared)flow\b/.test(text)) {
-        return ["kotlin-coroutines"];
-    }
-    if (/\.gradle(?:\.kts)?$/.test(path) || /(?:^|\/)build\.gradle/.test(path)) {
-        return /com\.android|android\s*\{|compilesdk|targetsdk/.test(text)
-            ? ["agp", "gradle"]
-            : ["gradle"];
-    }
-    const platform = platformFor(file);
+    // 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")
-        return ["apple"];
+        add("apple", true);
     if (platform === "android")
-        return ["android"];
-    return ["react-native"];
+        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];
@@ -345,12 +363,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 = [
@@ -377,7 +396,7 @@ export function researchChildEnvironment(source = process.env) {
     }
     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 {
@@ -385,6 +404,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, "")
@@ -414,6 +519,219 @@ 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, 20_000),
+            ...(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 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 },
+    ]));
+    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;
+    });
+}
+/**
+ * Keep only reviewer decisions backed by an exact URL from this run's MCP audit.
+ * 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 },
+    ]));
+    return decisions.flatMap((decision) => {
+        const sources = mergeResearchSources(decision.sources.flatMap((source) => {
+            const canonical = allowed.get(source.url);
+            return canonical ? [canonical] : [];
+        }));
+        if (sources.length === 0)
+            return [];
+        return [
+            {
+                outcome: decision.outcome,
+                summary: cleanEvidenceText(decision.summary, 240),
+                sources,
+                agent: cleanEvidenceText(agent, 120),
+            },
+        ];
+    });
+}
+/**
+ * Bound the cross-agent decision channel after grounding. Reviewer tasks finish
+ * concurrently, so sort before applying limits to keep the retained set stable.
+ */
+export function boundResearchDecisions(decisions) {
+    const sorted = [...decisions].sort((left, right) => {
+        const leftKey = `${left.agent}\0${left.outcome}\0${left.summary}\0${left.sources[0]?.url ?? ""}`;
+        const rightKey = `${right.agent}\0${right.outcome}\0${right.summary}\0${right.sources[0]?.url ?? ""}`;
+        return leftKey.localeCompare(rightKey);
+    });
+    const kept = sorted.slice(0, RESEARCH_DECISION_COUNT_LIMIT);
+    let omitted = sorted.length - kept.length;
+    while (kept.length > 0 &&
+        Buffer.byteLength(JSON.stringify(kept), "utf8") > RESEARCH_DECISION_BYTES_LIMIT) {
+        kept.pop();
+        omitted++;
+    }
+    return { decisions: kept, omitted };
+}
+/** 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));
+    const citedUrls = new Set(findings.flatMap((finding) => (finding.sources ?? []).flatMap((source) => (resultUrls.has(source.url) ? [source.url] : []))));
+    const decisions = provenance.decisions ?? [];
+    const decisionUrls = new Set(decisions.flatMap((decision) => decision.sources.flatMap((source) => (resultUrls.has(source.url) ? [source.url] : []))));
+    const utilizedUrls = new Set([...citedUrls, ...decisionUrls]);
+    return {
+        finalFindingsWithSources: findings.filter((finding) => (finding.sources ?? []).some((source) => resultUrls.has(source.url))).length,
+        citedResultCount: citedUrls.size,
+        supportedFindingCandidates: decisions.filter((decision) => decision.outcome === "supported-finding").length,
+        dismissedCandidates: decisions.filter((decision) => decision.outcome === "dismissed-candidate")
+            .length,
+        decisionResultCount: decisionUrls.size,
+        utilizedResultCount: utilizedUrls.size,
+        unusedResultCount: Math.max(0, resultUrls.size - utilizedUrls.size),
+    };
+}
+export function formatResearchUsefulness(usefulness) {
+    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`);
+}
+export function renderResearchUsefulnessMarkdown(provenance) {
+    const usefulness = provenance.usefulness;
+    if (!usefulness)
+        return "";
+    const totalUniqueResults = usefulness.utilizedResultCount + usefulness.unusedResultCount;
+    const lines = [
+        "### 📚 Documentation research usefulness",
+        "",
+        `- Final findings with grounded citations: **${usefulness.finalFindingsWithSources}**`,
+        `- Unique results cited by final findings: **${usefulness.citedResultCount}**`,
+        `- Candidate decisions: **${usefulness.supportedFindingCandidates} supported**, **${usefulness.dismissedCandidates} dismissed**`,
+        `- Unique results materially used: **${usefulness.utilizedResultCount}/${totalUniqueResults}**`,
+    ];
+    if (provenance.decisions?.length) {
+        lines.push("", "Grounded candidate decisions:");
+        for (const decision of provenance.decisions) {
+            const sources = decision.sources
+                .map((source) => `[${escapeMarkdownLabel(source.title)}](<${source.url}>)`)
+                .join(", ");
+            lines.push(`- **${decision.outcome === "supported-finding" ? "Supported finding" : "Dismissed candidate"}** (${escapeMarkdownLabel(decision.agent)}): ${escapeMarkdownLabel(decision.summary)} — ${sources}`);
+        }
+    }
+    return lines.join("\n");
+}
 export async function collectPlatformResearch(files, config) {
     const queries = deriveResearchQueries(files, config.maxQueries);
     if (!config.enabled || queries.length === 0) {