opencode-rag-plugin 1.14.7 → 1.14.8

package/dist/index.d.ts

@@ -1,20 +1,23 @@
 /**
- * Low-level building blocks — chunkers, embedders, vector stores, and retrieval primitives.
- * @module
+ * @fileoverview Main package entry point. Re-exports all public API symbols:
+ * low-level building blocks (chunkers, embedders, vector stores, retrieval),
+ * high-level convenience API (search, index, getContext), and plugin entry.
  */
 export { chunkFile, getChunker, registerChunker } from "./chunker/factory.js";
 export { createEmbedder, embedBatch } from "./embedder/factory.js";
 export { createDescriptionProvider } from "./describer/factory.js";
 export { createVectorStore } from "./vectorstore/factory.js";
-export { LanceDBStore } from "./vectorstore/lancedb.js";
+export { LanceDbStore } from "./vectorstore/lancedb.js";
 export { InMemoryVectorStore } from "./vectorstore/memory.js";
 export { retrieve } from "./retriever/retriever.js";
+export { optimizeContext, DEFAULT_CONTEXT_OPTIMIZATION } from "./retriever/context-optimizer.js";
 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 type { RagConfig, DescriptionConfig, ImageDescriptionConfig } from "./core/config.js";
-export type { Chunk, SearchResult, Chunker, DescriptionProvider, EmbeddingProvider, VectorStore } from "./core/interfaces.js";
+export type { Chunk, SearchResult, OptimizedSearchResult, Chunker, DescriptionProvider, EmbeddingProvider, VectorStore } from "./core/interfaces.js";
+export type { ContextOptimizationConfig, ContextOptimizationOptions } from "./retriever/context-optimizer.js";
 /**
  * High-level convenience API — search, index, and retrieve context in a single function call.
  * @module

package/dist/index.js

@@ -1,14 +1,16 @@
 /**
- * Low-level building blocks — chunkers, embedders, vector stores, and retrieval primitives.
- * @module
+ * @fileoverview Main package entry point. Re-exports all public API symbols:
+ * low-level building blocks (chunkers, embedders, vector stores, retrieval),
+ * high-level convenience API (search, index, getContext), and plugin entry.
  */
 export { chunkFile, getChunker, registerChunker } from "./chunker/factory.js";
 export { createEmbedder, embedBatch } from "./embedder/factory.js";
 export { createDescriptionProvider } from "./describer/factory.js";
 export { createVectorStore } from "./vectorstore/factory.js";
-export { LanceDBStore } from "./vectorstore/lancedb.js";
+export { LanceDbStore } from "./vectorstore/lancedb.js";
 export { InMemoryVectorStore } from "./vectorstore/memory.js";
 export { retrieve } from "./retriever/retriever.js";
