@mrclrchtr/supi-code-intelligence 0.2.0 → 1.1.3

package/node_modules/@mrclrchtr/supi-tree-sitter/README.md

@@ -1,97 +1,65 @@
 # @mrclrchtr/supi-tree-sitter
 
-Tree-sitter structural analysis for the [pi coding agent](https://github.com/earendil-works/pi).
+Structural code analysis for PI — your agent parses code, not just text.
 
-This package registers a `tree_sitter` tool and also exports a small TypeScript service API for other SuPi extensions. It is designed as a standalone structural-analysis substrate: it does not depend on `supi-lsp` or semantic language-server tooling, and it remains correct and useful when installed by itself.
+Grep matches strings. Tree-sitter parses structure — functions, classes, imports, call chains. The agent stops pattern-matching and starts understanding your code.
 
-## Install
+## What you get
 
-```bash
-pi install npm:@mrclrchtr/supi-tree-sitter
-```
+### See code structure
 
-Standalone installs include the runtime grammar dependencies needed for the supported non-vendored languages. Kotlin and SQL use vendored WASM grammars bundled with this package.
+Extract functions, classes, interfaces, and methods from any file. The agent knows what lives where without reading every line.
 
-It is also bundled by the full SuPi meta-package:
+### Trace call chains
 
-```bash
-pi install npm:@mrclrchtr/supi
-```
+Find every function call from a given location. The agent follows the code's actual shape instead of guessing from text proximity.
 
-## Supported files
+### 14 languages
 
-The runtime can parse these file families:
+JavaScript, TypeScript, Python, Rust, Go, C, C++, Java, Kotlin, Ruby, Bash, HTML, R, SQL — get structural analysis for every project you touch.
 
-- **JavaScript / TypeScript** — `.ts`, `.tsx`, `.mts`, `.cts`, `.js`, `.jsx`, `.mjs`, `.cjs`
-- **Python** — `.py`, `.pyi`
-- **Rust** — `.rs`
-- **Go** — `.go`, `.mod`
-- **C / C++** — `.c`, `.h`, `.cpp`, `.hpp`, `.cc`, `.cxx`, `.hxx`, `.c++`, `.h++`
-- **Java** — `.java`
-- **Kotlin** — `.kt`, `.kts`
-- **Ruby** — `.rb`
-- **Bash / Shell** — `.sh`, `.bash`, `.zsh`
-- **HTML** — `.html`, `.htm`, `.xhtml`
-- **R** — `.r`
-- **SQL** — `.sql`
+Works standalone or alongside LSP. Grammar files are vendored — no native toolchain required at install time.
+
+## Install
 
-Grammar `.wasm` files are resolved from installed package metadata for npm-shipped grammars, not from repository-relative paths.
+```bash
+pi install npm:@mrclrchtr/supi-tree-sitter
+```
 
-## `tree_sitter` tool
+## Quick look
 
-Actions:
+The agent gets a `tree_sitter` tool with these actions:
 
-- `outline` — list structural declarations such as functions, classes, interfaces, methods, and variables (**currently JavaScript / TypeScript only**)
-- `imports` — list import statements and module specifiers (**currently JavaScript / TypeScript only**)
-- `exports` — list exported declarations, re-exports, and TypeScript `export =` assignments (**currently JavaScript / TypeScript only**)
-- `node_at` — return the smallest syntax node at a 1-based `line`/`character` position, plus ancestry (all supported grammars)
-- `query` — run a custom Tree-sitter query and return captures (all supported grammars)
-- `callees` — find outgoing function/method calls from a position; supports all grammars with a callee query configured
+| Action | What it does |
+|--------|-------------|
+| `outline` | List functions, classes, interfaces in a file |
+| `callees` | Find all function calls from a position |
+| `imports` / `exports` | See what a file imports and exports |
+| `node_at` | Inspect the AST node at any line/column |
+| `query` | Run a custom Tree-sitter query |
 
-Coordinates are 1-based and compatible with the `lsp` tool. `character` is a UTF-16 code-unit column. Relative file paths resolve from the pi session working directory.
+`outline`, `imports`, and `exports` are currently JavaScript/TypeScript only. `node_at`, `query`, and `callees` work across all 14 supported languages. Coordinates are 1-based, matching the `lsp` tool convention.
 
-Large result sets are capped at 100 emitted items per tool response. For outlines, nested children count toward the same cap so deeply nested classes do not bypass the limit.
+## For extension developers
 
-## Service API
+This package exports a reusable session-scoped parsing service:
 
 ```ts
 import { createTreeSitterSession } from "@mrclrchtr/supi-tree-sitter";
 
-const session = createTreeSitterSession(process.cwd());
-try {
-  const parseable = await session.canParse("src/index.ts");
-  if (parseable.kind === "success") {
-    console.log(parseable.data.file, parseable.data.language);
-  }
-
-  const outline = await session.outline("src/index.ts");
-  if (outline.kind === "success") {
-    console.log(outline.data);
-  }
-
-  const callees = await session.calleesAt("src/index.ts", 1, 10);
-  if (callees.kind === "success") {
-    console.log(callees.data.enclosingScope.name, callees.data.callees);
-  }
-} finally {
-  session.dispose();
-}
-```
-
-`canParse(file)` validates that a supported file can be read and parsed, then returns the resolved file path and grammar id. It does not expose the raw Tree-sitter tree; use `outline`, `query`, `imports`, `exports`, `nodeAt`, or `calleesAt` for structured results.
-
-`calleesAt(file, line, character)` extracts structural outgoing calls from the enclosing function/method scope at the given position. It returns the enclosing scope name and a deduplicated list of callees with their source ranges.
+const session = createTreeSitterSession("/project");
 
-Exported types include `TreeSitterResult`, `TreeSitterSession`, `OutlineItem`, `ImportRecord`, `ExportRecord`, `NodeAtResult`, `QueryCapture`, `CalleesAtResult`, `SourceRange`, `GrammarId`, and `SupportedExtension`.
+// Check if a file is parseable
+const result = await session.canParse("src/index.ts");
 
-Always call `dispose()` when the session is no longer needed. The runtime lazily initializes grammars, reuses parser instances within a session, deduplicates concurrent first-use grammar initialization, and retries after initialization failures.
+// Get structural outline
+const outline = await session.outline("src/index.ts");
 
-## Positioning
+// Trace outgoing calls from a position
+const callees = await session.calleesAt("src/index.ts", 42, 10);
 
-`supi-tree-sitter` is the structural-analysis substrate in SuPi's layered code-understanding stack:
-
-- `supi-tree-sitter` — parser-backed structural analysis (this package)
-- `supi-lsp` — live semantic analysis through language servers
-- `supi-code-intelligence` — higher-level agent-facing analysis built on top of both substrates
+// Always clean up
+session.dispose();
+```
 
-Each substrate can be installed and used independently. `supi-tree-sitter` does not require `supi-lsp` to be present, and its prompt guidance is written so it remains correct in standalone installs.
+Import from the package root. No internal imports needed. Call `dispose()` when done.

package/node_modules/@mrclrchtr/supi-tree-sitter/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mrclrchtr/supi-tree-sitter",
-  "version": "1.0.0",
+  "version": "1.1.3",
   "description": "SuPi Tree-sitter extension — structural AST analysis for pi",
   "license": "MIT",
   "repository": {
@@ -22,14 +22,6 @@
     "scripts/*.mjs",
     "!__tests__"
   ],
-  "scripts": {
-    "vendor:wasm": "node scripts/vendor-wasm.mjs",
-    "check:wasm": "node scripts/vendor-wasm.mjs --check",
-    "generate:kotlin-wasm": "node scripts/generate-kotlin-wasm.mjs",
-    "check:kotlin-wasm": "node scripts/generate-kotlin-wasm.mjs --check",
-    "generate:sql-wasm": "node scripts/generate-sql-wasm.mjs",
-    "check:sql-wasm": "node scripts/generate-sql-wasm.mjs --check"
-  },
   "dependencies": {
     "web-tree-sitter": "^0.26.8"
   },
@@ -38,30 +30,29 @@
     "@earendil-works/pi-coding-agent": "*",
     "typebox": "*"
   },
-  "devDependencies": {
-    "@davisvaughan/tree-sitter-r": "1.2.0",
-    "@derekstride/tree-sitter-sql": "0.3.11",
-    "@types/node": "25.6.2",
-    "tree-sitter-bash": "0.25.1",
-    "tree-sitter-c": "0.24.1",
-    "tree-sitter-cli": "0.26.8",
-    "tree-sitter-cpp": "0.23.4",
-    "tree-sitter-go": "0.25.0",
-    "tree-sitter-html": "0.23.2",
-    "tree-sitter-java": "0.23.5",
-    "tree-sitter-javascript": "0.25.0",
-    "tree-sitter-kotlin": "0.3.8",
-    "tree-sitter-python": "0.25.0",
-    "tree-sitter-ruby": "0.23.1",
-    "tree-sitter-rust": "0.24.0",
-    "tree-sitter-typescript": "0.23.2",
-    "vitest": "4.1.5",
-    "@mrclrchtr/supi-test-utils": "workspace:*"
+  "peerDependenciesMeta": {
+    "@earendil-works/pi-ai": {
+      "optional": true
+    },
+    "@earendil-works/pi-coding-agent": {
+      "optional": true
+    },
+    "typebox": {
+      "optional": true
+    }
   },
   "pi": {
     "extensions": [
       "./src/tree-sitter.ts"
     ]
   },
-  "main": "src/index.ts"
+  "main": "src/index.ts",
+  "scripts": {
+    "vendor:wasm": "node scripts/vendor-wasm.mjs",
+    "check:wasm": "node scripts/vendor-wasm.mjs --check",
+    "generate:kotlin-wasm": "node scripts/generate-kotlin-wasm.mjs",
+    "check:kotlin-wasm": "node scripts/generate-kotlin-wasm.mjs --check",
+    "generate:sql-wasm": "node scripts/generate-sql-wasm.mjs",
+    "check:sql-wasm": "node scripts/generate-sql-wasm.mjs --check"
+  }
 }

package/node_modules/@mrclrchtr/supi-tree-sitter/src/runtime.ts

@@ -158,6 +158,12 @@ export class TreeSitterRuntime {
     if (!queryString || queryString.trim().length === 0) {
       return { kind: "validation-error", message: "query is required and must be non-empty" };
     }
+    if (queryString.length > MAX_QUERY_LENGTH) {
+      return {
+        kind: "validation-error",
+        message: `query exceeds maximum length of ${MAX_QUERY_LENGTH} characters`,
+      };
+    }
 
     const parseResult = await this.parseFile(filePath);
     if (parseResult.kind !== "success") return parseResult;
@@ -229,6 +235,9 @@ export class TreeSitterRuntime {
   }
 }
 
+/** Max query string length to prevent ReDoS via overly complex Tree-sitter patterns. */
+const MAX_QUERY_LENGTH = 10_000;
+
 /** Format errors with their cause chain's first message for user-facing tool output. */
 function formatError(err: unknown, fallback = "Operation failed"): string {
   if (!(err instanceof Error)) return String(err || fallback);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mrclrchtr/supi-code-intelligence",
-  "version": "0.2.0",
+  "version": "1.1.3",
   "description": "SuPi Code Intelligence extension — architecture briefs, caller/callee analysis, impact assessment, and pattern search for pi",
   "license": "MIT",
   "repository": {
@@ -19,9 +19,9 @@
     "src/**/*.ts"
   ],
   "dependencies": {
-    "@mrclrchtr/supi-core": "workspace:*",
-    "@mrclrchtr/supi-lsp": "workspace:*",
-    "@mrclrchtr/supi-tree-sitter": "workspace:*"
+    "@mrclrchtr/supi-core": "1.1.3",
+    "@mrclrchtr/supi-lsp": "1.1.3",
+    "@mrclrchtr/supi-tree-sitter": "1.1.3"
   },
   "bundledDependencies": [
     "@mrclrchtr/supi-core",
@@ -33,10 +33,16 @@
     "@earendil-works/pi-coding-agent": "*",
     "typebox": "*"
   },
-  "devDependencies": {
-    "@types/node": "25.6.2",
-    "vitest": "4.1.5",
-    "@mrclrchtr/supi-test-utils": "workspace:*"
+  "peerDependenciesMeta": {
+    "@earendil-works/pi-ai": {
+      "optional": true
+    },
+    "@earendil-works/pi-coding-agent": {
+      "optional": true
+    },
+    "typebox": {
+      "optional": true
+    }
   },
   "pi": {
     "extensions": [

package/src/actions/affected-action.ts

@@ -1,8 +1,13 @@
 // Affected action — blast-radius analysis for a symbol change.
+// biome-ignore-all lint/nursery/noExcessiveLinesPerFile: file-level and single-target affected flows share helpers to keep the blast-radius logic in one place
 
 import * as path from "node:path";
 import { getSessionLspService } from "@mrclrchtr/supi-lsp";
 import { buildArchitectureModel, findModuleForPath, getDependents } from "../architecture.ts";
+import {
+  appendPrioritySignalsSection,
+  summarizePrioritySignalsForFiles,
+} from "../prioritization-signals.ts";
 import { resolveTarget } from "../resolve-target.ts";
 import {
   escapeRegex,
@@ -12,6 +17,12 @@ import {
   runRipgrep,
   uriToFile,
 } from "../search-helpers.ts";
+import {
+  dedupeFileLineRefs,
+  highestConfidence,
+  isResolvedTargetGroup,
+} from "../semantic-action-helpers.ts";
+import type { ResolvedTarget, ResolvedTargetGroup } from "../target-resolution.ts";
 import type { ActionParams } from "../tool-actions.ts";
 import type { AffectedDetails, CodeIntelResult, ConfidenceMode } from "../types.ts";
 
@@ -39,14 +50,46 @@ export async function executeAffectedAction(
     };
   }
 
-  const relPath = path.relative(cwd, target.file);
-  const symbolName = target.name ?? `symbol at ${relPath}:${target.displayLine}`;
+  if (isResolvedTargetGroup(target)) {
+    return executeFileLevelAffected(target, params, cwd);
+  }
+
+  const symbolName =
+    target.name ?? `symbol at ${path.relative(cwd, target.file)}:${target.displayLine}`;
+  return executeSingleAffected(target, symbolName, params, cwd);
+}
+
+interface GatheredRef {
+  file: string;
+  line: number;
+}
+
+interface ImpactAnalysis {
+  confidence: ConfidenceMode;
+  affectedFiles: Set<string>;
+  affectedModules: Set<string>;
+  downstreamCount: number;
+  checkNext: string[];
+  likelyTests: string[];
+  riskLevel: "low" | "medium" | "high";
+  externalRefs: number;
+}
 
+async function executeSingleAffected(
+  target: ResolvedTarget,
+  symbolName: string,
+  params: ActionParams,
+  cwd: string,
+): Promise<CodeIntelResult> {
   const refs = await gatherReferences(target, params, cwd);
   const model = await buildArchitectureModel(cwd);
   const analysis = analyzeImpact(refs, model, target.name, cwd);
 
-  const content = formatAffectedOutput(symbolName, refs, analysis, params);
+  const prioritySignals = summarizePrioritySignalsForFiles(
+    cwd,
+    analysis.affectedFiles.size > 0 ? [...analysis.affectedFiles] : [target.file],
+  );
+  const content = formatAffectedOutput(symbolName, refs, analysis, params, prioritySignals);
   const details: AffectedDetails = {
     confidence: analysis.confidence,
     directCount: refs.refs.length,
@@ -54,35 +97,94 @@ export async function executeAffectedAction(
     riskLevel: analysis.riskLevel,
     checkNext: analysis.checkNext,
     likelyTests: analysis.likelyTests,
-    omittedCount:
-      analysis.externalRefs + (analysis.affectedFiles.size > (params.maxResults ?? 8) ? 1 : 0),
+    omittedCount: computeOmittedCount(analysis.externalRefs, analysis.affectedFiles.size, params),
     nextQueries: [
       "`code_intel brief` on the most-affected module for deeper context",
       `\`code_intel callers\` with \`symbol: "${symbolName}"\` for grouped call-site detail`,
     ],
