@takara-ai/miru-code 1.0.5 → 1.1.1

package/src/mcp/index-cache.ts

@@ -1,5 +1,7 @@
 import { watch } from "node:fs";
-import { resolve } from "node:path";
+import { relative, resolve } from "node:path";
+import { walkFiles } from "../index/file-walker.ts";
+import { getExtensions } from "../index/files.ts";
 import { normalizeRelativePath, relativePathFromRoot } from "../index/incremental.ts";
 import { MiruIndex } from "../miru-index.ts";
 import type { ContentType } from "../types.ts";
@@ -118,7 +120,12 @@ export class IndexCache {
     const task = (async () => {
       const index = await MiruIndex.fromSource(source, this.content, undefined, ref);
       if (!isGitUrl(source)) {
-        await index.saveToDefaultCache(resolve(source));
+        await index.saveToCache(resolve(source));
+      }
+      if (index.loadedFromDisk) {
+        // Await reconciliation here (not fire-and-forget) so callers of `get()`
+        // never observe an index that's stale relative to what's on disk.
+        await this.checkAndQueueStaleFiles(source, index, cacheKey);
       }
       return index;
     })();
@@ -129,7 +136,6 @@ export class IndexCache {
       .then((index) => {
         entry.index = index;
         this.maybeStartWatcher(source);
-        void this.flushFileUpdates(cacheKey, source);
         return index;
       })
       .catch(() => {
@@ -162,7 +168,7 @@ export class IndexCache {
     if (!entry.flushQueued) {
       entry.flushQueued = true;
       queueMicrotask(() => {
-        this.flushFileUpdates(cacheKey, source);
+        void this.flushFileUpdates(cacheKey, source);
       });
     }
   }
@@ -219,10 +225,10 @@ export class IndexCache {
     this.scheduleFlush(cacheKey, source, entry);
   }
 
-  private flushFileUpdates(cacheKey: string, source: string): void {
+  private flushFileUpdates(cacheKey: string, source: string): Promise<void> {
     const entry = this.entries.get(cacheKey);
     if (!entry) {
-      return;
+      return Promise.resolve();
     }
     entry.flushQueued = false;
 
@@ -254,7 +260,7 @@ export class IndexCache {
       try {
         await index.applyFileChanges(paths);
         if (!isGitUrl(source)) {
-          await index.persistToCache(resolve(source));
+          await index.saveToCache(resolve(source), { force: true });
         }
       } catch {
         for (const p of paths) {
@@ -264,6 +270,57 @@ export class IndexCache {
     };
 
     entry.updateChain = entry.updateChain.then(run, run);
+    return entry.updateChain;
+  }
+
+  private async checkAndQueueStaleFiles(
+    source: string,
+    index: MiruIndex,
+    cacheKey: string,
+  ): Promise<void> {
+    if (isGitUrl(source)) {
+      return;
+    }
+
+    const root = index.root;
+    if (!root) {
+      return;
+    }
+
+    const storedMtimes = index.getStoredFileMtimes();
+    const entry = this.ensureEntry(cacheKey, source);
+
+    try {
+      await Promise.all(
+        [...storedMtimes].map(async ([filePath, storedMtime]) => {
+          try {
+            const currentStat = await Bun.file(resolve(root, filePath)).stat();
+            const currentMtime = Math.floor(currentStat.mtime?.getTime() ?? 0);
+
+            if (currentMtime !== storedMtime) {
+              entry.pendingPaths.add(normalizeRelativePath(filePath));
+            }
+          } catch {
+            entry.pendingPaths.add(normalizeRelativePath(filePath));
+          }
+        }),
+      );
+
+      // Files created on disk while this index wasn't loaded (or never indexed
+      // before) have no entry in `storedMtimes` and are otherwise invisible to
+      // the mtime comparison above; a directory walk is the only way to find them.
+      const extensions = getExtensions(index.contentTypes);
+      for await (const absolutePath of walkFiles(root, extensions)) {
+        const relativePath = normalizeRelativePath(relative(root, absolutePath));
+        if (!storedMtimes.has(relativePath)) {
+          entry.pendingPaths.add(relativePath);
+        }
+      }
+
+      if (entry.pendingPaths.size > 0) {
+        await this.flushFileUpdates(cacheKey, source);
+      }
+    } catch {}
   }
 
   private maybeStartWatcher(source: string): void {

package/src/mcp/server.ts

@@ -87,12 +87,10 @@ export function createMcpServer(cache: IndexCache): MiruMcpServer {
         file_path: z
           .string()
           .describe("Path from a search hit (`file_path` or `absolute_path` for local repos)."),
-        line: z
+        anchor_line: z
           .number()
           .int()
-          .describe(
-            "Line from the hit: `anchor_line` when truncated, otherwise `start_line` (1-indexed).",
-          ),
+          .describe("Line from the search hit (`anchor_line` when truncated, else `start_line`)."),
         repo: z.string().describe(REPO_DESCRIPTION),
         before: z
           .number()
@@ -108,7 +106,7 @@ export function createMcpServer(cache: IndexCache): MiruMcpServer {
           .describe("Extra chunks after the anchor (default 1)."),
       },
     },
-    async ({ file_path: filePath, line, repo, before, after }) => {
+    async ({ file_path: filePath, anchor_line: anchorLine, repo, before, after }) => {
       try {
         const index = await getIndexForRepo(repo, cache);
         const repoRoot = localRepoRoot(repo);
@@ -117,19 +115,19 @@ export function createMcpServer(cache: IndexCache): MiruMcpServer {
         const { anchor, chunks: expanded } = expandChunksAtLine(
           index.chunks,
           filePath,
-          line,
+          anchorLine,
           repoRoot,
           beforeCount,
           afterCount,
         );
         if (!anchor) {
           return toolText(
-            `No chunk found at ${filePath}:${line}. Make sure the file is indexed and the line number is within a known chunk.`,
+            `No chunk found at ${filePath}:${anchorLine}. Make sure the file is indexed and the line number is within a known chunk.`,
           );
         }
         return toolText(
           JSON.stringify(
-            formatExpandResults(filePath, line, anchor, expanded, {
+            formatExpandResults(filePath, anchorLine, anchor, expanded, {
               repoRoot,
               before: beforeCount,
               after: afterCount,
@@ -150,12 +148,10 @@ export function createMcpServer(cache: IndexCache): MiruMcpServer {
         file_path: z
           .string()
           .describe("Path from a search hit (`file_path` or `absolute_path` for local repos)."),
-        line: z
+        anchor_line: z
           .number()
           .int()
-          .describe(
-            "Line from the hit: `anchor_line` when truncated, otherwise `start_line` (1-indexed).",
-          ),
+          .describe("Line from the search hit (`anchor_line` when truncated, else `start_line`)."),
         repo: z.string().describe(REPO_DESCRIPTION),
         top_k: z
           .number()
@@ -168,25 +164,25 @@ export function createMcpServer(cache: IndexCache): MiruMcpServer {
           ),
       },
     },
-    async ({ file_path: filePath, line, repo, top_k: topK }) => {
+    async ({ file_path: filePath, anchor_line: anchorLine, repo, top_k: topK }) => {
       try {
         const index = await getIndexForRepo(repo, cache);
         const repoRoot = localRepoRoot(repo);
-        const chunk = resolveChunk(index.chunks, filePath, line, repoRoot);
+        const chunk = resolveChunk(index.chunks, filePath, anchorLine, repoRoot);
         if (!chunk) {
           return toolText(
-            `No chunk found at ${filePath}:${line}. Make sure the file is indexed and the line number is within a known chunk.`,
+            `No chunk found at ${filePath}:${anchorLine}. Make sure the file is indexed and the line number is within a known chunk.`,
           );
         }
         const results = await index.findRelated(chunk, clampMcpTopK(topK));
         if (results.length === 0) {
           return toolText(
-            JSON.stringify({ error: `No related chunks found for ${filePath}:${line}.` }),
+            JSON.stringify({ error: `No related chunks found for ${filePath}:${anchorLine}.` }),
           );
         }
         return toolText(
           JSON.stringify(
-            formatResults(`Chunks related to ${filePath}:${line}`, results, {
+            formatResults(`Chunks related to ${filePath}:${anchorLine}`, results, {
               repoRoot,
               snippet: true,
             }),

package/src/miru-index.ts

@@ -9,6 +9,7 @@ import {
 } from "./embeddings/openai.ts";
 import { cloneGitRepository } from "./git.ts";
 import type { BM25Index } from "./index/bm25.ts";
+import { buildChunkSelector } from "./index/chunk-selector.ts";
 import { createIndexFromPath } from "./index/create.ts";
 import { applyIncrementalFileChanges } from "./index/incremental.ts";
 import { persistencePaths, saveIndexBundle } from "./index/persistence.ts";
@@ -19,27 +20,89 @@ import { chunkKey, chunkToDict } from "./types.ts";
 import { computeSourceCacheKey, isGitUrl } from "./utils.ts";
 import { indexCacheEpoch } from "./version.ts";
 
+/**
+ * In-memory search index over a codebase: BM25 keyword scores plus semantic
+ * embeddings, with optional disk cache for reuse across runs.
+ *
+ * Construct via `fromPath`, `fromGit`, or `fromSource`; load a saved bundle
+ * with `loadFromDisk`. Search combines both signals; `findRelated` is
+ * semantic-only similarity from an existing chunk or hit.
+ *
+ * Lifecycle:
+ * - **Build** — parse files, chunk, embed, score with BM25
+ * - **Cache** — `save` writes a bundle keyed by source path or git URL + ref
+ * - **Query** — `search` blends BM25 and vectors; filters use prebuilt mappings
+ * - **Update** — `applyFileChanges` re-indexes only touched paths (local roots)
+ */
 export class MiruIndex {
+  /** OpenAI (or configured) client used for query embeddings and reranking. */
   readonly embeddings: EmbeddingBackend;
+
+  /** Flat list of all chunks; index position is the stable chunk id. */
   private chunksInternal: Chunk[];
+
+  /** Inverted index for lexical (BM25) retrieval. */
   private bm25Index: BM25Index;
+
+  /** Vector store for semantic nearest-neighbor search. */
   private semanticIndex: SemanticIndex;
+
+  /**
+   * True when hydrated from disk via `loadFromDisk`.
+   * Affects `saveToCache`, which skips re-saving already-cached indexes unless forced.
+   */
   private loadedFromDiskFlag: boolean;
 
+  /** Model id stored in cache metadata and used for new embeddings. */
   readonly embeddingModel: string;
-  private readonly root: string | null;
+
+  /**
+   * Absolute path to the indexed tree on disk, or `null` for git-only indexes
+   * (clone is deleted after indexing; incremental updates need a local root).
+   */
+  private readonly _root: string | null;
+
+  /** Content kinds indexed at build time (e.g. `code`, `markdown`). */
   private readonly content: ContentType[];
+
+  /** Repo-relative file path → chunk indices in `chunksInternal`. */
   private fileMapping: Map<string, number[]>;
+
+  /** Language tag → chunk indices, for `filterLanguages` in search. */
   private languageMapping: Map<string, number[]>;
 
+  /** Stored file mtimes (file path → mtime_ms) for cache freshness checking. */
+  private storedFileMtimes: Map<string, number>;
+
+  /** Read-only view of indexed chunks. */
   get chunks(): Chunk[] {
     return this.chunksInternal;
   }
 
+  /** Whether this instance was loaded from a cache bundle rather than freshly built. */
   get loadedFromDisk(): boolean {
     return this.loadedFromDiskFlag;
   }
 
+  /** Get stored file mtimes for cache validation. */
+  getStoredFileMtimes(): Map<string, number> {
+    return this.storedFileMtimes;
+  }
+
+  /** Get the root path for local indexes (null for git indexes). */
+  get root(): string | null {
+    return this._root;
+  }
+
+  /** Content kinds indexed at build time, for re-walking the tree during freshness checks. */
+  get contentTypes(): ContentType[] {
+    return this.content;
+  }
+
+  /**
+   * Prefer static factories (`fromPath`, `fromGit`, `loadFromDisk`) over calling
+   * directly; the constructor is public for tests and advanced composition.
+   */
   constructor(options: {
     embeddings: EmbeddingBackend;
     bm25Index: BM25Index;
@@ -49,20 +112,26 @@ export class MiruIndex {
     root?: string | null;
     content?: ContentType[];
     loadedFromDisk?: boolean;
+    storedFileMtimes?: Record<string, number>;
   }) {
     this.embeddings = options.embeddings;
     this.bm25Index = options.bm25Index;
     this.semanticIndex = options.semanticIndex;
     this.chunksInternal = options.chunks;
     this.embeddingModel = options.embeddingModel;
-    this.root = options.root ?? null;
+    this._root = options.root ?? null;
     this.content = options.content ?? ["code"];
     this.loadedFromDiskFlag = options.loadedFromDisk ?? false;
+    this.storedFileMtimes = new Map(Object.entries(options.storedFileMtimes ?? {}));
     this.fileMapping = new Map();
     this.languageMapping = new Map();
     this.rebuildMappings();
   }
 
+  /**
+   * Rebuild file/language → chunk-index maps after chunks change.
+   * Called from the constructor and after incremental updates.
+   */
   private rebuildMappings(): void {
     this.fileMapping = new Map();
     this.languageMapping = new Map();
@@ -85,6 +154,12 @@ export class MiruIndex {
     }
   }
 
+  /**
+   * Clone a remote repo, index it, persist to cache, and return the in-memory index.
+   *
+   * Cache key is derived from URL + ref. On hit, skips clone and embedding work.
+   * The temporary clone directory is always removed in `finally`.
+   */
   static async fromGit(
     url: string,
     content: ContentType[] = ["code"],
@@ -113,6 +188,7 @@ export class MiruIndex {
         semanticIndex: semantic,
         chunks,
         embeddingModel: model,
+        // No durable local root — clone is deleted; incremental updates unavailable.
         root: null,
         content,
       });
@@ -123,6 +199,7 @@ export class MiruIndex {
     }
   }
 
+  /** Resolve a local path or git URL and delegate to `fromPath` or `fromGit`. */
   static async fromSource(
     source: string,
     content: ContentType[] = ["code"],
@@ -135,6 +212,13 @@ export class MiruIndex {
     return MiruIndex.fromPath(source, content, embeddingModel);
   }
 
+  /**
+   * Index a directory on disk, reusing a validated cache hit when available.
+   *
+   * `root` is set to the resolved path so `applyFileChanges` can re-chunk files
+   * later. Unlike `fromGit`, this does not auto-save to cache; callers use
+   * `saveToCache` when they want persistence.
+   */
   static async fromPath(
     path: string,
     content: ContentType[] = ["code"],
@@ -178,11 +262,18 @@ export class MiruIndex {
     });
   }
 
+  /**
+   * Hydrate BM25, semantic vectors, and chunks from a saved index bundle.
+   *
+   * Validates embedding model compatibility via cache metadata. Sets
+   * `loadedFromDisk` so callers can avoid redundant cache writes.
+   */
   static async loadFromDisk(path: string, embeddingModel?: string): Promise<MiruIndex> {
     const model = embeddingModel ?? resolveEmbeddingModel();
     const { bm25, semantic, chunks, metadata } = await loadCachedIndex(path);
     const content = (metadata.content_type as ContentType[]) ?? ["code"];
     const root = metadata.root_path ? String(metadata.root_path) : null;
+    const storedFileMtimes = (metadata.file_mtimes as Record<string, number>) ?? {};
 
     return new MiruIndex({
       embeddings: getEmbeddingBackend(model),
@@ -193,12 +284,32 @@ export class MiruIndex {
       root,
       content,
       loadedFromDisk: true,
+      storedFileMtimes,
     });
   }
 
+  /**
+   * Write BM25, semantic vectors, chunk metadata, and index metadata to `path`.
+   *
+   * Metadata includes `index_epoch` for invalidation when Miru's on-disk format
+   * changes, plus embedding model/dimensions for cache validation on reload.
+   */
   async save(path: string): Promise<void> {
     const paths = persistencePaths(path);
     await mkdir(paths.root, { recursive: true });
+
+    const fileMtimes: Record<string, number> = {};
+    if (this._root) {
+      for (const filePath of this.fileMapping.keys()) {
+        try {
+          const stat = await Bun.file(resolve(this._root, filePath)).stat();
+          fileMtimes[filePath] = Math.floor(stat.mtime?.getTime() ?? 0);
+        } catch {
+          fileMtimes[filePath] = 0;
+        }
+      }
+    }
+
     await saveIndexBundle({
       paths,
       bm25: this.bm25Index,
@@ -206,7 +317,7 @@ export class MiruIndex {
       chunks: this.chunks.map(chunkToDict),
       metadata: {
         index_epoch: indexCacheEpoch(),
-        root_path: this.root,
+        root_path: this._root,
         time: Date.now() / 1000,
         embedding_model: this.embeddingModel,
         embedding_dimensions:
@@ -214,23 +325,31 @@ export class MiruIndex {
         embedding_provider: "openai",
         content_type: this.content,
         file_paths: [...this.fileMapping.keys()].sort(),
+        file_mtimes: fileMtimes,
       },
     });
   }
 
-  async saveToDefaultCache(sourcePath: string): Promise<void> {
-    if (!this.loadedFromDiskFlag) {
+  /**
+   * Persist to the default cache location for `sourcePath`.
+   *
+   * By default this is a no-op for unchanged indexes loaded from disk, avoiding
+   * redundant cache writes. Pass `force: true` after mutating a cached index.
+   */
+  async saveToCache(sourcePath: string, options: { force?: boolean } = {}): Promise<void> {
+    if (!this.loadedFromDiskFlag || options.force) {
       await this.save(findIndexCachePath(sourcePath));
     }
   }
 
-  async persistToCache(sourcePath: string): Promise<void> {
-    await this.save(findIndexCachePath(sourcePath));
-  }
-
-  /** Re-chunk and re-embed only the given repo-relative paths; drop their old chunks. */
+  /**
+   * Re-chunk and re-embed only the given repo-relative paths; drop their old chunks.
+   *
+   * Requires `root` (local `fromPath` indexes only). Updates BM25, semantic
+   * index, and mappings in place; clears `loadedFromDisk` since data changed.
+   */
   async applyFileChanges(relativePaths: readonly string[]): Promise<void> {
-    if (!this.root) {
+    if (!this._root) {
       throw new Error("Incremental update requires a local index with root_path set.");
     }
     if (relativePaths.length === 0) {
@@ -238,7 +357,7 @@ export class MiruIndex {
     }
 
     const updated = await applyIncrementalFileChanges({
-      root: this.root,
+      root: this._root,
       content: this.content,
       embeddings: this.embeddings,
       chunks: this.chunksInternal,
@@ -253,20 +372,27 @@ export class MiruIndex {
     this.rebuildMappings();
   }
 
-  private getSelector(filterLanguages?: string[], filterPaths?: string[]): number[] | undefined {
-    const selector: number[] = [];
-    for (const lang of filterLanguages ?? []) {
-      selector.push(...(this.languageMapping.get(lang) ?? []));
-    }
-    for (const fp of filterPaths ?? []) {
-      selector.push(...(this.fileMapping.get(fp) ?? []));
-    }
-    if (selector.length === 0) {
-      return undefined;
-    }
-    return [...new Set(selector)];
+  private getSelector(
+    filterLanguages?: string[],
+    filterPaths?: string[],
+  ): readonly number[] | undefined {
+    return buildChunkSelector(
+      {
+        fileMapping: this.fileMapping,
+        languageMapping: this.languageMapping,
+      },
+      filterLanguages,
+      filterPaths,
+    );
   }
 
+  /**
+   * Hybrid BM25 + semantic search over indexed chunks.
+   *
+   * `alpha` blends keyword vs vector scores (default depends on content type).
+   * `filterLanguages` / `filterPaths` restrict candidates before ranking.
+   * `rerank` defaults to on for code indexes (cross-encoder style reranking).
+   */
   async search(options: {
     query: string;
     topK?: number;
@@ -296,6 +422,13 @@ export class MiruIndex {
     });
   }
 
+  /**
+   * Semantic neighbors of a chunk or search hit, excluding the source itself.
+   *
+   * Uses the chunk's text as the query embedding. When the source has a
+   * language, search is scoped to same-language chunks. Requests `topK + 1`
+   * hits so filtering out the source still yields `topK` results.
+   */
   async findRelated(source: Chunk | SearchResult, topK = 5): Promise<SearchResult[]> {
     const target = "chunk" in source ? source.chunk : source;
     const selector = target.language ? this.getSelector([target.language]) : undefined;

package/src/search.ts

@@ -35,7 +35,7 @@ function semanticFromQueryVector(
   semanticIndex: SemanticIndex,
   chunks: Chunk[],
   topK: number,
-  selector?: number[],
+  selector?: readonly number[],
 ): SearchResult[] {
   const { indices, distances } = semanticIndex.query(queryVec, topK, selector);
   return indices.flatMap((index, i) => {
@@ -52,7 +52,7 @@ async function searchBm25(
   bm25Index: BM25Index,
   chunks: Chunk[],
   topK: number,
-  selector?: number[],
+  selector?: readonly number[],
 ): Promise<SearchResult[]> {
   const tokens = tokenize(query);
   if (tokens.length === 0) {
@@ -79,7 +79,7 @@ export async function hybridSearch(options: {
   chunks: Chunk[];
   topK: number;
   alpha?: number | null;
-  selector?: number[];
+  selector?: readonly number[];
   rerank?: boolean;
 }): Promise<SearchResult[]> {
   const {
@@ -170,7 +170,7 @@ export async function searchSemanticOnly(options: {
   semanticIndex: SemanticIndex;
   chunks: Chunk[];
   topK: number;
-  selector?: number[];
+  selector?: readonly number[];
 }): Promise<SearchResult[]> {
   const queryVec = await options.embeddings.embedQuery(options.query);
   return semanticFromQueryVector(

package/src/setup.ts

@@ -1,4 +1,4 @@
-import { brandTitle, divider, fail, hint, info, success, writeStderr } from "./cli-ui.ts";
+import { divider, fail, hint, info, printBrandBanner, success, writeStderr } from "./cli-ui.ts";
 import {
   clearStoredCredentials,
   loadStoredCredentials,
@@ -55,7 +55,8 @@ export async function runSetup(options: RunSetupOptions = {}): Promise<RunSetupR
   }
 
   writeStderr("");
-  writeStderr(`${brandTitle()} setup`);
+  // stderr banner: setup runs before stdout may be a TTY (e.g. piped miru search).
+  printBrandBanner(process.stderr);
   divider("─", 48, process.stderr);
   writeStderr("Miru needs a Takara API key for code embeddings.");
   hint("Get a bearer token from Takara, then enter it below.");
@@ -129,6 +130,11 @@ export async function ensureCredentials(options?: { interactive?: boolean }): Pr
     return;
   }
 
+  writeStderr("");
+  // Brand on stderr when credentials are missing in non-interactive mode (stdout may not be a TTY).
+  printBrandBanner(process.stderr);
+  writeStderr("");
+
   throw new Error(
     "Takara API key required. Run `miru setup` in a terminal, or set TAKARA_API_KEY " +
       "in your MCP server env (Cursor mcp.json) or .env.local.",