opencode-rag-plugin 1.15.1 → 1.17.0

package/dist/eval/run-branch-compare.js

@@ -0,0 +1,220 @@
+/**
+ * @fileoverview Branch comparison benchmark — runs N queries against the indexed codebase
+ * and outputs per-query results as JSON for later comparison.
+ *
+ * Usage: node --import tsx src/eval/run-branch-compare.ts --output .opencode/rag_db/eval-results/branch.json
+ */
+import { writeFileSync } from "node:fs";
+import path from "node:path";
+import { loadConfig, DEFAULT_CONFIG } from "../core/config.js";
+import { createEmbedder } from "../embedder/factory.js";
+import { createVectorStore } from "../vectorstore/factory.js";
+import { retrieve } from "../retriever/retriever.js";
+import { KeywordIndex } from "../retriever/keyword-index.js";
+import { loadRuntimeOverrides, applyRuntimeOverrides, } from "../core/runtime-overrides.js";
+import { resolveApiKey } from "../core/resolve-api-key.js";
+import { execSync } from "node:child_process";
+const WORKTREE = process.cwd();
+const STORE_PATH = path.join(WORKTREE, ".opencode", "rag_db");
+const QUERIES = [
+    "How does the retrieval pipeline work end-to-end?",
+    "How does the plugin interact with chat messages?",
+    "How does the keyword index combine with vector search?",
+    "Where is the embedder factory defined?",
+    "Where is the LanceDB store implementation?",
+    "Find all usages of the retrieve function",
+    "Find all usages of SearchResult type",
+    "How does the chunker factory register new languages?",
+    "What is the default minScore configuration?",
+    "How does the session logger capture token usage?",
+    "How does L2 normalization affect vector search scores?",
+    "What is the MetadataFilter interface used for?",
+    "How does the background indexer handle file changes?",
+    "Where is the config validation logic?",
+    "How are PDF documents chunked and indexed?",
+    "What embedding providers are supported?",
+    "How does the CLI parse and dispatch commands?",
+    "How does the session logger persist events?",
+    "What is the manifest schema version used for?",
+    "How does the OpenCode plugin register tools?",
+    "Where is the globMatch function defined?",
+    "How does the proxy-aware HTTP client work?",
+    "What is the FETCH_OVERFETCH_FACTOR constant?",
+    "How does the TUI settings menu work?",
+    "How are image descriptions generated?",
+    // Set B — Code-identifier queries (test hybrid search with keyword contributions)
+    "retrieve function",
+    "KeywordIndex class",
+    "embedder factory",
+    "vector store LanceDB",
+    "find usages SearchResult",
+    "chunkFile method",
+    "embedBatch function",
+    "retriever retrieve vector search",
+    "session logger token",
+    "config validation",
+];
+const THRESHOLDS = [0.85, 0.75, 0.65, 0.50, 0.35];
+function getGitInfo() {
+    try {
+        const branch = execSync("git rev-parse --abbrev-ref HEAD", {
+            encoding: "utf-8",
+        }).trim();
+        const commit = execSync("git rev-parse --short HEAD", {
+            encoding: "utf-8",
+        }).trim();
+        return { branch, commit };
+    }
+    catch {
+        return { branch: "unknown", commit: "unknown" };
+    }
+}
+function getConfig() {
+    const configPath = path.join(WORKTREE, "opencode-rag.json");
+    let cfg;
+    try {
+        cfg = loadConfig(configPath);
+    }
+    catch {
+        cfg = DEFAULT_CONFIG;
+    }
+    const overrides = loadRuntimeOverrides(STORE_PATH);
+    cfg = applyRuntimeOverrides(cfg, overrides);
+    resolveApiKey(cfg, WORKTREE);
+    return cfg;
+}
+async function probeDimension(embedder) {
+    try {
+        const probe = await embedder.embed(["dimension-probe"], "query");
+        if (probe.length > 0 && probe[0].length > 0) {
+            return probe[0].length;
+        }
+    }
+    catch {
+        // fall through to default
+    }
+    return 384;
+}
+function topResults(results, worktree, max = 5) {
+    return results.slice(0, max).map((r, i) => {
+        const exp = r.explanation;
+        return {
+            rank: i,
+            score: r.score,
+            filePath: path.relative(worktree, r.chunk.metadata.filePath).replace(/\\/g, "/"),
+            startLine: r.chunk.metadata.startLine,
+            endLine: r.chunk.metadata.endLine,
+            language: r.chunk.metadata.language,
+            explanation: exp
+                ? {
+                    vectorScore: exp.scoreBreakdown.vectorScore,
+                    keywordScore: exp.scoreBreakdown.keywordScore,
+                    rawVectorScore: exp.scoreBreakdown.rawVectorScore,
+                    rawKeywordScore: exp.scoreBreakdown.rawKeywordScore,
+                    keywordWeight: exp.scoreBreakdown.keywordWeight,
+                    vectorRank: exp.scoreBreakdown.vectorRank,
+                    keywordRank: exp.scoreBreakdown.keywordRank,
+                    matchedTerms: exp.matchedTerms,
+                }
+                : undefined,
+        };
+    });
+}
+function thresholdAnalysis(results) {
+    return THRESHOLDS.map((t) => ({
+        threshold: t,
+        passedCount: results.filter((r) => r.score >= t).length,
+        wouldInject: results.some((r) => r.score >= t),
+    }));
+}
+function parseArgs() {
+    const args = process.argv.slice(2);
+    let output = path.join(WORKTREE, ".opencode", "rag_db", "eval-results", "branch.json");
+    for (let i = 0; i < args.length; i++) {
+        if (args[i] === "--output" && args[i + 1]) {
+            output = path.resolve(WORKTREE, args[i + 1]);
+            break;
+        }
+    }
+    return { output };
+}
+async function main() {
+    const { output } = parseArgs();
+    const { branch, commit } = getGitInfo();
+    console.log(`\n  OpenCodeRAG Branch Benchmark`);
+    console.log(`  Branch: ${branch} @ ${commit}`);
+    console.log(`  Output: ${output}\n`);
+    const cfg = getConfig();
+    const embedder = createEmbedder(cfg);
+    const dimension = await probeDimension(embedder);
+    const store = createVectorStore(cfg, STORE_PATH, dimension);
+    let keywordIndex;
+    try {
+        keywordIndex = await KeywordIndex.load(STORE_PATH);
+    }
+    catch {
+        // optional
+    }
+    const indexedCount = await store.count();
+    console.log(`  Indexed chunks: ${indexedCount}`);
+    console.log(`  Embedding: ${cfg.embedding.provider}/${cfg.embedding.model} (${dimension}d)`);
+    console.log(`  Retrieval: topK=${cfg.retrieval.topK}, minScore=${cfg.retrieval.minScore}, hybrid=${cfg.retrieval.hybridSearch?.enabled}\n`);
+    const queryResults = [];
+    for (let i = 0; i < QUERIES.length; i++) {
+        const query = QUERIES[i];
+        process.stdout.write(`  [${i + 1}/${QUERIES.length}] ${query.substring(0, 55)}...`);
+        const start = performance.now();
+        const searchResults = await retrieve(query, embedder, store, {
+            topK: cfg.retrieval.topK,
+            minScore: 0, // no filter — we want all scores for threshold analysis
+            keywordIndex,
+            keywordWeight: cfg.retrieval.hybridSearch?.keywordWeight,
+            hybridEnabled: cfg.retrieval.hybridSearch?.enabled,
+            queryPrefix: cfg.embedding.queryPrefix,
+            explain: true,
+        });
+        const elapsed = performance.now() - start;
+        queryResults.push({
+            query,
+            queryIndex: i,
+            resultCount: searchResults.length,
+            latencyMs: Math.round(elapsed * 10) / 10,
+            topResults: topResults(searchResults, WORKTREE, 5),
+            thresholdAnalysis: thresholdAnalysis(searchResults),
+        });
+        const topScore = searchResults.length > 0
+            ? searchResults[0].score.toFixed(3)
+            : "N/A";
+        console.log(` ${searchResults.length} results, top=${topScore}, ${Math.round(elapsed)}ms`);
+    }
+    const outputPayload = {
+        branch,
+        commit,
+        timestamp: new Date().toISOString(),
+        config: {
+            embeddingProvider: cfg.embedding.provider,
+            embeddingModel: cfg.embedding.model,
+            topK: cfg.retrieval.topK,
+            minScore: cfg.retrieval.minScore,
+            hybridEnabled: cfg.retrieval.hybridSearch?.enabled ?? false,
+            keywordWeight: cfg.retrieval.hybridSearch?.keywordWeight ?? 0.4,
+        },
+        indexChunkCount: indexedCount,
+        queries: queryResults,
+    };
+    const dir = path.dirname(output);
+    try {
+        const { mkdirSync } = await import("node:fs");
+        mkdirSync(dir, { recursive: true });
+    }
+    catch {
+        // dir already exists
+    }
+    writeFileSync(output, JSON.stringify(outputPayload, null, 2), "utf-8");
+    console.log(`\n  Results written to: ${output}\n`);
+}
+main().catch((err) => {
+    console.error("Benchmark failed:", err);
+    process.exit(1);
+});
+//# sourceMappingURL=run-branch-compare.js.map

