rbxstudio-mcp 2.3.1 → 2.4.0

package/dist/docs/search.d.ts

@@ -0,0 +1,194 @@
+/**
+ * Pure-JS regex search over the cached docs tree.
+ *
+ * Why not shell out to ripgrep?
+ *   1. We can't assume `rg` is on the user's PATH (npm package, no
+ *      system-deps story).
+ *   2. The cached tree is small (~30MB, ~3k files). A naive
+ *      Promise.all() walk + JS regex on each file finishes in ~50–
+ *      200ms cold-cache and ~10–40ms hot-cache, which is fine for an
+ *      interactive tool call.
+ *   3. We get full control of result shape, context lines, and graceful
+ *      ignore of binary garbage.
+ *
+ * If this ever becomes a bottleneck the obvious upgrade is an in-memory
+ * grep index keyed by 4-grams or similar — but YAGNI for now.
+ */
+export interface SearchHit {
+    /** Doc path relative to the content root, e.g. "en-us/reference/engine/classes/Part.yaml". */
+    path: string;
+    /** 1-indexed line number inside the file. */
+    line: number;
+    /** The matching line (rstripped). */
+    text: string;
+    /** Optional surrounding lines, included only when contextLines > 0 (or token-AND mode). */
+    context?: {
+        line: number;
+        text: string;
+    }[];
+    /**
+     * Token-AND mode only: which tokens matched the anchor line itself.
+     * Useful for the model to see "this line has Motor6D, but C0 is in the
+     * surrounding context".
+     */
+    matchedTokens?: string[];
+    /**
+     * Hybrid mode only: aggregate score in [0, 1] used to rank this hit.
+     * Combines keyword token coverage and semantic similarity. Populated
+     * by `searchDocsHybrid`; absent in pure literal / token-AND modes.
+     */
+    score?: number;
+    /**
+     * Hybrid mode only: raw cosine similarity of the embedding of the
+     * passage containing this hit against the query embedding, in
+     * [-1, 1]. Useful for the model to gauge how "topical" the hit is.
+     */
+    semanticScore?: number;
+}
+export interface SearchOptions {
+    /** Restrict to a subdirectory of `content/` (e.g. "en-us/animation"). */
+    scope?: string;
+    /** File extensions to search (default ["md","yaml","yml"]). Pass without leading dot. */
+    extensions?: string[];
+    /** Treat `pattern` as a JS regex instead of a literal string. Default false. */
+    useRegex?: boolean;
+    /** Case-sensitive match. Default false. */
+    caseSensitive?: boolean;
+    /** Lines of context before/after each hit (like grep -C). Default 0. */
+    contextLines?: number;
+    /** Hard cap on hits returned. Default 200 — generous but bounded. */
+    maxHits?: number;
+    /**
+     * Token-AND mode: lines of slack on either side of the anchor in which
+     * every whitespace-separated token in the query must appear at least
+     * once. Default 3. Ignored when `useRegex: true` or the query is a
+     * single token (those fall back to literal substring search).
+     */
+    windowLines?: number;
+    /**
+     * Semantic rerank toggle. Defaults to true.
+     *
+     * When true AND the query is in token-AND mode (multi-token, not
+     * regex), the keyword hits are reranked by cosine similarity against
+     * a sentence-embedding index of the docs. This dramatically improves
+     * relevance for natural-language queries while preserving all the
+     * keyword guarantees (every returned hit still contains all tokens
+     * within `windowLines`).
+     *
+     * Set to false to force pure keyword mode — useful for deterministic
+     * tests or when the semantic index is unavailable / undesired.
+     *
+     * Has no effect in literal mode (single token, quoted phrase, regex)
+     * because those queries already have unambiguous ranking by file
+     * position.
+     */
+    semantic?: boolean;
+}
+export interface SearchSummary {
+    totalHits: number;
+    truncated: boolean;
+    hits: SearchHit[];
+    /** How many files were scanned (not skipped by extension/scope filters). */
+    filesScanned: number;
+    /** ms spent inside this call. */
+    durationMs: number;
+    /**
+     * "literal"   = single-token / regex / single phrase.
+     * "token-and" = multi-token AND-match within `windowLines`.
+     * "hybrid"    = token-AND filtering + semantic rerank.
+     */
+    mode: 'literal' | 'token-and' | 'hybrid';
+    /** Tokens we actually searched for in token-and / hybrid mode. */
+    tokens?: string[];
+    /**
+     * Hybrid mode only: whether the semantic index was actually used. False
+     * means we wanted to rerank but the index was unavailable (first call
+     * before build finished, model download failure, etc.) and we fell
+     * back to plain keyword ranking. Lets the caller decide whether to
+     * retry, warm the cache, or just accept keyword results.
+     */
+    semanticUsed?: boolean;
+    /**
+     * Hybrid mode only: whether the returned hits are guaranteed to
+     * contain every meaningful query token. True for the normal
+     * "keyword AND + semantic rerank" path. False when keyword filtering
+     * yielded zero candidates and we fell back to pure-semantic top-K
+     * over the chunk index — in that case the model should treat hits
+     * as "topically relevant" rather than "lexically matching".
+     */
+    keywordFiltered?: boolean;
+}
+/**
+ * Inputs passed to `searchDocs` *in addition to* the public options.
+ * Currently just the docs SHA so the hybrid path can locate the right
+ * vector index. Keeping this out of `SearchOptions` because it's
+ * server-internal — the LLM never sets it.
+ */
+export interface InternalSearchInputs {
+    /** Docs cache SHA, used to load/build the semantic index. */
+    docsSha?: string;
+}
+/**
+ * Top-level entry point. Decides between literal (single-token / regex)
+ * and token-AND (multi-token, windowed) search and dispatches.
+ *
+ * Token-AND mode triggers when ALL of:
+ *   - `useRegex: false` (or unset)
+ *   - the tokenized query has 2+ tokens
+ *
+ * Why? Plain literal substring is "the docs say `Motor6D C0` somewhere?"
+ * which is almost never true (the docs use dotted/quoted forms like
+ * `Class.Motor6D.C0|C0`). Token-AND turns the query into "find lines
+ * where Motor6D and C0 are both nearby", which is what the model
+ * actually meant.
+ */
+export declare function searchDocs(cacheDir: string, pattern: string, options?: SearchOptions, internal?: InternalSearchInputs): Promise<SearchSummary>;
+/**
+ * Read a single doc file by its content-relative path.
+ *
+ * Two flavors of input are accepted to make the LLM-facing tool more
+ * forgiving:
+ *   • "en-us/reference/engine/classes/Part.yaml" (canonical)
+ *   • "Part" / "Part.yaml" — best-effort lookup under reference/engine
+ *     (handled by `resolveReferenceDoc` in reference.ts, not here).
+ */
+export declare function readDocFile(cacheDir: string, relPath: string): Promise<{
+    path: string;
+    bytes: number;
+    content: string;
+} | null>;
+/**
+ * List doc files / subdirectories under a given relative path.
+ *
+ * Returns a flat structured listing intended for an LLM to navigate
+ * (think `ls`, not `tree`).
+ *
+ * Paginated: the engine docs `classes/` directory has ~1000 YAMLs and
+ * blowing all of them into a single tool response is just expensive
+ * tokens for nothing. Pass `offset`/`limit` to page through; default
+ * limit is 100. The full count is reported as `totalEntries`.
+ */
+export interface DocListing {
+    path: string;
+    /** Total number of children at this path (across all pages). */
+    totalEntries: number;
+    /** Page offset that produced `entries`. */
+    offset: number;
+    /** Page limit that produced `entries`. */
+    limit: number;
+    /** True if there are more entries beyond this page. */
+    truncated: boolean;
+    entries: {
+        name: string;
+        type: 'file' | 'dir';
+        size?: number;
+    }[];
+}
+export interface ListOptions {
+    /** Page offset (default 0). */
+    offset?: number;
+    /** Page size (default 100, max 1000). */
+    limit?: number;
+}
+export declare function listDocs(cacheDir: string, relPath?: string, options?: ListOptions): Promise<DocListing | null>;
+//# sourceMappingURL=search.d.ts.map

package/dist/docs/search.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"search.d.ts","sourceRoot":"","sources":["../../src/docs/search.ts"],"names":[],"mappings":"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"}