@expo/code-review-cli 0.11.1 → 0.12.1

package/build/research-mcp/apple-docc.js

@@ -0,0 +1,161 @@
+function objectValue(value) {
+    return value && typeof value === "object" && !Array.isArray(value)
+        ? value
+        : null;
+}
+function inlineText(value) {
+    if (!Array.isArray(value))
+        return "";
+    return value
+        .map((item) => {
+        const object = objectValue(item);
+        return object && typeof object.text === "string" ? object.text : "";
+    })
+        .join("")
+        .trim();
+}
+function cleanBlock(value) {
+    return value.replace(/\s+/g, " ").trim();
+}
+function referenceTitle(identifier, references) {
+    if (typeof identifier !== "string")
+        return "";
+    const reference = objectValue(references?.[identifier]);
+    return typeof reference?.title === "string" ? reference.title : "";
+}
+function inlineContentText(value, references) {
+    if (Array.isArray(value)) {
+        return value.map((item) => inlineContentText(item, references)).join("");
+    }
+    const object = objectValue(value);
+    if (!object)
+        return "";
+    if (typeof object.text === "string")
+        return object.text;
+    if (typeof object.code === "string")
+        return object.code;
+    if (object.type === "reference")
+        return referenceTitle(object.identifier, references);
+    return Object.values(object)
+        .map((child) => inlineContentText(child, references))
+        .join("");
+}
+function collectReadableBlocks(value, references, output) {
+    if (Array.isArray(value)) {
+        for (const item of value)
+            collectReadableBlocks(item, references, output);
+        return;
+    }
+    const object = objectValue(value);
+    if (!object)
+        return;
+    if (Array.isArray(object.tokens)) {
+        const declaration = cleanBlock(inlineContentText(object.tokens, references));
+        if (declaration)
+            output.push(declaration);
+        return;
+    }
+    if (object.type === "paragraph") {
+        const paragraph = cleanBlock(inlineContentText(object.inlineContent, references));
+        if (paragraph)
+            output.push(paragraph);
+        return;
+    }
+    if (object.type === "heading" && typeof object.text === "string") {
+        const heading = cleanBlock(object.text);
+        if (heading)
+            output.push(heading);
+        return;
+    }
+    if (object.type === "codeListing" && Array.isArray(object.code)) {
+        const code = object.code.filter((line) => typeof line === "string").join("\n");
+        if (code.trim())
+            output.push(code.trim());
+        return;
+    }
+    if (typeof object.name === "string" && Array.isArray(object.content)) {
+        const content = [];
+        collectReadableBlocks(object.content, references, content);
+        const body = content.join("\n\n");
+        output.push(body ? `${object.name}: ${body}` : object.name);
+        return;
+    }
+    if (object.type === "aside" && Array.isArray(object.content)) {
+        const content = [];
+        collectReadableBlocks(object.content, references, content);
+        const label = typeof object.name === "string"
+            ? object.name
+            : typeof object.style === "string"
+                ? object.style
+                : "Note";
+        if (content.length > 0)
+            output.push(`${label}: ${content.join("\n\n")}`);
+        return;
+    }
+    for (const child of Object.values(object)) {
+        collectReadableBlocks(child, references, output);
+    }
+}
+function languageFromIdentifier(identifier) {
+    const language = identifier?.interfaceLanguage;
+    if (language === "swift")
+        return "swift";
+    if (language === "occ" || language === "objective-c")
+        return "objective-c";
+    return undefined;
+}
+export function extractAppleDocCPage(json, url, source = {}) {
+    const root = objectValue(JSON.parse(json));
+    const metadata = objectValue(root?.metadata);
+    const identifier = objectValue(root?.identifier);
+    const title = typeof metadata?.title === "string" ? metadata.title.trim() : "";
+    if (!root || !metadata || !title)
+        return null;
+    const text = [];
+    const abstract = inlineText(root.abstract);
+    if (abstract)
+        text.push(abstract);
+    const references = objectValue(root.references);
+    collectReadableBlocks(root.primaryContentSections, references, text);
+    collectReadableBlocks(root.relationshipsSections, references, text);
+    const links = new Set();
+    for (const value of Object.values(references ?? {})) {
+        const reference = objectValue(value);
+        if (!reference || typeof reference.url !== "string")
+            continue;
+        if (reference.url.startsWith("/documentation/")) {
+            links.add(reference.url);
+        }
+    }
+    const body = [...new Set(text.map(cleanBlock).filter(Boolean))].join("\n\n");
+    if (body.length < 40)
+        return null;
+    const platforms = Array.isArray(metadata.platforms) ? metadata.platforms : [];
+    const availability = platforms.flatMap((item) => {
+        const platform = objectValue(item);
+        if (!platform || typeof platform.name !== "string")
+            return [];
+        const introduced = typeof platform.introducedAt === "string" ? ` ${platform.introducedAt}` : "";
+        const deprecated = typeof platform.deprecatedAt === "string" ? ` (deprecated ${platform.deprecatedAt})` : "";
+        return [`${platform.name}${introduced}${deprecated}`];
+    });
+    const modules = Array.isArray(metadata.modules) ? metadata.modules : [];
+    const firstModule = objectValue(modules[0]);
+    const isSymbol = metadata.role === "symbol" || typeof metadata.symbolKind === "string";
+    return {
+        document: {
+            platform: "apple",
+            ...source,
+            title,
+            url,
+            body,
+            ...(typeof firstModule?.name === "string" ? { framework: firstModule.name } : {}),
+            ...(isSymbol ? { symbol: title } : {}),
+            ...(languageFromIdentifier(identifier)
+                ? { language: languageFromIdentifier(identifier) }
+                : {}),
+            ...(availability.length > 0 ? { availability } : {}),
+        },
+        links: [...links],
+    };
+}

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