package/dist/eval/run-token-test.js

@@ -95,6 +95,7 @@ async function main() {
             minScore: cfg.retrieval.minScore,
             keywordIndex,
             keywordWeight: cfg.retrieval.hybridSearch?.keywordWeight,
+            hybridEnabled: cfg.retrieval.hybridSearch?.enabled,
             queryPrefix: cfg.embedding.queryPrefix,
         });
         const inputTokens = countTokens(query);

package/dist/eval/test-kw.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/eval/test-kw.js

@@ -0,0 +1,22 @@
+import { KeywordIndex } from "../retriever/keyword-index.js";
+import path from "node:path";
+const storePath = path.join(process.cwd(), ".opencode", "rag_db");
+const ki = await KeywordIndex.load(storePath);
+console.log("Keyword index entries:", ki.count());
+const queries = [
+    "retrieve function",
+    "KeywordIndex class",
+    "embedder factory",
+    "vector store LanceDB",
+    "find usages SearchResult",
+];
+for (const q of queries) {
+    const res = ki.search(q, 5);
+    console.log(`\n"${q}": ${res.length} results`);
+    for (const r of res) {
+        const fp = r.chunk.metadata.filePath.substring(r.chunk.metadata.filePath.lastIndexOf("/src/") + 1);
+        console.log(`  score=${r.score.toFixed(2)} ${fp}:${r.chunk.metadata.startLine}-${r.chunk.metadata.endLine}`);
+    }
+}
+ki.close();
+//# sourceMappingURL=test-kw.js.map

