@duckmind/dm-darwin-x64 0.66.5 → 0.66.6

package/extensions/dm-lens/dist/tools/ast-grep-search.js

@@ -0,0 +1,687 @@
+import { Type } from "../clients/deps/typebox.js";
+import { astGrepRemediationHint, classifyAstGrepError, logAstGrepToolEvent } from "../clients/ast-grep-tool-logger.js";
+import { hasStructuralIntent, synthesizeRule } from "../clients/ast-grep-yaml-synth.js";
+import { isAtOrAboveHomeDir } from "../clients/path-utils.js";
+import { compactRenderResult } from "./render-compact.js";
+import { combineAbortSignals } from "../clients/deadline-utils.js";
+import { LANGUAGES, resolveAstGrepPaths } from "./shared.js";
+function errorTextWithHint(raw) {
+  const hint = astGrepRemediationHint(classifyAstGrepError(raw));
+  return hint ? `Error: ${raw}
+
+${hint}` : `Error: ${raw}`;
+}
+export function _telemetryErrorForTest(raw) {
+  if (!raw)
+    return;
+  return raw.replace(/\0/g, "\\0").slice(0, 2000);
+}
+export function _telemetryClassificationErrorForTest(raw) {
+  return raw?.replace(/\0/g, "");
+}
+function toSearchReads(matches) {
+  const out = [];
+  for (const m of matches) {
+    const span = toLineSpan(m);
+    if (!span)
+      continue;
+    out.push({
+      file: span.file,
+      startLine: span.startLine,
+      endLine: span.endLine
+    });
+  }
+  return out;
+}
+const DEFAULT_PAGE_SIZE = 50;
+const MAX_PAGE_SIZE = 200;
+const MAX_PATHS = 200;
+const AST_GREP_SEARCH_TIMEOUT_MS = 30000;
+function formatGroupedByFile(matches) {
+  const byFile = new Map;
+  for (const m of matches) {
+    if (!m.file)
+      continue;
+    const list = byFile.get(m.file);
+    if (list)
+      list.push(m);
+    else
+      byFile.set(m.file, [m]);
+  }
+  const total = matches.length;
+  const fileCount = byFile.size;
+  const lines = [
+    `${fileCount} file${fileCount === 1 ? "" : "s"}, ${total} match${total === 1 ? "" : "es"}:`
+  ];
+  for (const [file, group] of byFile) {
+    const locs = group.map((m) => {
+      const line = (m.range?.start?.line ?? 0) + 1;
+      const col = (m.range?.start?.column ?? 0) + 1;
+      return `L${line}:${col}`;
+    }).join(", ");
+    lines.push(`${file} (${group.length}): ${locs}`);
+  }
+  return lines.join(`
+`);
+}
+const DEFAULT_READ_SLICE_MARGIN = 3;
+const MAX_READ_SLICE_MARGIN = 20;
+const MAX_RAW_RULE_CHARS = 1e5;
+function rawRuleValidationError(rule) {
+  if (rule === undefined)
+    return null;
+  if (rule.includes("\x00"))
+    return "rule contains a NUL byte";
+  if (rule.length > MAX_RAW_RULE_CHARS)
+    return "rule is too long";
+  return null;
+}
+function patternValidationError(pattern) {
+  if (pattern.includes("\x00"))
+    return "pattern contains a NUL byte";
+  if (pattern.length > 4000)
+    return "pattern is too long";
+  return null;
+}
+function toLineSpan(match) {
+  const start = match.range?.start?.line;
+  if (!match.file || typeof start !== "number")
+    return null;
+  const end = match.range?.end?.line;
+  return {
+    file: match.file,
+    startLine: start + 1,
+    endLine: (typeof end === "number" ? end : start) + 1
+  };
+}
+function toMatchLocations(matches, contextLines) {
+  const margin = typeof contextLines === "number" && Number.isFinite(contextLines) ? Math.min(MAX_READ_SLICE_MARGIN, Math.max(0, Math.floor(contextLines))) : DEFAULT_READ_SLICE_MARGIN;
+  const out = [];
+  for (const match of matches) {
+    const span = toLineSpan(match);
+    if (!span)
+      continue;
+    const offset = Math.max(1, span.startLine - margin);
+    out.push({
+      file: span.file,
+      line: span.startLine,
+      endLine: span.endLine,
+      readSlice: {
+        path: span.file,
+        offset,
+        limit: span.endLine - offset + 1 + margin
+      }
+    });
+  }
+  return out;
+}
+function suggestedDump(lang) {
+  return {
+    tool: "ast_grep_search",
+    mode: "dump",
+    lang,
+    note: "Run ast_grep_search with dump=true on a small representative source snippet (not a whole file) to inspect AST node kinds before retrying the search."
+  };
+}
+function lineCount(value) {
+  if (!value)
+    return 0;
+  let lines = 1;
+  for (let i = 0;i < value.length; i++) {
+    if (value.charCodeAt(i) === 10)
+      lines++;
+  }
+  return lines;
+}
+function looksLikeRuleYamlOrPlainText(pattern) {
+  const text = pattern.trim();
+  if (!text)
+    return true;
+  const lower = text.toLowerCase();
+  if (/(^|\n)\s*(id|language|rule|rules|kind|pattern|message|severity)\s*:/.test(lower)) {
+    return true;
+  }
+  if (/\b(id|language|rule|rules|kind|pattern|message|severity)\s*:\s*[a-z0-9_-]+/i.test(text)) {
+    return true;
+  }
+  if (/^[-*]\s+/.test(text))
+    return true;
+  const hasAstSignals = /[$(){}[\].;:'"`]/.test(text);
+  const hasWhitespace = /\s/.test(text);
+  if (hasWhitespace && !hasAstSignals)
+    return true;
+  return false;
+}
+function getPatternHint(pattern, lang, selector) {
+  const src = pattern.trim();
+  if (selector) {
+    return `Hint: selector=${JSON.stringify(selector)} narrows the AST node kind searched; it does not extract fields from matches. Retry once without selector, or use a selector that is the outer node kind you want to match.`;
+  }
+  if (/\\[wWdDsSbB]/.test(src)) {
+    return 'Hint: "\\w", "\\d", "\\s", "\\b" are regex escapes. ast-grep matches AST nodes, not text — use $VAR for identifiers, $$$ for node lists, or switch to grep for text search.';
+  }
+  if (/\[[a-zA-Z0-9]-[a-zA-Z0-9]\]/.test(src)) {
+    return 'Hint: "[a-z]" and similar character classes are regex, not AST. Use $VAR to match any identifier, or switch to grep for text search.';
+  }
+  if (!src.includes("$") && /\w\.[*+]/.test(src)) {
+    return 'Hint: ".*" and ".+" are regex wildcards. In ast-grep use $$$ for multiple AST nodes and $VAR for a single node. For text patterns, switch to grep.';
+  }
+  if (/^[-\w.*]+\|[-\w.*|]+$/.test(src)) {
+    return 'Hint: "|" is regex alternation and does NOT work in ast-grep patterns. Options: (a) fire one ast_grep_search per alternative, or (b) switch to grep with a regex pattern like "foo|bar".';
+  }
+  if (lang === "python") {
+    if ((src.startsWith("def ") || src.startsWith("async def ")) && src.endsWith(":")) {
+      return `Hint: Remove trailing colon from Python patterns. Try: "${src.slice(0, -1)}"`;
+    }
+    if (src.startsWith("class ") && src.endsWith(":")) {
+      return `Hint: Remove trailing colon from class patterns. Try: "${src.slice(0, -1)}"`;
+    }
+  }
+  if (["javascript", "typescript", "tsx"].includes(lang)) {
+    if (/^(export\s+)?(async\s+)?function\s+\$[A-Z_]+\s*$/i.test(src)) {
+      return 'Hint: Function patterns need params and body. Try "function $NAME($$$) { $$$ }"';
+    }
+  }
+  if (lang === "go") {
+    if (/^func\s+\$[A-Z_]+\s*$/i.test(src)) {
+      return 'Hint: Go function patterns need params and body. Try "func $NAME($$$) { $$$ }"';
+    }
+  }
+  if (lang === "rust") {
+    if (/^fn\s+\$[A-Z_]+\s*$/i.test(src)) {
+      return 'Hint: Rust fn patterns need params and body. Try "fn $NAME($$$) { $$$ }"';
+    }
+  }
+  return "Hint: No matches. Retry once with a smaller valid AST pattern scoped to the same paths (for example a call like `foo($$$ARGS)`, an import statement, or `function $NAME($$$ARGS) { $$$BODY }`). If you're actually looking for a name/usage rather than a structural pattern, prefer symbol_search (ranked identifier search) or module_report (file outline) over another AST retry; lsp_navigation findReferences finds exact call sites once you have a definition. If that also fails, use grep for text search, or ast_grep_search with dump=true on a small representative snippet to inspect node kinds.";
+}
+export function astGrepDumpCompatibilityResult(params, surface) {
+  return {
+    content: [
+      {
+        type: "text",
+        text: `The ast_grep_dump tool was retired. Call ${surface === "mcp" ? "dmlens_" : ""}ast_grep_search with dump=true and put the snippet in pattern instead.`
+      }
+    ],
+    isError: true,
+    details: {
+      compatibility: "ast_grep_dump -> ast_grep_search",
+      call: {
+        tool: surface === "mcp" ? "dmlens_ast_grep_search" : "ast_grep_search",
+        arguments: {
+          dump: true,
+          pattern: params.source,
+          lang: params.lang
+        }
+      }
+    }
+  };
+}
+export function createAstGrepSearchTool(astGrepClient) {
+  return {
+    name: "ast_grep_search",
+    label: "AST Search",
+    description: "Search source by AST structure rather than text. Example: find calls with `console.log($MSG)`.",
+    promptSnippet: "Search source by AST structure",
+    renderResult: compactRenderResult(({ details, isError, text }) => {
+      if (details?.validateOnly) {
+        const mode = details.mode ?? "pattern";
+        return details.valid ? `ast_grep_search — valid ${mode}` : `ast_grep_search — invalid ${mode}`;
+      }
+      if (isError) {
+        return `ast_grep_search — ${text.split(`
+`)[0] ?? "error"}`;
+      }
+      const count = details?.matchCount ?? 0;
+      const total = details?.totalMatches;
+      const ofTotal = typeof total === "number" && total > count ? ` of ${total}` : "";
+      const applied = details?.applied ? " (applied)" : "";
+      return `ast_grep_search — ${count}${ofTotal} match${count === 1 && !ofTotal ? "" : "es"}${applied}`;
+    }),
+    parameters: Type.Object({
+      dump: Type.Optional(Type.Boolean()),
+      pattern: Type.Optional(Type.String({ description: "AST pattern." })),
+      lang: Type.String({
+        enum: [...LANGUAGES],
+        description: "Target language"
+      }),
+      paths: Type.Optional(Type.Array(Type.String(), {
+        maxItems: MAX_PATHS,
+        description: "Files or directories to search."
+      })),
+      selector: Type.Optional(Type.String({
+        description: "AST node kind filter."
+      })),
+      context: Type.Optional(Type.Number({
+        description: "Context lines around matches."
+      })),
+      nodeKind: Type.Optional(Type.String({
+        description: "AST node kind without a pattern."
+      })),
+      insideKind: Type.Optional(Type.String({
+        description: "Ancestor AST node kind filter."
+      })),
+      hasKind: Type.Optional(Type.String({
+        description: "Immediate-child AST node kind filter."
+      })),
+      hasDescendantKind: Type.Optional(Type.String({
+        description: "Recursive descendant AST node kind filter."
+      })),
+      follows: Type.Optional(Type.String({
+        description: "Preceding sibling pattern filter."
+      })),
+      precedes: Type.Optional(Type.String({
+        description: "Following sibling pattern filter."
+      })),
+      rule: Type.Optional(Type.String({
+        description: "Raw ast-grep YAML rule."
+      })),
+      skip: Type.Optional(Type.Number({
+        description: "Matches to skip for pagination."
+      })),
+      maxMatches: Type.Optional(Type.Number({
+        description: "Maximum matches to return."
+      })),
+      groupByFile: Type.Optional(Type.Boolean({
+        description: "Group matches by file."
+      })),
+      strictness: Type.Optional(Type.String({
+        enum: ["smart", "relaxed", "ast", "cst", "signature", "template"],
+        description: "Pattern matching strictness."
+      })),
+      validateOnly: Type.Optional(Type.Boolean({
+        description: "Validate without scanning."
+      }))
+    }),
+    async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+      const abortSignal = combineAbortSignals(_signal, ctx.signal);
+      const startedAt = Date.now();
+      const deadlineAt = startedAt + AST_GREP_SEARCH_TIMEOUT_MS;
+      const { paths, nodeKind, selector, context, skip, maxMatches, groupByFile, strictness, rule, insideKind, hasKind, hasDescendantKind, follows, precedes, validateOnly, dump } = params;
+      const pattern = typeof params.pattern === "string" ? params.pattern : "";
+      const rawLang = typeof params.lang === "string" ? params.lang : "";
+      const normalizedNodeKind = typeof nodeKind === "string" ? nodeKind.trim() : "";
+      const skipOffset = Math.max(0, Math.floor(skip ?? 0));
+      const lang = rawLang.replace(/^"|"$/g, "");
+      const searchPathsCount = paths?.length ?? 1;
+      const executionOptions = { signal: abortSignal, deadlineAt };
+      const dumpMode = dump === true;
+      function logOutcome(outcome, details = {}) {
+        try {
+          const errorRaw = _telemetryErrorForTest(details.errorRaw);
+          const classificationError = _telemetryClassificationErrorForTest(details.errorRaw);
+          logAstGrepToolEvent({
+            tool: "ast_grep_search",
+            lang,
+            pattern,
+            patternLineCount: lineCount(pattern),
+            pathsCount: searchPathsCount,
+            outcome,
+            errorKind: outcome === "error" ? classifyAstGrepError(classificationError) : undefined,
+            errorRaw,
+            matchCount: details.matchCount ?? 0,
+            truncated: details.truncated ?? false,
+            durationMs: Date.now() - startedAt
+          });
+        } catch (err) {
+          try {
+            process.emitWarning(`ast_grep_search telemetry failed: ${err}`, {
+              code: "DM_LENS_AST_GREP_SEARCH_TELEMETRY_FAILED"
+            });
+          } catch {}
+        }
+      }
+      function abortError() {
+        logOutcome("error", { errorRaw: "operation aborted" });
+        return {
+          content: [
+            { type: "text", text: "Error: operation aborted" }
+          ],
+          isError: true,
+          details: {}
+        };
+      }
+      try {
+        const rawRule = typeof rule === "string" ? rule : undefined;
+        const hasRawRule = Boolean(rawRule?.trim());
+        const hasPattern = Boolean(pattern.trim());
+        const hasNodeKind = normalizedNodeKind.length > 0;
+        const rawPaths = params.paths;
+        if (rawPaths !== undefined && (!Array.isArray(rawPaths) || rawPaths.length > MAX_PATHS || rawPaths.some((value) => typeof value !== "string"))) {
+          const errorRaw = `paths must contain at most ${MAX_PATHS} string entries`;
+          logOutcome("error", { errorRaw });
+          return {
+            content: [{ type: "text", text: `Error: ${errorRaw}` }],
+            isError: true,
+            details: {}
+          };
+        }
+        const rawRuleError = rawRuleValidationError(rawRule);
+        if (rawRuleError) {
+          logOutcome("error", { errorRaw: rawRuleError });
+          return {
+            content: [
+              { type: "text", text: `Error: ${rawRuleError}` }
+            ],
+            isError: true,
+            details: {}
+          };
+        }
+        if (!dumpMode && !hasPattern && !hasRawRule && !hasNodeKind) {
+          logOutcome("error", {
+            errorRaw: "pattern is required unless rule or nodeKind is provided"
+          });
+          return {
+            content: [
+              {
+                type: "text",
+                text: "Error: pattern is required unless rule or nodeKind is provided"
+              }
+            ],
+            isError: true,
+            details: {}
+          };
+        }
+        const patternError = patternValidationError(pattern);
+        if (pattern.trim() && patternError) {
+          logOutcome("error", { errorRaw: patternError });
+          return {
+            content: [
+              { type: "text", text: `Error: ${patternError}` }
+            ],
+            isError: true,
+            details: {}
+          };
+        }
+        if (!lang.trim()) {
+          logOutcome("error", { errorRaw: "lang is required" });
+          return {
+            content: [
+              { type: "text", text: "Error: lang is required" }
+            ],
+            isError: true,
+            details: {}
+          };
+        }
+        if (abortSignal?.aborted)
+          return abortError();
+        if (!await astGrepClient.ensureAvailable()) {
+          logOutcome("error", {
+            errorRaw: "ast-grep CLI not found"
+          });
+          return {
+            content: [
+              {
+                type: "text",
+                text: "ast-grep CLI not found. Install: npm i -D @ast-grep/cli"
+              }
+            ],
+            isError: true,
+            details: {}
+          };
+        }
+        if (abortSignal?.aborted)
+          return abortError();
+        if (dumpMode) {
+          if (!pattern.trim()) {
+            const errorRaw = "source is required when dump is true";
+            logOutcome("error", { errorRaw });
+            return {
+              content: [{ type: "text", text: `Error: ${errorRaw}` }],
+              isError: true,
+              details: { mode: "dump", lang }
+            };
+          }
+          const result = await astGrepClient.dumpAst(pattern, lang);
+          if (result.error) {
+            logOutcome("error", { errorRaw: result.error });
+            return {
+              content: [
+                { type: "text", text: `Error: ${result.error}` }
+              ],
+              isError: true,
+              details: { mode: "dump", lang }
+            };
+          }
+          const output = result.output ?? "";
+          logOutcome("success", { matchCount: lineCount(output) });
+          return {
+            content: [{ type: "text", text: output }],
+            details: {
+              mode: "dump",
+              lang,
+              matchCount: lineCount(output),
+              totalMatches: lineCount(output),
+              truncated: false
+            }
+          };
+        }
+        if (!hasRawRule && hasPattern && looksLikeRuleYamlOrPlainText(pattern)) {
+          logOutcome("error", {
+            errorRaw: "pattern looks like rule YAML or plain text (rejected pre-spawn)"
+          });
+          return {
+            content: [
+              {
+                type: "text",
+                text: "Error: ast_grep_search expects a valid AST code pattern, not plain text/rule YAML. Use patterns like `function $NAME($$$ARGS) { $$$BODY }` or use grep/read for plain text diagnostics."
+              }
+            ],
+            isError: true,
+            details: {}
+          };
+        }
+        if (!paths?.length && isAtOrAboveHomeDir(ctx.cwd || ".")) {
+          logOutcome("error", {
+            errorRaw: "defaulted cwd resolves at or above home directory"
+          });
+          return {
+            content: [
+              {
+                type: "text",
+                text: `Refused: no \`paths\` given and the working directory (${ctx.cwd || "."}) resolves at or above the home directory — searching it would scan every unrelated tree under your home. Pass explicit \`paths\`, or run from a project directory.`
+              }
+            ],
+            isError: true,
+            details: {}
+          };
+        }
+        if (hasNodeKind && hasPattern) {
+          const errorRaw = "nodeKind cannot be combined with pattern";
+          logOutcome("error", { errorRaw });
+          return {
+            content: [{ type: "text", text: `Error: ${errorRaw}` }],
+            isError: true,
+            details: {}
+          };
+        }
+        if (hasNodeKind && hasRawRule) {
+          const errorRaw = "nodeKind cannot be combined with rule";
+          logOutcome("error", { errorRaw });
+          return {
+            content: [{ type: "text", text: `Error: ${errorRaw}` }],
+            isError: true,
+            details: {}
+          };
+        }
+        const searchPaths = resolveAstGrepPaths(paths, ctx.cwd);
+        const PAGE_SIZE = Math.max(1, Math.min(MAX_PAGE_SIZE, Number.isFinite(maxMatches) ? Math.floor(maxMatches) : DEFAULT_PAGE_SIZE));
+        let effectiveRule = hasRawRule ? rawRule : undefined;
+        if (!effectiveRule && (hasNodeKind || hasStructuralIntent({
+          nodeKind: normalizedNodeKind,
+          insideKind,
+          hasKind,
+          hasDescendantKind,
+          follows,
+          precedes
+        }))) {
+          try {
+            effectiveRule = synthesizeRule({
+              pattern: hasPattern ? pattern : undefined,
+              nodeKind: hasNodeKind ? normalizedNodeKind : undefined,
+              lang,
+              insideKind,
+              hasKind,
+              hasDescendantKind,
+              follows,
+              precedes
+            });
+          } catch (err) {
+            logOutcome("error", { errorRaw: String(err) });
+            return {
+              content: [
+                {
+                  type: "text",
+                  text: `Error synthesizing rule: ${err}`
+                }
+              ],
+              isError: true,
+              details: {}
+            };
+          }
+        }
+        if (validateOnly) {
+          const validation = effectiveRule?.trim() ? await astGrepClient.validateRule(effectiveRule, executionOptions) : await astGrepClient.validatePattern(pattern, lang, {
+            selector,
+            strictness,
+            ...executionOptions
+          });
+          if (!validation.valid) {
+            logOutcome("error", { errorRaw: validation.error });
+            return {
+              content: [
+                {
+                  type: "text",
+                  text: `Invalid ast-grep ${effectiveRule ? "rule" : "pattern"}: ${validation.error ?? "unknown error"}`
+                }
+              ],
+              isError: true,
+              details: { valid: false, validateOnly: true }
+            };
+          }
+          logOutcome("success", { matchCount: 0 });
+          const warning = "warning" in validation ? validation.warning : undefined;
+          return {
+            content: [
+              {
+                type: "text",
+                text: `Valid ast-grep ${effectiveRule ? "rule" : "pattern"}.${warning ? ` Warning: ${warning}` : ""}`
+              }
+            ],
+            details: {
+              valid: true,
+              validateOnly: true,
+              mode: effectiveRule ? "rule" : "pattern",
+              ...warning ? { warning } : {}
+            }
+          };
+        }
+        if (effectiveRule && effectiveRule.trim().length > 0) {
+          if (abortSignal?.aborted)
+            return abortError();
+          const ruleResult = await astGrepClient.searchWithRule(effectiveRule, searchPaths, executionOptions);
+          if (abortSignal?.aborted)
+            return abortError();
+          if (ruleResult.error) {
+            logOutcome("error", { errorRaw: ruleResult.error });
+            return {
+              content: [
+                {
+                  type: "text",
+                  text: errorTextWithHint(ruleResult.error)
+                }
+              ],
+              isError: true,
+              details: {}
+            };
+          }
+          const afterSkip = ruleResult.matches.slice(skipOffset);
+          const page = afterSkip.slice(0, PAGE_SIZE);
+          const hasMore = afterSkip.length > PAGE_SIZE;
+          const output = groupByFile ? formatGroupedByFile(page) : astGrepClient.formatMatches(page, false, false, PAGE_SIZE);
+          const paginationNote = hasMore && page.length > 0 ? `
+
+(Showing ${page.length} of ${ruleResult.matches.length - skipOffset} remaining matches. Use skip=${skipOffset + PAGE_SIZE} for the next page.)` : "";
+          logOutcome(page.length === 0 ? "no_matches" : "success", {
+            matchCount: page.length,
+            truncated: hasMore
+          });
+          const matchLocations = toMatchLocations(page, context);
+          return {
+            content: [
+              { type: "text", text: `${output}${paginationNote}` }
+            ],
+            details: {
+              matchCount: page.length,
+              totalMatches: ruleResult.totalMatches,
+              truncated: hasMore,
+              hasMore,
+              skip: skipOffset,
+              groupByFile: groupByFile === true,
+              searchReads: toSearchReads(page),
+              matchLocations,
+              suggestedDump: page.length === 0 ? suggestedDump(lang) : undefined
+            }
+          };
+        }
+        if (abortSignal?.aborted)
+          return abortError();
+        const result = await astGrepClient.search(pattern, lang, searchPaths, {
+          selector,
+          context,
+          strictness,
+          ...executionOptions
+        });
+        if (abortSignal?.aborted)
+          return abortError();
+        if (result.error) {
+          logOutcome("error", { errorRaw: result.error });
+          return {
+            content: [
+              { type: "text", text: errorTextWithHint(result.error) }
+            ],
+            isError: true,
+            details: {}
+          };
+        }
+        const afterSkip = result.matches.slice(skipOffset);
+        const page = afterSkip.slice(0, PAGE_SIZE);
+        const hasMore = afterSkip.length > PAGE_SIZE || result.truncated;
+        const output = groupByFile ? formatGroupedByFile(page) : astGrepClient.formatMatches(page, false, false, PAGE_SIZE);
+        const hint = page.length === 0 && !result.error ? getPatternHint(pattern, lang, selector) : undefined;
+        const paginationNote = hasMore && page.length > 0 ? `
+
+(Showing ${page.length} of ${result.matches.length - skipOffset} remaining matches. Use skip=${skipOffset + PAGE_SIZE} for the next page.)` : "";
+        const finalOutput = hint ? `${output}
+
+${hint}` : `${output}${paginationNote}`;
+        logOutcome(page.length === 0 ? "no_matches" : "success", {
+          matchCount: page.length,
+          truncated: hasMore
+        });
+        const matchLocations = toMatchLocations(page, context);
+        return {
+          content: [{ type: "text", text: finalOutput }],
+          details: {
+            matchCount: page.length,
+            totalMatches: result.matches.length,
+            truncated: hasMore,
+            hasMore,
+            skip: skipOffset,
+            groupByFile: groupByFile === true,
+            searchReads: toSearchReads(page),
+            matchLocations,
+            suggestedDump: page.length === 0 ? suggestedDump(lang) : undefined
+          }
+        };
+      } catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        logOutcome("error", { errorRaw: message });
+        return {
+          content: [{ type: "text", text: `Error: ${message}` }],
+          isError: true,
+          details: {}
+        };
+      }
+    }
+  };
+}