@expo/code-review-cli 0.11.0 → 0.12.0

package/build/core/research.js

@@ -0,0 +1,498 @@
+// @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
+import { existsSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { fileURLToPath } from "node:url";
+import { z } from "zod";
+import { run } from "./exec.js";
+const APPLE_EXTENSIONS = /\.(?:swift|m|mm)$/i;
+const ANDROID_EXTENSIONS = /\.(?:kt|java|gradle|gradle\.kts)$/i;
+const REACT_NATIVE_EXTENSIONS = /\.(?:[cm]?[jt]sx?)$/i;
+const QUERY_TOKEN = /[A-Za-z][A-Za-z0-9_.:-]{1,79}/g;
+const MAX_ANALYZED_PATCH_LINE_LENGTH = 4096;
+const TYPE_TOKEN = /\b[A-Z][A-Za-z0-9_]{2,}(?:\.[A-Za-z_][A-Za-z0-9_]*)*/g;
+const MEMBER_TOKEN = /\.([a-z][A-Za-z0-9_]{3,})\s*(?:\(|\b)/g;
+const ECOSYSTEM_CALL_TOKEN = /\b((?:create|enable|make|measure|run|schedule|scrollTo|use|with)[A-Z][A-Za-z0-9_]*)\s*\(/g;
+const IGNORED_TYPES = new Set([
+    "Array",
+    "Bool",
+    "Boolean",
+    "Class",
+    "Data",
+    "Double",
+    "Error",
+    "Exception",
+    "Float",
+    "Int",
+    "Integer",
+    "List",
+    "Long",
+    "Map",
+    "Object",
+    "Promise",
+    "Set",
+    "String",
+    "URL",
+    "Unit",
+]);
+const IGNORED_MEMBERS = new Set([
+    "apply",
+    "build",
+    "copy",
+    "equals",
+    "filter",
+    "first",
+    "get",
+    "hashCode",
+    "invoke",
+    "last",
+    "let",
+    "map",
+    "remove",
+    "run",
+    "set",
+    "toString",
+]);
+function startsModuleSpecifier(code) {
+    return /(?:\b(?:from|import)\s*|\brequire\s*\(\s*)$/.test(code);
+}
+function analyzePatchLine(source, state, collectProviderSignals, providerSignals) {
+    let code = "";
+    const finishModuleSpecifier = () => {
+        const value = state.moduleSpecifier;
+        if (value && /^[A-Za-z0-9@._/+~-]{1,200}$/.test(value))
+            providerSignals.push(value);
+        state.moduleSpecifier = null;
+    };
+    for (let index = 0; index < source.length;) {
+        if (state.mode === "block-comment") {
+            if (source.startsWith("*/", index)) {
+                state.mode = "code";
+                code += "  ";
+                index += 2;
+            }
+            else {
+                code += " ";
+                index++;
+            }
+            continue;
+        }
+        if (state.mode === "triple-single-quote" || state.mode === "triple-double-quote") {
+            const delimiter = state.mode === "triple-single-quote" ? "'''" : '"""';
+            if (source.startsWith(delimiter, index)) {
+                state.mode = "code";
+                code += "   ";
+                index += 3;
+            }
+            else {
+                code += " ";
+                index++;
+            }
+            continue;
+        }
+        if (state.mode === "single-quote" ||
+            state.mode === "double-quote" ||
+            state.mode === "template") {
+            const delimiter = state.mode === "single-quote" ? "'" : state.mode === "double-quote" ? '"' : "`";
+            const character = source[index];
+            if (state.escaped) {
+                if (state.moduleSpecifier !== null)
+                    state.moduleSpecifier += character;
+                state.escaped = false;
+                code += " ";
+                index++;
+            }
+            else if (character === "\\") {
+                state.escaped = true;
+                code += " ";
+                index++;
+            }
+            else if (character === delimiter) {
+                finishModuleSpecifier();
+                state.mode = "code";
+                code += " ";
+                index++;
+            }
+            else {
+                if (state.moduleSpecifier !== null)
+                    state.moduleSpecifier += character;
+                code += " ";
+                index++;
+            }
+            continue;
+        }
+        if (source.startsWith("//", index)) {
+            code += " ".repeat(source.length - index);
+            break;
+        }
+        if (source.startsWith("/*", index)) {
+            state.mode = "block-comment";
+            code += "  ";
+            index += 2;
+            continue;
+        }
+        if (source.startsWith("'''", index) || source.startsWith('"""', index)) {
+            state.mode = source.startsWith("'''", index) ? "triple-single-quote" : "triple-double-quote";
+            state.moduleSpecifier = null;
+            code += "   ";
+            index += 3;
+            continue;
+        }
+        const character = source[index];
+        if (character === "'" || character === '"' || character === "`") {
+            state.mode =
+                character === "'" ? "single-quote" : character === '"' ? "double-quote" : "template";
+            state.escaped = false;
+            state.moduleSpecifier =
+                collectProviderSignals && character !== "`" && startsModuleSpecifier(code) ? "" : null;
+            code += " ";
+            index++;
+            continue;
+        }
+        code += character;
+        index++;
+    }
+    // JavaScript/TypeScript, Swift, and Kotlin single/double-quoted strings do not
+    // continue onto the next physical line unless the final character escapes the
+    // newline. Reset malformed prose-like quotes (notably JSX apostrophes) here so
+    // they cannot invert how later patch lines are classified. Templates, triple
+    // quotes, and block comments intentionally retain their multiline state.
+    const continuesQuotedLine = (state.mode === "single-quote" || state.mode === "double-quote") && state.escaped;
+    if ((state.mode === "single-quote" || state.mode === "double-quote") && !continuesQuotedLine) {
+        state.mode = "code";
+        state.moduleSpecifier = null;
+    }
+    state.escaped = false;
+    return code.trim();
+}
+/**
+ * Analyze the resulting side of a unified diff while keeping lexical state across
+ * lines. Provider routing may retain only import/require module specifiers; those
+ * strings are kept separate and can never become outbound query text.
+ */
+function analyzeAddedPatch(patch) {
+    const codeLines = [];
+    const providerSignals = [];
+    const state = { mode: "code", escaped: false, moduleSpecifier: null };
+    for (const patchLine of patch.split("\n")) {
+        if (patchLine.startsWith("@@")) {
+            state.mode = "code";
+            state.escaped = false;
+            state.moduleSpecifier = null;
+            continue;
+        }
+        if (patchLine.startsWith("+++") || patchLine.startsWith("---"))
+            continue;
+        const isAdded = patchLine.startsWith("+");
+        const isContext = patchLine.startsWith(" ");
+        if (!isAdded && !isContext)
+            continue;
+        const source = patchLine.slice(1);
+        if (source.length > MAX_ANALYZED_PATCH_LINE_LENGTH) {
+            // A quote startsModuleSpecifier check examines the accumulated line prefix.
+            // Stop this file before an attacker-controlled giant line can turn that
+            // bounded research prepass into quadratic work. Abandoning later lines also
+            // avoids guessing whether the skipped input opened a multiline literal.
+            break;
+        }
+        const code = analyzePatchLine(source, state, isAdded, providerSignals);
+        if (isAdded && code)
+            codeLines.push(code);
+    }
+    return {
+        codeLines,
+        providerSignals: providerSignals.join("\n").slice(0, 256_000).toLowerCase(),
+    };
+}
+function normalizeQuery(parts) {
+    const tokens = parts.join(" ").match(QUERY_TOKEN) ?? [];
+    return [...new Set(tokens)].join(" ").slice(0, 120).trim();
+}
+function platformFor(file) {
+    const normalized = file.path.replace(/\\/g, "/");
+    if (APPLE_EXTENSIONS.test(normalized) || /(?:^|\/)ios(?:\/|$)/i.test(normalized)) {
+        return "apple";
+    }
+    if (ANDROID_EXTENSIONS.test(normalized) || /(?:^|\/)android(?:\/|$)/i.test(normalized)) {
+        return "android";
+    }
+    if (REACT_NATIVE_EXTENSIONS.test(normalized))
+        return "react-native";
+    return null;
+}
+const REACT_NATIVE_PROVIDERS = new Set([
+    "expo",
+    "react-native",
+    "react-native-reanimated",
+    "react-native-gesture-handler",
+    "react-native-screens",
+    "react-native-worklets",
+]);
+function providersFor(file, code, signals) {
+    const path = file.path.toLowerCase();
+    const text = code.toLowerCase();
+    const 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);
+    if (platform === "apple")
+        return ["apple"];
+    if (platform === "android")
+        return ["android"];
+    return ["react-native"];
+}
+function lineQuery(line) {
+    const declared = line.match(/\b(?:class|struct|enum|interface|protocol)\s+([A-Z][A-Za-z0-9_]*)/)?.[1];
+    const types = [...line.matchAll(TYPE_TOKEN)]
+        .map((match) => match[0])
+        .filter((value) => value !== declared && !IGNORED_TYPES.has(value.split(".")[0]));
+    if (types.length === 0) {
+        const call = [...line.matchAll(ECOSYSTEM_CALL_TOKEN)][0]?.[1];
+        return call ? normalizeQuery([call]) : null;
+    }
+    const members = [...line.matchAll(MEMBER_TOKEN)]
+        .map((match) => match[1])
+        .filter((value) => !IGNORED_MEMBERS.has(value));
+    const primary = types[0];
+    const member = members.find((value) => !primary.toLowerCase().includes(value.toLowerCase()));
+    return normalizeQuery(member ? [primary, member] : [primary]);
+}
+function addQuery(target, seen, platform, providers, query) {
+    const normalized = normalizeQuery([query]);
+    if (!normalized)
+        return;
+    const key = `${platform}|${providers.join(",")}|${normalized.toLowerCase()}`;
+    if (seen.has(key))
+        return;
+    seen.add(key);
+    target.push({ platform, providers, query: normalized });
+}
+/**
+ * Derive bounded documentation searches from code identifiers only. String literals,
+ * comments, removed lines, paths, and raw source snippets never become query text.
+ */
+export function deriveResearchQueries(files, maxQueries = 8) {
+    const queries = [];
+    const seen = new Set();
+    for (const file of files) {
+        const platform = platformFor(file);
+        if (!platform)
+            continue;
+        const { codeLines: lines, providerSignals } = analyzeAddedPatch(file.patch);
+        const code = lines.join("\n").slice(0, 256_000);
+        const providers = providersFor(file, code, providerSignals);
+        for (const provider of providers) {
+            let addedForProvider = 0;
+            for (const line of lines) {
+                const query = lineQuery(line);
+                if (!query)
+                    continue;
+                const before = queries.length;
+                addQuery(queries, seen, REACT_NATIVE_PROVIDERS.has(provider) ? "react-native" : platform, [provider], query);
+                if (queries.length > before && ++addedForProvider >= 2)
+                    break;
+                if (queries.length >= maxQueries)
+                    return queries;
+            }
+        }
+        if (platform === "apple" &&
+            /\b(?:actor|MainActor|Sendable|TaskGroup|Task\.sleep)\b/.test(code)) {
+            const concept = code.match(/\b(?:MainActor|Sendable|TaskGroup|actor|Task\.sleep)\b/)?.[0];
+            if (concept)
+                addQuery(queries, seen, "apple", ["swift-evolution"], concept);
+        }
+        if (platform === "android" && /\b(?:VERSION_CODES|SDK_INT|targetSdk|compileSdk)\b/.test(code)) {
+            const api = code.match(/\b(?:VERSION_CODES(?:\.[A-Z_]+)?|SDK_INT|targetSdk|compileSdk)\b/)?.[0];
+            if (api)
+                addQuery(queries, seen, "android", ["android-releases"], api);
+        }
+        if (queries.length >= maxQueries)
+            return queries.slice(0, maxQueries);
+    }
+    return queries.slice(0, maxQueries);
+}
+const ToolResultSchema = z.object({
+    content: z.array(z.object({
+        type: z.string(),
+        text: z.string().optional(),
+    })),
+});
+const SearchPayloadSchema = z.object({
+    warnings: z.array(z.string().max(500)).max(10).optional(),
+    results: z.array(z.object({
+        provider: z.string(),
+        sourceKind: z.string(),
+        title: z.string(),
+        url: z.string().url(),
+        passage: z.string(),
+        availability: z.array(z.string()).optional(),
+    })),
+});
+const RESEARCH_PROXY_ENV_KEYS = [
+    "HTTP_PROXY",
+    "HTTPS_PROXY",
+    "NO_PROXY",
+    "http_proxy",
+    "https_proxy",
+    "no_proxy",
+];
+export function researchChildEnvironment(source = process.env) {
+    const environment = {
+        LANG: "C.UTF-8",
+        LC_ALL: "C.UTF-8",
+        ...(process.platform === "win32" && source.SystemRoot ? { SystemRoot: source.SystemRoot } : {}),
+    };
+    for (const key of RESEARCH_PROXY_ENV_KEYS) {
+        if (source[key])
+            environment[key] = source[key];
+    }
+    return environment;
+}
+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 {
+        command: process.execPath,
+        args: [existsSync(builtEntry) ? builtEntry : sourceEntry],
+    };
+}
+function cleanEvidenceText(value, maxLength) {
+    return (value
+        .replace(/^\s*-{3,}\s*(?:BEGIN|END)\s+PLATFORM RESEARCH.*$/gim, "")
+        .replace(/`{3,}/g, "'''")
+        .replace(/<\/?\s*(?:system|user|assistant|instructions?|prompt|tool)[^>]*>/gi, "")
+        // oxlint-disable-next-line no-control-regex -- intentional prompt-data sanitization
+        .replace(/[\u0000-\u0008\u000b\u000c\u000e-\u001f\u007f]/g, "")
+        .slice(0, maxLength)
+        .trim());
+}
+export function formatResearchEvidence(evidence) {
+    if (evidence.length === 0)
+        return "";
+    const body = evidence
+        .map((item) => {
+        const availability = item.availability?.length
+            ? `\nAvailability: ${cleanEvidenceText(item.availability.join(", "), 500)}`
+            : "";
+        return [
+            `Query: ${cleanEvidenceText(item.query.query, 120)}`,
+            `Provider: ${cleanEvidenceText(item.provider, 80)} (${cleanEvidenceText(item.sourceKind, 80)})`,
+            `Source: ${cleanEvidenceText(item.title, 240)} — ${item.url}${availability}`,
+            "Passage:",
+            cleanEvidenceText(item.passage, 1200),
+        ].join("\n");
+    })
+        .join("\n\n");
+    return cleanEvidenceText(body, 16_000);
+}
+export async function collectPlatformResearch(files, config) {
+    const queries = deriveResearchQueries(files, config.maxQueries);
+    if (!config.enabled || !config.indexPath || queries.length === 0) {
+        return { queries, evidence: [], warnings: [], promptText: "" };
+    }
+    const calls = queries.map((query, index) => ({
+        jsonrpc: "2.0",
+        id: index + 2,
+        method: "tools/call",
+        params: {
+            name: "search_platform_docs",
+            arguments: {
+                platform: query.platform,
+                providers: query.providers,
+                query: query.query,
+                limit: config.resultsPerQuery,
+            },
+        },
+    }));
+    const messages = [
+        {
+            jsonrpc: "2.0",
+            id: 1,
+            method: "initialize",
+            params: {
+                protocolVersion: "2025-06-18",
+                capabilities: {},
+                clientInfo: { name: "expo-code-review-cli", version: "0.0.0" },
+            },
+        },
+        { jsonrpc: "2.0", method: "notifications/initialized", params: {} },
+        ...calls,
+    ];
+    const server = bundledResearchServer();
+    const serverArgs = [...server.args, "serve", "--index", config.indexPath];
+    const result = await run(server.command, serverArgs, {
+        input: `${messages.map((message) => JSON.stringify(message)).join("\n")}\n`,
+        cwd: tmpdir(),
+        env: researchChildEnvironment(),
+        timeout: config.timeoutMs,
+        maxBuffer: 2 * 1024 * 1024,
+        check: false,
+    });
+    if (result.timedOut)
+        throw new Error("platform research MCP timed out");
+    if (result.overflowed)
+        throw new Error("platform research MCP output exceeded 2 MB");
+    if (result.code !== 0) {
+        throw new Error(`platform research MCP exited ${result.code}: ${result.stderr.slice(0, 500)}`);
+    }
+    const responses = new Map();
+    for (const line of result.stdout.split("\n")) {
+        if (!line.trim())
+            continue;
+        const parsed = JSON.parse(line);
+        if (typeof parsed.id === "number") {
+            if (parsed.error)
+                throw new Error(`platform research MCP error for request ${parsed.id}`);
+            responses.set(parsed.id, parsed.result);
+        }
+    }
+    if (!responses.has(1))
+        throw new Error("platform research MCP did not initialize");
+    const evidence = [];
+    const warnings = [];
+    for (let index = 0; index < queries.length; index++) {
+        const query = queries[index];
+        const toolResult = ToolResultSchema.parse(responses.get(index + 2));
+        const text = toolResult.content.find((block) => block.type === "text")?.text;
+        if (!text)
+            continue;
+        const payload = SearchPayloadSchema.parse(JSON.parse(text));
+        warnings.push(...(payload.warnings ?? []).map((warning) => cleanEvidenceText(warning, 500)).filter(Boolean));
+        for (const item of payload.results.slice(0, config.resultsPerQuery)) {
+            if (!item.url.startsWith("https://") || !query.providers.includes(item.provider))
+                continue;
+            evidence.push({ query, ...item });
+        }
+    }
+    return {
+        queries,
+        evidence,
+        warnings: [...new Set(warnings)].slice(0, 10),
+        promptText: formatResearchEvidence(evidence),
+    };
+}

package/build/core/review.js

@@ -18,6 +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 { collectPlatformResearch } 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,
@@ -132,6 +133,25 @@ export async function runReview(source, options) {
         });
         return output;
     }
+    let researchText = "";
+    if (config.research.enabled) {
+        progress("Researching platform documentation from changed API identifiers…");
+        try {
+            const research = await collectPlatformResearch(kept, config.research);
+            researchText = research.promptText;
+            progress(research.queries.length === 0
+                ? "  research: no native platform identifiers found"
+                : `  research: ${research.evidence.length} passage(s) from ${research.queries.length} bounded query(s)`);
+            for (const warning of research.warnings) {
+                progress(`  research warning: ${warning}`);
+            }
+        }
+        catch (error) {
+            // Documentation is supporting evidence, not a prerequisite for reviewing the
+            // code. Fail open with a visible diagnostic; never weaken or skip the review.
+            progress(`  research unavailable; continuing without it (${errorMessage(error)})`);
+        }
+    }
     // Materialize the PR-head tree (not the current checkout) when the source can, so
     // the agents' surrounding-source reads and the verifier's re-reads see the versions
     // that match the diff. Config is already fully loaded in memory, so the chdir below
@@ -460,8 +480,8 @@ export async function runReview(source, options) {
         // smaller file set); a fallback task forbids tools and reviews the inlined diff.
         const buildTaskText = (task) => {
             const base = task.kind === "cross-cutting"
-                ? buildCrossCuttingTask(task.files, selectedAgents, filtered, { noTools: task.fallback }, options.contextText)
-                : buildReviewerTask(task.files, workspace.files, filtered, options.contextText);
+                ? buildCrossCuttingTask(task.files, selectedAgents, filtered, { noTools: task.fallback }, options.contextText, researchText)
+                : buildReviewerTask(task.files, workspace.files, filtered, options.contextText, researchText);
             return task.fallback ? `${base}\n\n${NO_TOOLS_INSTRUCTION}` : base;
         };
         const filesLabel = (files) => files.length === 1

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

@@ -0,0 +1,122 @@
+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();
+}
+const readableKeys = new Set(["text", "code", "title", "name"]);
+const skippedKeys = new Set([
+    "anchor",
+    "checksum",
+    "identifier",
+    "identifiers",
+    "images",
+    "kind",
+    "role",
+    "type",
+    "url",
+]);
+function collectReadableText(value, output, key) {
+    if (typeof value === "string") {
+        if (key && readableKeys.has(key))
+            output.push(value);
+        return;
+    }
+    if (Array.isArray(value)) {
+        for (const item of value)
+            collectReadableText(item, output, key);
+        return;
+    }
+    const object = objectValue(value);
+    if (!object)
+        return;
+    for (const [childKey, child] of Object.entries(object)) {
+        if (!skippedKeys.has(childKey))
+            collectReadableText(child, output, childKey);
+    }
+}
+function cleanLines(lines) {
+    const output = [];
+    let previous = "";
+    for (const line of lines) {
+        const cleaned = line.replace(/\s+/g, " ").trim();
+        if (cleaned && cleaned !== previous) {
+            output.push(cleaned);
+            previous = cleaned;
+        }
+    }
+    return output.join("\n\n");
+}
+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);
+    collectReadableText(root.primaryContentSections, text);
+    collectReadableText(root.relationshipsSections, text);
+    const links = new Set();
+    const references = objectValue(root.references);
+    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 = cleanLines(text);
+    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],
+    };
+}