package/dist/eval/update-descriptions.d.ts

@@ -0,0 +1,7 @@
+/**
+ * @fileoverview Update a LanceDB index's chunk descriptions from a JSON dump file.
+ * Run AFTER normal indexing to replace descriptions with ones from another branch.
+ *
+ * Usage: node --import tsx src/eval/update-descriptions.ts --input .opencode/rag_db/chunk-descriptions.json
+ */
+export {};

package/dist/eval/update-descriptions.js

@@ -0,0 +1,84 @@
+/**
+ * @fileoverview Update a LanceDB index's chunk descriptions from a JSON dump file.
+ * Run AFTER normal indexing to replace descriptions with ones from another branch.
+ *
+ * Usage: node --import tsx src/eval/update-descriptions.ts --input .opencode/rag_db/chunk-descriptions.json
+ */
+import { readFileSync } from "node:fs";
+import path from "node:path";
+async function main() {
+    const args = process.argv.slice(2);
+    const storePath = path.join(process.cwd(), ".opencode", "rag_db");
+    let inputPath = "";
+    for (let i = 0; i < args.length; i++) {
+        if (args[i] === "--input" && args[i + 1]) {
+            inputPath = path.resolve(args[i + 1]);
+            break;
+        }
+    }
+    if (!inputPath) {
+        console.error("Usage: node --import tsx src/eval/update-descriptions.ts --input <descriptions.json>");
+        process.exit(1);
+    }
+    console.log(`  Loading descriptions from: ${inputPath}`);
+    const sourceDescs = JSON.parse(readFileSync(inputPath, "utf-8"));
+    console.log(`  Loaded ${Object.keys(sourceDescs).length} descriptions`);
+    console.log(`  Connecting to store: ${storePath}`);
+    const lancedb = await import("@lancedb/lancedb");
+    const db = await lancedb.connect(storePath);
+    const tableNames = await db.tableNames();
+    if (!tableNames.includes("chunks")) {
+        console.error("  No chunks table found.");
+        await db.close();
+        process.exit(1);
+    }
+    const table = await db.openTable("chunks");
+    const count = await table.countRows();
+    console.log(`  Total rows: ${count}`);
+    // Read all rows
+    const rows = await table.query().select(["id", "description"]).limit(count).toArray();
+    let updated = 0;
+    let notFound = 0;
+    let batch = [];
+    for (const row of rows) {
+        const id = row.id;
+        const sourceDesc = sourceDescs[id];
+        if (sourceDesc === undefined) {
+            notFound++;
+            continue;
+        }
+        batch.push({ id, description: sourceDesc });
+        updated++;
+        // Update in batches of 100
+        if (batch.length >= 100) {
+            console.log(`    Updating batch of ${batch.length}...`);
+            for (const b of batch) {
+                await table.update({
+                    where: `id = '${b.id.replace(/'/g, "''")}'`,
+                    values: { description: b.description },
+                });
+            }
+            batch = [];
+        }
+    }
+    // Final batch
+    if (batch.length > 0) {
+        console.log(`    Updating final batch of ${batch.length}...`);
+        for (const b of batch) {
+            await table.update({
+                where: `id = '${b.id.replace(/'/g, "''")}'`,
+                values: { description: b.description },
+            });
+        }
+    }
+    console.log(`\n  Done:`);
+    console.log(`    Updated: ${updated}`);
+    console.log(`    Not found in dump: ${notFound}`);
+    console.log(`    Source dump had ${Object.keys(sourceDescs).length} entries`);
+    await db.close();
+}
+main().catch((err) => {
+    console.error("Update failed:", err);
+    process.exit(1);
+});
+//# sourceMappingURL=update-descriptions.js.map