+export { optimizeContext, DEFAULT_CONTEXT_OPTIMIZATION } from "./retriever/context-optimizer.js";
 export { loadConfig, DEFAULT_CONFIG } from "./core/config.js";
 export { createBackgroundIndexer } from "./watcher.js";
 export { createWatchIgnore } from "./indexer.js";

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,SAAS,EAAE,UAAU,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAC9E,OAAO,EAAE,cAAc,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAC;AACnE,OAAO,EAAE,yBAAyB,EAAE,MAAM,wBAAwB,CAAC;AACnE,OAAO,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAC7D,OAAO,EAAE,YAAY,EAAE,MAAM,0BAA0B,CAAC;AACxD,OAAO,EAAE,mBAAmB,EAAE,MAAM,yBAAyB,CAAC;AAC9D,OAAO,EAAE,QAAQ,EAAE,MAAM,0BAA0B,CAAC;AACpD,OAAO,EAAE,UAAU,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAC9D,OAAO,EAAE,uBAAuB,EAAE,MAAM,cAAc,CAAC;AACvD,OAAO,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AACjD,OAAO,EAAE,YAAY,EAAE,yBAAyB,EAAE,WAAW,EAAE,0BAA0B,EAAE,MAAM,oBAAoB,CAAC;AAItH;;;GAGG;AACH,OAAO,EAAE,MAAM,EAAE,cAAc,EAAE,UAAU,EAAE,cAAc,EAAE,aAAa,EAAE,qBAAqB,EAAE,MAAM,UAAU,CAAC;AAGpH,gEAAgE;AAChE,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAExC,kGAAkG;AAClG,MAAM,CAAC,MAAM,MAAM,GAAG,SAAS,CAAC;AAEhC,oDAAoD;AACpD,MAAM,CAAC,MAAM,EAAE,GAAG,qBAAqB,CAAC;AAExC,uEAAuE;AACvE,eAAe,EAAE,EAAE,EAAE,MAAM,EAAE,SAAS,EAAE,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,SAAS,EAAE,UAAU,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAC9E,OAAO,EAAE,cAAc,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAC;AACnE,OAAO,EAAE,yBAAyB,EAAE,MAAM,wBAAwB,CAAC;AACnE,OAAO,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAC7D,OAAO,EAAE,YAAY,EAAE,MAAM,0BAA0B,CAAC;AACxD,OAAO,EAAE,mBAAmB,EAAE,MAAM,yBAAyB,CAAC;AAC9D,OAAO,EAAE,QAAQ,EAAE,MAAM,0BAA0B,CAAC;AACpD,OAAO,EAAE,eAAe,EAAE,4BAA4B,EAAE,MAAM,kCAAkC,CAAC;AACjG,OAAO,EAAE,UAAU,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAC9D,OAAO,EAAE,uBAAuB,EAAE,MAAM,cAAc,CAAC;AACvD,OAAO,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AACjD,OAAO,EAAE,YAAY,EAAE,yBAAyB,EAAE,WAAW,EAAE,0BAA0B,EAAE,MAAM,oBAAoB,CAAC;AAKtH;;;GAGG;AACH,OAAO,EAAE,MAAM,EAAE,cAAc,EAAE,UAAU,EAAE,cAAc,EAAE,aAAa,EAAE,qBAAqB,EAAE,MAAM,UAAU,CAAC;AAGpH,gEAAgE;AAChE,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAExC,kGAAkG;AAClG,MAAM,CAAC,MAAM,MAAM,GAAG,SAAS,CAAC;AAEhC,oDAAoD;AACpD,MAAM,CAAC,MAAM,EAAE,GAAG,qBAAqB,CAAC;AAExC,uEAAuE;AACvE,eAAe,EAAE,EAAE,EAAE,MAAM,EAAE,SAAS,EAAE,CAAC"}

package/dist/indexer/description-stage.d.ts

@@ -1,4 +1,8 @@
+/**
+ * @fileoverview Generates AI and fallback descriptions for code chunks.
+ */
 import type { Chunk, DescriptionProvider } from "../core/interfaces.js";
