@takara-ai/miru-code 1.12.0 → 1.12.2

package/README.md

@@ -200,9 +200,9 @@ When wired via `miru install`, the MCP server exposes `search`, `locate`, `expan
 ### Workflow
 
 1. **`search`** with `query` — returns compact snippets (~±15 lines) and relevance scores.
-2. If a hit has **`truncated: true`**, call **`expand`** with `file_path` and `anchor_line` — not another search or a full-file read.
-3. To trace similar patterns elsewhere, call **`find_related`** with the same `file_path` and `anchor_line`.
-4. Use your editor's **Read** on `absolute_path` only when editing or when `expand` still lacks context.
+2. If a hit has **`truncated: true`**, its header names the symbol and its exact lines (`path:start-end Symbol`) plus `anchor_line`. Read just those lines with a ranged **Read** (`offset`/`limit`) — not another search or a full-file read.
+3. If that range lacks context, call **`expand`** with `file_path` and `anchor_line` for neighbouring chunks. To trace similar patterns elsewhere, call **`find_related`** with the same `file_path` and `anchor_line`.
+4. Use your editor's **Read** on `absolute_path` only for a hit's line range, to see a truncated body or edit it.
 
 Keep `repo` on follow-up calls when set.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@takara-ai/miru-code",
-  "version": "1.12.0",
+  "version": "1.12.2",
   "mcpName": "ai.takara/miru",
   "description": "Miru (見る) — hybrid code search for agents. Bun, TypeScript, Takara embeddings.",
   "type": "module",

package/src/installer/config.ts

@@ -14,53 +14,13 @@ args = ["${MIRU_BUNX_PACKAGE}", "mcp", "--benchmark"]
 startup_timeout_sec = 60
 `;
 
