@takara-ai/miru-code 0.4.12 → 0.6.0

package/src/ranking/boosting.ts

@@ -2,6 +2,12 @@ import { basename, dirname } from "node:path";
 import { splitIdentifier } from "../tokens.ts";
 import type { Chunk } from "../types.ts";
 import { chunkKey } from "../types.ts";
+import { searchImprovementsEnabled } from "./features.ts";
+import {
+  boostExactStemMatches,
+  boostLocationSignals,
+  penalizeInstallerForLocation,
+} from "./location.ts";
 
 const SYMBOL_QUERY_RE =
   /^(?:(?:[A-Za-z_][A-Za-z0-9_]*(?:(?:::|\\|->|\.)[A-Za-z_][A-Za-z0-9_]*)+)|_(?:[A-Za-z0-9_]*)|(?:[A-Za-z][A-Za-z0-9]*[A-Z_][A-Za-z0-9_]*)|(?:[A-Z][A-Za-z0-9]*))$/;
@@ -165,6 +171,11 @@ export function applyQueryBoost(
   } else {
     boostStemMatches(combinedScores, query, maxScore, chunksByKey);
     boostEmbeddedSymbols(combinedScores, query, maxScore, allChunks, chunksByKey);
+    if (searchImprovementsEnabled()) {
+      boostExactStemMatches(combinedScores, query, maxScore, chunksByKey);
+      boostLocationSignals(combinedScores, query, maxScore, allChunks, chunksByKey);
+      penalizeInstallerForLocation(combinedScores, query, chunksByKey);
+    }
   }
   return combinedScores;
 }

package/src/ranking/features.ts

@@ -0,0 +1,11 @@
+/** Toggle search ranking/indexing improvements (A/B via MIRU_SEARCH_V2=0|1). */
+export function searchImprovementsEnabled(): boolean {
+  const value = process.env.MIRU_SEARCH_V2;
+  if (value === "0" || value === "false") {
+    return false;
+  }
+  if (value === "1" || value === "true") {
+    return true;
+  }
+  return true;
+}

package/src/ranking/location.ts

