mirror of
https://github.com/expo/code-review-cli.git
synced 2026-11-15 03:38:09 -10:00
Compare commits
| Author | SHA1 | Date | |
|---|---|---|---|
 Brent Vatne
|
a87b5085eb |
No files matched your search
@@ -9,4 +9,3 @@ build/
|
||||
|
||||
# Claude Code local worktrees
|
||||
.claude/worktrees/
|
||||
research/data/
|
||||
@@ -325,14 +325,11 @@ downloads the fixed official `lysine.dev` static search index, validates and ind
|
||||
it in memory once per MCP process, and rejects any entry outside the existing OkHttp
|
||||
allowlist. Brave remains a fallback if that official index is unavailable.
|
||||
|
||||
An absolute `research.indexPath` remains available as an optional local fallback.
|
||||
The MCP and its trusted updater ship with ECR: build that fallback from this
|
||||
repository with `bun run research:update`, or from an installed package with
|
||||
`review-research-mcp update`. This is operator/scheduled offline tooling, not a
|
||||
step to run before each review. The built-in seed catalog lives in
|
||||
`research/sources.json`; `seedUrls` are deterministic starting pages for the
|
||||
bounded crawler, and extraction/indexing use no LLM. Installations requiring a fully
|
||||
offline review can supply a separately built, verified index and omit the Brave key.
|
||||
There is no offline index. Every passage a review sees is fetched live from the
|
||||
provider allowlist during that review, so evidence is never served from a local
|
||||
artifact whose contents ECR cannot vouch for. The crawler, its seed catalog, and
|
||||
`research.indexPath` were removed once live discovery replaced them; a config still
|
||||
naming `indexPath` fails to parse rather than silently ignoring it.
|
||||
Installation-specific provider configuration is intentionally
|
||||
deferred: when added, it should follow the trusted root-config model used for agents
|
||||
without permitting PR-controlled URLs, commands, or executable parsers. Expo skills
|
||||
|
||||
@@ -119,24 +119,24 @@ has the same response-size/schema/URL constraints, is cached only within the MCP
|
||||
process, and can never admit a URL outside the OkHttp provider allowlist. Brave is a
|
||||
fallback when that first-party index is unavailable.
|
||||
|
||||
`review-research-mcp update` is a separate, operator-invoked command for trusted
|
||||
scheduled jobs. The updater uses exact HTTPS host/path allowlists, manually
|
||||
revalidates redirects, checks response content types, and bounds response size,
|
||||
crawl depth, page count, timeout, and delay. The Expo crawl supplies a local fallback;
|
||||
precise Expo search uses the live query rather than pretending an empty-query result
|
||||
page is a complete Algolia index.
|
||||
There is no offline index, and no crawler to build one. Live discovery replaced the
|
||||
deterministic prefetch it was designed for, and the fallback it provided was never
|
||||
free: an index is an artifact whose bytes sit outside the trust boundary the rest of
|
||||
the system establishes. `research.indexPath` had to be an absolute path, so it
|
||||
resolved against the runner's filesystem rather than the materialized trusted base —
|
||||
the trusted-base mechanism protected the config that NAMED the index, never the
|
||||
contents at that path, and nothing carried a digest. Index passages were also the one
|
||||
evidence source returned unbounded, while every live source is length-capped.
|
||||
|
||||
The crawler is not part of the ordinary review workflow. An adopter requiring an
|
||||
offline fallback may run `update` in a separate scheduled secretless job from a
|
||||
pinned package and trusted checkout. That job must execute no PR code, receive no
|
||||
model credential, and publish a verified read-only index artifact.
|
||||
Removing it deletes that whole class of question rather than answering it. Every
|
||||
passage a review sees is now fetched during that review from an allowlisted host,
|
||||
bounded on entry. A config still naming `research.indexPath` fails to parse, so a
|
||||
stale setting surfaces as an error instead of being silently ignored.
|
||||
|
||||
The generated index is deliberately not published in the npm package. Documentation
|
||||
changes independently of ECR, and coupling a snapshot to every CLI install would make
|
||||
releases and invalidation expensive. If supplied, an absolute trusted-base
|
||||
`research.indexPath` is fallback evidence when remote discovery fails or misses.
|
||||
Research-enabled reviews bypass result-cache reuse because remote search,
|
||||
documentation, and optional index content can change without a config change.
|
||||
This also removes the reason researched reviews could not reuse a cached result.
|
||||
Reuse was disabled whenever research was enabled because evidence depended on mounted
|
||||
index contents that the cache key could not represent; with no mounted artifact, the
|
||||
ordinary input hash covers the whole review again.
|
||||
|
||||
## Query and Prompt Boundary
|
||||
|
||||
|
||||
+1
-3
@@ -16,8 +16,7 @@
|
||||
},
|
||||
"files": [
|
||||
"build",
|
||||
"templates",
|
||||
"research/sources.json"
|
||||
"templates"
|
||||
],
|
||||
"engines": {
|
||||
"node": ">=20"
|
||||
@@ -38,7 +37,6 @@
|
||||
"llp:check": "./ref-check",
|
||||
"dev": "bun run src/cli.ts",
|
||||
"test:unit": "bun test",
|
||||
"research:update": "bun run src/research-mcp/cli.ts update",
|
||||
"research:evaluate:corpora": "bun run build && node scripts/research/evaluate-corpora.mjs",
|
||||
"research:evaluate:expo": "bun run build && node scripts/research/evaluate-expo-prs.mjs",
|
||||
"release": "bash scripts/release.sh",
|
||||
|
||||
@@ -1,295 +0,0 @@
|
||||
{
|
||||
"output": "data/docs-index.json",
|
||||
"crawl": {
|
||||
"maxPagesPerProvider": 250,
|
||||
"maxDepth": 4,
|
||||
"delayMs": 200,
|
||||
"timeoutMs": 15000,
|
||||
"maxResponseBytes": 5000000
|
||||
},
|
||||
"sources": [
|
||||
{
|
||||
"provider": "apple",
|
||||
"sourceKind": "official-api",
|
||||
"maxPages": 170,
|
||||
"seedUrls": [
|
||||
"https://developer.apple.com/documentation/swift",
|
||||
"https://developer.apple.com/documentation/swiftui",
|
||||
"https://developer.apple.com/documentation/uikit",
|
||||
"https://developer.apple.com/documentation/foundation",
|
||||
"https://developer.apple.com/documentation/avfoundation",
|
||||
"https://developer.apple.com/documentation/coregraphics",
|
||||
"https://developer.apple.com/documentation/photos",
|
||||
"https://developer.apple.com/documentation/usernotifications",
|
||||
"https://developer.apple.com/documentation/webkit",
|
||||
"https://developer.apple.com/documentation/storekit",
|
||||
"https://developer.apple.com/documentation/activitykit",
|
||||
"https://developer.apple.com/documentation/widgetkit",
|
||||
"https://developer.apple.com/documentation/appintents",
|
||||
"https://developer.apple.com/documentation/network",
|
||||
"https://developer.apple.com/documentation/photos/phasset",
|
||||
"https://developer.apple.com/documentation/photos/phasset/location",
|
||||
"https://developer.apple.com/documentation/network/nwpathmonitor",
|
||||
"https://developer.apple.com/documentation/network/nwpathmonitor/pathupdatehandler",
|
||||
"https://developer.apple.com/documentation/appintents/liveactivityintent",
|
||||
"https://developer.apple.com/documentation/activitykit/activity",
|
||||
"https://developer.apple.com/documentation/activitykit/activity/id",
|
||||
"https://developer.apple.com/documentation/activitykit/activity/activities",
|
||||
"https://developer.apple.com/documentation/activitykit/activity/activitystate",
|
||||
"https://developer.apple.com/documentation/activitykit/activity/pushtokenupdates-swift.property",
|
||||
"https://developer.apple.com/documentation/avfaudio/avaudiosession",
|
||||
"https://developer.apple.com/documentation/avfaudio/avaudiosession/setactive(_:options:)",
|
||||
"https://developer.apple.com/documentation/avfaudio/avaudiosession/setactiveoptions/notifyothersondeactivation",
|
||||
"https://developer.apple.com/documentation/swiftui/view/widgeturl(_:)",
|
||||
"https://developer.apple.com/design/human-interface-guidelines/"
|
||||
]
|
||||
},
|
||||
{
|
||||
"provider": "apple-releases",
|
||||
"sourceKind": "release-notes",
|
||||
"maxPages": 40,
|
||||
"maxDepth": 2,
|
||||
"seedUrls": [
|
||||
"https://developer.apple.com/documentation/xcode-release-notes",
|
||||
"https://developer.apple.com/documentation/ios-ipados-release-notes"
|
||||
]
|
||||
},
|
||||
{
|
||||
"provider": "swift-evolution",
|
||||
"sourceKind": "official-guide",
|
||||
"maxPages": 35,
|
||||
"maxDepth": 1,
|
||||
"seedUrls": [
|
||||
"https://www.swift.org/swift-evolution/",
|
||||
"https://github.com/swiftlang/swift-evolution/blob/main/proposals/0302-concurrent-value-and-concurrent-closures.md",
|
||||
"https://github.com/swiftlang/swift-evolution/blob/main/proposals/0304-structured-concurrency.md",
|
||||
"https://github.com/swiftlang/swift-evolution/blob/main/proposals/0306-actors.md",
|
||||
"https://github.com/swiftlang/swift-evolution/blob/main/proposals/0316-global-actors.md",
|
||||
"https://github.com/swiftlang/swift-evolution/blob/main/proposals/0338-clarify-execution-non-actor-async.md",
|
||||
"https://github.com/swiftlang/swift-evolution/blob/main/proposals/0420-inheritance-of-actor-isolation.md",
|
||||
"https://github.com/swiftlang/swift-evolution/blob/main/proposals/0430-transferring-parameters-and-results.md"
|
||||
]
|
||||
},
|
||||
{
|
||||
"provider": "sdwebimage",
|
||||
"sourceKind": "official-api",
|
||||
"maxPages": 30,
|
||||
"maxDepth": 2,
|
||||
"seedUrls": [
|
||||
"https://sdwebimage.github.io/documentation/sdwebimage/",
|
||||
"https://sdwebimage.github.io/documentation/sdwebimage/sdwebimagemanager/",
|
||||
"https://sdwebimage.github.io/documentation/sdwebimage/sdwebimageoptions/",
|
||||
"https://sdwebimage.github.io/documentation/sdwebimage/sdwebimagecontextoption/"
|
||||
]
|
||||
},
|
||||
{
|
||||
"provider": "android",
|
||||
"sourceKind": "official-api",
|
||||
"maxPages": 150,
|
||||
"seedUrls": [
|
||||
"https://developer.android.com/develop",
|
||||
"https://developer.android.com/reference",
|
||||
"https://developer.android.com/develop/ui/views/text-and-emoji/fonts-in-xml",
|
||||
"https://developer.android.com/reference/androidx/biometric/BiometricPrompt.PromptInfo.Builder",
|
||||
"https://developer.android.com/reference/android/media/AudioFocusRequest",
|
||||
"https://developer.android.com/reference/android/media/AudioManager",
|
||||
"https://developer.android.com/reference/android/net/ConnectivityManager",
|
||||
"https://developer.android.com/reference/android/net/ConnectivityManager.NetworkCallback",
|
||||
"https://developer.android.com/reference/android/content/Intent",
|
||||
"https://developer.android.com/reference/android/app/NotificationManager",
|
||||
"https://developer.android.com/reference/android/os/Build.VERSION_CODES",
|
||||
"https://developer.android.com/reference/androidx/core/os/BuildCompat",
|
||||
"https://developer.android.com/reference/androidx/work/Constraints.Builder",
|
||||
"https://developer.android.com/reference/androidx/work/NetworkType",
|
||||
"https://developer.android.com/develop/ui/compose/graphics/images/loading",
|
||||
"https://developer.android.com/develop/ui/compose/graphics/images/customize",
|
||||
"https://developer.android.com/reference/kotlin/androidx/compose/foundation/Image.composable",
|
||||
"https://developers.google.com/android/reference/com/google/android/gms/location/FusedLocationProviderClient",
|
||||
"https://developers.google.com/android/reference/com/google/android/gms/location/LocationCallback"
|
||||
]
|
||||
},
|
||||
{
|
||||
"provider": "android-releases",
|
||||
"sourceKind": "release-notes",
|
||||
"maxPages": 50,
|
||||
"maxDepth": 2,
|
||||
"seedUrls": [
|
||||
"https://developer.android.com/about/versions/16",
|
||||
"https://developer.android.com/about/versions/16/features",
|
||||
"https://developer.android.com/about/versions/16/behavior-changes-all",
|
||||
"https://developer.android.com/about/versions/16/behavior-changes-16",
|
||||
"https://developer.android.com/about/versions/15/behavior-changes-all",
|
||||
"https://developer.android.com/about/versions/15/behavior-changes-15",
|
||||
"https://developer.android.com/about/versions/14/behavior-changes-all",
|
||||
"https://developer.android.com/about/versions/14/behavior-changes-14"
|
||||
]
|
||||
},
|
||||
{
|
||||
"provider": "media3",
|
||||
"sourceKind": "official-guide",
|
||||
"maxPages": 40,
|
||||
"maxDepth": 2,
|
||||
"seedUrls": [
|
||||
"https://developer.android.com/media/media3",
|
||||
"https://developer.android.com/media/media3/session/background-playback",
|
||||
"https://developer.android.com/jetpack/androidx/releases/media3",
|
||||
"https://developer.android.com/reference/androidx/media3/common/Player",
|
||||
"https://developer.android.com/reference/androidx/media3/session/MediaSessionService"
|
||||
]
|
||||
},
|
||||
{
|
||||
"provider": "glide",
|
||||
"sourceKind": "official-guide",
|
||||
"maxPages": 30,
|
||||
"maxDepth": 2,
|
||||
"seedUrls": [
|
||||
"https://bumptech.github.io/glide/doc/caching.html",
|
||||
"https://bumptech.github.io/glide/doc/configuration.html",
|
||||
"https://bumptech.github.io/glide/javadocs/450/com/bumptech/glide/load/engine/cache/DiskCache.html",
|
||||
"https://bumptech.github.io/glide/javadocs/450/com/bumptech/glide/load/engine/cache/InternalCacheDiskCacheFactory.html"
|
||||
]
|
||||
},
|
||||
{
|
||||
"provider": "okhttp",
|
||||
"sourceKind": "official-guide",
|
||||
"maxPages": 30,
|
||||
"maxDepth": 2,
|
||||
"seedUrls": [
|
||||
"https://lysine.dev/okhttp/",
|
||||
"https://lysine.dev/okhttp/recipes/",
|
||||
"https://lysine.dev/okhttp/features/caching/",
|
||||
"https://lysine.dev/okhttp/features/calls/",
|
||||
"https://lysine.dev/okhttp/features/connections/",
|
||||
"https://lysine.dev/okhttp/features/https/",
|
||||
"https://lysine.dev/okhttp/features/interceptors/",
|
||||
"https://lysine.dev/okhttp/changelogs/changelog/",
|
||||
"https://lysine.dev/okhttp/5.x/okhttp/okhttp3/-ok-http-client/"
|
||||
]
|
||||
},
|
||||
{
|
||||
"provider": "kotlin-coroutines",
|
||||
"sourceKind": "official-guide",
|
||||
"maxPages": 40,
|
||||
"maxDepth": 1,
|
||||
"seedUrls": [
|
||||
"https://kotlinlang.org/docs/coroutines-guide.html",
|
||||
"https://kotlinlang.org/docs/coroutines-basics.html",
|
||||
"https://kotlinlang.org/docs/cancellation-and-timeouts.html",
|
||||
"https://kotlinlang.org/docs/exception-handling.html",
|
||||
"https://kotlinlang.org/docs/shared-mutable-state-and-concurrency.html",
|
||||
"https://kotlinlang.org/docs/flow.html",
|
||||
"https://kotlinlang.org/api/kotlinx.coroutines/"
|
||||
]
|
||||
},
|
||||
{
|
||||
"provider": "gradle",
|
||||
"sourceKind": "official-guide",
|
||||
"maxPages": 40,
|
||||
"maxDepth": 1,
|
||||
"seedUrls": [
|
||||
"https://docs.gradle.org/current/userguide/tooling_api.html",
|
||||
"https://docs.gradle.org/current/userguide/composite_builds.html",
|
||||
"https://docs.gradle.org/current/userguide/public_apis.html",
|
||||
"https://docs.gradle.org/current/userguide/upgrading_version_9.html",
|
||||
"https://docs.gradle.org/current/release-notes.html"
|
||||
]
|
||||
},
|
||||
{
|
||||
"provider": "agp",
|
||||
"sourceKind": "release-notes",
|
||||
"maxPages": 40,
|
||||
"maxDepth": 1,
|
||||
"seedUrls": [
|
||||
"https://developer.android.com/build/releases/about-agp",
|
||||
"https://developer.android.com/build/releases/gradle-plugin-roadmap",
|
||||
"https://developer.android.com/build/releases/agp-9-0-0-release-notes",
|
||||
"https://developer.android.com/reference/tools/gradle-api"
|
||||
]
|
||||
},
|
||||
{
|
||||
"provider": "jetbrains-issues",
|
||||
"sourceKind": "issue-tracker",
|
||||
"maxPages": 1,
|
||||
"maxDepth": 0,
|
||||
"seedUrls": [
|
||||
"https://youtrack.jetbrains.com/issue/IDEA-329756/Importing-symlinked-Gradle-included-build-fails"
|
||||
]
|
||||
},
|
||||
{
|
||||
"provider": "expo",
|
||||
"sourceKind": "official-api",
|
||||
"maxPages": 100,
|
||||
"maxDepth": 3,
|
||||
"seedUrls": [
|
||||
"https://docs.expo.dev/versions/latest/",
|
||||
"https://docs.expo.dev/versions/latest/sdk/expo/",
|
||||
"https://docs.expo.dev/versions/latest/sdk/camera/",
|
||||
"https://docs.expo.dev/versions/latest/sdk/notifications/",
|
||||
"https://docs.expo.dev/router/introduction/",
|
||||
"https://docs.expo.dev/modules/overview/",
|
||||
"https://docs.expo.dev/guides/new-architecture/"
|
||||
]
|
||||
},
|
||||
{
|
||||
"provider": "react-native",
|
||||
"sourceKind": "official-api",
|
||||
"maxPages": 80,
|
||||
"maxDepth": 3,
|
||||
"seedUrls": [
|
||||
"https://reactnative.dev/docs/getting-started",
|
||||
"https://reactnative.dev/docs/components-and-apis",
|
||||
"https://reactnative.dev/docs/flatlist",
|
||||
"https://reactnative.dev/docs/view",
|
||||
"https://reactnative.dev/docs/platform",
|
||||
"https://reactnative.dev/architecture/landing-page"
|
||||
]
|
||||
},
|
||||
{
|
||||
"provider": "react-native-reanimated",
|
||||
"sourceKind": "official-guide",
|
||||
"maxPages": 60,
|
||||
"maxDepth": 3,
|
||||
"seedUrls": [
|
||||
"https://docs.swmansion.com/react-native-reanimated/docs/fundamentals/getting-started/",
|
||||
"https://docs.swmansion.com/react-native-reanimated/docs/guides/testing/",
|
||||
"https://docs.swmansion.com/react-native-reanimated/docs/guides/compatibility/",
|
||||
"https://docs.swmansion.com/react-native-reanimated/docs/category/core/",
|
||||
"https://docs.swmansion.com/react-native-reanimated/docs/category/advanced-apis/"
|
||||
]
|
||||
},
|
||||
{
|
||||
"provider": "react-native-gesture-handler",
|
||||
"sourceKind": "official-guide",
|
||||
"maxPages": 60,
|
||||
"maxDepth": 3,
|
||||
"seedUrls": [
|
||||
"https://docs.swmansion.com/react-native-gesture-handler/docs/fundamentals/getting-started/",
|
||||
"https://docs.swmansion.com/react-native-gesture-handler/docs/gestures/pan-gesture/",
|
||||
"https://docs.swmansion.com/react-native-gesture-handler/docs/gestures/gesture-detector/"
|
||||
]
|
||||
},
|
||||
{
|
||||
"provider": "react-native-screens",
|
||||
"sourceKind": "official-guide",
|
||||
"maxPages": 50,
|
||||
"maxDepth": 3,
|
||||
"seedUrls": [
|
||||
"https://docs.swmansion.com/react-native-screens/",
|
||||
"https://github.com/software-mansion/react-native-screens/blob/main/README.md"
|
||||
]
|
||||
},
|
||||
{
|
||||
"provider": "react-native-worklets",
|
||||
"sourceKind": "official-guide",
|
||||
"maxPages": 60,
|
||||
"maxDepth": 3,
|
||||
"seedUrls": [
|
||||
"https://docs.swmansion.com/react-native-worklets/docs/fundamentals/getting-started/",
|
||||
"https://docs.swmansion.com/react-native-worklets/docs/guides/testing/",
|
||||
"https://docs.swmansion.com/react-native-worklets/docs/category/fundamentals/",
|
||||
"https://docs.swmansion.com/react-native-worklets/docs/fundamentals/sharing-memory/",
|
||||
"https://docs.swmansion.com/react-native-worklets/docs/guides/feature-flags/"
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
@@ -3,8 +3,6 @@
|
||||
// Default mode replays recorded fixtures (no network, no key) and validates
|
||||
// the full MCP pipeline deterministically. Set RESEARCH_EVAL_LIVE=1 (plus
|
||||
// BRAVE_SEARCH_API_KEY) to run the same cases against live search instead.
|
||||
import { existsSync } from "node:fs";
|
||||
import { fileURLToPath } from "node:url";
|
||||
|
||||
import { Client } from "@modelcontextprotocol/sdk/client/index.js";
|
||||
import { InMemoryTransport } from "@modelcontextprotocol/sdk/inMemory.js";
|
||||
@@ -12,8 +10,6 @@ import { InMemoryTransport } from "@modelcontextprotocol/sdk/inMemory.js";
|
||||
import { createDocumentationServer } from "../../build/research-mcp/server.js";
|
||||
import { createRecordedFetch } from "./recorded-fetch.mjs";
|
||||
|
||||
const INDEX_PATH = fileURLToPath(new URL("../../research/data/docs-index.json", import.meta.url));
|
||||
|
||||
async function callSearch(serverOptions, name, args) {
|
||||
// One server per case keeps every case inside the per-server call budget.
|
||||
const server = await createDocumentationServer(serverOptions);
|
||||
@@ -44,7 +40,6 @@ export async function runEvalCases(cases, { clientName, buildArguments, assertCa
|
||||
...(process.env.BRAVE_SEARCH_API_KEY
|
||||
? { braveApiKey: process.env.BRAVE_SEARCH_API_KEY }
|
||||
: {}),
|
||||
...(existsSync(INDEX_PATH) ? { indexPath: INDEX_PATH } : {}),
|
||||
}
|
||||
: { fetchImplementation: createRecordedFetch(cases), braveApiKey: "recorded-fixtures" };
|
||||
|
||||
|
||||
@@ -1,68 +0,0 @@
|
||||
import { expect, test } from "bun:test";
|
||||
import { mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
|
||||
import { tmpdir } from "node:os";
|
||||
import path from "node:path";
|
||||
|
||||
import { resolveIndexOutputPath, updateDocumentationIndex } from "../../research-mcp/crawler.js";
|
||||
|
||||
test("default index output is relative to the source config directory", () => {
|
||||
const configPath = path.join("repo", "research", "sources.json");
|
||||
|
||||
expect(resolveIndexOutputPath(configPath, "data/docs-index.json")).toBe(
|
||||
path.resolve("repo", "research", "data", "docs-index.json"),
|
||||
);
|
||||
});
|
||||
|
||||
test("an explicit output path remains relative to the caller's working directory", () => {
|
||||
expect(
|
||||
resolveIndexOutputPath(
|
||||
path.join("repo", "research", "sources.json"),
|
||||
"data/docs-index.json",
|
||||
"custom/index.json",
|
||||
),
|
||||
).toBe(path.resolve("custom", "index.json"));
|
||||
});
|
||||
|
||||
test("an invalid seed is reported without aborting other seeds", async () => {
|
||||
const directory = await mkdtemp(path.join(tmpdir(), "review-research-crawler-"));
|
||||
const configPath = path.join(directory, "sources.json");
|
||||
const originalFetch = globalThis.fetch;
|
||||
globalThis.fetch = async () =>
|
||||
new Response(
|
||||
"<html><head><title>Android Widget</title></head><body><main><h1>Android Widget</h1><p>A documented Android API with enough visible text to produce a searchable local index passage.</p></main></body></html>",
|
||||
{ headers: { "content-type": "text/html" } },
|
||||
);
|
||||
try {
|
||||
await writeFile(
|
||||
configPath,
|
||||
JSON.stringify({
|
||||
output: "data/index.json",
|
||||
crawl: {
|
||||
maxPagesPerProvider: 2,
|
||||
maxDepth: 0,
|
||||
delayMs: 0,
|
||||
timeoutMs: 1000,
|
||||
maxResponseBytes: 4096,
|
||||
},
|
||||
sources: [
|
||||
{
|
||||
provider: "android",
|
||||
sourceKind: "official-api",
|
||||
seedUrls: [
|
||||
"https://untrusted.example/reference/widget",
|
||||
"https://developer.android.com/reference/widget",
|
||||
],
|
||||
},
|
||||
],
|
||||
}),
|
||||
);
|
||||
|
||||
const result = await updateDocumentationIndex({ configPath });
|
||||
expect(result.documentCount).toBe(1);
|
||||
expect(result.providers[0]?.errors[0]).toContain("untrusted.example");
|
||||
expect(JSON.parse(await readFile(result.outputPath, "utf8")).documentCount).toBe(1);
|
||||
} finally {
|
||||
globalThis.fetch = originalFetch;
|
||||
await rm(directory, { recursive: true, force: true });
|
||||
}
|
||||
});
|
||||
@@ -7,45 +7,13 @@ import { fileURLToPath } from "node:url";
|
||||
import { Client } from "@modelcontextprotocol/sdk/client/index.js";
|
||||
import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
|
||||
|
||||
import { buildSearchIndex, writeSearchIndex } from "../../research-mcp/search-index.js";
|
||||
|
||||
test("stdio MCP lists and calls the read-only documentation search tool", async () => {
|
||||
const directory = await mkdtemp(path.join(tmpdir(), "review-research-mcp-"));
|
||||
const indexPath = path.join(directory, "index.json");
|
||||
const built = buildSearchIndex(
|
||||
[
|
||||
{
|
||||
id: "apple:mainactor",
|
||||
platform: "apple",
|
||||
provider: "apple",
|
||||
sourceKind: "official-api",
|
||||
title: "MainActor",
|
||||
url: "https://developer.apple.com/documentation/swift/mainactor",
|
||||
passage: "A singleton actor whose executor is equivalent to the main dispatch queue.",
|
||||
language: "swift",
|
||||
indexedAt: "2026-08-06T00:00:00.000Z",
|
||||
},
|
||||
{
|
||||
id: "apple:poisoned-mainactor",
|
||||
platform: "apple",
|
||||
provider: "apple",
|
||||
sourceKind: "official-api",
|
||||
title: "MainActor forged mirror",
|
||||
url: "https://attacker.example/documentation/swift/mainactor",
|
||||
passage: "MainActor dispatch queue documentation copied to an untrusted host.",
|
||||
language: "swift",
|
||||
indexedAt: "2026-08-06T00:00:00.000Z",
|
||||
},
|
||||
],
|
||||
1,
|
||||
"2026-08-06T00:00:00.000Z",
|
||||
);
|
||||
await writeSearchIndex(indexPath, built.serialized);
|
||||
|
||||
// The only test that drives the real stdio binary, so it owns the tool-metadata
|
||||
// contract: names, annotations, and the schemas a model actually reads.
|
||||
test("stdio MCP advertises the read-only documentation tools and their enforced bounds", async () => {
|
||||
const cliPath = fileURLToPath(new URL("../../research-mcp/cli.ts", import.meta.url));
|
||||
const transport = new StdioClientTransport({
|
||||
command: process.execPath,
|
||||
args: [cliPath, "serve", "--index", indexPath],
|
||||
args: [cliPath, "serve"],
|
||||
stderr: "pipe",
|
||||
});
|
||||
const client = new Client({ name: "test-client", version: "1.0.0" });
|
||||
@@ -101,34 +69,12 @@ test("stdio MCP lists and calls the read-only documentation search tool", async
|
||||
| undefined;
|
||||
expect(searchInputSchema?.properties?.limit?.maximum).toBe(3);
|
||||
expect(searchInputSchema?.properties?.limit?.default).toBe(3);
|
||||
|
||||
const response = await client.callTool({
|
||||
name: "search_platform_docs",
|
||||
arguments: {
|
||||
platform: "apple",
|
||||
providers: ["apple"],
|
||||
sourceKinds: ["official-api"],
|
||||
query: "MainActor dispatch queue",
|
||||
limit: 3,
|
||||
},
|
||||
});
|
||||
const content = response.content as Array<{ type: string; text?: string }>;
|
||||
const textBlock = content.find((block) => block.type === "text");
|
||||
expect(textBlock?.type).toBe("text");
|
||||
const payload = JSON.parse(textBlock.text ?? "") as {
|
||||
results: Array<{ title: string; provider: string; sourceKind: string }>;
|
||||
};
|
||||
expect(payload.results[0]?.title).toBe("MainActor");
|
||||
expect(payload.results[0]?.provider).toBe("apple");
|
||||
expect(payload.results[0]?.sourceKind).toBe("official-api");
|
||||
expect(payload.results).toHaveLength(1);
|
||||
} finally {
|
||||
await client.close();
|
||||
await rm(directory, { recursive: true, force: true });
|
||||
}
|
||||
});
|
||||
|
||||
test("stdio MCP starts without an index and reports unavailable remote discovery honestly", async () => {
|
||||
test("stdio MCP reports unavailable remote discovery honestly", async () => {
|
||||
const cliPath = fileURLToPath(new URL("../../research-mcp/cli.ts", import.meta.url));
|
||||
const transport = new StdioClientTransport({
|
||||
command: process.execPath,
|
||||
@@ -152,7 +98,6 @@ test("stdio MCP starts without an index and reports unavailable remote discovery
|
||||
const content = response.content as Array<{ type: string; text?: string }>;
|
||||
const payload = JSON.parse(content.find((block) => block.type === "text")?.text ?? "") as {
|
||||
retrieval: {
|
||||
localIndex: unknown;
|
||||
scopedWebSearch: boolean;
|
||||
network: Record<string, number>;
|
||||
};
|
||||
@@ -162,7 +107,6 @@ test("stdio MCP starts without an index and reports unavailable remote discovery
|
||||
expect(payload.retrieval).toMatchObject({
|
||||
scopedWebSearch: false,
|
||||
expoSearch: false,
|
||||
localIndex: null,
|
||||
});
|
||||
// No key and no provider reachable, so the call must not have touched the network.
|
||||
expect(payload.retrieval.network).toMatchObject({
|
||||
|
||||
@@ -1,14 +1,6 @@
|
||||
import { expect, test } from "bun:test";
|
||||
import { mkdtemp, rm } from "node:fs/promises";
|
||||
import { tmpdir } from "node:os";
|
||||
import path from "node:path";
|
||||
|
||||
import {
|
||||
buildSearchIndex,
|
||||
loadSearchIndex,
|
||||
searchDocumentation,
|
||||
writeSearchIndex,
|
||||
} from "../../research-mcp/search-index.js";
|
||||
import { buildSearchIndex, searchDocumentation } from "../../research-mcp/search-index.js";
|
||||
import type { IndexedChunk } from "../../research-mcp/types.js";
|
||||
|
||||
const chunks: IndexedChunk[] = [
|
||||
@@ -33,36 +25,28 @@ const chunks: IndexedChunk[] = [
|
||||
},
|
||||
];
|
||||
|
||||
test("a serialized index reloads and filters search results by platform", async () => {
|
||||
const directory = await mkdtemp(path.join(tmpdir(), "review-research-index-"));
|
||||
try {
|
||||
const filePath = path.join(directory, "index.json");
|
||||
const built = buildSearchIndex(chunks, 2, "2026-08-06T00:00:00.000Z");
|
||||
await writeSearchIndex(filePath, built.serialized);
|
||||
const loaded = await loadSearchIndex(filePath);
|
||||
test("search filters results by platform and language", () => {
|
||||
const index = buildSearchIndex(chunks);
|
||||
|
||||
const appleResults = searchDocumentation(loaded, "main actor dispatch queue", {
|
||||
platform: "apple",
|
||||
language: "swift",
|
||||
limit: 5,
|
||||
});
|
||||
expect(appleResults).toHaveLength(1);
|
||||
expect(appleResults[0]?.title).toBe("MainActor");
|
||||
expect(appleResults[0]?.nextPassageId).toBe("apple:2");
|
||||
const appleResults = searchDocumentation(index, "main actor dispatch queue", {
|
||||
platform: "apple",
|
||||
language: "swift",
|
||||
limit: 5,
|
||||
});
|
||||
expect(appleResults).toHaveLength(1);
|
||||
expect(appleResults[0]?.title).toBe("MainActor");
|
||||
expect(appleResults[0]?.nextPassageId).toBe("apple:2");
|
||||
|
||||
const androidResults = searchDocumentation(loaded, "lifecycle callbacks", {
|
||||
platform: "android",
|
||||
limit: 5,
|
||||
});
|
||||
expect(androidResults).toHaveLength(1);
|
||||
expect(androidResults[0]?.platform).toBe("android");
|
||||
} finally {
|
||||
await rm(directory, { recursive: true, force: true });
|
||||
}
|
||||
const androidResults = searchDocumentation(index, "lifecycle callbacks", {
|
||||
platform: "android",
|
||||
limit: 5,
|
||||
});
|
||||
expect(androidResults).toHaveLength(1);
|
||||
expect(androidResults[0]?.platform).toBe("android");
|
||||
});
|
||||
|
||||
test("search rejects empty and oversized queries", () => {
|
||||
const index = buildSearchIndex(chunks, 2);
|
||||
const index = buildSearchIndex(chunks);
|
||||
expect(() => searchDocumentation(index, "\u0000\n", { platform: "all", limit: 5 })).toThrow(
|
||||
/between 1 and 300/,
|
||||
);
|
||||
@@ -72,19 +56,16 @@ test("search rejects empty and oversized queries", () => {
|
||||
});
|
||||
|
||||
test("symbol queries do not fall back to unrelated partial matches", () => {
|
||||
const index = buildSearchIndex(
|
||||
[
|
||||
{
|
||||
id: "android:unrelated",
|
||||
platform: "android",
|
||||
title: "Transient UI",
|
||||
url: "https://developer.android.com/example",
|
||||
passage: "A transient user interface action.",
|
||||
indexedAt: "2026-08-06T00:00:00.000Z",
|
||||
},
|
||||
],
|
||||
1,
|
||||
);
|
||||
const index = buildSearchIndex([
|
||||
{
|
||||
id: "android:unrelated",
|
||||
platform: "android",
|
||||
title: "Transient UI",
|
||||
url: "https://developer.android.com/example",
|
||||
passage: "A transient user interface action.",
|
||||
indexedAt: "2026-08-06T00:00:00.000Z",
|
||||
},
|
||||
]);
|
||||
|
||||
expect(
|
||||
searchDocumentation(index, "AudioManager AUDIOFOCUS_GAIN_TRANSIENT", {
|
||||
@@ -95,19 +76,16 @@ test("symbol queries do not fall back to unrelated partial matches", () => {
|
||||
});
|
||||
|
||||
test("symbol fallback keeps results anchored by canonical identity", () => {
|
||||
const index = buildSearchIndex(
|
||||
[
|
||||
{
|
||||
id: "apple:phasset",
|
||||
platform: "apple",
|
||||
title: "PHAsset",
|
||||
url: "https://developer.apple.com/documentation/photos/phasset",
|
||||
passage: "An image, video, or Live Photo in the Photos library.",
|
||||
indexedAt: "2026-08-06T00:00:00.000Z",
|
||||
},
|
||||
],
|
||||
1,
|
||||
);
|
||||
const index = buildSearchIndex([
|
||||
{
|
||||
id: "apple:phasset",
|
||||
platform: "apple",
|
||||
title: "PHAsset",
|
||||
url: "https://developer.apple.com/documentation/photos/phasset",
|
||||
passage: "An image, video, or Live Photo in the Photos library.",
|
||||
indexedAt: "2026-08-06T00:00:00.000Z",
|
||||
},
|
||||
]);
|
||||
|
||||
const results = searchDocumentation(index, "PHAsset location", {
|
||||
platform: "apple",
|
||||
@@ -117,19 +95,16 @@ test("symbol fallback keeps results anchored by canonical identity", () => {
|
||||
});
|
||||
|
||||
test("symbol anchors do not match identifier suffixes or generic acronyms", () => {
|
||||
const index = buildSearchIndex(
|
||||
[
|
||||
{
|
||||
id: "android:audio-focus-builder",
|
||||
platform: "android",
|
||||
title: "AudioFocusRequest.Builder API",
|
||||
url: "https://developer.android.com/reference/android/media/AudioFocusRequest.Builder",
|
||||
passage: "Builds an audio focus request with a custom listener.",
|
||||
indexedAt: "2026-08-06T00:00:00.000Z",
|
||||
},
|
||||
],
|
||||
1,
|
||||
);
|
||||
const index = buildSearchIndex([
|
||||
{
|
||||
id: "android:audio-focus-builder",
|
||||
platform: "android",
|
||||
title: "AudioFocusRequest.Builder API",
|
||||
url: "https://developer.android.com/reference/android/media/AudioFocusRequest.Builder",
|
||||
passage: "Builds an audio focus request with a custom listener.",
|
||||
indexedAt: "2026-08-06T00:00:00.000Z",
|
||||
},
|
||||
]);
|
||||
|
||||
expect(
|
||||
searchDocumentation(index, "OkHttp Request.Builder custom header API", {
|
||||
@@ -140,31 +115,28 @@ test("symbol anchors do not match identifier suffixes or generic acronyms", () =
|
||||
});
|
||||
|
||||
test("search filters named corpora and provenance classes", () => {
|
||||
const index = buildSearchIndex(
|
||||
[
|
||||
{
|
||||
id: "glide:cache",
|
||||
platform: "android",
|
||||
provider: "glide",
|
||||
sourceKind: "official-guide",
|
||||
title: "Glide caching",
|
||||
url: "https://bumptech.github.io/glide/doc/caching.html",
|
||||
passage: "Configure a custom DiskCache implementation.",
|
||||
indexedAt: "2026-08-06T00:00:00.000Z",
|
||||
},
|
||||
{
|
||||
id: "jetbrains:cache",
|
||||
platform: "android",
|
||||
provider: "jetbrains-issues",
|
||||
sourceKind: "issue-tracker",
|
||||
title: "Cache issue",
|
||||
url: "https://youtrack.jetbrains.com/issue/IDEA-1",
|
||||
passage: "A user reported a DiskCache problem.",
|
||||
indexedAt: "2026-08-06T00:00:00.000Z",
|
||||
},
|
||||
],
|
||||
2,
|
||||
);
|
||||
const index = buildSearchIndex([
|
||||
{
|
||||
id: "glide:cache",
|
||||
platform: "android",
|
||||
provider: "glide",
|
||||
sourceKind: "official-guide",
|
||||
title: "Glide caching",
|
||||
url: "https://bumptech.github.io/glide/doc/caching.html",
|
||||
passage: "Configure a custom DiskCache implementation.",
|
||||
indexedAt: "2026-08-06T00:00:00.000Z",
|
||||
},
|
||||
{
|
||||
id: "jetbrains:cache",
|
||||
platform: "android",
|
||||
provider: "jetbrains-issues",
|
||||
sourceKind: "issue-tracker",
|
||||
title: "Cache issue",
|
||||
url: "https://youtrack.jetbrains.com/issue/IDEA-1",
|
||||
passage: "A user reported a DiskCache problem.",
|
||||
indexedAt: "2026-08-06T00:00:00.000Z",
|
||||
},
|
||||
]);
|
||||
|
||||
const results = searchDocumentation(index, "DiskCache", {
|
||||
platform: "android",
|
||||
@@ -178,20 +150,17 @@ test("search filters named corpora and provenance classes", () => {
|
||||
});
|
||||
|
||||
test("a language filter excludes otherwise matching untagged documents", () => {
|
||||
const index = buildSearchIndex(
|
||||
[
|
||||
...chunks,
|
||||
{
|
||||
id: "apple:untagged",
|
||||
platform: "apple",
|
||||
title: "MainActor overview",
|
||||
url: "https://developer.apple.com/documentation/swift/mainactor-overview",
|
||||
passage: "Main actor dispatch queue behavior without language metadata.",
|
||||
indexedAt: "2026-08-06T00:00:00.000Z",
|
||||
},
|
||||
],
|
||||
3,
|
||||
);
|
||||
const index = buildSearchIndex([
|
||||
...chunks,
|
||||
{
|
||||
id: "apple:untagged",
|
||||
platform: "apple",
|
||||
title: "MainActor overview",
|
||||
url: "https://developer.apple.com/documentation/swift/mainactor-overview",
|
||||
passage: "Main actor dispatch queue behavior without language metadata.",
|
||||
indexedAt: "2026-08-06T00:00:00.000Z",
|
||||
},
|
||||
]);
|
||||
|
||||
const results = searchDocumentation(index, "MainActor dispatch queue", {
|
||||
platform: "apple",
|
||||
|
||||
@@ -106,16 +106,14 @@ test("research child environment forwards only locale, proxy variables, and the
|
||||
expect(researchChildEnvironment({ PATH: "/private/bin" })).not.toHaveProperty("PATH");
|
||||
});
|
||||
|
||||
test("research index fallback is absolute and research remains root-only", () => {
|
||||
expect(
|
||||
ReviewConfigSchema.safeParse({ research: { enabled: true, indexPath: "index.json" } }).success,
|
||||
).toBe(false);
|
||||
test("research is root-only and rejects an unknown key", () => {
|
||||
expect(ReviewConfigSchema.safeParse({ research: { enabled: true } }).success).toBe(true);
|
||||
// The offline index is gone; a stale config naming it must fail loudly rather
|
||||
// than be silently ignored.
|
||||
expect(
|
||||
ReviewConfigSchema.safeParse({
|
||||
research: { enabled: true, indexPath: path.join(tmpdir(), "index.json") },
|
||||
}).success,
|
||||
).toBe(true);
|
||||
ReviewConfigSchema.safeParse({ research: { enabled: true, indexPath: "/tmp/index.json" } })
|
||||
.success,
|
||||
).toBe(false);
|
||||
expect(ScopeReviewConfigSchema.safeParse({ research: { enabled: false } }).success).toBe(false);
|
||||
});
|
||||
|
||||
|
||||
+4
-5
@@ -578,11 +578,10 @@ async function runLegacyCi(
|
||||
// Dynamic stack context and model-backed reply adjudication have inputs outside
|
||||
// the scoped diff. Keep those paths fresh until their inputs join the cache key.
|
||||
// A maintainer's explicit /review is also always a real rerun.
|
||||
// Research output depends on the mounted index contents, not merely its configured
|
||||
// path. Until a signed index digest joins the cache key, a researched review must
|
||||
// run fresh rather than reuse evidence from an older artifact at the same path.
|
||||
const cacheAllowed =
|
||||
!bypassTriggerGate && !stack && !feedback && !config.research.enabled && metadata !== undefined;
|
||||
// Research no longer forces a fresh run: with the local index gone, every result
|
||||
// is fetched live from an allowlisted host during the run, so there is no mounted
|
||||
// artifact whose contents could drift out from under the cache key.
|
||||
const cacheAllowed = !bypassTriggerGate && !stack && !feedback && metadata !== undefined;
|
||||
let inputHash: string | undefined;
|
||||
|
||||
try {
|
||||
|
||||
@@ -65,10 +65,14 @@ export const ReviewConfigSchema = z.object({
|
||||
research: z
|
||||
.object({
|
||||
enabled: z.boolean().default(false),
|
||||
// Removed with the offline index. An unknown key would be stripped silently,
|
||||
// so name it explicitly: a config carrying it is stale, and quietly ignoring
|
||||
// the setting is worse than refusing to start.
|
||||
indexPath: z
|
||||
.string()
|
||||
.min(1)
|
||||
.refine((value) => path.isAbsolute(value), "research.indexPath must be an absolute path")
|
||||
.never({
|
||||
error:
|
||||
"research.indexPath was removed — documentation is now always fetched live from the provider allowlist. Delete this key.",
|
||||
})
|
||||
.optional(),
|
||||
maxQueries: z.number().int().min(1).max(20).default(8),
|
||||
resultsPerQuery: z.number().int().min(1).max(3).default(2),
|
||||
@@ -433,7 +437,6 @@ export interface LoadedConfig {
|
||||
/** Root-only configuration for the bundled, bounded documentation MCP. */
|
||||
research: {
|
||||
enabled: boolean;
|
||||
indexPath?: string;
|
||||
maxQueries: number;
|
||||
resultsPerQuery: number;
|
||||
timeoutMs: number;
|
||||
|
||||
@@ -146,11 +146,7 @@ export async function createResearchMcpRuntime(
|
||||
const auditPath = path.join(directory, "audit.jsonl");
|
||||
const claudeConfigPath = path.join(directory, "mcp.json");
|
||||
const server = bundledResearchServer();
|
||||
const args = [
|
||||
...server.args,
|
||||
"serve",
|
||||
...(config.indexPath ? ["--index", config.indexPath] : []),
|
||||
];
|
||||
const args = [...server.args, "serve"];
|
||||
const child = researchChildEnvironment();
|
||||
const environment = Object.fromEntries(
|
||||
Object.entries({
|
||||
|
||||
@@ -37,7 +37,6 @@ export const RESEARCH_SEARCH_API_KEY = "BRAVE_SEARCH_API_KEY";
|
||||
*/
|
||||
export const RESEARCH_RUNTIME_ENV_KEYS = [
|
||||
"REVIEW_RESEARCH_AUDIT_PATH",
|
||||
"REVIEW_RESEARCH_INDEX_PATH",
|
||||
"REVIEW_RESEARCH_MAX_CALLS",
|
||||
"REVIEW_RESEARCH_MAX_RESULTS",
|
||||
"REVIEW_RESEARCH_TIMEOUT_MS",
|
||||
|
||||
+10
-61
@@ -1,28 +1,20 @@
|
||||
#!/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
|
||||
// @ref LLP 0013#one-package-two-binaries [implements] — the package's second binary serves the bounded MCP
|
||||
// @ref LLP 0013#search-fetch-and-optional-index-boundary [implements] — live discovery is the only evidence path
|
||||
|
||||
import { parseArgs } from "node:util";
|
||||
|
||||
import { defaultConfigPath } from "./paths.js";
|
||||
import { runStdioServer } from "./server.js";
|
||||
import { PLATFORMS, type Platform } 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. Its fetch_platform_doc tool can fetch
|
||||
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.
|
||||
The serve command uses BRAVE_SEARCH_API_KEY for scoped web discovery and fetches only
|
||||
allowlisted official pages. 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 and return focused, section, or bounded-document extracted
|
||||
context.
|
||||
`);
|
||||
}
|
||||
|
||||
@@ -48,16 +40,10 @@ async function main() {
|
||||
printHelp();
|
||||
return;
|
||||
}
|
||||
const { values } = parseArgs({
|
||||
args: rest,
|
||||
options: {
|
||||
index: { type: "string" },
|
||||
},
|
||||
strict: true,
|
||||
});
|
||||
const indexPath = values.index ?? process.env.REVIEW_RESEARCH_INDEX_PATH;
|
||||
if (rest.length > 0) {
|
||||
throw new Error(`Unexpected argument: ${rest[0]}`);
|
||||
}
|
||||
await runStdioServer({
|
||||
...(indexPath ? { indexPath } : {}),
|
||||
...(process.env.REVIEW_RESEARCH_AUDIT_PATH
|
||||
? { auditPath: process.env.REVIEW_RESEARCH_AUDIT_PATH }
|
||||
: {}),
|
||||
@@ -71,43 +57,6 @@ async function main() {
|
||||
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 as 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 as Platform[] } : {}),
|
||||
...(maxPages ? { maxPagesPerProvider: maxPages } : {}),
|
||||
});
|
||||
process.stderr.write(`${JSON.stringify(result, null, 2)}\n`);
|
||||
return;
|
||||
}
|
||||
|
||||
throw new Error(`Unknown command: ${command}`);
|
||||
}
|
||||
|
||||
|
||||
@@ -1,214 +0,0 @@
|
||||
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, type DocumentationProvider } from "./providers.js";
|
||||
import { buildSearchIndex, writeSearchIndex } from "./search-index.js";
|
||||
import { extractYouTrackIssue } from "./youtrack.js";
|
||||
import {
|
||||
PLATFORMS,
|
||||
PROVIDERS,
|
||||
SOURCE_KINDS,
|
||||
type DiscoveredDocument,
|
||||
type IndexedChunk,
|
||||
type Platform,
|
||||
type ProviderId,
|
||||
type SourceDefinition,
|
||||
type SourcesConfig,
|
||||
} 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),
|
||||
});
|
||||
|
||||
interface CrawlItem {
|
||||
url: URL;
|
||||
depth: number;
|
||||
}
|
||||
|
||||
interface CrawlResult {
|
||||
provider: ProviderId;
|
||||
platform: Platform;
|
||||
documents: DiscoveredDocument[];
|
||||
errors: string[];
|
||||
}
|
||||
|
||||
export interface UpdateOptions {
|
||||
configPath: string;
|
||||
outputPath?: string;
|
||||
platforms?: Platform[];
|
||||
maxPagesPerProvider?: number;
|
||||
}
|
||||
|
||||
function sleep(milliseconds: number) {
|
||||
return new Promise((resolve) => setTimeout(resolve, milliseconds));
|
||||
}
|
||||
|
||||
async function crawlProvider(
|
||||
provider: DocumentationProvider,
|
||||
source: SourceDefinition,
|
||||
limits: SourcesConfig["crawl"],
|
||||
): Promise<CrawlResult> {
|
||||
const queue: CrawlItem[] = [];
|
||||
const errors: string[] = [];
|
||||
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<string>();
|
||||
const documents: DiscoveredDocument[] = [];
|
||||
|
||||
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: string): Promise<SourcesConfig> {
|
||||
return sourcesConfigSchema.parse(JSON.parse(await readFile(configPath, "utf8")));
|
||||
}
|
||||
|
||||
export function resolveIndexOutputPath(
|
||||
configPath: string,
|
||||
configuredOutput: string,
|
||||
outputPath?: string,
|
||||
): string {
|
||||
if (outputPath) return path.resolve(outputPath);
|
||||
return path.resolve(path.dirname(path.resolve(configPath)), configuredOutput);
|
||||
}
|
||||
|
||||
export async function updateDocumentationIndex(options: UpdateOptions) {
|
||||
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: IndexedChunk[] = 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,
|
||||
})),
|
||||
};
|
||||
}
|
||||
@@ -100,7 +100,7 @@ function rankedAnchor(
|
||||
query?: string,
|
||||
): SearchResult | undefined {
|
||||
if (!query?.trim()) return chunks[0] ? withScore(chunks[0]) : undefined;
|
||||
const index = buildSearchIndex(chunks, 1);
|
||||
const index = buildSearchIndex(chunks);
|
||||
return (
|
||||
searchDocumentation(index, query, {
|
||||
platform: document.platform,
|
||||
|
||||
@@ -7,14 +7,17 @@ import {
|
||||
type DocumentationProvider,
|
||||
} from "./providers.js";
|
||||
import { readBodyWithLimit } from "./response.js";
|
||||
import type { DiscoveredDocument, ProviderId, SourceKind, SourcesConfig } from "./types.js";
|
||||
import type { DiscoveredDocument, ProviderId, SourceKind } from "./types.js";
|
||||
import { extractYouTrackIssue } from "./youtrack.js";
|
||||
import type { FetchImplementation } from "./brave-search.js";
|
||||
|
||||
export const onDemandFetchLimits: SourcesConfig["crawl"] = {
|
||||
maxPagesPerProvider: 10,
|
||||
maxDepth: 0,
|
||||
delayMs: 0,
|
||||
/** Per-attempt bounds for one documentation request. */
|
||||
export interface DocumentFetchLimits {
|
||||
timeoutMs: number;
|
||||
maxResponseBytes: number;
|
||||
}
|
||||
|
||||
export const onDemandFetchLimits: DocumentFetchLimits = {
|
||||
timeoutMs: 10_000,
|
||||
maxResponseBytes: 5_000_000,
|
||||
};
|
||||
@@ -22,7 +25,7 @@ export const onDemandFetchLimits: SourcesConfig["crawl"] = {
|
||||
export async function fetchAllowedContent(
|
||||
provider: DocumentationProvider,
|
||||
documentUrl: URL,
|
||||
limits: Pick<SourcesConfig["crawl"], "timeoutMs" | "maxResponseBytes">,
|
||||
limits: DocumentFetchLimits,
|
||||
fetchImplementation: FetchImplementation = fetch,
|
||||
): Promise<string> {
|
||||
let currentUrl = resolveAllowedRequestUrl(provider, provider.requestUrl(documentUrl).href);
|
||||
|
||||
@@ -73,7 +73,7 @@ async function loadOkHttpSearchIndex(
|
||||
}
|
||||
});
|
||||
const chunks = documents.flatMap((document) => chunkDocument(document, indexedAt));
|
||||
return buildSearchIndex(chunks, documents.length, indexedAt);
|
||||
return buildSearchIndex(chunks);
|
||||
}
|
||||
|
||||
function cachedOkHttpSearchIndex(
|
||||
|
||||
@@ -1,9 +0,0 @@
|
||||
import { fileURLToPath } from "node:url";
|
||||
|
||||
export const packageRoot = fileURLToPath(new URL("../..", import.meta.url));
|
||||
export const defaultConfigPath = fileURLToPath(
|
||||
new URL("../../research/sources.json", import.meta.url),
|
||||
);
|
||||
export const defaultIndexPath = fileURLToPath(
|
||||
new URL("../../research/data/docs-index.json", import.meta.url),
|
||||
);
|
||||
@@ -139,7 +139,7 @@ function bestPassage(
|
||||
if (chunks.length === 0) {
|
||||
return { passage: document.body.slice(0, 1_400), relevance: 0 };
|
||||
}
|
||||
const index = buildSearchIndex(chunks, 1, indexedAt);
|
||||
const index = buildSearchIndex(chunks);
|
||||
const result = searchDocumentation(index, query, {
|
||||
platform: document.platform,
|
||||
providers: document.provider ? [document.provider] : undefined,
|
||||
|
||||
@@ -1,6 +1,3 @@
|
||||
import { mkdir, readFile, rename, writeFile } from "node:fs/promises";
|
||||
import path from "node:path";
|
||||
|
||||
import MiniSearch, { type SearchOptions } from "minisearch";
|
||||
|
||||
import type {
|
||||
@@ -10,7 +7,6 @@ import type {
|
||||
PlatformFilter,
|
||||
ProviderId,
|
||||
SearchResult,
|
||||
SerializedSearchIndex,
|
||||
SourceKind,
|
||||
} from "./types.js";
|
||||
|
||||
@@ -35,51 +31,18 @@ const miniSearchOptions = {
|
||||
};
|
||||
|
||||
export interface BuiltSearchIndex {
|
||||
serialized: SerializedSearchIndex;
|
||||
miniSearch: MiniSearch<IndexedChunk>;
|
||||
}
|
||||
|
||||
export function buildSearchIndex(
|
||||
chunks: IndexedChunk[],
|
||||
documentCount: number,
|
||||
generatedAt = new Date().toISOString(),
|
||||
): BuiltSearchIndex {
|
||||
/**
|
||||
* Build a throwaway in-memory index over one fetch's chunks, purely to rank them.
|
||||
* Nothing is serialized or persisted: since the offline index was removed, every
|
||||
* caller builds this per request and discards it.
|
||||
*/
|
||||
export function buildSearchIndex(chunks: IndexedChunk[]): BuiltSearchIndex {
|
||||
const miniSearch = new MiniSearch<IndexedChunk>(miniSearchOptions);
|
||||
miniSearch.addAll(chunks);
|
||||
|
||||
const providers = [
|
||||
...new Set(chunks.map((chunk) => chunk.provider ?? chunk.platform)),
|
||||
].sort() as ProviderId[];
|
||||
return {
|
||||
miniSearch,
|
||||
serialized: {
|
||||
schemaVersion: 1,
|
||||
generatedAt,
|
||||
documentCount,
|
||||
chunkCount: chunks.length,
|
||||
providers,
|
||||
searchIndex: miniSearch.toJSON(),
|
||||
},
|
||||
};
|
||||
}
|
||||
|
||||
export async function writeSearchIndex(filePath: string, index: SerializedSearchIndex) {
|
||||
await mkdir(path.dirname(filePath), { recursive: true });
|
||||
const temporaryPath = `${filePath}.tmp-${process.pid}`;
|
||||
await writeFile(temporaryPath, `${JSON.stringify(index)}\n`, { mode: 0o644 });
|
||||
await rename(temporaryPath, filePath);
|
||||
}
|
||||
|
||||
export async function loadSearchIndex(filePath: string): Promise<BuiltSearchIndex> {
|
||||
const serialized = JSON.parse(await readFile(filePath, "utf8")) as SerializedSearchIndex;
|
||||
if (serialized.schemaVersion !== 1 || typeof serialized.searchIndex !== "object") {
|
||||
throw new Error(`Unsupported or invalid search index at ${filePath}`);
|
||||
}
|
||||
const miniSearch = MiniSearch.loadJSON<IndexedChunk>(
|
||||
JSON.stringify(serialized.searchIndex),
|
||||
miniSearchOptions,
|
||||
);
|
||||
return { serialized, miniSearch };
|
||||
return { miniSearch };
|
||||
}
|
||||
|
||||
function searchOptions(combineWith: "AND" | "OR", exact = false): SearchOptions {
|
||||
|
||||
@@ -15,7 +15,6 @@ import { searchExpoAlgolia } from "./expo-algolia.js";
|
||||
import { searchOkHttpDocumentation } from "./okhttp-search.js";
|
||||
import { getProvider, resolveAllowedUrl } from "./providers.js";
|
||||
import { searchRemoteDocumentation } from "./remote-search.js";
|
||||
import { loadSearchIndex, searchDocumentation } from "./search-index.js";
|
||||
import { LANGUAGES, PROVIDERS, SOURCE_KINDS } from "./types.js";
|
||||
import type { PlatformFilter, ProviderId, SearchResult } from "./types.js";
|
||||
|
||||
@@ -29,7 +28,6 @@ const providerGuidance =
|
||||
"Provider map: apple=Apple SDK APIs and Human Interface Guidelines; apple-releases=Xcode and Apple platform release notes; swift-evolution=Swift Evolution proposals; sdwebimage=SDWebImage APIs and caching/loading behavior; android=Android, Jetpack, Compose, and Google Play services APIs; android-releases=Android platform releases and behavior changes; media3=Jetpack Media3; glide=Glide; okhttp=OkHttp; kotlin-coroutines=Kotlin coroutines; gradle=Gradle; agp=Android Gradle Plugin; jetbrains-issues=JetBrains YouTrack context; expo=Expo documentation; react-native=React Native core; react-native-reanimated=Reanimated; react-native-gesture-handler=Gesture Handler; react-native-screens=Screens; react-native-worklets=Worklets. Native source retains platform context: use apple/android for OS contracts and add the dependency provider for dependency-owned behavior; an Expo package path does not make a native API an Expo-docs query. Issue-tracker results are context, not API contracts.";
|
||||
|
||||
export interface DocumentationServerOptions {
|
||||
indexPath?: string;
|
||||
braveApiKey?: string;
|
||||
fetchImplementation?: FetchImplementation;
|
||||
auditPath?: string;
|
||||
@@ -47,7 +45,6 @@ function defaultProviders(platform: PlatformFilter): ProviderId[] {
|
||||
}
|
||||
|
||||
export async function createDocumentationServer(options: DocumentationServerOptions = {}) {
|
||||
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 timeoutMs = Math.min(60_000, Math.max(1_000, options.timeoutMs ?? 30_000));
|
||||
@@ -62,7 +59,7 @@ export async function createDocumentationServer(options: DocumentationServerOpti
|
||||
"search_platform_docs",
|
||||
{
|
||||
title: "Search official platform documentation",
|
||||
description: `Search official platform, dependency, build-tool, and release documentation. Discovery uses scoped web search (or Expo's public documentation search), then fetches only allowlisted official pages; an optional local index is fallback evidence. Returns short passages with canonical source URLs. ${providerGuidance} ${queryGuidance}`,
|
||||
description: `Search official platform, dependency, build-tool, and release documentation. Discovery uses scoped web search (or Expo's public documentation search), then fetches only allowlisted official pages. Returns short passages with canonical source URLs. ${providerGuidance} ${queryGuidance}`,
|
||||
inputSchema: {
|
||||
platform: z
|
||||
.enum(["apple", "android", "react-native", "all"])
|
||||
@@ -123,15 +120,6 @@ export async function createDocumentationServer(options: DocumentationServerOpti
|
||||
// One deadline and one request ledger for everything this call issues.
|
||||
const network = createResearchNetwork(baseFetch, timeoutMs);
|
||||
try {
|
||||
const localResults = index
|
||||
? searchDocumentation(index, sanitizedQuery, {
|
||||
platform,
|
||||
limit: boundedLimit,
|
||||
providers: selectedProviders,
|
||||
...(sourceKinds ? { sourceKinds } : {}),
|
||||
...(language ? { language } : {}),
|
||||
})
|
||||
: [];
|
||||
const warnings: string[] = [];
|
||||
const remoteResults: SearchResult[] = [];
|
||||
const perProviderLimit = Math.max(1, Math.ceil(boundedLimit / selectedProviders.length));
|
||||
@@ -226,7 +214,7 @@ export async function createDocumentationServer(options: DocumentationServerOpti
|
||||
}
|
||||
|
||||
const seen = new Set<string>();
|
||||
const results = [...remoteResults, ...localResults]
|
||||
const results = remoteResults
|
||||
.filter((result) => {
|
||||
if (!result.provider) return false;
|
||||
try {
|
||||
@@ -249,12 +237,6 @@ export async function createDocumentationServer(options: DocumentationServerOpti
|
||||
// What this single budget unit actually cost.
|
||||
network: network_,
|
||||
expoSearch: selectedProviders.includes("expo"),
|
||||
localIndex: index
|
||||
? {
|
||||
generatedAt: index.serialized.generatedAt,
|
||||
providers: index.serialized.providers,
|
||||
}
|
||||
: null,
|
||||
},
|
||||
...(uniqueWarnings.length > 0 ? { warnings: uniqueWarnings } : {}),
|
||||
results,
|
||||
|
||||
@@ -82,25 +82,3 @@ export interface SerializedSearchIndex {
|
||||
providers: ProviderId[];
|
||||
searchIndex: unknown;
|
||||
}
|
||||
|
||||
export interface CrawlLimits {
|
||||
maxPagesPerProvider: number;
|
||||
maxDepth: number;
|
||||
delayMs: number;
|
||||
timeoutMs: number;
|
||||
maxResponseBytes: number;
|
||||
}
|
||||
|
||||
export interface SourceDefinition {
|
||||
provider: ProviderId;
|
||||
sourceKind: SourceKind;
|
||||
seedUrls: string[];
|
||||
maxPages?: number;
|
||||
maxDepth?: number;
|
||||
}
|
||||
|
||||
export interface SourcesConfig {
|
||||
output: string;
|
||||
crawl: CrawlLimits;
|
||||
sources: SourceDefinition[];
|
||||
}
|
||||
@@ -39,7 +39,8 @@
|
||||
//
|
||||
// maxQueries bounds MCP CALLS, not requests — one search can issue a discovery
|
||||
// request per provider plus a page fetch per candidate. timeoutMs is the MCP's own
|
||||
// end-to-end deadline per call. indexPath remains an optional offline fallback.
|
||||
// end-to-end deadline per call. Every passage is fetched live from the allowlist;
|
||||
// there is no offline index.
|
||||
// "research": {
|
||||
// "enabled": true,
|
||||
// "maxQueries": 8,
|
||||
|
||||
Reference in new issue
Block a user