@@ -0,0 +1,77 @@
+import { z } from "zod";
+import { readBodyWithLimit } from "./response.js";
+const BRAVE_SEARCH_ENDPOINT = "https://api.search.brave.com/res/v1/web/search";
+const BRAVE_RESPONSE_LIMIT_BYTES = 1_000_000;
+const BRAVE_TIMEOUT_MS = 10_000;
+const braveResponseSchema = z.object({
+    web: z
+        .object({
+        results: z
+            .array(z.object({
+            title: z.string().min(1).max(500),
+            url: z.string().url().max(2_000),
+            description: z.string().max(2_000).optional(),
+        }))
+            .max(50),
+    })
+        .optional(),
+});
+function normalizeSearchText(value) {
+    return (value
+        // oxlint-disable-next-line no-control-regex -- outbound query sanitization
+        .replace(/[\u0000-\u001f\u007f]/g, " ")
+        .replace(/\s+/g, " ")
+        .trim());
+}
+export function buildScopedSearchQuery(query, scopes) {
+    const normalized = normalizeSearchText(query);
+    if (!normalized || normalized.length > 300) {
+        throw new Error("Query must contain between 1 and 300 visible characters");
+    }
+    if (scopes.length === 0 || scopes.length > 8) {
+        throw new Error("A documentation search requires between 1 and 8 fixed scopes");
+    }
+    const scopeExpression = scopes.length === 1
+        ? `site:${scopes[0]}`
+        : `(${scopes.map((scope) => `site:${scope}`).join(" OR ")})`;
+    const scopedQuery = `${scopeExpression} ${normalized}`;
+    if (scopedQuery.length > 400 || scopedQuery.split(/\s+/).length > 50) {
+        throw new Error("Scoped query exceeds Brave Search limits");
+    }
+    return scopedQuery;
+}
+export async function searchBrave(query, scopes, limit, apiKey, fetchImplementation = fetch) {
+    if (!apiKey.trim()) {
+        throw new Error("BRAVE_SEARCH_API_KEY is not set");
+    }
+    if (!Number.isInteger(limit) || limit < 1 || limit > 10) {
+        throw new Error("Search result limit must be between 1 and 10");
+    }
+    const url = new URL(BRAVE_SEARCH_ENDPOINT);
+    url.searchParams.set("q", buildScopedSearchQuery(query, scopes));
+    url.searchParams.set("count", String(limit));
+    url.searchParams.set("search_lang", "en");
+    url.searchParams.set("safesearch", "moderate");
+    const response = await fetchImplementation(url, {
+        redirect: "manual",
+        signal: AbortSignal.timeout(BRAVE_TIMEOUT_MS),
+        headers: {
+            accept: "application/json",
+            "accept-encoding": "gzip",
+            "x-subscription-token": apiKey,
+            "user-agent": "review-research-mcp/0.2 (+scoped documentation search)",
+        },
+    });
+    if (response.status >= 300 && response.status < 400) {
+        throw new Error(`Brave Search unexpectedly redirected with HTTP ${response.status}`);
+    }
+    if (!response.ok) {
+        throw new Error(`Brave Search returned HTTP ${response.status}`);
+    }
+    const contentType = response.headers.get("content-type")?.toLowerCase() ?? "";
+    if (!contentType.includes("application/json")) {
+        throw new Error(`Brave Search returned unsupported content type: ${contentType || "missing"}`);
+    }
+    const parsed = braveResponseSchema.parse(JSON.parse(await readBodyWithLimit(response, BRAVE_RESPONSE_LIMIT_BYTES)));
+    return parsed.web?.results ?? [];
+}