package/dist/index.d.ts

@@ -15,6 +15,7 @@ export { loadConfig, DEFAULT_CONFIG } from "./core/config.js";
 export { createBackgroundIndexer } from "./watcher.js";
 export { createWatchIgnore } from "./indexer.js";
 export { ImageChunker, createImageVisionProvider, getMimeType, SUPPORTED_IMAGE_EXTENSIONS } from "./chunker/image.js";
+export { DescriptionCache } from "./core/desc-cache.js";
 export type { RagConfig, DescriptionConfig, ImageDescriptionConfig } from "./core/config.js";
 export type { Chunk, SearchResult, OptimizedSearchResult, Chunker, DescriptionProvider, EmbeddingProvider, VectorStore } from "./core/interfaces.js";
 export type { ContextOptimizationConfig, ContextOptimizationOptions } from "./retriever/context-optimizer.js";

package/dist/index.js

@@ -15,6 +15,7 @@ export { loadConfig, DEFAULT_CONFIG } from "./core/config.js";
 export { createBackgroundIndexer } from "./watcher.js";
 export { createWatchIgnore } from "./indexer.js";
 export { ImageChunker, createImageVisionProvider, getMimeType, SUPPORTED_IMAGE_EXTENSIONS } from "./chunker/image.js";
+export { DescriptionCache } from "./core/desc-cache.js";
 /**
  * High-level convenience API — search, index, and retrieve context in a single function call.
  * @module

package/dist/indexer/embed-stage.js

@@ -18,7 +18,8 @@ export async function embedChunks({ chunks, embedder, batchSize, concurrency, })
         const chunk = chunks[i];
         if (chunk.embedding && chunk.embedding.length > 0)
             continue;
-        textsToEmbed.push(chunk.content);
+        const text = "Description: " + "\n" + (chunk.description || "") + "\n" + "Content:" + "\n" + chunk.content;
+        textsToEmbed.push(text);
         chunkIndices.push(i);
     }
     if (textsToEmbed.length > 0) {

package/dist/indexer/git-diff.js

@@ -1,7 +1,7 @@
 /**
  * @fileoverview Uses git to detect changed, deleted, and untracked files for incremental indexing.
  */