+    prioritySignals,
   };
   return { content, details: { type: "affected" as const, data: details } };
 }
 
-interface GatheredRef {
-  file: string;
-  line: number;
-}
+async function executeFileLevelAffected(
+  targetGroup: ResolvedTargetGroup,
+  params: ActionParams,
+  cwd: string,
+): Promise<CodeIntelResult> {
+  const perTarget = await Promise.all(
+    targetGroup.targets.map(async (target) => ({
+      target,
+      refs: await gatherReferences(target, params, cwd),
+    })),
+  );
 
-interface ImpactAnalysis {
-  confidence: ConfidenceMode;
-  affectedFiles: Set<string>;
-  affectedModules: Set<string>;
-  downstreamCount: number;
-  checkNext: string[];
-  likelyTests: string[];
-  riskLevel: "low" | "medium" | "high";
-  externalRefs: number;
+  const combinedRefs = dedupeFileLineRefs(perTarget.flatMap((entry) => entry.refs.refs));
+  const combinedExternal = perTarget.reduce((sum, entry) => sum + entry.refs.externalCount, 0);
+  const combinedConfidence = highestConfidence(perTarget.map((entry) => entry.refs.confidence));
+  const model = await buildArchitectureModel(cwd);
+  const analysis = analyzeImpact(
+    { refs: combinedRefs, confidence: combinedConfidence, externalCount: combinedExternal },
+    model,
+    null,
+    cwd,
+  );
+
+  const prioritySignals = summarizePrioritySignalsForFiles(
+    cwd,
+    analysis.affectedFiles.size > 0 ? [...analysis.affectedFiles] : [targetGroup.file],
+  );
+
+  const lines: string[] = [];
+  lines.push(`# Affected: \`${targetGroup.displayName}\``);
+  lines.push("");
+  const totalRefs = combinedRefs.length + combinedExternal;
+  const refSummary =
+    combinedExternal > 0
+      ? `${totalRefs} refs (${combinedRefs.length} direct + ${combinedExternal} external)`
+      : `${totalRefs} ref${totalRefs !== 1 ? "s" : ""}`;
+  lines.push(formatFileLevelAffectedHeader(targetGroup.targets.length, refSummary, analysis));
+  lines.push("");
+
+  lines.push("## Exported Targets");
+  for (const entry of perTarget) {
+    lines.push(
+      `- \`${entry.target.name ?? "symbol"}\` — ${entry.refs.refs.length} ref${entry.refs.refs.length !== 1 ? "s" : ""}`,
+    );
+  }
+  lines.push("");
+
+  addRiskSection(lines, analysis, totalRefs);
+  addReferencesSection(lines, combinedRefs, params.maxResults ?? 8);
+  appendPrioritySignalsSection(lines, prioritySignals);
+  addCheckNextSection(lines, analysis.checkNext);
+  addTestsSection(lines, analysis.likelyTests);
+  lines.push("## Next");
+  lines.push("- `code_intel brief` on the most-affected module for deeper context");
+  lines.push("- Use `file` + coordinates to inspect one exported target precisely");
+  lines.push("");
+
+  const details: AffectedDetails = {
+    confidence: analysis.confidence,
+    directCount: combinedRefs.length,
+    downstreamCount: analysis.downstreamCount,
+    riskLevel: analysis.riskLevel,
+    checkNext: analysis.checkNext,
+    likelyTests: analysis.likelyTests,
+    omittedCount: computeOmittedCount(analysis.externalRefs, analysis.affectedFiles.size, params),
+    nextQueries: [
+      "`code_intel brief` on the most-affected module for deeper context",
+      "Use `file` + coordinates to inspect one exported target precisely",
+    ],
+    prioritySignals,
+  };
+
+  return { content: lines.join("\n"), details: { type: "affected" as const, data: details } };
 }
 
 // biome-ignore lint/complexity/noExcessiveCognitiveComplexity: multi-source reference gathering with fallback logic
 async function gatherReferences(
-  target: { file: string; position: { line: number; character: number }; name: string | null },
+  target: ResolvedTarget,
   params: ActionParams,
   cwd: string,
 ): Promise<{ refs: GatheredRef[]; confidence: ConfidenceMode; externalCount: number }> {
@@ -93,8 +195,6 @@ async function gatherReferences(
   if (lspState.kind === "ready") {
     const lspRefs = await lspState.service.references(target.file, target.position);
     if (lspRefs && lspRefs.length > 0) {
-      // Filter out the declaration itself — LSP includes it with includeDeclaration.
-      // The declaration is the symbol being changed, not something affected by the change.
       const filtered = filterOutDeclaration(lspRefs, target.file, target.position);
       for (const ref of filtered) {
         const filePath = uriToFile(ref.uri);
@@ -113,7 +213,9 @@ async function gatherReferences(
     const pattern = `\\b${escapeRegex(target.name)}\\b`;
     const matches = runRipgrep(pattern, scopePath, cwd, { maxMatches: 30 });
     for (const m of matches) {
-      refs.push({ file: m.file, line: m.line });
+      if (!isDeclarationMatch(m.file, m.line, target, cwd)) {
+        refs.push({ file: path.relative(cwd, path.resolve(cwd, m.file)), line: m.line });
+      }
     }
     return { refs, confidence: "heuristic", externalCount: 0 };
   }
@@ -139,7 +241,6 @@ function analyzeImpact(
       if (mod) affectedModules.add(mod.name);
     }
 
-    // Transitive downstream: BFS to find all modules reachable through dependents
     const downstreamModules = new Set<string>();
     const queue = [...affectedModules];
     while (queue.length > 0) {
@@ -195,11 +296,13 @@ function assessRisk(
   return "low";
 }
 
+// biome-ignore lint/complexity/useMaxParams: affected formatting keeps related inputs explicit for readability
 function formatAffectedOutput(
   symbolName: string,
   result: { refs: GatheredRef[]; confidence: ConfidenceMode; externalCount: number },
   analysis: ImpactAnalysis,
   params: ActionParams,
+  prioritySignals: import("../prioritization-signals.ts").PrioritySignalsSummary | null,
 ): string {
   const totalRefs = result.refs.length + analysis.externalRefs;
   const lines: string[] = [];
@@ -215,13 +318,14 @@ function formatAffectedOutput(
   );
   if (analysis.externalRefs > 0) {
     lines.push(
-      `_External references are not listed individually (node_modules, .pnpm, or out-of-tree)_`,
+      "_External references are not listed individually (node_modules, .pnpm, or out-of-tree)_",
     );
   }
   lines.push("");
 
   addRiskSection(lines, analysis, totalRefs);
   addReferencesSection(lines, result.refs, params.maxResults ?? 8);
+  appendPrioritySignalsSection(lines, prioritySignals);
   addCheckNextSection(lines, analysis.checkNext);
   addTestsSection(lines, analysis.likelyTests);
   addAffectedNextQueries(lines, symbolName, analysis);
@@ -294,6 +398,22 @@ function addTestsSection(lines: string[], tests: string[]): void {
   lines.push("");
 }
 
+function computeOmittedCount(
+  externalRefs: number,
+  affectedFileCount: number,
+  params: ActionParams,
+): number {
+  return externalRefs + Math.max(0, affectedFileCount - (params.maxResults ?? 8));
+}
+
+function formatFileLevelAffectedHeader(
+  targetCount: number,
+  refSummary: string,
+  analysis: ImpactAnalysis,
+): string {
+  return `**Risk: ${analysis.riskLevel.toUpperCase()}** | ${targetCount} exported target${targetCount !== 1 ? "s" : ""} | ${refSummary} | ${analysis.affectedFiles.size} file${analysis.affectedFiles.size !== 1 ? "s" : ""} | ${analysis.affectedModules.size} module${analysis.affectedModules.size !== 1 ? "s" : ""} | ${analysis.downstreamCount} downstream (${analysis.confidence})`;
+}
+
 function addAffectedNextQueries(
   lines: string[],
   symbolName: string,
@@ -308,3 +428,12 @@ function addAffectedNextQueries(
   );
   lines.push("");
 }
+
+function isDeclarationMatch(
+  file: string,
+  line: number,
+  target: ResolvedTarget,
+  cwd: string,
+): boolean {
+  return path.resolve(cwd, file) === target.file && line === target.displayLine;
+}

package/src/actions/callees-action.ts

@@ -5,6 +5,7 @@
 import * as path from "node:path";
 import { createTreeSitterSession } from "@mrclrchtr/supi-tree-sitter";
 import { resolveTarget } from "../resolve-target.ts";
+import { isResolvedTargetGroup } from "../semantic-action-helpers.ts";
 import type { ActionParams } from "../tool-actions.ts";
 import type { CodeIntelResult, SearchDetails } from "../types.ts";
 
@@ -29,6 +30,22 @@ export async function executeCalleesAction(
     };
   }
 
+  if (isResolvedTargetGroup(target)) {
+    return {
+      content: `**Error:** File-level callee discovery is not available for \`${path.relative(cwd, target.file)}\`.\n\nProvide \`line\` and \`character\`, or a \`symbol\` for discovery.`,
+      details: {
+        type: "search" as const,
+        data: {
+          confidence: "unavailable",
+          scope: params.path ?? null,
+          candidateCount: 0,
+          omittedCount: 0,
+          nextQueries: ["Use `file` + coordinates or `symbol` for callee lookup"],
+        },
+      },
+    };
+  }
+
   const relPath = path.relative(cwd, target.file);
   let tsSession: ReturnType<typeof createTreeSitterSession> | null = null;