package/build/research-mcp/cli.js

@@ -0,0 +1,89 @@
+#!/usr/bin/env node
+// @ref LLP 0013#one-package-two-binaries [implements] — the package's second binary owns serve/update dispatch
+// @ref LLP 0013#search-fetch-and-optional-index-boundary [implements] — review-facing serve and operator-only update stay separate
+import { parseArgs } from "node:util";
+import { defaultConfigPath } from "./paths.js";
+import { runStdioServer } from "./server.js";
+import { PLATFORMS } from "./types.js";
+function printHelp() {
+    process.stdout.write(`review-research-mcp
+
+Usage:
+  review-research-mcp [serve]
+  review-research-mcp serve [--index PATH]
+  review-research-mcp update [--config PATH] [--output PATH]
+                             [--platform apple|android|react-native] [--max-pages NUMBER]
+
+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. The update command is an optional
+offline crawler for operator-managed fallback indexes.
+`);
+}
+async function main() {
+    const [command = "serve", ...rest] = process.argv.slice(2);
+    if (command === "--help" || command === "-h" || command === "help") {
+        printHelp();
+        return;
+    }
+    if (command === "serve") {
+        if (rest.includes("--help") || rest.includes("-h")) {
+            printHelp();
+            return;
+        }
+        const { values } = parseArgs({
+            args: rest,
+            options: {
+                index: { type: "string" },
+            },
+            strict: true,
+        });
+        const indexPath = values.index ?? process.env.REVIEW_RESEARCH_INDEX_PATH;
+        await runStdioServer({
+            ...(indexPath ? { indexPath } : {}),
+            ...(process.env.BRAVE_SEARCH_API_KEY
+                ? { braveApiKey: process.env.BRAVE_SEARCH_API_KEY }
+                : {}),
+        });
+        return;
+    }
+    if (command === "update") {
+        if (rest.includes("--help") || rest.includes("-h")) {
+            printHelp();
+            return;
+        }
+        const { values } = parseArgs({
+            args: rest,
+            options: {
+                config: { type: "string" },
+                output: { type: "string" },
+                platform: { type: "string", multiple: true },
+                "max-pages": { type: "string" },
+            },
+            strict: true,
+        });
+        const invalidPlatform = values.platform?.find((platform) => !PLATFORMS.includes(platform));
+        if (invalidPlatform) {
+            throw new Error(`Unknown platform: ${invalidPlatform}`);
+        }
+        const maxPages = values["max-pages"] ? Number(values["max-pages"]) : undefined;
+        if (maxPages !== undefined && (!Number.isInteger(maxPages) || maxPages < 1)) {
+            throw new Error("--max-pages must be a positive integer");
+        }
+        const { updateDocumentationIndex } = await import("./crawler.js");
+        const result = await updateDocumentationIndex({
+            configPath: values.config ?? defaultConfigPath,
+            ...(values.output ? { outputPath: values.output } : {}),
+            ...(values.platform ? { platforms: values.platform } : {}),
+            ...(maxPages ? { maxPagesPerProvider: maxPages } : {}),
+        });
+        process.stderr.write(`${JSON.stringify(result, null, 2)}\n`);
+        return;
+    }
+    throw new Error(`Unknown command: ${command}`);
+}
+main().catch((error) => {
+    const message = error instanceof Error ? error.message : String(error);
+    process.stderr.write(`review-research-mcp: ${message}\n`);
+    process.exitCode = 1;
+});