-import { execSync } from "node:child_process";
+import { execFileSync } from "node:child_process";
 /**
  * Resolve the root directory of the git repository containing `cwd`.
  *
@@ -10,7 +10,7 @@ import { execSync } from "node:child_process";
  */
 export function getRepoRoot(cwd) {
     try {
-        return execSync("git rev-parse --show-toplevel", {
+        return execFileSync("git", ["rev-parse", "--show-toplevel"], {
             cwd,
             encoding: "utf-8",
             timeout: 5000,
@@ -29,7 +29,7 @@ export function getRepoRoot(cwd) {
  */
 export function getCurrentCommit(cwd) {
     try {
-        return execSync("git rev-parse HEAD", {
+        return execFileSync("git", ["rev-parse", "HEAD"], {
             cwd,
             encoding: "utf-8",
             timeout: 5000,
@@ -49,8 +49,12 @@ export function getCurrentCommit(cwd) {
  */
 export function getChangedFilesSince(cwd, fromCommit) {
     try {
-        const changedRaw = execSync(`git diff --name-only --diff-filter=ACMRT "${fromCommit}" HEAD`, { cwd, encoding: "utf-8", timeout: 10000, stdio: ["ignore", "pipe", "ignore"] }).trim();
-        const deletedRaw = execSync(`git diff --name-only --diff-filter=D "${fromCommit}" HEAD`, { cwd, encoding: "utf-8", timeout: 10000, stdio: ["ignore", "pipe", "ignore"] }).trim();
+        const changedRaw = execFileSync("git", ["diff", "--name-only", "--diff-filter=ACMRT", fromCommit, "HEAD"], {
+            cwd, encoding: "utf-8", timeout: 10000, stdio: ["ignore", "pipe", "ignore"],
+        }).trim();
+        const deletedRaw = execFileSync("git", ["diff", "--name-only", "--diff-filter=D", fromCommit, "HEAD"], {
+            cwd, encoding: "utf-8", timeout: 10000, stdio: ["ignore", "pipe", "ignore"],
+        }).trim();
         const changedFiles = changedRaw.length > 0 ? changedRaw.split("\n") : [];
         const deletedFiles = deletedRaw.length > 0 ? deletedRaw.split("\n") : [];
         const currentCommit = getCurrentCommit(cwd);
@@ -70,7 +74,9 @@ export function getChangedFilesSince(cwd, fromCommit) {
  */
 export function getUntrackedFiles(cwd) {
     try {
-        const raw = execSync("git ls-files --others --exclude-standard", { cwd, encoding: "utf-8", timeout: 5000, stdio: ["ignore", "pipe", "ignore"] }).trim();
+        const raw = execFileSync("git", ["ls-files", "--others", "--exclude-standard"], {
+            cwd, encoding: "utf-8", timeout: 5000, stdio: ["ignore", "pipe", "ignore"],
+        }).trim();
         return raw.length > 0 ? raw.split("\n") : [];
     }
     catch {
@@ -87,9 +93,15 @@ export function getUntrackedFiles(cwd) {
  */
 export function getWorkingTreeChanges(cwd) {
     try {
-        const modifiedRaw = execSync("git diff-index --name-only -M HEAD", { cwd, encoding: "utf-8", timeout: 10000, stdio: ["ignore", "pipe", "ignore"] }).trim();
-        const deletedRaw = execSync("git diff --name-only --diff-filter=D HEAD", { cwd, encoding: "utf-8", timeout: 10000, stdio: ["ignore", "pipe", "ignore"] }).trim();
-        const untrackedRaw = execSync("git ls-files --others --exclude-standard", { cwd, encoding: "utf-8", timeout: 5000, stdio: ["ignore", "pipe", "ignore"] }).trim();
+        const modifiedRaw = execFileSync("git", ["diff-index", "--name-only", "-M", "HEAD"], {
+            cwd, encoding: "utf-8", timeout: 10000, stdio: ["ignore", "pipe", "ignore"],
+        }).trim();
+        const deletedRaw = execFileSync("git", ["diff", "--name-only", "--diff-filter=D", "HEAD"], {
+            cwd, encoding: "utf-8", timeout: 10000, stdio: ["ignore", "pipe", "ignore"],
+        }).trim();
+        const untrackedRaw = execFileSync("git", ["ls-files", "--others", "--exclude-standard"], {
+            cwd, encoding: "utf-8", timeout: 5000, stdio: ["ignore", "pipe", "ignore"],
+        }).trim();
         const changedFiles = modifiedRaw.length > 0 ? modifiedRaw.split("\n") : [];
         const deletedFiles = deletedRaw.length > 0 ? deletedRaw.split("\n") : [];
         const untrackedFiles = untrackedRaw.length > 0 ? untrackedRaw.split("\n") : [];

package/dist/indexer/pipeline.d.ts

@@ -1,5 +1,6 @@
 import type { RagConfig } from "../core/config.js";
 import type { DescriptionProvider, EmbeddingProvider, IndexProgress, KeywordIndex, VectorStore } from "../core/interfaces.js";
+import type { ImageVisionProvider } from "../chunker/image.js";
 import { type IndexRunStats, type IndexStatusSummary } from "./stats.js";
 export type { WatchPassScheduler } from "./watch.js";
 export { createWatchPassScheduler, createWatchIgnore } from "./watch.js";
@@ -39,6 +40,11 @@ export interface RunIndexPassOptions {
      * entries are removed from the index without comparing against the scanned set.
      */
     deletedPaths?: string[];
+    /**
+     * Optional injected image vision provider for testing. When omitted, the
+     * provider is created from the imageDescription config as usual.
+     */
+    imageVisionProvider?: ImageVisionProvider;
 }
 /** Minimal logger interface for indexing pipeline diagnostics. */
 export interface Logger {