@expo/code-review-cli 0.12.2 → 0.12.4

package/build/core/review.js

@@ -18,7 +18,7 @@ import { errorMessage, sleep } from "./util.js";
 import { reviewSetupRefNotes } from "./config-refs.js";
 import { verifyFindings } from "./verify.js";
 import { applyInlineIgnores } from "./suppress.js";
-import { createResearchMcpRuntime, formatResearchProgress, groundResearchSources, mergeResearchSources, researchProvenanceFromAudit, renderResearchMarkdown, } from "./research.js";
+import { boundResearchDecisions, createResearchMcpRuntime, formatResearchProgress, formatResearchUsefulness, groundResearchDecisions, groundResearchSources, mergeResearchSources, researchProvenanceFromAudit, renderResearchMarkdown, renderResearchUsefulnessMarkdown, summarizeResearchUsefulness, } from "./research.js";
 /**
  * Filter changed files down to an explicit include set (exact-path membership, not
  * globs — scope assignment already happened in resolveScopes). With no include set,
@@ -307,6 +307,9 @@ export async function runReview(source, options) {
     // reviewers produced before the failure — partial findings are exactly what's
     // needed to debug a run that died mid-way.
     const agentFindings = {};
+    // Reviewer-declared, conclusion-only records of cases where documentation changed
+    // a concrete candidate decision. They remain inert until exact-source grounding.
+    const agentResearchDecisions = {};
     // Bounded, conclusion-only diagnostics for machine consumers of the hidden
     // comment state. These are deliberately separate from findings: they never reach
     // the coordinator, verification, policy, or decision paths.
@@ -521,6 +524,9 @@ export async function runReview(source, options) {
                 trackTokens(task.bucket, tokens);
                 trackModel(task.bucket, taskModel(task), model);
                 (agentFindings[task.bucket] ??= []).push(...value.findings);
+                if (value.researchDecisions) {
+                    (agentResearchDecisions[task.bucket] ??= []).push(...value.researchDecisions);
+                }
                 if (value.trace) {
                     mergeTraceNotes(agentTrace, task.bucket, value.trace);
                 }
@@ -644,6 +650,20 @@ export async function runReview(source, options) {
                 sourcesByFp.set(fp, mergeResearchSources(sourcesByFp.get(fp), finding.sources));
             }
         }
+        if (researchRecord) {
+            const groundedDecisions = Object.entries(agentResearchDecisions).flatMap(([agent, records]) => groundResearchDecisions(records, researchEvidence, agent));
+            const { decisions, omitted } = boundResearchDecisions(groundedDecisions);
+            if (decisions.length > 0)
+                researchRecord = { ...researchRecord, decisions };
+            if (omitted > 0) {
+                const warning = `${omitted} grounded research decision(s) omitted by output bounds`;
+                researchRecord = {
+                    ...researchRecord,
+                    warnings: [...researchRecord.warnings, warning],
+                };
+                progress(`  research: ${warning}`);
+            }
+        }
         // A substituted model means the review did not run on the model this repo
         // configured — the findings may be from a weaker (or free-tier) model entirely.
         // Never silent: it goes to the log, the coverage notes, and the run log.
@@ -734,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
@@ -903,6 +941,15 @@ export async function runReview(source, options) {
                 progress(`Author-reply adjudication failed (${errorMessage(error)}); continuing without it.`);
             }
         }
+        // Measure utility only after verification, suppression, citation carry-through,
+        // and feedback adjudication have produced the final finding set. Counts use
+        // unique audited URLs, not passages, so duplicate search hits cannot inflate them.
+        if (researchRecord) {
+            const usefulness = summarizeResearchUsefulness(researchRecord, output.findings);
+            researchRecord = { ...researchRecord, usefulness };
+            progress(formatResearchUsefulness(usefulness));
+            await appendStepSummary(renderResearchUsefulnessMarkdown(researchRecord));
+        }
         // Surface provider throttling as a fact about the run: passes already waited or
         // backed off, but the operator should still SEE that it happened (a run that
         // was rate-limited is slower and may carry partial passes — that's the cause).
@@ -947,6 +994,7 @@ export async function runReview(source, options) {
             coverageNotes,
             verifierDropped,
             requalificationStrips,
+            citationStrips,
             ...(rlTotal > 0
                 ? {
                     rateLimitEvents: rlTotal,

package/build/core/schema.js

@@ -17,6 +17,17 @@ export const FindingSourceSchema = z.object({
         .max(2_000)
         .refine((value) => new URL(value).protocol === "https:", "source URL must use HTTPS"),
 });
+export const RESEARCH_DECISION_OUTCOMES = ["supported-finding", "dismissed-candidate"];
+/**
+ * A reviewer-declared decision that documentation materially changed. Sources are
+ * later grounded against the MCP audit exactly like finding citations; an ungrounded
+ * record is discarded and can never inflate usefulness metrics.
+ */
+export const ResearchDecisionSchema = z.object({
+    outcome: z.enum(RESEARCH_DECISION_OUTCOMES),
+    summary: z.string().min(1).max(240),
+    sources: z.array(FindingSourceSchema).min(1).max(5),
+});
 export const FindingSchema = z.object({
     severity: z.enum(SEVERITIES),
     category: z.enum(CATEGORIES),
@@ -29,7 +40,7 @@ export const FindingSchema = z.object({
         .array(FindingSourceSchema)
         .max(5)
         .optional()
-        .describe("Exact documentation sources used to support this finding; copy title and URL from the injected research evidence and omit when unused"),
+        .describe("Exact documentation sources used to support this finding; copy the returned title and canonical URL from this review's MCP results and omit when unused"),
     /**
      * Verbatim snippet of the flagged code, copied from the file. Used to
      * quote-ground the finding: if this text isn't actually present in the file,
@@ -79,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
@@ -125,6 +142,7 @@ export const ReviewerTraceNotesSchema = z.object({
 const ReviewerModelOutputSchema = z.object({
     findings: z.array(ModelFindingSchema).default([]),
     trace: ReviewerTraceNotesSchema.optional(),
+    researchDecisions: z.array(ResearchDecisionSchema).max(8).optional(),
 });
 /**
  * Local trust boundary for reviewer output. Findings stay strict, while diagnostics
@@ -135,12 +153,18 @@ export const ReviewerOutputSchema = z
     .object({
     findings: z.array(ModelFindingSchema).default([]),
     trace: z.unknown().optional(),
+    researchDecisions: z.unknown().optional(),
 })
     .transform((output) => {
     const trace = ReviewerTraceNotesSchema.safeParse(output.trace);
+    const researchDecisions = z
+        .array(ResearchDecisionSchema)
+        .max(8)
+        .safeParse(output.researchDecisions);
     return {
         findings: output.findings,
         ...(trace.success ? { trace: trace.data } : {}),
+        ...(researchDecisions.success ? { researchDecisions: researchDecisions.data } : {}),
     };
 });
 export const ReviewTraceSchema = z.object({

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,7 +1,18 @@
 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;
 function delay(ms) {
     return new Promise((resolve) => setTimeout(resolve, ms));
 }
@@ -18,13 +29,19 @@ function boundedResult(result) {
         sourceKind: result.sourceKind,
         title: result.title.slice(0, 240),
         url: result.url.slice(0, 2_000),
-        passage: result.passage.slice(0, 1_400),
+        // This equals the direct-fetch document ceiling, so the artifact preserves the
+        // exact bounded text shown to the reviewer without ever storing the raw page.
+        passage: result.passage.slice(0, MAX_AUDITED_PASSAGE_CHARACTERS),
         ...(result.availability?.length
             ? { availability: result.availability.slice(0, 20).map((value) => value.slice(0, 240)) }
             : {}),
         ...(result.framework ? { framework: result.framework.slice(0, 240) } : {}),
         ...(result.language ? { language: result.language } : {}),
         ...(result.symbol ? { symbol: result.symbol.slice(0, 240) } : {}),
+        ...(result.previousPassageId
+            ? { previousPassageId: result.previousPassageId.slice(0, 240) }
+            : {}),
+        ...(result.nextPassageId ? { nextPassageId: result.nextPassageId.slice(0, 240) } : {}),
     };
 }
 /** Shared append-only audit and global request budget for all MCP processes in one review. */
@@ -90,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)
@@ -125,6 +150,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 = "";
@@ -133,10 +167,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;
@@ -154,10 +189,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/cli.js

@@ -17,7 +17,8 @@ Usage:
 The serve command uses BRAVE_SEARCH_API_KEY for scoped web discovery, fetches only
 allowlisted official pages, and optionally falls back to a local index. Expo-provider
 searches use Expo's public documentation index. Its fetch_platform_doc tool can fetch
-one exact allowlisted documentation URL without a search key. The update command is
+one exact allowlisted documentation URL without a search key and return focused,
+section, or bounded-document extracted context. The update command is
 an optional offline crawler for operator-managed fallback indexes.
 `);
 }

package/build/research-mcp/direct-fetch.js

@@ -6,6 +6,7 @@ import { buildSearchIndex, searchDocumentation } from "./search-index.js";
 /** Specific corpora precede their broader host/path parents during URL inference. */
 const DIRECT_PROVIDER_ORDER = [
     "apple-releases",
+    "sdwebimage",
     "apple",
     "swift-evolution",
     "android-releases",
@@ -28,6 +29,7 @@ const DIRECT_SOURCE_KIND = {
     apple: "official-api",
     "apple-releases": "release-notes",
     "swift-evolution": "official-guide",
+    sdwebimage: "official-api",
     android: "official-api",
     "android-releases": "release-notes",
     media3: "official-guide",
@@ -44,6 +46,48 @@ const DIRECT_SOURCE_KIND = {
     "react-native-screens": "official-guide",
     "react-native-worklets": "official-guide",
 };
+export const DIRECT_DOCUMENT_CONTEXT_MODES = ["focused", "section", "document"];
+const SECTION_CONTEXT_CHARACTERS = 12_000;
+const DOCUMENT_CONTEXT_CHARACTERS = 20_000;
+function withScore(chunk, score = 0) {
+    return { ...chunk, score };
+}
+function rankedAnchor(chunks, document, provider, query) {
+    if (!query?.trim())
+        return chunks[0] ? withScore(chunks[0]) : undefined;
+    const index = buildSearchIndex(chunks, 1);
+    return (searchDocumentation(index, query, {
+        platform: document.platform,
+        providers: [provider],
+        limit: 1,
+    })[0] ?? (chunks[0] ? withScore(chunks[0]) : undefined));
+}
+function contiguousWindow(body, anchor, maxCharacters) {
+    if (body.length <= maxCharacters)
+        return body;
+    const exactIndex = body.indexOf(anchor);
+    const prefixIndex = exactIndex >= 0 ? exactIndex : body.indexOf(anchor.slice(0, 160));
+    const anchorIndex = prefixIndex >= 0 ? prefixIndex : 0;
+    const centeredStart = Math.max(0, anchorIndex - Math.floor(maxCharacters / 3));
+    let start = centeredStart;
+    const previousBoundary = body.lastIndexOf("\n\n", centeredStart);
+    if (previousBoundary >= Math.max(0, centeredStart - 300))
+        start = previousBoundary + 2;
+    let end = Math.min(body.length, start + maxCharacters);
+    const nextBoundary = body.indexOf("\n\n", end - 300);
+    if (nextBoundary >= 0 && nextBoundary <= start + maxCharacters)
+        end = nextBoundary;
+    return body.slice(start, end).trim();
+}
+function focusedResults(chunks, anchor, limit) {
+    if (!anchor)
+        return [];
+    const anchorIndex = Math.max(0, chunks.findIndex((chunk) => chunk.id === anchor.id));
+    const start = Math.max(0, Math.min(anchorIndex - Math.floor(limit / 2), chunks.length - limit));
+    return chunks
+        .slice(start, start + limit)
+        .map((chunk) => withScore(chunk, chunk.id === anchor.id ? anchor.score : 0));
+}
 /** Resolve a caller-supplied URL against the fixed provider allowlist. */
 export function resolveDirectDocumentationTarget(rawUrl, providerHint) {
     assertSafeDocumentationUrlShape(rawUrl);
@@ -76,25 +120,41 @@ export async function fetchDocumentationUrl(rawUrl, options = {}) {
     const indexedAt = new Date().toISOString();
     const chunks = chunkDocument(document, indexedAt);
     const limit = Math.min(5, Math.max(1, options.limit ?? 3));
-    let results;
-    if (options.query?.trim()) {
-        const index = buildSearchIndex(chunks, 1, indexedAt);
-        results = searchDocumentation(index, options.query, {
-            platform: document.platform,
-            providers: [target.provider],
-            limit,
-        });
-        if (results.length === 0) {
-            results = chunks.slice(0, limit).map((chunk) => ({ ...chunk, score: 0 }));
-        }
+    const mode = options.context ?? "section";
+    const anchor = rankedAnchor(chunks, document, target.provider, options.query);
+    let results = [];
+    if (mode === "focused") {
+        results = focusedResults(chunks, anchor, limit);
     }
-    else {
-        results = chunks.slice(0, limit).map((chunk) => ({ ...chunk, score: 0 }));
+    else if (anchor) {
+        const maxCharacters = mode === "document" ? DOCUMENT_CONTEXT_CHARACTERS : SECTION_CONTEXT_CHARACTERS;
+        const passage = mode === "document"
+            ? document.body.slice(0, maxCharacters).trim()
+            : contiguousWindow(document.body, anchor.passage, maxCharacters);
+        const { previousPassageId: _previous, nextPassageId: _next, ...anchorWithoutNeighbors } = anchor;
+        results = [
+            {
+                ...anchorWithoutNeighbors,
+                id: `${anchor.id.replace(/#\d+$/, "")}#${mode}`,
+                passage,
+            },
+        ];
     }
+    const returnedCharacters = results.reduce((total, result) => total + result.passage.length, 0);
     return {
         provider: target.provider,
         sourceKind: target.sourceKind,
         canonicalUrl: target.url.href,
+        context: {
+            mode,
+            returnedCharacters,
+            documentCharacters: document.body.length,
+            truncated: returnedCharacters < document.body.length,
+            ...(anchor ? { anchorPassageId: anchor.id } : {}),
+            availablePassageCount: chunks.length,
+            availablePassageIds: chunks.slice(0, 100).map((chunk) => chunk.id),
+            ...(chunks.length > 100 ? { passageIdsTruncated: true } : {}),
+        },
         results,
     };
 }

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/html.js

@@ -128,11 +128,14 @@ export function chunkDocument(document, indexedAt, targetCharacters = 1400, over
         .update(`${document.provider ?? document.platform}\0${document.url}\0${document.title}`)
         .digest("hex")
         .slice(0, 16);
+    const passageId = (chunkIndex) => `${document.provider ?? document.platform}:${documentId}#${chunkIndex}`;
     return passages.map((passage, chunkIndex) => ({
         ...document,
         body: undefined,
-        id: `${document.provider ?? document.platform}:${documentId}#${chunkIndex}`,
+        id: passageId(chunkIndex),
         passage,
+        ...(chunkIndex > 0 ? { previousPassageId: passageId(chunkIndex - 1) } : {}),
+        ...(chunkIndex + 1 < passages.length ? { nextPassageId: passageId(chunkIndex + 1) } : {}),
         indexedAt,
     }));
 }

package/build/research-mcp/providers.js

@@ -130,6 +130,43 @@ export const swiftEvolutionProvider = {
         return documentUrl.hostname === "github.com" ? "markdown" : "html";
     },
 };
