@duckmind/dm-linux-x64 0.66.0 → 0.66.2

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

@@ -1,687 +0,0 @@
-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 } 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 = paths?.length ? 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: {}
-        };
-      }
-    }
-  };
-}