+/** A string literal (kept) or a comment (dropped); a string left open runs to the end of the input. */
+const STRING_OR_COMMENT =
+  /("(?:\\[\s\S]|[^"\\])*\\?(?:"|$)|'(?:\\[\s\S]|[^'\\])*\\?(?:'|$))|\/\/[^\n]*|\/\*[\s\S]*?(?:\*\/|$)/g;
+
 /** Strip line and block comments so JSONC configs can be parsed. */
 export function stripJsonComments(text: string): string {
-  let out = "";
-  let i = 0;
-  let inString = false;
-  let stringQuote = '"';
-  while (i < text.length) {
-    const ch = text[i];
-    const next = text[i + 1];
-    if (inString) {
-      out += ch;
-      if (ch === "\\" && next !== undefined) {
-        out += next;
-        i += 2;
-        continue;
-      }
-      if (ch === stringQuote) {
-        inString = false;
-      }
-      i++;
-      continue;
-    }
-    if (ch === '"' || ch === "'") {
-      inString = true;
-      stringQuote = ch;
-      out += ch;
-      i++;
-      continue;
-    }
-    if (ch === "/" && next === "/") {
-      while (i < text.length && text[i] !== "\n") {
-        i++;
-      }
-      continue;
-    }
-    if (ch === "/" && next === "*") {
-      i += 2;
-      while (i < text.length && !(text[i] === "*" && text[i + 1] === "/")) {
-        i++;
-      }
-      i += 2;
-      continue;
-    }
-    out += ch;
-    i++;
-  }
-  return out;
+  return text.replace(STRING_OR_COMMENT, (_match, str?: string) => str ?? "");
 }
 
 function parseJsonObject(text: string): Record<string, unknown> | "error" {
@@ -285,34 +245,7 @@ function removeJsonMemberText(text: string, sectionKey: string, memberKey: strin
 
 /** True only when // or /* appear outside of strings (URLs like https:// must not match). */
 function hasJsoncSyntax(text: string): boolean {
-  let inString = false;
-  let quote = "";
-  for (let i = 0; i < text.length; i++) {
-    const ch = text[i] ?? "";
-    const next = text[i + 1] ?? "";
-    if (inString) {
-      if (ch === "\\") {
-        i++;
-        continue;
-      }
-      if (ch === quote) {
-        inString = false;
-      }
-      continue;
-    }
-    if (ch === '"' || ch === "'") {
-      inString = true;
-      quote = ch;
-      continue;
-    }
-    if (ch === "/" && next === "/") {
-      return true;
-    }
-    if (ch === "/" && next === "*") {
-      return true;
-    }
-  }
-  return false;
+  return stripJsonComments(text) !== text;
 }
 
 /** Locate an object section by dotted path, matching each key among direct children. */

package/src/installer/search-policy.ts

@@ -1,8 +1,9 @@
 /** Shared code-search policy text for instructions, Cursor rules, and sub-agents. */
 
 export const SNIPPET_GUIDANCE =
-  "Snippets are ~±15 lines. On `truncated: true`, call `expand` with `file_path` and " +
-  "`anchor_line` — only if the snippet doesn't already answer.";
+  "Snippets are ~±15 lines. A `truncated: true` hit names its symbol and exact lines (`path:start-end Symbol`) plus `anchor_line`: " +
+  "to see the full body, read exactly those lines with a ranged read (`offset`/`limit`), never the whole file. " +
+  "`expand` (`file_path` + `anchor_line`) is the fallback for neighbouring chunks — only if the snippet doesn't already answer.";
 
 export const WHEN_TO_REACH_FOR_MIRU =
   "Reach for Miru FIRST, before opening files, whenever you don't know the exact path: starting in unfamiliar code, " +
@@ -23,10 +24,11 @@ export function buildSearchPolicyTable(native: NativeToolNames): string {
 | Regex over code | Miru MCP \`locate\` with \`/regex/\` (\`mode=files\` for paths only) | ${native.grep} |
 | List files by name pattern | Miru MCP \`locate\` with \`include\` globs and no literal | Glob |
 | How/where/what handles X? (conceptual) | Miru MCP \`search\` (once) | ${native.grep}, ${native.explorationDenied} |
-| Same file, more context | Miru MCP \`expand\` on \`truncated: true\` | Re-search, ${native.read} whole file |
+| Full body of a \`truncated: true\` hit | ${native.read} the hit's \`start-end\` lines (\`offset\`/\`limit\`) | Re-search, ${native.read} whole file |
+| Same file, neighbouring chunks | Miru MCP \`expand\` (fallback) | Re-search |
 | Similar code elsewhere | Miru MCP \`find_related\` | ${native.grep} chains |
 | Search docs or config | Miru \`search\` | ${native.grep} README paths |
-| Edit a known file:line | ${native.read} (after Miru found it) | ${native.read}-before-search |`;
+| Edit a known file:line | ${native.read} the hit's \`start-end\` lines (after Miru found it) | ${native.read}-before-search |`;
 }
 
 export function buildSearchPolicyBody(native: NativeToolNames): string {
@@ -43,8 +45,8 @@ ${SNIPPET_GUIDANCE}
 Use Miru MCP tools:
 - \`locate\` — exact substring (env var, symbol, error code) or \`/regex/\`; no literal + \`include\` globs lists files; prefer \`mode=count\`, \`files\` or \`locations\`
 - \`search\` — one call per conceptual question; use \`include\` / \`exclude\` Gitignore-style globs to scope files (same syntax as \`locate\`)
-- \`expand\` — more context in the same file when \`truncated: true\` (\`file_path\` + \`anchor_line\`)
-- \`find_related\` — similar code in other files (hits may also be snippets; use \`expand\` if truncated)
+- \`expand\` — fallback: neighbouring chunks in the same file around \`anchor_line\` (\`file_path\` + \`anchor_line\`)
+- \`find_related\` — similar code in other files (hits may also be snippets; read the hit's lines if truncated)
 
 Call shapes:
 - \`locate(literal="<exact substring>")\` — prefer \`mode="locations"\`/\`"count"\`
@@ -53,8 +55,8 @@ Call shapes:
 Stop rules:
 - Literal in the request → \`locate\`, not \`search\`
 - One \`search\` per question — no paraphrase retries
-- \`expand\` only if the snippet doesn't already answer
-- ${native.read} only to edit a path Miru already found, not to explore
+- On \`truncated: true\`, ${native.read} only the hit's \`start-end\` lines (\`offset\`/\`limit\`); \`expand\` only if that doesn't answer
+- ${native.read} only a path Miru already found, to see a truncated body or edit it — never to explore, never the whole file
 
 Native tools are allowed ONLY when:
 - reading a file you already located via Miru, to edit it
@@ -69,9 +71,9 @@ export function buildMcpWorkflow(native: NativeToolNames): string {
 
 1. Call \`search\`; add \`repo\` only for another repo.
 2. For exact literals, call \`locate\` (prefer \`mode=count\` or \`locations\`).
-3. On \`truncated: true\`, call \`expand\` — only if the snippet doesn't already answer.
-4. Use \`find_related\` to trace similar code in other files — not for more context in the same file.
-5. ${native.read} via \`absolute_path\` only when editing or when \`expand\` still lacks context.`;
+3. On \`truncated: true\`, ${native.read} the hit's \`start-end\` lines (\`offset\`/\`limit\`) — only if the snippet doesn't already answer.
+4. Use \`expand\` for neighbouring chunks if that range lacks context; \`find_related\` to trace similar code in other files.
+5. ${native.read} via \`absolute_path\` only for the hit's range, to see a truncated body or edit it.`;
 }
 
 const CLI_FALLBACK = `### CLI fallback (no MCP in this session)
@@ -154,13 +156,13 @@ export const MCP_SEARCH_TOOL_DESCRIPTION =
 export const MCP_LOCATE_TOOL_DESCRIPTION =
   "Exact substring locator over the Miru index, also `/regex/` and file lists (grep for identifiers, env vars, error strings, quoted text, without the noise). " +
   'Use for known literals, not meaning-based questions (`search`), even when phrased "where is X" if X is a literal. ' +
-  "A literal in slashes (`/foo\\w+Bar/`, `/…/i`) is a regex. No literal + `include` globs lists files by name pattern; mode=files returns just matching paths. " +
+  "A literal wrapped in slashes is always a regex (`/foo\\w+Bar/`, `/bench/i`); omit the slashes for plain text. No literal + `include` globs lists files by name pattern; mode=files returns just matching paths. " +
   "Returns ALL matches by default — do NOT fall back to Grep/rg when n is large; prefer mode=count/files/locations unless you need line text. " +
   "`context_lines` (mode=lines) saves a follow-up `expand`. In benchmark mode, includes token savings vs Grep.";
 
 export const MCP_EXPAND_TOOL_DESCRIPTION =
-  "More context in the SAME file as a search hit. Pass `file_path` + `anchor_line` from the hit. " +
-  "Use only if `truncated: true` and the snippet doesn't already answer the question — not for similar code elsewhere (use find_related).";
+  "Neighbouring chunks in the SAME file as a search hit (`file_path` + `anchor_line` from the hit). " +
+  "For a `truncated: true` hit's own full body, read its `start-end` lines instead; use this only if that doesn't answer — not for similar code elsewhere (use find_related).";
 
 export const MCP_FIND_RELATED_TOOL_DESCRIPTION =
   "Find up to 5 chunks similar to a file:line in OTHER parts of the codebase. Results may be snippets; use `expand` when `truncated: true`. " +

package/src/literal.ts

@@ -56,19 +56,22 @@ export interface LiteralLocateOptions {
   context_lines?: number;
 }
 
-/** A `/body/` (optionally `/body/i`) literal is a regex only if the body has regex syntax, so `/api/users/` stays a plain substring. */
-const SLASH_REGEX = /^\/(.+)\/(i?)$/s;
-const REGEX_SYNTAX = /[\\^$.*+?()[\]{}|]/;
+/**
+ * `/body/` and `/body/i` are always regexes. Anything else is plain text, so drop the outer
+ * slashes to search a path such as `api/users/` as a substring.
+ */
+const SLASH_REGEX = /^\/(?<body>.+)\/(?<flag>i?)$/s;
 /** Regex is tested per line; cap the tested prefix so a minified line cannot stall the scan. */
 const MAX_REGEX_LINE_CHARS = 4096;
 
+/** The regex a slash-wrapped literal denotes, or null for a plain-text literal. */
 function parseRegexLiteral(literal: string, ignoreCase: boolean): RegExp | null {
-  const m = SLASH_REGEX.exec(literal);
-  if (!m || !REGEX_SYNTAX.test(m[1] ?? "")) {
+  const groups = SLASH_REGEX.exec(literal)?.groups;
+  if (!groups) {
     return null;
   }
   try {
-    return new RegExp(m[1] ?? "", ignoreCase || m[2] === "i" ? "i" : "");
+    return new RegExp(groups.body ?? "", ignoreCase || groups.flag === "i" ? "i" : "");
   } catch (err) {
     throw new Error(
       `Invalid regex ${literal}: ${err instanceof Error ? err.message : String(err)}`,
@@ -100,6 +103,9 @@ function lineMatchesAny(
   needles: readonly string[],
   ignoreCase: boolean,
 ): boolean {
+  if (needles.length === 0) {
+    return false;
+  }
   const hay = ignoreCase ? haystack.toLowerCase() : haystack;
   for (const needle of needles) {
     const n = ignoreCase ? needle.toLowerCase() : needle;
@@ -158,6 +164,51 @@ function expandLiterals(literals: readonly string[], matchVariants: boolean): st
   return [...seen];
 }
 
+interface LiteralMatcher {
+  /** Plain substrings actually searched, after identifier-variant expansion. */
+  needles: readonly string[];
+  /** The slash-wrapped inputs, verbatim. */
+  regexLiterals: readonly string[];
+  isEmpty: boolean;
+  matchesLine(line: string): boolean;
+  /** Cheap whole-chunk test: false means no line in the chunk can match. */
+  chunkMayMatch(content: string): boolean;
+}
+
+/** Splits literals into plain substrings and regexes, and builds the line and chunk tests. */
+function compileMatcher(
+  literals: readonly string[],
+  ignoreCase: boolean,
+  matchVariants: boolean,
+): LiteralMatcher {
+  const regexes: RegExp[] = [];
+  const regexLiterals: string[] = [];
+  const plain: string[] = [];
+  for (const literal of literals) {
+    const re = parseRegexLiteral(literal, ignoreCase);
+    if (re) {
+      regexes.push(re);
+      regexLiterals.push(literal);
+    } else {
+      plain.push(literal);
+    }
+  }
+  const needles = expandLiterals(plain, matchVariants);
+  // One JIT-compiled pass per chunk rules out most chunks before any line is split or tested.
+  // Multiline anchors keep `^`/`$` line-relative, so this can only over-match, never miss.
+  const chunkRegexes = regexes.map((re) => new RegExp(re.source, `${re.flags}m`));
+
+  return {
+    needles,
+    regexLiterals,
+    isEmpty: needles.length === 0 && regexes.length === 0,
+    matchesLine: (line) =>
+      lineMatchesAny(line, needles, ignoreCase) || regexMatchesLine(line, regexes),
+    chunkMayMatch: (content) =>
+      lineMatchesAny(content, needles, ignoreCase) || chunkRegexes.some((re) => re.test(content)),
+  };
+}
+
 export function filterChunksByGlob(
   chunks: readonly Chunk[],
   include: string[] | undefined,
@@ -242,21 +293,8 @@ export function locateLiteral(
 
   const inputLiterals = (Array.isArray(literal) ? literal : [literal]).filter((l) => l.length > 0);
   const label = inputLiterals.join(" | ");
-  const regexes: RegExp[] = [];
-  const plainLiterals: string[] = [];
-  for (const lit of inputLiterals) {
-    const re = parseRegexLiteral(lit, ignoreCase);
-    if (re) {
-      regexes.push(re);
-    } else {
-      plainLiterals.push(lit);
-    }
-  }
-  const needles = expandLiterals(plainLiterals, options.match_variants === true);
-  const matchesLine = (text: string): boolean =>
-    lineMatchesAny(text, needles, ignoreCase) || regexMatchesLine(text, regexes);
-
-  if (needles.length === 0 && regexes.length === 0) {
+  const matcher = compileMatcher(inputLiterals, ignoreCase, options.match_variants === true);
+  if (matcher.isEmpty) {
     return { literal: label, mode, n: 0, files: 0, truncated: false, hits: [] };
   }
 
@@ -270,13 +308,13 @@ export function locateLiteral(
   let n = 0;
 
   for (const chunk of scopedChunks) {
-    if (regexes.length === 0 && !lineMatchesAny(chunk.content, needles, ignoreCase)) {
+    if (!matcher.chunkMayMatch(chunk.content)) {
       continue;
     }
     const lines = chunk.content.split("\n");
     for (let i = 0; i < lines.length; i++) {
       const lineText = lines[i] ?? "";
-      if (!matchesLine(lineText)) {
+      if (!matcher.matchesLine(lineText)) {
         continue;
       }
       const line = chunk.start_line + i;
@@ -318,7 +356,7 @@ export function locateLiteral(
   if (mode === "files") {
     result.file_list = [...fileSet].sort();
   }
-  const searched = [...needles, ...inputLiterals.filter((l) => !plainLiterals.includes(l))];
+  const searched = [...matcher.needles, ...matcher.regexLiterals];
   if (searched.length > 1) {
     result.literals = searched;
   }

package/src/mcp/format-text.ts

@@ -12,10 +12,19 @@ export function formatResultsText(payload: {
 
   const blocks = payload.results.map((result) => {
     const chunk = result.chunk as Record<string, unknown>;
-    const startLine = chunk.truncated ? chunk.full_start_line : chunk.start_line;
-    const endLine = chunk.truncated ? chunk.full_end_line : chunk.end_line;
-    const truncatedNote = chunk.truncated ? " [truncated: call expand for full chunk]" : "";
-    const header = `${chunk.file_path}:${startLine}-${endLine}${truncatedNote}`;
+    // A truncated hit names the matched symbol's exact range (not the source file's) so the full
+    // body is one ranged read away; `anchor_line` is the matched line for `expand`/`find_related`.
+    const startLine = chunk.truncated
+      ? (chunk.match_start_line ?? chunk.full_start_line)
+      : chunk.start_line;
+    const endLine = chunk.truncated
+      ? (chunk.match_end_line ?? chunk.full_end_line)
+      : chunk.end_line;
+    const symbol = chunk.truncated && chunk.symbol ? ` ${chunk.symbol}` : "";
+    const truncatedNote = chunk.truncated
+      ? ` [truncated: anchor_line ${chunk.anchor_line}; read lines ${startLine}-${endLine} for the full symbol, or call expand]`
+      : "";
+    const header = `${chunk.file_path}:${startLine}-${endLine}${symbol}${truncatedNote}`;
     return `${header}\n${chunk.content}`;
   });
 

package/src/mcp/server.ts

@@ -250,7 +250,7 @@ export function createMcpServer(
           .union([z.string().min(1), z.array(z.string().min(1)).min(1)])
           .optional()
           .describe(
-            "Exact substring, or a regex in slashes like `/foo\\w+Bar/` (`/…/i` ignores case). An array ORs several. Omit and pass `include` to list files.",
+            "Exact substring, or a regex wrapped in slashes like `/foo\\w+Bar/` or `/bench/i` (ignores case). An array ORs several. Omit and pass `include` to list files.",
           ),
         query: z
           .union([z.string().min(1), z.array(z.string().min(1)).min(1)])

package/src/snippet.ts

@@ -13,6 +13,11 @@ export interface SnippetMeta {
   anchor_line: number;
   full_start_line: number;
   full_end_line: number;
+  /** Exact lines of the matched (ranked) chunk — the symbol-sized range to read, not the source file. */
+  match_start_line: number;
+  match_end_line: number;
+  /** Name of the symbol the matched chunk declares, when one is recognizable. */
+  symbol: string | null;
 }
 
 export interface SnippetResult {
@@ -73,6 +78,24 @@ function scoreLine(line: string, terms: Set<string>): number {
 
 const DECLARATION_RE =
   /^\s*(?:export\s+)?(?:default\s+)?(?:async\s+)?(?:function|class|interface|enum|type|struct|trait|impl|record|namespace|contract|library|object)\b|^\s*(?:export\s+)?(?:const|let|var)\s+[$\w]+\s*=\s*[{[(]|^\s*(?:async\s+)?def\s+\w+|^\s*def\s+\w+|^\s*fn\s+\w+|^\s*func\s+\w+|^\s*defmodule\b|^\s*def\w*\b|^\s*(?:(?:public|private|protected|internal|static|final|abstract|virtual|override|sealed|partial|unsafe|extern)\s+)+(?:[A-Za-z_$][\w:<>[\]?.,\s]*\s+)+[A-Za-z_$]\w*\s*\(|^\s*(?:void|bool|boolean|char|short|int|long|float|double|string|[A-Z][\w:<>[\]?.,]*)\s+[A-Za-z_$]\w*\s*\(|^\s*(?:function\s+)?[A-Za-z_]\w*\s*\(\)\s*\{/;
+const DECLARED_NAME_RE =
+  /\b(?:function\*?|class|interface|enum|type|struct|trait|impl|record|namespace|contract|library|object|def|fn|func|defmodule)\s+([A-Za-z_$][\w$]*)|\b(?:const|let|var)\s+([A-Za-z_$][\w$]*)\s*=/;
+
+/** Name declared by the first declaration line in `content`, or null when none is recognizable. */
+export function declaredSymbol(content: string): string | null {
+  for (const line of content.split("\n").slice(0, MAX_DECLARATION_LOOKBACK)) {
+    if (!DECLARATION_RE.test(line)) {
+      continue;
+    }
+    const match = DECLARED_NAME_RE.exec(line);
+    const name = match?.[1] ?? match?.[2];
+    if (name) {
+      return name;
+    }
+  }
+  return null;
+}
+
 const BRACE_BODY_RE =
   /\b(?:function|class|interface|enum|struct|trait|impl|record|namespace|contract|library|object|fn|func)\b|=\s*[{[(]|[A-Za-z_$]\w*\s*\([^)]*\)\s*\{/;
 const RUBY_OR_ELIXIR_BODY_RE = /^\s*def\w*\b|^\s*defmodule\b/;
@@ -419,6 +442,9 @@ export function trimChunkToSnippet(
         anchor_line: chunk.start_line + anchorOffset,
         full_start_line: chunk.start_line,
         full_end_line: chunk.end_line,
+        match_start_line: chunk.start_line,
+        match_end_line: chunk.end_line,
+        symbol: declaredSymbol(chunk.content),
       },
     };
   }
@@ -436,6 +462,9 @@ export function trimChunkToSnippet(
       anchor_line: chunk.start_line + anchorOffset,
       full_start_line: chunk.start_line,
       full_end_line: chunk.end_line,
+      match_start_line: chunk.start_line,
+      match_end_line: chunk.end_line,
+      symbol: declaredSymbol(chunk.content),
     },
   };
 }
@@ -460,8 +489,20 @@ export function applySnippetsToResults(
   });
   return contextualResults.map(({ result, anchorLine }, rank) => {
     const { chunk, meta } = trimChunkToSnippet(result.chunk, query, radius, anchorLine);
+    // `result.chunk` may be the whole source file; the ranked chunk is the symbol-sized match.
+    const ranked = results[rank]?.chunk;
     const snippet = compactSupportingSnippet(
-      { chunk, meta },
+      {
+        chunk,
+        meta: ranked
+          ? {
+              ...meta,
+              match_start_line: ranked.start_line,
+              match_end_line: ranked.end_line,
+              symbol: declaredSymbol(ranked.content) ?? meta.symbol,
+            }
+          : meta,
+      },
       rank === 0 ? primaryMaxLines : supportingMaxLines,
     );
     return { result: { chunk: snippet.chunk, score: result.score }, meta: snippet.meta };

package/src/utils.ts

@@ -210,6 +210,9 @@ export function formatResults(
             anchor_line: entry.meta.anchor_line,
             full_start_line: entry.meta.full_start_line,
             full_end_line: entry.meta.full_end_line,
+            match_start_line: entry.meta.match_start_line,
+            match_end_line: entry.meta.match_end_line,
+            ...(entry.meta.symbol ? { symbol: entry.meta.symbol } : {}),
           },
           score,
         };