package/build/research-mcp/crawler.js

@@ -0,0 +1,148 @@
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+import { z } from "zod";
+import { extractAppleDocCPage } from "./apple-docc.js";
+import { fetchAllowedContent } from "./fetch-document.js";
+import { chunkDocument, extractDocumentationPage } from "./html.js";
+import { extractMarkdownDocumentationPage } from "./markdown.js";
+import { getProvider, resolveAllowedUrl } from "./providers.js";
+import { buildSearchIndex, writeSearchIndex } from "./search-index.js";
+import { extractYouTrackIssue } from "./youtrack.js";
+import { PLATFORMS, PROVIDERS, SOURCE_KINDS, } from "./types.js";
+const sourcesConfigSchema = z.object({
+    output: z.string().min(1),
+    crawl: z.object({
+        maxPagesPerProvider: z.number().int().min(1).max(100_000),
+        maxDepth: z.number().int().min(0).max(20),
+        delayMs: z.number().int().min(0).max(60_000),
+        timeoutMs: z.number().int().min(100).max(120_000),
+        maxResponseBytes: z.number().int().min(1_024).max(20_000_000),
+    }),
+    sources: z
+        .array(z.object({
+        provider: z.enum(PROVIDERS),
+        sourceKind: z.enum(SOURCE_KINDS),
+        seedUrls: z.array(z.string().url()).min(1),
+        maxPages: z.number().int().min(1).max(100_000).optional(),
+        maxDepth: z.number().int().min(0).max(20).optional(),
+    }))
+        .min(1),
+});
+function sleep(milliseconds) {
+    return new Promise((resolve) => setTimeout(resolve, milliseconds));
+}
+async function crawlProvider(provider, source, limits) {
+    const queue = [];
+    const errors = [];
+    for (const seedUrl of source.seedUrls) {
+        try {
+            queue.push({ url: resolveAllowedUrl(provider, seedUrl), depth: 0 });
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            errors.push(`${seedUrl}: ${message}`);
+        }
+    }
+    const queued = new Set(queue.map((item) => item.url.href));
+    const visited = new Set();
+    const documents = [];
+    while (queue.length > 0 && visited.size < limits.maxPagesPerProvider) {
+        const item = queue.shift();
+        if (!item || visited.has(item.url.href))
+            continue;
+        visited.add(item.url.href);
+        try {
+            const content = await fetchAllowedContent(provider, item.url, limits);
+            const sourceMetadata = {
+                provider: provider.id,
+                sourceKind: source.sourceKind,
+            };
+            const format = provider.responseFormat(item.url);
+            const page = format === "docc-json"
+                ? extractAppleDocCPage(content, item.url.href, sourceMetadata)
+                : format === "markdown"
+                    ? extractMarkdownDocumentationPage(content, item.url.href, provider.platform, sourceMetadata)
+                    : format === "youtrack-json"
+                        ? extractYouTrackIssue(content, item.url.href, sourceMetadata)
+                        : extractDocumentationPage(content, item.url.href, provider.platform, sourceMetadata);
+            if (page) {
+                documents.push(page.document);
+                if (item.depth < limits.maxDepth) {
+                    for (const href of page.links) {
+                        try {
+                            const nextUrl = resolveAllowedUrl(provider, href, item.url.href);
+                            if (!queued.has(nextUrl.href) && !visited.has(nextUrl.href)) {
+                                queued.add(nextUrl.href);
+                                queue.push({ url: nextUrl, depth: item.depth + 1 });
+                            }
+                        }
+                        catch {
+                            // Off-allowlist and malformed links are intentionally ignored.
+                        }
+                    }
+                }
+            }
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            errors.push(`${item.url.href}: ${message}`);
+        }
+        if (limits.delayMs > 0 && queue.length > 0) {
+            await sleep(limits.delayMs);
+        }
+    }
+    return { provider: provider.id, platform: provider.platform, documents, errors };
+}
+export async function readSourcesConfig(configPath) {
+    return sourcesConfigSchema.parse(JSON.parse(await readFile(configPath, "utf8")));
+}
+export function resolveIndexOutputPath(configPath, configuredOutput, outputPath) {
+    if (outputPath)
+        return path.resolve(outputPath);
+    return path.resolve(path.dirname(path.resolve(configPath)), configuredOutput);
+}
+export async function updateDocumentationIndex(options) {
+    const absoluteConfigPath = path.resolve(options.configPath);
+    const config = await readSourcesConfig(absoluteConfigPath);
+    const selectedPlatforms = new Set(options.platforms ?? PLATFORMS);
+    const limits = {
+        ...config.crawl,
+        ...(options.maxPagesPerProvider ? { maxPagesPerProvider: options.maxPagesPerProvider } : {}),
+    };
+    const selectedSources = config.sources.filter((source) => selectedPlatforms.has(getProvider(source.provider).platform));
+    if (selectedSources.length === 0) {
+        throw new Error("No configured sources matched the selected platforms");
+    }
+    const crawlResults = await Promise.all(selectedSources.map((source) => {
+        const sourceLimits = {
+            ...limits,
+            maxPagesPerProvider: Math.min(limits.maxPagesPerProvider, source.maxPages ?? limits.maxPagesPerProvider),
+            maxDepth: Math.min(limits.maxDepth, source.maxDepth ?? limits.maxDepth),
+        };
+        return crawlProvider(getProvider(source.provider), source, sourceLimits);
+    }));
+    const indexedAt = new Date().toISOString();
+    const documents = crawlResults.flatMap((result) => result.documents);
+    const chunks = documents.flatMap((document) => chunkDocument(document, indexedAt));
+    if (chunks.length === 0) {
+        const details = crawlResults
+            .flatMap((result) => result.errors)
+            .slice(0, 10)
+            .join("\n");
+        throw new Error(`Index update produced no searchable content${details ? `:\n${details}` : ""}`);
+    }
+    const outputPath = resolveIndexOutputPath(absoluteConfigPath, config.output, options.outputPath);
+    const index = buildSearchIndex(chunks, documents.length, indexedAt);
+    await writeSearchIndex(outputPath, index.serialized);
+    return {
+        outputPath,
+        documentCount: documents.length,
+        chunkCount: chunks.length,
+        providers: crawlResults.map((result) => ({
+            provider: result.provider,
+            platform: result.platform,
+            documentCount: result.documents.length,
+            errors: result.errors,
+        })),
+    };
+}

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

