@takara-ai/miru-code 1.12.0 → 1.12.1

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.1",
   "mcpName": "ai.takara/miru",
   "description": "Miru (見る) — hybrid code search for agents. Bun, TypeScript, Takara embeddings.",
   "type": "module",

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)
@@ -159,8 +161,8 @@ export const MCP_LOCATE_TOOL_DESCRIPTION =
   "`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/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/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,
         };