+/** Result of a description generation run, including per-chunk descriptions and any failures. */
 export interface DescriptionResult {
     descriptionMap: Map<string, string>;
     failures: Array<{
@@ -10,6 +14,28 @@ interface Logger {
     warn(message: string): void;
     debug(message: string): void;
 }
+/**
+ * Generate AI or fallback descriptions for a set of code chunks.
+ *
+ * Chunks that already have a description (e.g. from docstrings) are skipped.
+ * Oversized chunks exceeding `maxContentChars` receive a fallback description
+ * instead of being sent to the LLM.  Remaining chunks are sent in batch to
+ * the description provider, with individual fallback on batch failure.
+ *
+ * @param chunks - Chunks to describe.
+ * @param descriptionProvider - Provider that generates AI descriptions.
+ * @param logger - Optional logger for diagnostic messages.
+ * @param maxContentChars - Optional maximum content length for LLM submission;
+ *   chunks longer than this get a fallback description.
+ * @returns A map of chunk ID to description and a list of failures.
+ */
 export declare function generateDescriptions(chunks: Chunk[], descriptionProvider: DescriptionProvider, logger?: Logger, maxContentChars?: number): Promise<DescriptionResult>;
+/**
+ * Build a simple fallback description from a chunk's file location metadata.
+ * Used when AI description generation is unavailable or fails.
+ *
+ * @param chunk - The chunk to describe.
+ * @returns A description string like `"lines 10-25, typescript"`.
+ */
 export declare function buildFallbackDescription(chunk: Chunk): string;
 export {};

package/dist/indexer/description-stage.js

@@ -1,3 +1,18 @@
+/**
+ * Generate AI or fallback descriptions for a set of code chunks.
+ *
+ * Chunks that already have a description (e.g. from docstrings) are skipped.
+ * Oversized chunks exceeding `maxContentChars` receive a fallback description
+ * instead of being sent to the LLM.  Remaining chunks are sent in batch to
+ * the description provider, with individual fallback on batch failure.
+ *
+ * @param chunks - Chunks to describe.
+ * @param descriptionProvider - Provider that generates AI descriptions.
+ * @param logger - Optional logger for diagnostic messages.
+ * @param maxContentChars - Optional maximum content length for LLM submission;
+ *   chunks longer than this get a fallback description.
+ * @returns A map of chunk ID to description and a list of failures.
+ */
 export async function generateDescriptions(chunks, descriptionProvider, logger, maxContentChars) {
     const descriptionMap = new Map();
     const failures = [];
@@ -65,6 +80,13 @@ export async function generateDescriptions(chunks, descriptionProvider, logger,
     }
     return { descriptionMap, failures };
 }
+/**
+ * Build a simple fallback description from a chunk's file location metadata.
+ * Used when AI description generation is unavailable or fails.
+ *
+ * @param chunk - The chunk to describe.
+ * @returns A description string like `"lines 10-25, typescript"`.
+ */
 export function buildFallbackDescription(chunk) {
     return `lines ${chunk.metadata.startLine}-${chunk.metadata.endLine}, ${chunk.metadata.language}`;
 }

package/dist/indexer/description-stage.js.map

@@ -1 +1 @@
-{"version":3,"file":"description-stage.js","sourceRoot":"","sources":["../../src/indexer/description-stage.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"description-stage.js","sourceRoot":"","sources":["../../src/indexer/description-stage.ts"],"names":[],"mappings":"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"}

package/dist/indexer/embed-stage.d.ts

@@ -1,8 +1,22 @@
+/**
+ * @fileoverview Batches chunks for embedding generation.
+ */
 import type { Chunk, EmbeddingProvider } from "../core/interfaces.js";
+/** Options for embedding a batch of chunks. */
 export interface EmbedChunksOptions {
     chunks: Chunk[];
     embedder: EmbeddingProvider;
     batchSize: number;
     concurrency: number;
 }
+/**
+ * Generate embeddings for chunks that don't already have one.
+ * Skips chunks that already have a valid embedding vector.
+ *
+ * @param chunks - Chunks to embed; existing embeddings are preserved in-place.
+ * @param embedder - Embedding provider for vector generation.
+ * @param batchSize - Number of texts to embed per batch.
+ * @param concurrency - Number of concurrent embedding requests.
+ * @returns The same chunk array with embeddings attached.
+ */
 export declare function embedChunks({ chunks, embedder, batchSize, concurrency, }: EmbedChunksOptions): Promise<Chunk[]>;

package/dist/indexer/embed-stage.js

@@ -1,4 +1,14 @@
 import { embedBatch } from "../embedder/factory.js";
+/**
+ * Generate embeddings for chunks that don't already have one.
+ * Skips chunks that already have a valid embedding vector.
+ *
+ * @param chunks - Chunks to embed; existing embeddings are preserved in-place.
+ * @param embedder - Embedding provider for vector generation.
+ * @param batchSize - Number of texts to embed per batch.
+ * @param concurrency - Number of concurrent embedding requests.
+ * @returns The same chunk array with embeddings attached.
+ */
 export async function embedChunks({ chunks, embedder, batchSize, concurrency, }) {
     if (chunks.length === 0)
         return [];

package/dist/indexer/embed-stage.js.map

@@ -1 +1 @@
-{"version":3,"file":"embed-stage.js","sourceRoot":"","sources":["../../src/indexer/embed-stage.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAC;AASpD,MAAM,CAAC,KAAK,UAAU,WAAW,CAAC,EAChC,MAAM,EACN,QAAQ,EACR,SAAS,EACT,WAAW,GACQ;IACnB,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,EAAE,CAAC;IAEnC,MAAM,YAAY,GAAa,EAAE,CAAC;IAClC,MAAM,YAAY,GAAa,EAAE,CAAC;IAElC,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACvC,MAAM,KAAK,GAAG,MAAM,CAAC,CAAC,CAAE,CAAC;QACzB,IAAI,KAAK,CAAC,SAAS,IAAI,KAAK,CAAC,SAAS,CAAC,MAAM,GAAG,CAAC;YAAE,SAAS;QAC5D,YAAY,CAAC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;QACjC,YAAY,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IACvB,CAAC;IAED,IAAI,YAAY,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC5B,MAAM,UAAU,GAAG,MAAM,UAAU,CAAC,QAAQ,EAAE,YAAY,EAAE,SAAS,EAAE,UAAU,EAAE,WAAW,CAAC,CAAC;QAEhG,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,YAAY,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;YAC7C,MAAM,QAAQ,GAAG,YAAY,CAAC,CAAC,CAAE,CAAC;YAClC,MAAM,GAAG,GAAG,UAAU,CAAC,CAAC,CAAC,CAAC;YAC1B,IAAI,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,GAAG,CAAC,MAAM,GAAG,CAAC,IAAI,OAAO,GAAG,CAAC,CAAC,CAAC,KAAK,QAAQ,EAAE,CAAC;gBACvE,MAAM,CAAC,QAAQ,CAAE,CAAC,SAAS,GAAG,GAAe,CAAC;YAChD,CAAC;QACH,CAAC;IACH,CAAC;IAED,OAAO,MAAM,CAAC;AAChB,CAAC"}
+{"version":3,"file":"embed-stage.js","sourceRoot":"","sources":["../../src/indexer/embed-stage.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAC;AAUpD;;;;;;;;;GASG;AACH,MAAM,CAAC,KAAK,UAAU,WAAW,CAAC,EAChC,MAAM,EACN,QAAQ,EACR,SAAS,EACT,WAAW,GACQ;IACnB,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,EAAE,CAAC;IAEnC,MAAM,YAAY,GAAa,EAAE,CAAC;IAClC,MAAM,YAAY,GAAa,EAAE,CAAC;IAElC,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACvC,MAAM,KAAK,GAAG,MAAM,CAAC,CAAC,CAAE,CAAC;QACzB,IAAI,KAAK,CAAC,SAAS,IAAI,KAAK,CAAC,SAAS,CAAC,MAAM,GAAG,CAAC;YAAE,SAAS;QAC5D,YAAY,CAAC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;QACjC,YAAY,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IACvB,CAAC;IAED,IAAI,YAAY,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC5B,MAAM,UAAU,GAAG,MAAM,UAAU,CAAC,QAAQ,EAAE,YAAY,EAAE,SAAS,EAAE,UAAU,EAAE,WAAW,CAAC,CAAC;QAEhG,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,YAAY,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;YAC7C,MAAM,QAAQ,GAAG,YAAY,CAAC,CAAC,CAAE,CAAC;YAClC,MAAM,GAAG,GAAG,UAAU,CAAC,CAAC,CAAC,CAAC;YAC1B,IAAI,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,GAAG,CAAC,MAAM,GAAG,CAAC,IAAI,OAAO,GAAG,CAAC,CAAC,CAAC,KAAK,QAAQ,EAAE,CAAC;gBACvE,MAAM,CAAC,QAAQ,CAAE,CAAC,SAAS,GAAG,GAAe,CAAC;YAChD,CAAC;QACH,CAAC;IACH,CAAC;IAED,OAAO,MAAM,CAAC;AAChB,CAAC"}

package/dist/indexer/git-diff.d.ts

@@ -1,9 +1,53 @@
+/** Result of comparing the working tree against a prior commit. */
 export interface GitDiffResult {
     changedFiles: string[];
     deletedFiles: string[];
     currentCommit: string;
 }
+/**
+ * Resolve the root directory of the git repository containing `cwd`.
+ *
+ * @param cwd - A path inside the repository.
+ * @returns The absolute repository root path, or `null` if not a git repo.
+ */
 export declare function getRepoRoot(cwd: string): string | null;
+/**
+ * Get the full SHA of the current HEAD commit.
+ *
+ * @param cwd - A path inside the repository.
+ * @returns The commit SHA, or `null` on failure.
+ */
 export declare function getCurrentCommit(cwd: string): string | null;
+/**
+ * List changed, added, and deleted files between `fromCommit` and HEAD.
+ *
+ * @param cwd - A path inside the repository.
+ * @param fromCommit - The commit SHA to diff against.
+ * @returns A diff result, or `null` if the git command fails.
+ */
 export declare function getChangedFilesSince(cwd: string, fromCommit: string): GitDiffResult | null;
+/**
+ * List untracked files in the repository, respecting .gitignore rules.
+ *
+ * @param cwd - A path inside the repository.
+ * @returns An array of untracked file paths (relative to repo root).
+ */
 export declare function getUntrackedFiles(cwd: string): string[];
+/** Result of comparing the working tree against HEAD. */
+export interface WorkingTreeChanges {
+    /** Modified/renamed tracked files (unstaged + staged but not committed). */
+    changedFiles: string[];
+    /** Deleted tracked files (relative to repo root). */
+    deletedFiles: string[];
+    /** Untracked files respecting .gitignore (relative to repo root). */
+    untrackedFiles: string[];
+}
+/**
+ * Detect uncommitted working-tree changes by comparing against HEAD.
+ * Uses `git diff-index` for tracked file modifications, `git diff --diff-filter=D`
+ * for deleted files, and `git ls-files --others` for untracked files.
+ *
+ * @param cwd - A path inside the repository.
+ * @returns Working-tree changes, or `null` if not a git repo.
+ */
+export declare function getWorkingTreeChanges(cwd: string): WorkingTreeChanges | null;

package/dist/indexer/git-diff.js

@@ -1,4 +1,13 @@
+/**
+ * @fileoverview Uses git to detect changed, deleted, and untracked files for incremental indexing.
+ */
 import { execSync } from "node:child_process";
+/**
+ * Resolve the root directory of the git repository containing `cwd`.
+ *
+ * @param cwd - A path inside the repository.
+ * @returns The absolute repository root path, or `null` if not a git repo.
+ */
 export function getRepoRoot(cwd) {
     try {
         return execSync("git rev-parse --show-toplevel", {
@@ -12,6 +21,12 @@ export function getRepoRoot(cwd) {
         return null;
     }
 }
+/**
+ * Get the full SHA of the current HEAD commit.
+ *
+ * @param cwd - A path inside the repository.
+ * @returns The commit SHA, or `null` on failure.
+ */
 export function getCurrentCommit(cwd) {
     try {
         return execSync("git rev-parse HEAD", {
@@ -25,6 +40,13 @@ export function getCurrentCommit(cwd) {
         return null;
     }
 }
+/**
+ * List changed, added, and deleted files between `fromCommit` and HEAD.
+ *
+ * @param cwd - A path inside the repository.
+ * @param fromCommit - The commit SHA to diff against.
+ * @returns A diff result, or `null` if the git command fails.
+ */
 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();
@@ -40,6 +62,12 @@ export function getChangedFilesSince(cwd, fromCommit) {
         return null;
     }
 }
+/**
+ * List untracked files in the repository, respecting .gitignore rules.
+ *
+ * @param cwd - A path inside the repository.
+ * @returns An array of untracked file paths (relative to repo root).
+ */
 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();
@@ -49,4 +77,26 @@ export function getUntrackedFiles(cwd) {
         return [];
     }
 }
+/**
+ * Detect uncommitted working-tree changes by comparing against HEAD.
+ * Uses `git diff-index` for tracked file modifications, `git diff --diff-filter=D`
+ * for deleted files, and `git ls-files --others` for untracked files.
+ *
+ * @param cwd - A path inside the repository.
+ * @returns Working-tree changes, or `null` if not a git repo.
+ */
+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 changedFiles = modifiedRaw.length > 0 ? modifiedRaw.split("\n") : [];
+        const deletedFiles = deletedRaw.length > 0 ? deletedRaw.split("\n") : [];
+        const untrackedFiles = untrackedRaw.length > 0 ? untrackedRaw.split("\n") : [];
+        return { changedFiles, deletedFiles, untrackedFiles };
+    }
+    catch {
+        return null;
+    }
+}
 //# sourceMappingURL=git-diff.js.map

package/dist/indexer/git-diff.js.map

@@ -1 +1 @@
-{"version":3,"file":"git-diff.js","sourceRoot":"","sources":["../../src/indexer/git-diff.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAQ9C,MAAM,UAAU,WAAW,CAAC,GAAW;IACrC,IAAI,CAAC;QACH,OAAO,QAAQ,CAAC,+BAA+B,EAAE;YAC/C,GAAG;YACH,QAAQ,EAAE,OAAO;YACjB,OAAO,EAAE,IAAI;YACb,KAAK,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,CAAC;SACpC,CAAC,CAAC,IAAI,EAAE,CAAC;IACZ,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC;AAED,MAAM,UAAU,gBAAgB,CAAC,GAAW;IAC1C,IAAI,CAAC;QACH,OAAO,QAAQ,CAAC,oBAAoB,EAAE;YACpC,GAAG;YACH,QAAQ,EAAE,OAAO;YACjB,OAAO,EAAE,IAAI;YACb,KAAK,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,CAAC;SACpC,CAAC,CAAC,IAAI,EAAE,CAAC;IACZ,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC;AAED,MAAM,UAAU,oBAAoB,CAClC,GAAW,EACX,UAAkB;IAElB,IAAI,CAAC;QACH,MAAM,UAAU,GAAG,QAAQ,CACzB,6CAA6C,UAAU,QAAQ,EAC/D,EAAE,GAAG,EAAE,QAAQ,EAAE,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,CAChF,CAAC,IAAI,EAAE,CAAC;QAET,MAAM,UAAU,GAAG,QAAQ,CACzB,yCAAyC,UAAU,QAAQ,EAC3D,EAAE,GAAG,EAAE,QAAQ,EAAE,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,CAChF,CAAC,IAAI,EAAE,CAAC;QAET,MAAM,YAAY,GAAG,UAAU,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;QACzE,MAAM,YAAY,GAAG,UAAU,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;QAEzE,MAAM,aAAa,GAAG,gBAAgB,CAAC,GAAG,CAAC,CAAC;QAC5C,IAAI,CAAC,aAAa;YAAE,OAAO,IAAI,CAAC;QAEhC,OAAO,EAAE,YAAY,EAAE,YAAY,EAAE,aAAa,EAAE,CAAC;IACvD,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC;AAED,MAAM,UAAU,iBAAiB,CAAC,GAAW;IAC3C,IAAI,CAAC;QACH,MAAM,GAAG,GAAG,QAAQ,CAClB,0CAA0C,EAC1C,EAAE,GAAG,EAAE,QAAQ,EAAE,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,CAC/E,CAAC,IAAI,EAAE,CAAC;QACT,OAAO,GAAG,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;IAC/C,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,EAAE,CAAC;IACZ,CAAC;AACH,CAAC"}
+{"version":3,"file":"git-diff.js","sourceRoot":"","sources":["../../src/indexer/git-diff.ts"],"names":[],"mappings":"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"}

package/dist/indexer/metadata.d.ts

@@ -1 +1,10 @@
+/**
+ * Build a metadata header string for embedding context that describes the
+ * file type, top-level directory, content classification, and document title.
+ *
+ * @param filePath - Absolute path to the file.
+ * @param cwd - Workspace root directory (used to compute relative path).
+ * @param content - File content used to extract a document title.
+ * @returns A space-delimited metadata string such as `"[typescript] [src] [source] MyComponent"`.
+ */
 export declare function buildFileMetadataHeader(filePath: string, cwd: string, content: string): string;

package/dist/indexer/metadata.js

@@ -1,3 +1,6 @@
+/**
+ * @fileoverview Builds metadata headers (file type, content type, document title) for embedding context.
+ */
 import path from "node:path";
 const FILE_TYPE_LABELS = {
     ".pdf": "pdf",
@@ -76,6 +79,15 @@ function extractDocumentTitle(content, filePath) {
         .replace(/\b\w/g, (c) => c.toUpperCase())
         .slice(0, 80);
 }
+/**
+ * Build a metadata header string for embedding context that describes the
+ * file type, top-level directory, content classification, and document title.
+ *
+ * @param filePath - Absolute path to the file.
+ * @param cwd - Workspace root directory (used to compute relative path).
+ * @param content - File content used to extract a document title.
+ * @returns A space-delimited metadata string such as `"[typescript] [src] [source] MyComponent"`.
+ */
 export function buildFileMetadataHeader(filePath, cwd, content) {
     const ext = path.extname(filePath).toLowerCase();
     const relPath = path.relative(cwd, filePath).replace(/\\/g, "/");

package/dist/indexer/metadata.js.map

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

package/dist/indexer/pipeline.d.ts

@@ -29,7 +29,18 @@ export interface RunIndexPassOptions {
     abortSignal?: AbortSignal;
     /** Embedding vector dimension — needed when creating a temporary store for atomic rebuilds. */
     dimension?: number;
+    /**
+     * Caller-provided list of changed file paths (absolute). When set, only these
+     * files are scanned — full directory walk is skipped.
+     */
+    filterPaths?: string[];
+    /**
+     * Caller-provided list of deleted file paths (absolute). When set, these
+     * entries are removed from the index without comparing against the scanned set.
+     */
+    deletedPaths?: string[];
 }
+/** Minimal logger interface for indexing pipeline diagnostics. */
 export interface Logger {
     info(message: string): void;
     warn(message: string): void;
@@ -44,4 +55,17 @@ export interface Logger {
  * @returns Aggregate statistics for the pass.
  */
 export declare function runIndexPass(options: RunIndexPassOptions): Promise<IndexRunStats>;
+/**
+ * Build an overview of the current index health without running a full pass.
+ * Scans workspace files and compares their hashes against the manifest to
+ * determine how many are up-to-date vs pending re-indexing.
+ *
+ * @param cwd - Workspace root directory.
+ * @param storePath - Path to the vector store data directory.
+ * @param config - Full RAG configuration.
+ * @param store - Vector store instance for chunk count.
+ * @param skipScan - When true, skip the workspace file scan and only report
+ *   manifest / store metadata.
+ * @returns A summary of the current index status.
+ */
 export declare function getIndexStatusSummary(cwd: string, storePath: string, config: RagConfig, store: VectorStore, skipScan?: boolean): Promise<IndexStatusSummary>;

package/dist/indexer/pipeline.js

@@ -1,3 +1,6 @@
+/**
+ * @fileoverview Orchestrates the full indexing pipeline: scan, chunk, embed, and store.
+ */
 import fs from "node:fs/promises";
 import path from "node:path";
 import pLimit from "p-limit";
@@ -151,7 +154,7 @@ async function runIndexPassInner(options, logger) {
             delete manifest.files[key];
         }
         manifest.lastIndexedAt = undefined;
-        rebuildPerformed = existingCount > 0 || Boolean(options.force);
+        rebuildPerformed = existingCount > 0 || !!options.force;
         if (manifestStatus !== "ok" && existingCount > 0) {
             logger.warn("Manifest missing or corrupt; rebuilding full index.");
         }
@@ -225,7 +228,6 @@ async function runIndexPassInner(options, logger) {
         logger.debug(`Removed ${stats.deletedFiles} deleted files from index.`);
     }
     logger.debug(`Processing ${workspaceFiles.length} files (${newCount} new, ${modifiedCount} modified, ${unchangedCount} unchanged)...`);
-    // ── Phase 1: prepare all files (chunk + keyword, defer descriptions if provider present) ──
     const limit = pLimit(options.config.indexing.concurrency);
     const deferDescriptions = !!options.descriptionProvider;
     const prepared = await Promise.all(workspaceFiles.map((file) => limit(async () => {
@@ -241,7 +243,6 @@ async function runIndexPassInner(options, logger) {
         }
         return prep;
     })));
-    // ── Phase 1.5: global description generation (single pool, no nested concurrency) ──
     if (deferDescriptions) {
         const deferredPreps = prepared.filter((p) => p.chunks && p.chunks.length > 0 && p.relPath !== undefined);
         if (deferredPreps.length > 0) {
@@ -286,13 +287,11 @@ async function runIndexPassInner(options, logger) {
                     }
                 }
             }
-            // Phase 1.6: build textToEmbed with descriptions injected
             for (const prep of deferredPreps) {
                 prep.textToEmbed = buildTextsToEmbed(prep.chunks, prep.relPath, prep.metaHeader ?? "", prep.docPrefix ?? "", prep.isImageFile ?? false);
             }
         }
     }
-    // ── Phase 2+3: per-file delete, embed + store (in parallel) ──
     // Deletions for modified/re-removed files happen per-worker, right before
     // embedding, so that an abort mid-embed doesn't orphan old entries.
     const isOllama = options.embedder.name === "ollama";
@@ -311,11 +310,9 @@ async function runIndexPassInner(options, logger) {
     const aborted = () => options.abortSignal?.aborted ?? false;
     const embedStoreLimit = pLimit(options.config.indexing.concurrency);
     const workerResults = await Promise.all(prepared.map((prep) => embedStoreLimit(async () => {
-        // ── Check abort signal before any work ──
         if (aborted()) {
             return { normalizedPath: prep.normalizedPath, skipped: true };
         }
-        // ── Early results (empty / too-small / unchanged / chunking failure) ──
         if (prep.earlyResult) {
             // Remove stale manifest/store entries for files that no longer produce chunks
             if (prep.earlyResult.isRemoved) {
@@ -336,7 +333,6 @@ async function runIndexPassInner(options, logger) {
                 descriptionFailed: prep.descriptionFailed,
             };
         }
-        // ── Embed ──
         const batchSize = isOllama
             ? Math.min(prep.textToEmbed.length, ollamaMaxBatch)
             : defaultBatchSize;
@@ -379,7 +375,6 @@ async function runIndexPassInner(options, logger) {
         options.progress?.finishFile(prep.fileLabel);
         return result;
     })));
-    // Strip skipped sentinels
     const finalResults = [];
     for (const r of workerResults) {
         if (r.skipped)
@@ -396,7 +391,6 @@ async function runIndexPassInner(options, logger) {
             entry.size = size;
         }
     }
-    // ── Aggregate stats ──
     aggregateStats(stats, finalResults);
     // Update timestamps; advance lastGitCommit ONLY on a complete pass
     manifest.lastIndexedAt = Date.now();
@@ -487,6 +481,19 @@ function aggregateStats(stats, results) {
         }
     }
 }
+/**
+ * Build an overview of the current index health without running a full pass.
+ * Scans workspace files and compares their hashes against the manifest to
+ * determine how many are up-to-date vs pending re-indexing.
+ *
+ * @param cwd - Workspace root directory.
+ * @param storePath - Path to the vector store data directory.
+ * @param config - Full RAG configuration.
+ * @param store - Vector store instance for chunk count.
+ * @param skipScan - When true, skip the workspace file scan and only report
+ *   manifest / store metadata.
+ * @returns A summary of the current index status.
+ */
 export async function getIndexStatusSummary(cwd, storePath, config, store, skipScan) {
     const loadResult = await loadManifest(storePath);
     const manifest = loadResult.manifest;