@@ -0,0 +1,95 @@
+// Expo embeds this search-only key in docs.expo.dev's browser client. It cannot
+// browse or mutate the index and is not a secret. Expo-provider searches send
+// only the already-sanitized API/concept query.
+import * as cheerio from "cheerio";
+import { z } from "zod";
+import { expoProvider, resolveAllowedUrl } from "./providers.js";
+import { readBodyWithLimit } from "./response.js";
+const EXPO_ALGOLIA_ENDPOINT = "https://qex7pb7d46-dsn.algolia.net/1/indexes/expo/query";
+const EXPO_ALGOLIA_APPLICATION_ID = "QEX7PB7D46";
+const EXPO_ALGOLIA_PUBLIC_SEARCH_KEY = "6652d26570e8628af4601e1d78ad456b";
+const MAX_HITS = 10;
+const hitSchema = z.object({
+    objectID: z.string().max(500),
+    url: z.string().url().max(2048),
+    content: z.string().max(50_000).nullable().optional(),
+    language: z.string().max(50).optional(),
+    hierarchy: z.record(z.string().max(50), z.string().max(10_000).nullable()).optional(),
+});
+const responseSchema = z.object({
+    hits: z.array(hitSchema).max(MAX_HITS),
+});
+function text(value) {
+    const $ = cheerio.load(`<body>${value}</body>`);
+    $("script,style,noscript").remove();
+    return $("body").text().replace(/\s+/g, " ").trim();
+}
+export function extractExpoAlgoliaDocuments(json) {
+    const response = responseSchema.parse(JSON.parse(json));
+    const documents = [];
+    const seen = new Set();
+    for (const hit of response.hits) {
+        const originalUrl = new URL(hit.url);
+        const canonicalUrl = resolveAllowedUrl(expoProvider, hit.url);
+        canonicalUrl.hash = originalUrl.hash.slice(0, 300);
+        const url = canonicalUrl.href;
+        const hierarchy = Object.entries(hit.hierarchy ?? {})
+            .sort(([left], [right]) => left.localeCompare(right))
+            .map(([, value]) => (value ? text(value) : ""))
+            .filter(Boolean);
+        const title = hierarchy.at(-1) ?? hierarchy[0];
+        const body = [...hierarchy, hit.content ? text(hit.content) : ""].filter(Boolean).join("\n\n");
+        if (!title || body.length < 20 || seen.has(hit.objectID))
+            continue;
+        seen.add(hit.objectID);
+        documents.push({
+            platform: "react-native",
+            provider: "expo",
+            sourceKind: "official-api",
+            title,
+            url,
+            body,
+        });
+    }
+    return documents;
+}
+async function fetchExpoAlgolia(query, limit, timeoutMs, maxResponseBytes) {
+    const response = await fetch(EXPO_ALGOLIA_ENDPOINT, {
+        method: "POST",
+        redirect: "error",
+        signal: AbortSignal.timeout(timeoutMs),
+        headers: {
+            "content-type": "application/json",
+            "x-algolia-api-key": EXPO_ALGOLIA_PUBLIC_SEARCH_KEY,
+            "x-algolia-application-id": EXPO_ALGOLIA_APPLICATION_ID,
+        },
+        body: JSON.stringify({
+            params: new URLSearchParams({
+                query,
+                hitsPerPage: String(limit),
+                page: "0",
+            }).toString(),
+            facetFilters: [["version:none", "version:latest"]],
+            attributesToRetrieve: ["objectID", "url", "content", "hierarchy", "language"],
+            attributesToHighlight: [],
+        }),
+    });
+    if (!response.ok)
+        throw new Error(`Expo Algolia returned HTTP ${response.status}`);
+    const contentType = response.headers.get("content-type")?.toLowerCase() ?? "";
+    if (!contentType.includes("json")) {
+        throw new Error(`Expo Algolia returned unsupported content type: ${contentType || "missing"}`);
+    }
+    const body = await readBodyWithLimit(response, maxResponseBytes);
+    return extractExpoAlgoliaDocuments(body);
+}
+export async function searchExpoAlgolia(query, limit) {
+    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");
+    }
+    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);
+}

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