@@ -0,0 +1,237 @@
+import { basename } from "node:path";
+import type { Chunk } from "../types.ts";
+import { chunkKey } from "../types.ts";
+
+const LOCATION_QUERY_RE =
+  /\b(where(?:'s| is)?|entry\s*point|bootstrap|starts?|live[s]?|located|defined|wiring)\b/i;
+
+const ENTRY_POINT_QUERY_RE = /\b(entry\s*point|bootstrap|starts?|wiring|command\s*line)\b/i;
+
+const INTEGRATION_QUERY_RE = /\b(install|uninstall|hook|agent|configure|setup)\b/i;
+
+const INSTALLER_PATH_RE = /(?:^|\/)installer(?:\/|$)/;
+
+const ENTRY_POINT_CONTENT_RE =
+  /#!\/usr\/bin|(?:^|\n)\s*(?:async\s+)?function\s+main\s*\(|(?:^|\n)\s*if\s*\(\s*require\.main\s*===\s*module/;
+
+const PACKAGE_ENTRY_RE = /^\[package entry\]/;
+
+const LOCATION_BOOST_MULTIPLIER = 2.5;
+const INSTALLER_LOCATION_PENALTY = 0.35;
+
+/** Too common as filenames to get exact-stem boosts from incidental query tokens. */
+const IMPLEMENTATION_HINTS = new Set(
+  [
+    "command",
+    "handler",
+    "router",
+    "routing",
+    "middleware",
+    "model",
+    "channel",
+    "request",
+    "response",
+    "dispatch",
+    "pipeline",
+  ].map((w) => w.toLowerCase()),
+);
+
+const GENERIC_STEM_DENY = new Set(
+  [
+    "route",
+    "routes",
+    "router",
+    "routing",
+    "handler",
+    "middleware",
+    "channel",
+    "model",
+    "models",
+    "request",
+    "response",
+    "utils",
+    "util",
+    "server",
+    "client",
+    "application",
+    "dispatch",
+    "core",
+    "lib",
+    "main",
+    "mod",
+    "test",
+    "tests",
+    "schema",
+    "config",
+    "helper",
+    "helpers",
+    "engine",
+    "pipeline",
+    "plug",
+    "plugs",
+    "command",
+    "commands",
+    "index",
+  ].map((w) => w.toLowerCase()),
+);
+
+export function isLocationQuery(query: string): boolean {
+  return LOCATION_QUERY_RE.test(query);
+}
+
+export function isEntryPointQuery(query: string): boolean {
+  return ENTRY_POINT_QUERY_RE.test(query);
+}
+
+function fileStemMatchesQuery(filePath: string, query: string): boolean {
+  const stem = basename(filePath)
+    .replace(/\.[^.]+$/, "")
+    .toLowerCase();
+  const rawTokens = (query.match(/[a-zA-Z_][a-zA-Z0-9_-]*/g) ?? []).map((t) => t.toLowerCase());
+
+  if (rawTokens.includes(stem)) {
+    return true;
+  }
+
+  for (const token of rawTokens) {
+    if (token.includes("-") && token.split("-").includes(stem)) {
+      return false;
+    }
+  }
+
+  const stemNorm = stem.replace(/[-_]/g, "");
+  return rawTokens.some((t) => t.replace(/[-_]/g, "") === stemNorm);
+}
+
+export function isIntegrationQuery(query: string): boolean {
+  return INTEGRATION_QUERY_RE.test(query);
+}
+
+function chunkLooksLikeEntryPoint(chunk: Chunk): boolean {
+  if (PACKAGE_ENTRY_RE.test(chunk.content)) {
+    return true;
+  }
+  return ENTRY_POINT_CONTENT_RE.test(chunk.content);
+}
+
+export function boostLocationSignals(
+  boosted: Map<string, number>,
+  query: string,
+  maxScore: number,
+  allChunks: Chunk[],
+  chunksByKey: Map<string, Chunk>,
+): void {
+  if (!isLocationQuery(query)) {
+    return;
+  }
+
+  const entryPointQuery = isEntryPointQuery(query);
+  const packageBoost = maxScore * (entryPointQuery ? LOCATION_BOOST_MULTIPLIER : 0.75);
+  const codeBoost = maxScore * LOCATION_BOOST_MULTIPLIER;
+
+  for (const chunk of allChunks) {
+    if (!chunkLooksLikeEntryPoint(chunk)) {
+      continue;
+    }
+
+    const isPackageEntry = PACKAGE_ENTRY_RE.test(chunk.content);
+    if (isPackageEntry) {
+      const key = chunkKey(chunk);
+      boosted.set(key, (boosted.get(key) ?? 0) + packageBoost);
+      chunksByKey.set(key, chunk);
+      continue;
+    }
+
+    if (!entryPointQuery && !fileStemMatchesQuery(chunk.file_path, query)) {
+      continue;
+    }
+
+    const key = chunkKey(chunk);
+    boosted.set(key, (boosted.get(key) ?? 0) + codeBoost);
+    chunksByKey.set(key, chunk);
+  }
+}
+
+export function penalizeInstallerForLocation(
+  boosted: Map<string, number>,
+  query: string,
+  chunksByKey: Map<string, Chunk>,
+): void {
+  if (!isLocationQuery(query) || isIntegrationQuery(query)) {
+    return;
+  }
+
+  for (const [key, score] of boosted) {
+    const chunk = chunksByKey.get(key);
+    if (!chunk) {
+      continue;
+    }
+    if (INSTALLER_PATH_RE.test(chunk.file_path.replace(/\\/g, "/"))) {
+      boosted.set(key, score * INSTALLER_LOCATION_PENALTY);
+    }
+  }
+}
+
+function hasSpecificImplementationTarget(query: string, chunksByKey: Map<string, Chunk>): boolean {
+  const lowered = query.toLowerCase();
+  for (const hint of IMPLEMENTATION_HINTS) {
+    if (!lowered.includes(hint)) {
+      continue;
+    }
+    for (const chunk of chunksByKey.values()) {
+      const stem = basename(chunk.file_path)
+        .replace(/\.[^.]+$/, "")
+        .toLowerCase();
+      if (stem === hint) {
+        return true;
+      }
+    }
+  }
+  return false;
+}
+
+export function boostExactStemMatches(
+  boosted: Map<string, number>,
+  query: string,
+  maxScore: number,
+  chunksByKey: Map<string, Chunk>,
+): void {
+  const keywords = new Set(
+    (query.match(/[a-zA-Z_][a-zA-Z0-9_-]*/g) ?? [])
+      .filter((w) => w.length > 2)
+      .map((w) => w.toLowerCase()),
+  );
+  if (keywords.size === 0) {
+    return;
+  }
+
+  const boost = maxScore * 0.75;
+  const preferImplementation = hasSpecificImplementationTarget(query, chunksByKey);
+
+  for (const key of [...boosted.keys()]) {
+    const chunk = chunksByKey.get(key);
+    if (!chunk) {
+      continue;
+    }
+    const stem = basename(chunk.file_path)
+      .replace(/\.[^.]+$/, "")
+      .toLowerCase();
+    const stemNorm = stem.replace(/[-_]/g, "");
+    for (const keyword of keywords) {
+      if (GENERIC_STEM_DENY.has(keyword)) {
+        continue;
+      }
+      if (preferImplementation && stem === keyword && !IMPLEMENTATION_HINTS.has(stem)) {
+        continue;
+      }
+      const keywordNorm = keyword.replace(/[-_]/g, "");
+      if (stem === keyword || stemNorm === keywordNorm) {
+        boosted.set(key, (boosted.get(key) ?? 0) + boost);
+        break;
+      }
+      const parts = keyword.split("-").filter((p) => p.length > 2);
+      if (parts.length > 1 && parts.some((p) => p === stem)) {
+      }
+    }
+  }
+}

package/src/search.ts

@@ -4,6 +4,8 @@ import type { SemanticIndex } from "./index/semantic-index.ts";
 import { selectorToMask } from "./index/sparse.ts";
 import { selectTopKScoreIndices } from "./index/topk.ts";
 import { applyQueryBoost, boostMultiChunkFiles } from "./ranking/boosting.ts";
+import { searchImprovementsEnabled } from "./ranking/features.ts";
+import { isLocationQuery } from "./ranking/location.ts";
 import { rerankTopk } from "./ranking/penalties.ts";
 import { resolveAlpha } from "./ranking/weighting.ts";
 import { tokenize } from "./tokens.ts";
@@ -93,7 +95,8 @@ export async function hybridSearch(options: {
   } = options;
 
   const alphaWeight = resolveAlpha(query, alpha);
-  const candidateCount = topK * 5;
+  const candidateCount =
+    searchImprovementsEnabled() && isLocationQuery(query) ? topK * 10 : topK * 5;
   const chunksByKey = new Map(chunks.map((c) => [chunkKey(c), c]));
 
   const queryVecPromise = embeddings.embedQuery(query);

package/src/setup.ts

@@ -63,7 +63,7 @@ export async function runSetup(options: RunSetupOptions = {}): Promise<string> {
     spinner.start();
     const result = await validateEmbeddingApiKey({ apiKey });
     if (!result.valid) {
-      spinner.fail(result.message);
+      spinner.stop();
       throw new Error(result.message);
     }
     spinner.succeed("API key validated");

package/src/snippet.ts

@@ -0,0 +1,154 @@
+import { envOptionalInt } from "./env.ts";
+import { tokenize } from "./tokens.ts";
+import type { Chunk, SearchResult } from "./types.ts";
+
+const SNIPPET_STOPWORDS = new Set(
+  "a an and are as at be by do does for from has have how if in is it not of on or the to was what when where which who why with".split(
+    " ",
+  ),
+);
+
+export interface SnippetMeta {
+  truncated: boolean;
+  anchor_line: number;
+  full_start_line: number;
+  full_end_line: number;
+}
+
+export interface SnippetResult {
+  chunk: Chunk;
+  meta: SnippetMeta;
+}
+
+export function resolveSnippetLines(): number {
+  return envOptionalInt(["MIRU_SNIPPET_LINES"], 3) ?? 15;
+}
+
+export function searchSnippetsEnabled(): boolean {
+  const value = process.env.MIRU_SEARCH_SNIPPETS;
+  if (value === "0" || value === "false") {
+    return false;
+  }
+  if (value === "1" || value === "true") {
+    return true;
+  }
+  return true;
+}
+
+function queryMatchTerms(query: string): Set<string> {
+  const terms = new Set<string>();
+  for (const tok of tokenize(query)) {
+    if (tok.length >= 3 && !SNIPPET_STOPWORDS.has(tok)) {
+      terms.add(tok);
+    }
+  }
+  for (const word of query.match(/[a-zA-Z_][a-zA-Z0-9_-]*/g) ?? []) {
+    const lower = word.toLowerCase();
+    if (lower.length >= 3 && !SNIPPET_STOPWORDS.has(lower)) {
+      terms.add(lower);
+    }
+  }
+  return terms;
+}
+
+function scoreLine(line: string, terms: Set<string>): number {
+  const lower = line.toLowerCase();
+  let score = 0;
+  for (const term of terms) {
+    if (lower.includes(term)) {
+      score++;
+    }
+  }
+  return score;
+}
+
+/** Pick the 0-based line index inside `content` that best matches the query. */
+export function anchorLineOffset(content: string, query: string): number {
+  const lines = content.split("\n");
+  if (lines.length === 0) {
+    return 0;
+  }
+
+  const terms = queryMatchTerms(query);
+  let bestIndex = Math.floor(lines.length / 2);
+  let bestScore = -1;
+
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i] ?? "";
+    const score = scoreLine(line, terms);
+    if (score > bestScore) {
+      bestScore = score;
+      bestIndex = i;
+    }
+  }
+
+  return bestIndex;
+}
+
+export function trimChunkToSnippet(
+  chunk: Chunk,
+  query: string,
+  linesEachSide = resolveSnippetLines(),
+): SnippetResult {
+  const lines = chunk.content.split("\n");
+  if (lines.length === 0) {
+    return {
+      chunk,
+      meta: {
+        truncated: false,
+        anchor_line: chunk.start_line,
+        full_start_line: chunk.start_line,
+        full_end_line: chunk.end_line,
+      },
+    };
+  }
+
+  const anchorOffset = anchorLineOffset(chunk.content, query);
+  const startOffset = Math.max(0, anchorOffset - linesEachSide);
+  const endOffset = Math.min(lines.length, anchorOffset + linesEachSide + 1);
+  const truncated = startOffset > 0 || endOffset < lines.length;
+
+  if (!truncated) {
+    return {
+      chunk,
+      meta: {
+        truncated: false,
+        anchor_line: chunk.start_line + anchorOffset,
+        full_start_line: chunk.start_line,
+        full_end_line: chunk.end_line,
+      },
+    };
+  }
+
+  const snippetContent = lines.slice(startOffset, endOffset).join("\n");
+  return {
+    chunk: {
+      ...chunk,
+      content: snippetContent,
+      start_line: chunk.start_line + startOffset,
+      end_line: chunk.start_line + endOffset - 1,
+    },
+    meta: {
+      truncated: true,
+      anchor_line: chunk.start_line + anchorOffset,
+      full_start_line: chunk.start_line,
+      full_end_line: chunk.end_line,
+    },
+  };
+}
+
+export function applySnippetsToResults(
+  results: SearchResult[],
+  query: string,
+  linesEachSide?: number,
+): Array<{ result: SearchResult; meta: SnippetMeta }> {
+  const radius = linesEachSide ?? resolveSnippetLines();
+  return results.map((result) => {
+    const { chunk, meta } = trimChunkToSnippet(result.chunk, query, radius);
+    return { result: { chunk, score: result.score }, meta };
+  });
+}
+
+export function estimateResultTokens(results: SearchResult[]): number {
+  return results.reduce((sum, r) => sum + Math.floor(r.chunk.content.length / 4), 0);
+}

package/src/spinner.ts

@@ -57,7 +57,7 @@ export async function withSpinner<T>(
     spinner.succeed(options?.successMessage ?? "");
     return result;
   } catch (err) {
-    spinner.fail(options?.failMessage);
+    spinner.stop();
     throw err;
   }
 }

package/src/utils.ts

@@ -1,4 +1,5 @@
 import { join, relative, resolve, sep } from "node:path";
+import { applySnippetsToResults, searchSnippetsEnabled } from "./snippet.ts";
 import type { Chunk, ContentType, SearchResult } from "./types.ts";
 import { chunkToDict } from "./types.ts";
 
@@ -16,11 +17,22 @@ export function isGitUrl(path: string): boolean {
   return GIT_URL_SCHEMES.some((scheme) => path.startsWith(scheme)) || SCP_GIT_URL_RE.test(path);
 }
 
+export function httpGitCloneAllowed(): boolean {
+  const raw = process.env.MIRU_ALLOW_HTTP_GIT;
+  return raw === "1" || raw === "true";
+}
+
 export function isAllowedRepoSource(repo: string): boolean {
   if (!isGitUrl(repo)) {
     return true;
   }
-  return repo.startsWith("https://") || repo.startsWith("http://");
+  if (repo.startsWith("https://")) {
+    return true;
+  }
+  if (repo.startsWith("http://")) {
+    return httpGitCloneAllowed();
+  }
+  return false;
 }
 
 /** Resolved local repo root for MCP output; null for remote git URLs. */
@@ -28,6 +40,20 @@ export function localRepoRoot(repo: string): string | null {
   return isGitUrl(repo) ? null : resolve(repo);
 }
 
+/** When MIRU_WORKSPACE_ROOT is set, local repo paths must stay inside it. */
+export function validateLocalRepoPath(repo: string): void {
+  const workspaceRoot = process.env.MIRU_WORKSPACE_ROOT?.trim();
+  if (!workspaceRoot || isGitUrl(repo)) {
+    return;
+  }
+  const resolvedRepo = resolve(repo);
+  const resolvedWorkspace = resolve(workspaceRoot);
+  const prefix = resolvedWorkspace.endsWith(sep) ? resolvedWorkspace : `${resolvedWorkspace}${sep}`;
+  if (resolvedRepo !== resolvedWorkspace && !resolvedRepo.startsWith(prefix)) {
+    throw new Error(`Local repo path is outside workspace: ${repo}`);
+  }
+}
+
 /** Map an absolute or repo-relative path to the index-relative form. */
 export function toIndexedFilePath(filePath: string, repoRoot?: string | null): string {
   if (!repoRoot) {
@@ -154,18 +180,49 @@ export function expandChunksAtLine(
   return { anchor, chunks: fileChunks.slice(start, end) };
 }
 
+/** Relative relevance for MCP/CLI output (top hit in a batch is always 100%). */
+export function formatRelevanceScore(score: number, maxScore: number): string {
+  if (maxScore <= 0) {
+    return "0%";
+  }
+  const pct = Math.round((score / maxScore) * 100);
+  return `${pct}%`;
+}
+
 export function formatResults(
   query: string,
   results: SearchResult[],
-  options?: { repoRoot?: string | null },
+  options?: { repoRoot?: string | null; snippet?: boolean },
 ): { query: string; results: Record<string, unknown>[] } {
   const repoRoot = options?.repoRoot ?? null;
+  const useSnippet = options?.snippet ?? searchSnippetsEnabled();
+  const payload = useSnippet ? applySnippetsToResults(results, query) : null;
+  const maxScore = results.reduce((max, result) => Math.max(max, result.score), 0);
+
   return {
     query,
-    results: results.map((result) => ({
-      chunk: chunkToResponseDict(result.chunk, repoRoot),
-      score: result.score,
-    })),
+    results: results.map((result, index) => {
+      const entry = payload?.[index];
+      const chunk = entry?.result.chunk ?? result.chunk;
+      const dict = chunkToResponseDict(chunk, repoRoot);
+      const score = formatRelevanceScore(result.score, maxScore);
+      if (entry?.meta.truncated) {
+        return {
+          chunk: {
+            ...dict,
+            truncated: true,
+            anchor_line: entry.meta.anchor_line,
+            full_start_line: entry.meta.full_start_line,
+            full_end_line: entry.meta.full_end_line,
+          },
+          score,
+        };
+      }
+      return {
+        chunk: dict,
+        score,
+      };
+    }),
   };
 }