+const sdWebImageDocumentPrefix = "/documentation/sdwebimage";
+/** SDWebImage publishes a static DocC archive whose visible routes are JS shells. */
+export const sdWebImageProvider = {
+    id: "sdwebimage",
+    platform: "apple",
+    displayName: "SDWebImage documentation",
+    accepts(url) {
+        return (isSecurePublicUrl(url, "sdwebimage.github.io") &&
+            hasAllowedPath(url, [sdWebImageDocumentPrefix]));
+    },
+    acceptsRequest(url) {
+        if (this.accepts(url))
+            return true;
+        if (!isSecurePublicUrl(url, "sdwebimage.github.io") ||
+            !url.pathname.startsWith(`/data${sdWebImageDocumentPrefix}`) ||
+            !url.pathname.endsWith(".json")) {
+            return false;
+        }
+        const correspondingDocumentUrl = new URL(url.href);
+        correspondingDocumentUrl.pathname = url.pathname.slice("/data".length).replace(/\.json$/, "");
+        return hasAllowedPath(correspondingDocumentUrl, [sdWebImageDocumentPrefix]);
+    },
+    canonicalize(url) {
+        const hadTrailingSlash = url.pathname.endsWith("/");
+        const canonical = canonicalizeDocumentationUrl(url);
+        if (hadTrailingSlash && !canonical.pathname.endsWith("/"))
+            canonical.pathname += "/";
+        return canonical;
+    },
+    requestUrl(documentUrl) {
+        const documentPath = documentUrl.pathname.replace(/\/$/, "").toLowerCase();
+        return new URL(`/data${documentPath}.json`, documentUrl.origin);
+    },
+    responseFormat() {
+        return "docc-json";
+    },
+};
 const androidPrefixes = [
     "/build",
     "/develop",
@@ -272,6 +309,7 @@ const providers = {
     apple: appleProvider,
     "apple-releases": appleReleasesProvider,
     "swift-evolution": swiftEvolutionProvider,
+    sdwebimage: sdWebImageProvider,
     android: androidProvider,
     "android-releases": androidReleasesProvider,
     media3: media3Provider,

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)