@@ -0,0 +1,76 @@
+import { extractAppleDocCPage } from "./apple-docc.js";
+import { extractDocumentationPage } from "./html.js";
+import { extractMarkdownDocumentationPage } from "./markdown.js";
+import { resolveAllowedRequestUrl, resolveAllowedUrl, } from "./providers.js";
+import { readBodyWithLimit } from "./response.js";
+import { extractYouTrackIssue } from "./youtrack.js";
+export const onDemandFetchLimits = {
+    maxPagesPerProvider: 10,
+    maxDepth: 0,
+    delayMs: 0,
+    timeoutMs: 10_000,
+    maxResponseBytes: 5_000_000,
+};
+export async function fetchAllowedContent(provider, documentUrl, limits, fetchImplementation = fetch) {
+    let currentUrl = resolveAllowedRequestUrl(provider, provider.requestUrl(documentUrl).href);
+    for (let redirectCount = 0; redirectCount <= 5; redirectCount++) {
+        const response = await fetchImplementation(currentUrl, {
+            redirect: "manual",
+            signal: AbortSignal.timeout(limits.timeoutMs),
+            headers: {
+                "accept-language": "en-US,en;q=0.9",
+                accept: (() => {
+                    const format = provider.responseFormat(documentUrl);
+                    if (format === "docc-json" || format === "youtrack-json") {
+                        return "application/json";
+                    }
+                    if (format === "markdown") {
+                        return "text/markdown,text/plain;q=0.9";
+                    }
+                    return "text/html,application/xhtml+xml;q=0.9";
+                })(),
+                "user-agent": "review-research-mcp/0.2 (+on-demand official documentation fetcher)",
+            },
+        });
+        if (response.status >= 300 && response.status < 400) {
+            const location = response.headers.get("location");
+            if (!location) {
+                throw new Error(`redirect ${response.status} did not include Location`);
+            }
+            currentUrl = resolveAllowedRequestUrl(provider, location, currentUrl.href);
+            continue;
+        }
+        if (!response.ok) {
+            throw new Error(`HTTP ${response.status}`);
+        }
+        const contentType = response.headers.get("content-type")?.toLowerCase() ?? "";
+        const expectedFormat = provider.responseFormat(documentUrl);
+        const isExpectedType = expectedFormat === "docc-json" || expectedFormat === "youtrack-json"
+            ? contentType.includes("json")
+            : expectedFormat === "markdown"
+                ? contentType.includes("text/plain") || contentType.includes("text/markdown")
+                : contentType.includes("text/html") || contentType.includes("application/xhtml+xml");
+        if (!isExpectedType) {
+            throw new Error(`unsupported content type: ${contentType || "missing"}`);
+        }
+        return readBodyWithLimit(response, limits.maxResponseBytes);
+    }
+    throw new Error("too many redirects");
+}
+export async function fetchDocumentationDocument(provider, rawUrl, sourceKind, fetchImplementation = fetch) {
+    const documentUrl = resolveAllowedUrl(provider, rawUrl);
+    const content = await fetchAllowedContent(provider, documentUrl, onDemandFetchLimits, fetchImplementation);
+    const source = {
+        provider: provider.id,
+        sourceKind,
+    };
+    const format = provider.responseFormat(documentUrl);
+    const extracted = format === "docc-json"
+        ? extractAppleDocCPage(content, documentUrl.href, source)
+        : format === "markdown"
+            ? extractMarkdownDocumentationPage(content, documentUrl.href, provider.platform, source)
+            : format === "youtrack-json"
+                ? extractYouTrackIssue(content, documentUrl.href, source)
+                : extractDocumentationPage(content, documentUrl.href, provider.platform, source);
+    return extracted?.document ?? null;
+}