@expo/code-review-cli 0.12.1 → 0.12.2

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

@@ -0,0 +1,146 @@
+const MAX_QUERY_CHARACTERS = 160;
+const MAX_QUERY_TOKENS = 8;
+const MAX_TOKEN_CHARACTERS = 64;
+const SECRET_SHAPE = /(?:-----BEGIN [A-Z ]*PRIVATE KEY-----|\bAKIA[0-9A-Z]{16}\b|\b(?:sk|xox[baprs]|gh[opusr])[-_][A-Za-z0-9_-]{12,}\b|\beyJ[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\b)/i;
+const NAMED_SECRET = /\b(?:api[-_ ]?key|access[-_ ]?token|auth[-_ ]?token|password|passwd|secret|credential)\b\s*(?::|=|is)?\s*\S+/i;
+const QUOTED_LITERAL = /"(?:\\.|[^"\\])*"|'(?:\\.|[^'\\])*'|`(?:\\.|[^`\\])*`/g;
+const URL_OR_EMAIL = /\b(?:https?:\/\/|www\.)\S+|\b[^\s@]+@[^\s@]+\.[^\s@]+\b/gi;
+const PATH_LIKE = /(?:^|\s)(?:\.{0,2}[\\/]|[A-Za-z]:[\\/]|~[\\/])\S+/g;
+const QUERY_TOKEN = /[A-Za-z_][A-Za-z0-9_.:$#<>()[\]-]{0,63}|\b\d{1,4}(?:\.\d{1,3}){0,2}\b/g;
+const PROSE_STOP_WORDS = new Set([
+    "a",
+    "about",
+    "an",
+    "and",
+    "are",
+    "can",
+    "could",
+    "do",
+    "does",
+    "documentation",
+    "explain",
+    "find",
+    "for",
+    "from",
+    "how",
+    "i",
+    "in",
+    "is",
+    "it",
+    "of",
+    "on",
+    "or",
+    "please",
+    "search",
+    "show",
+    "tell",
+    "the",
+    "this",
+    "to",
+    "what",
+    "when",
+    "where",
+    "why",
+    "with",
+    "work",
+    "works",
+]);
+function shannonEntropy(value) {
+    const counts = new Map();
+    for (const character of value)
+        counts.set(character, (counts.get(character) ?? 0) + 1);
+    let entropy = 0;
+    for (const count of counts.values()) {
+        const probability = count / value.length;
+        entropy -= probability * Math.log2(probability);
+    }
+    return entropy;
+}
+function looksHighEntropy(value) {
+    if (/^[A-Fa-f0-9]{24,}$/.test(value))
+        return true;
+    if (/^[A-Za-z0-9+/]{20,}={0,2}$/.test(value) && /[+/=]/.test(value))
+        return true;
+    return (value.length >= 24 &&
+        /[a-z]/.test(value) &&
+        /[A-Z]/.test(value) &&
+        /\d/.test(value) &&
+        shannonEntropy(value) >= 4.2);
+}
+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));
+}
+/**
+ * Convert an agent-authored search into a short API-symbol query. Dangerous shapes
+ * fail closed; prose, literals, URLs, paths, and unsupported punctuation are removed.
+ */
+export function sanitizeDocumentationQuery(rawQuery) {
+    const visible = rawQuery
+        .normalize("NFKC")
+        // oxlint-disable-next-line no-control-regex -- outbound query containment
+        .replace(/[\u0000-\u001f\u007f]/g, " ")
+        .replace(/\s+/g, " ")
+        .trim();
+    if (!visible || visible.length > 300) {
+        throw new Error("Query must contain between 1 and 300 visible characters");
+    }
+    if (SECRET_SHAPE.test(visible) || NAMED_SECRET.test(visible)) {
+        throw new Error("Query contains credential-shaped or secret-labeled material");
+    }
+    const candidates = (visible
+        .replace(QUOTED_LITERAL, " ")
+        .replace(URL_OR_EMAIL, " ")
+        .replace(PATH_LIKE, " ")
+        .match(QUERY_TOKEN) ?? []).filter((token) => {
+        if (token.length > MAX_TOKEN_CHARACTERS || looksHighEntropy(token))
+            return false;
+        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");
+    }
+    const sanitized = unique.join(" ").slice(0, MAX_QUERY_CHARACTERS).trim();
+    if (!sanitized)
+        throw new Error("Query contained no safe documentation terms");
+    return sanitized;
+}
+/** Reject URL decorations and path segments that could encode arbitrary outbound data. */
+export function assertSafeDocumentationUrlShape(rawUrl) {
+    let url;
+    try {
+        url = new URL(rawUrl);
+    }
+    catch {
+        throw new Error("Invalid documentation URL");
+    }
+    if (url.protocol !== "https:" || url.username || url.password || url.port) {
+        throw new Error("Documentation URL must use plain HTTPS without credentials or a port");
+    }
+    if (url.search || url.hash) {
+        throw new Error("Documentation URL must not contain a query string or fragment");
+    }
+    const segments = url.pathname.split("/").filter(Boolean);
+    for (const segment of segments) {
+        let decoded;
+        try {
+            decoded = decodeURIComponent(segment);
+        }
+        catch {
+            throw new Error("Documentation URL contains an invalid encoded path segment");
+        }
+        // oxlint-disable-next-line no-control-regex -- URL path is an outbound data boundary
+        const containsControlCharacter = /[\\/\u0000-\u001f\u007f]/.test(decoded);
+        if (decoded.length > 120 ||
+            containsControlCharacter ||
+            SECRET_SHAPE.test(decoded) ||
+            NAMED_SECRET.test(decoded) ||
+            looksHighEntropy(decoded)) {
+            throw new Error("Documentation URL contains a suspicious path segment");
+        }
+    }
+    return url;
+}

package/build/research-mcp/server.js

@@ -1,6 +1,9 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { z } from "zod";
+import { ResearchAudit } from "./audit.js";
+import { sanitizeDocumentationQuery } from "./query-sanitizer.js";
+import { fetchDocumentationUrl, resolveDirectDocumentationTarget } from "./direct-fetch.js";
 import { searchExpoAlgolia } from "./expo-algolia.js";
 import { searchOkHttpDocumentation } from "./okhttp-search.js";
 import { getProvider, resolveAllowedUrl } from "./providers.js";
@@ -20,6 +23,9 @@ function defaultProviders(platform) {
 }
 export async function createDocumentationServer(options = {}) {
     const index = options.indexPath ? await loadSearchIndex(options.indexPath) : undefined;
+    const maxCalls = Math.min(20, Math.max(1, options.maxCalls ?? 8));
+    const maxResultsPerCall = Math.min(3, Math.max(1, options.maxResultsPerCall ?? 3));
+    const audit = new ResearchAudit(options.auditPath, maxCalls);
     const server = new McpServer({
         name: "review-research-mcp",
         version: "0.2.0",
@@ -58,130 +64,222 @@ export async function createDocumentationServer(options = {}) {
             openWorldHint: true,
         },
     }, async ({ platform, query, limit, language, providers, sourceKinds }) => {
+        const sanitizedQuery = sanitizeDocumentationQuery(query);
         const selectedProviders = (providers ?? defaultProviders(platform)).filter((provider) => platform === "all" || getProvider(provider).platform === platform);
-        const localResults = index
-            ? searchDocumentation(index, query, {
-                platform,
-                limit,
-                providers: selectedProviders,
-                ...(sourceKinds ? { sourceKinds } : {}),
-                ...(language ? { language } : {}),
-            })
-            : [];
-        const warnings = [];
-        const remoteResults = [];
-        const perProviderLimit = Math.max(1, Math.ceil(limit / selectedProviders.length));
-        const indexedAt = new Date().toISOString();
-        const searched = await Promise.all(selectedProviders.map(async (provider) => {
-            if (provider === "expo") {
-                if (sourceKinds && !sourceKinds.includes("official-api")) {
-                    return { results: [], warnings: [] };
+        if (selectedProviders.length === 0) {
+            throw new Error("No selected documentation provider matches the requested platform");
+        }
+        const boundedLimit = Math.min(limit, maxResultsPerCall);
+        const auditInput = {
+            platform,
+            providers: selectedProviders,
+            query: sanitizedQuery,
+        };
+        const requestId = await audit.reserve("search_platform_docs", auditInput);
+        try {
+            const localResults = index
+                ? searchDocumentation(index, sanitizedQuery, {
+                    platform,
+                    limit: boundedLimit,
+                    providers: selectedProviders,
+                    ...(sourceKinds ? { sourceKinds } : {}),
+                    ...(language ? { language } : {}),
+                })
+                : [];
+            const warnings = [];
+            const remoteResults = [];
+            const perProviderLimit = Math.max(1, Math.ceil(boundedLimit / selectedProviders.length));
+            const indexedAt = new Date().toISOString();
+            const searched = await Promise.all(selectedProviders.map(async (provider) => {
+                if (provider === "expo") {
+                    if (sourceKinds && !sourceKinds.includes("official-api")) {
+                        return { results: [], warnings: [] };
+                    }
+                    try {
+                        const documents = await searchExpoAlgolia(sanitizedQuery, perProviderLimit);
+                        return {
+                            results: documents.map((document, position) => ({
+                                id: `expo-algolia:${document.url}`,
+                                platform: document.platform,
+                                provider: "expo",
+                                sourceKind: "official-api",
+                                title: document.title,
+                                url: document.url,
+                                passage: document.body.slice(0, 1_400),
+                                indexedAt,
+                                score: perProviderLimit - position,
+                            })),
+                            warnings: [],
+                        };
+                    }
+                    catch (error) {
+                        const message = error instanceof Error ? error.message : String(error);
+                        return {
+                            results: [],
+                            warnings: [`Expo documentation search unavailable: ${message}`],
+                        };
+                    }
                 }
-                try {
-                    const documents = await searchExpoAlgolia(query, perProviderLimit);
+                if (provider === "okhttp" &&
+                    (!sourceKinds || sourceKinds.includes("official-guide")) &&
+                    !language) {
+                    try {
+                        const results = await searchOkHttpDocumentation(sanitizedQuery, perProviderLimit, options.fetchImplementation ?? fetch);
+                        if (results.length > 0) {
+                            return { results, warnings: [] };
+                        }
+                    }
+                    catch (error) {
+                        const message = error instanceof Error ? error.message : String(error);
+                        warnings.push(`OkHttp documentation search unavailable: ${message}`);
+                    }
+                }
+                if (!options.braveApiKey) {
                     return {
-                        results: documents.map((document, position) => ({
-                            id: `expo-algolia:${document.url}`,
-                            platform: document.platform,
-                            provider: "expo",
-                            sourceKind: "official-api",
-                            title: document.title,
-                            url: document.url,
-                            passage: document.body.slice(0, 1_400),
-                            indexedAt,
-                            score: perProviderLimit - position,
-                        })),
-                        warnings: [],
+                        results: [],
+                        warnings: [
+                            `Scoped web search unavailable for ${provider}: BRAVE_SEARCH_API_KEY is not set`,
+                        ],
                     };
                 }
+                try {
+                    return await searchRemoteDocumentation(provider, sanitizedQuery, perProviderLimit, {
+                        apiKey: options.braveApiKey,
+                        ...(options.fetchImplementation
+                            ? { fetchImplementation: options.fetchImplementation }
+                            : {}),
+                        ...(language ? { language } : {}),
+                        ...(sourceKinds ? { sourceKinds } : {}),
+                    });
+                }
                 catch (error) {
                     const message = error instanceof Error ? error.message : String(error);
                     return {
                         results: [],
-                        warnings: [`Expo documentation search unavailable: ${message}`],
+                        warnings: [`Scoped web search unavailable for ${provider}: ${message}`],
                     };
                 }
+            }));
+            for (const searchedProvider of searched) {
+                remoteResults.push(...searchedProvider.results);
+                warnings.push(...searchedProvider.warnings);
             }
-            if (provider === "okhttp" &&
-                (!sourceKinds || sourceKinds.includes("official-guide")) &&
-                !language) {
+            const seen = new Set();
+            const results = [...remoteResults, ...localResults]
+                .filter((result) => {
+                if (!result.provider)
+                    return false;
                 try {
-                    const results = await searchOkHttpDocumentation(query, perProviderLimit, options.fetchImplementation ?? fetch);
-                    if (results.length > 0) {
-                        return { results, warnings: [] };
-                    }
+                    resolveAllowedUrl(getProvider(result.provider), result.url);
                 }
-                catch (error) {
-                    const message = error instanceof Error ? error.message : String(error);
-                    warnings.push(`OkHttp documentation search unavailable: ${message}`);
+                catch {
+                    return false;
                 }
-            }
-            if (!options.braveApiKey) {
-                return {
-                    results: [],
-                    warnings: [
-                        `Scoped web search unavailable for ${provider}: BRAVE_SEARCH_API_KEY is not set`,
-                    ],
-                };
-            }
-            try {
-                return await searchRemoteDocumentation(provider, query, perProviderLimit, {
-                    apiKey: options.braveApiKey,
-                    ...(options.fetchImplementation
-                        ? { fetchImplementation: options.fetchImplementation }
-                        : {}),
-                    ...(language ? { language } : {}),
-                    ...(sourceKinds ? { sourceKinds } : {}),
-                });
-            }
-            catch (error) {
-                const message = error instanceof Error ? error.message : String(error);
-                return {
-                    results: [],
-                    warnings: [`Scoped web search unavailable for ${provider}: ${message}`],
-                };
-            }
-        }));
-        for (const searchedProvider of searched) {
-            remoteResults.push(...searchedProvider.results);
-            warnings.push(...searchedProvider.warnings);
+                const key = `${result.provider}|${result.url}|${result.title}`;
+                if (seen.has(key))
+                    return false;
+                seen.add(key);
+                return true;
+            })
+                .slice(0, boundedLimit);
+            const uniqueWarnings = [...new Set(warnings)].slice(0, 10);
+            const payload = {
+                notice: untrustedMaterialNotice,
+                retrieval: {
+                    scopedWebSearch: Boolean(options.braveApiKey),
+                    expoSearch: selectedProviders.includes("expo"),
+                    localIndex: index
+                        ? {
+                            generatedAt: index.serialized.generatedAt,
+                            providers: index.serialized.providers,
+                        }
+                        : null,
+                },
+                ...(uniqueWarnings.length > 0 ? { warnings: uniqueWarnings } : {}),
+                results,
+            };
+            await audit.complete(requestId, "search_platform_docs", auditInput, results, uniqueWarnings);
+            return {
+                content: [{ type: "text", text: JSON.stringify(payload, null, 2) }],
+            };
         }
-        const seen = new Set();
-        const results = [...remoteResults, ...localResults]
-            .filter((result) => {
-            if (!result.provider)
-                return false;
-            try {
-                resolveAllowedUrl(getProvider(result.provider), result.url);
-            }
-            catch {
-                return false;
-            }
-            const key = `${result.provider}|${result.url}|${result.title}`;
-            if (seen.has(key))
-                return false;
-            seen.add(key);
-            return true;
-        })
-            .slice(0, limit);
-        const payload = {
-            notice: untrustedMaterialNotice,
-            retrieval: {
-                scopedWebSearch: Boolean(options.braveApiKey),
-                expoSearch: selectedProviders.includes("expo"),
-                localIndex: index
-                    ? {
-                        generatedAt: index.serialized.generatedAt,
-                        providers: index.serialized.providers,
-                    }
-                    : null,
-            },
-            ...(warnings.length > 0 ? { warnings: [...new Set(warnings)].slice(0, 10) } : {}),
-            results,
-        };
-        return {
-            content: [{ type: "text", text: JSON.stringify(payload, null, 2) }],
+        catch (error) {
+            await audit.fail(requestId, "search_platform_docs", auditInput, error);
+            throw error;
+        }
+    });
+    server.registerTool("fetch_platform_doc", {
+        title: "Fetch an official documentation URL",
+        description: "Fetch one caller-supplied documentation URL from the fixed Apple, Android, Expo, React Native, dependency, build-tool, release-note, or issue-source allowlist. The URL and every redirect are revalidated before download. Returns bounded extracted passages and the canonical source URL; use query only to rank passages within that page.",
+        inputSchema: {
+            url: z
+                .string()
+                .url()
+                .max(2_000)
+                .describe("Exact HTTPS documentation URL to fetch; must match a supported provider"),
+            provider: z
+                .enum(PROVIDERS)
+                .optional()
+                .describe("Optional provider hint for URLs accepted by more than one corpus"),
+            query: z
+                .string()
+                .min(1)
+                .max(300)
+                .optional()
+                .describe("Optional short phrase used only to select the most relevant page passages"),
+            limit: z.number().int().min(1).max(5).default(3),
+        },
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: true,
+        },
+    }, async ({ url, provider, query, limit }) => {
+        const sanitizedQuery = query ? sanitizeDocumentationQuery(query) : undefined;
+        // Resolve and validate before recording anything. This prevents credentials,
+        // query strings, or covert high-entropy path data from reaching either the
+        // network or the append-only audit file.
+        const target = resolveDirectDocumentationTarget(url, provider);
+        const auditInput = {
+            providers: [target.provider],
+            ...(sanitizedQuery ? { query: sanitizedQuery } : {}),
+            url: target.url.href,
         };
+        const requestId = await audit.reserve("fetch_platform_doc", auditInput);
+        try {
+            const fetched = await fetchDocumentationUrl(target.url.href, {
+                provider: target.provider,
+                ...(sanitizedQuery ? { query: sanitizedQuery } : {}),
+                limit: Math.min(limit, maxResultsPerCall),
+                ...(options.fetchImplementation
+                    ? { fetchImplementation: options.fetchImplementation }
+                    : {}),
+            });
+            const payload = {
+                notice: untrustedMaterialNotice,
+                retrieval: {
+                    mode: "direct-url",
+                    provider: fetched.provider,
+                    sourceKind: fetched.sourceKind,
+                    canonicalUrl: fetched.canonicalUrl,
+                },
+                results: fetched.results,
+            };
+            await audit.complete(requestId, "fetch_platform_doc", {
+                ...auditInput,
+                platform: getProvider(fetched.provider).platform,
+                providers: [fetched.provider],
+                url: fetched.canonicalUrl,
+            }, fetched.results);
+            return {
+                content: [{ type: "text", text: JSON.stringify(payload, null, 2) }],
+            };
+        }
+        catch (error) {
+            await audit.fail(requestId, "fetch_platform_doc", auditInput, error);
+            throw error;
+        }
     });
     return server;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@expo/code-review-cli",
-  "version": "0.12.1",
+  "version": "0.12.2",
   "description": "Generic, config-driven AI code reviewer engine. Repos supply their agents via .expo-code-review/.",
   "license": "MIT",
   "repository": {

package/templates/coordinator.md

@@ -34,6 +34,8 @@ metadata. You do **not** re-review the code. You consolidate and decide.
    field from the final finding after folding it into `rationale`; otherwise the
    reporter detaches it below the collapsed block. Infer conservatively when a
    reviewer omitted either signal. Drop low-confidence findings.
+   Preserve each kept finding's grounded `sources` array. When merging duplicates,
+   keep the union of their existing sources. Never invent or edit a source.
 <!-- @ref LLP 0009#prompt-rules-for-adopters [implements] — the handoff is summary input only, never a reported finding and never a decision input -->
 4. **Extract overall PR risk.** Find the internal `__overall_pr_risk__` handoff
    from the cross-cutting reviewer, or from the full-context security reviewer

package/templates/shared.md

@@ -215,7 +215,8 @@ Return **only** a single fenced ```json code block, an object of this shape:
       "title": "short one-line summary",
       "rationale": "**Confidence:** High — why certainty is high.<br>**Impact if shipped:** Medium — concrete expected consequence.\\n\\n<details>\\n<summary>Evidence and reasoning</summary>\\n\\nFull failure/exploit path.\\n\\n</details>",
       "evidence": "one contiguous line of the flagged code, copied VERBATIM",
-      "suggestion": "optional concrete fix, or omit"
+      "suggestion": "optional concrete fix, or omit",
+      "sources": [{ "title": "exact injected documentation title", "url": "exact injected URL" }]
     }
   ],
   "trace": {
@@ -225,6 +226,11 @@ Return **only** a single fenced ```json code block, an object of this shape:
 }
 ```
 
+`sources` is optional. Include it only when injected platform research materially
+supports the finding. Copy the exact title and URL from that research; the engine
+rejects sources outside the trusted result set. Omit it for findings that did not
+use documentation research.
+
 `line` is the start line in the new version of the file, or `null` if not
 line-specific. `evidence` is used to help verify the finding, so make it easy to
 locate: copy **one contiguous line** of the flagged code **verbatim** (not spanning