@mrclrchtr/supi-code-intelligence 0.1.0

package/src/actions/affected-action.ts

@@ -0,0 +1,310 @@
+// Affected action — blast-radius analysis for a symbol change.
+
+import * as path from "node:path";
+import { getSessionLspService } from "@mrclrchtr/supi-lsp";
+import { buildArchitectureModel, findModuleForPath, getDependents } from "../architecture.ts";
+import { resolveTarget } from "../resolve-target.ts";
+import {
+  escapeRegex,
+  filterOutDeclaration,
+  isInProjectPath,
+  normalizePath,
+  runRipgrep,
+  uriToFile,
+} from "../search-helpers.ts";
+import type { ActionParams } from "../tool-actions.ts";
+import type { AffectedDetails, CodeIntelResult, ConfidenceMode } from "../types.ts";
+
+export async function executeAffectedAction(
+  params: ActionParams,
+  cwd: string,
+): Promise<CodeIntelResult> {
+  const target = await resolveTarget(params, cwd);
+  if (typeof target === "string") {
+    return {
+      content: target,
+      details: {
+        type: "affected" as const,
+        data: {
+          confidence: "unavailable",
+          directCount: 0,
+          downstreamCount: 0,
+          riskLevel: "low",
+          checkNext: [],
+          likelyTests: [],
+          omittedCount: 0,
+          nextQueries: ["Provide `file`, `line`, `character` or a `symbol` to resolve the target"],
+        },
+      },
+    };
+  }
+
+  const relPath = path.relative(cwd, target.file);
+  const symbolName = target.name ?? `symbol at ${relPath}:${target.displayLine}`;
+
+  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 details: AffectedDetails = {
+    confidence: analysis.confidence,
+    directCount: refs.refs.length,
+    downstreamCount: analysis.downstreamCount,
+    riskLevel: analysis.riskLevel,
+    checkNext: analysis.checkNext,
+    likelyTests: analysis.likelyTests,
+    omittedCount:
+      analysis.externalRefs + (analysis.affectedFiles.size > (params.maxResults ?? 8) ? 1 : 0),
+    nextQueries: [
+      "`code_intel brief` on the most-affected module for deeper context",
+      `\`code_intel callers\` with \`symbol: "${symbolName}"\` for grouped call-site detail`,
+    ],
+  };
+  return { content, details: { type: "affected" as const, data: details } };
+}
+
+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;
+}
+
+// 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 },
+  params: ActionParams,
+  cwd: string,
+): Promise<{ refs: GatheredRef[]; confidence: ConfidenceMode; externalCount: number }> {
+  const lspState = getSessionLspService(cwd);
+  const refs: GatheredRef[] = [];
+  let externalCount = 0;
+
+  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);
+        if (isInProjectPath(filePath, cwd)) {
+          refs.push({ file: path.relative(cwd, filePath), line: ref.range.start.line + 1 });
+        } else {
+          externalCount++;
+        }
+      }
+      return { refs, confidence: "semantic", externalCount };
+    }
+  }
+
+  if (target.name) {
+    const scopePath = params.path ? normalizePath(params.path, cwd) : cwd;
+    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 });
+    }
+    return { refs, confidence: "heuristic", externalCount: 0 };
+  }
+
+  return { refs, confidence: "unavailable", externalCount: 0 };
+}
+
+// biome-ignore lint/complexity/noExcessiveCognitiveComplexity: impact analysis with downstream module traversal
+function analyzeImpact(
+  result: { refs: GatheredRef[]; confidence: ConfidenceMode; externalCount: number },
+  model: Awaited<ReturnType<typeof buildArchitectureModel>>,
+  symbolName: string | null,
+  cwd: string,
+): ImpactAnalysis {
+  const affectedFiles = new Set(result.refs.map((r) => r.file));
+  const affectedModules = new Set<string>();
+  const checkNext: string[] = [];
+  let downstreamCount = 0;
+
+  if (model) {
+    for (const file of affectedFiles) {
+      const mod = findModuleForPath(model, path.resolve(cwd, file));
+      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) {
+      const modName = queue.shift() as string;
+      for (const dep of getDependents(model, modName)) {
+        if (!affectedModules.has(dep.name) && !downstreamModules.has(dep.name)) {
+          downstreamModules.add(dep.name);
+          queue.push(dep.name);
+        }
+      }
+    }
+    downstreamCount = downstreamModules.size;
+
+    for (const modName of [...affectedModules, ...downstreamModules].slice(0, 3)) {
+      const mod = model.modules.find((m) => m.name === modName);
+      if (mod) checkNext.push(`${mod.name.replace(/^@[^/]+\//, "")} (\`${mod.relativePath}\`)`);
+    }
+  }
+
+  const likelyTests = findLikelyTests(affectedFiles, symbolName);
+  const totalRefs = result.refs.length + result.externalCount;
+  const riskLevel = assessRisk(totalRefs, affectedModules.size, downstreamCount);
+
+  return {
+    confidence: result.confidence,
+    affectedFiles,
+    affectedModules,
+    downstreamCount,
+    checkNext,
+    likelyTests,
+    riskLevel,
+    externalRefs: result.externalCount,
+  };
+}
+
+function findLikelyTests(affectedFiles: Set<string>, _symbolName: string | null): string[] {
+  const tests: string[] = [];
+  for (const file of affectedFiles) {
+    if (file.includes("test") || file.includes("spec") || file.includes("__tests__")) {
+      tests.push(file);
+    }
+  }
+  return tests.slice(0, 3);
+}
+
+function assessRisk(
+  directCount: number,
+  moduleCount: number,
+  downstreamCount: number,
+): "low" | "medium" | "high" {
+  if (directCount > 10 || moduleCount > 3 || downstreamCount > 1) return "high";
+  if (directCount > 3 || moduleCount > 1 || downstreamCount >= 1) return "medium";
+  return "low";
+}
+
+function formatAffectedOutput(
+  symbolName: string,
+  result: { refs: GatheredRef[]; confidence: ConfidenceMode; externalCount: number },
+  analysis: ImpactAnalysis,
+  params: ActionParams,
+): string {
+  const totalRefs = result.refs.length + analysis.externalRefs;
+  const lines: string[] = [];
+
+  lines.push(`# Affected: \`${symbolName}\``);
+  lines.push("");
+  const refSummary =
+    analysis.externalRefs > 0
+      ? `${totalRefs} refs (${result.refs.length} direct + ${analysis.externalRefs} external)`
+      : `${totalRefs} ref${totalRefs !== 1 ? "s" : ""}`;
+  lines.push(
+    `**Risk: ${analysis.riskLevel.toUpperCase()}** | ${refSummary} | ${analysis.affectedFiles.size} file${analysis.affectedFiles.size !== 1 ? "s" : ""} | ${analysis.affectedModules.size} module${analysis.affectedModules.size !== 1 ? "s" : ""} | ${analysis.downstreamCount} downstream (${analysis.confidence})`,
+  );
+  if (analysis.externalRefs > 0) {
+    lines.push(
+      `_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);
+  addCheckNextSection(lines, analysis.checkNext);
+  addTestsSection(lines, analysis.likelyTests);
+  addAffectedNextQueries(lines, symbolName, analysis);
+
+  return lines.join("\n");
+}
+
+// biome-ignore lint/complexity/noExcessiveCognitiveComplexity: risk level formatting with conditional branching
+function addRiskSection(lines: string[], analysis: ImpactAnalysis, directCount: number): void {
+  lines.push("## Risk Assessment");
+  const { riskLevel, affectedFiles, affectedModules, downstreamCount } = analysis;
+  if (riskLevel === "low") {
+    lines.push(
+      `\`low\` — ${directCount} ref${directCount !== 1 ? "s" : ""}, local, no downstream dependents.`,
+    );
+  } else if (riskLevel === "medium") {
+    lines.push(
+      `\`medium\` — ${directCount} ref${directCount !== 1 ? "s" : ""} across ${affectedFiles.size} file${affectedFiles.size !== 1 ? "s" : ""}${downstreamCount > 0 ? `, ${downstreamCount} downstream` : ""}.`,
+    );
+  } else {
+    lines.push(
+      `\`high\` — ${directCount} ref${directCount !== 1 ? "s" : ""} across ${affectedFiles.size} file${affectedFiles.size !== 1 ? "s" : ""} in ${affectedModules.size} module${affectedModules.size !== 1 ? "s" : ""}${downstreamCount > 0 ? `, ${downstreamCount} downstream` : ""}.`,
+    );
+  }
+  lines.push("");
+}
+
+function addReferencesSection(lines: string[], refs: GatheredRef[], maxFiles: number): void {
+  if (refs.length === 0) return;
+  lines.push("## Direct References");
+  const byFile = new Map<string, number[]>();
+  for (const ref of refs) {
+    const fileLines = byFile.get(ref.file) ?? [];
+    fileLines.push(ref.line);
+    byFile.set(ref.file, fileLines);
+  }
+
+  let shown = 0;
+  for (const [file, fileLines] of byFile) {
+    if (shown >= maxFiles) break;
+    const lineStr = fileLines
+      .slice(0, 5)
+      .map((l) => `L${l}`)
+      .join(", ");
+    const extra = fileLines.length > 5 ? ` +${fileLines.length - 5} more` : "";
+    lines.push(`- \`${file}\` ${lineStr}${extra}`);
+    shown++;
+  }
+  if (byFile.size > maxFiles) {
+    lines.push(`- _+${byFile.size - maxFiles} more files omitted_`);
+  }
+  lines.push("");
+}
+
+function addCheckNextSection(lines: string[], checkNext: string[]): void {
+  if (checkNext.length === 0) return;
+  lines.push("## Check Next");
+  for (const item of checkNext.slice(0, 3)) {
+    lines.push(`- ${item}`);
+  }
+  lines.push("");
+}
+
+function addTestsSection(lines: string[], tests: string[]): void {
+  if (tests.length === 0) return;
+  lines.push("## Likely Tests");
+  for (const t of tests.slice(0, 3)) {
+    lines.push(`- \`${t}\``);
+  }
+  lines.push("");
+}
+
+function addAffectedNextQueries(
+  lines: string[],
+  symbolName: string,
+  analysis: ImpactAnalysis,
+): void {
+  lines.push("## Next");
+  if (analysis.checkNext.length > 0) {
+    lines.push("- `code_intel brief` on the most-affected module for deeper context");
+  }
+  lines.push(
+    `- \`code_intel callers\` with \`symbol: "${symbolName}"\` for grouped call-site detail`,
+  );
+  lines.push("");
+}

package/src/actions/brief-action.ts

@@ -0,0 +1,242 @@
+// Brief action — architecture overviews and focused briefs.
+
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { createTreeSitterSession } from "@mrclrchtr/supi-tree-sitter";
+import { buildArchitectureModel, findModuleForPath } from "../architecture.ts";
+import { generateFocusedBrief, generateProjectBrief } from "../brief.ts";
+import { normalizePath } from "../search-helpers.ts";
+import type { ActionParams } from "../tool-actions.ts";
+import type { CodeIntelResult } from "../types.ts";
+
+export async function executeBriefAction(
+  params: ActionParams,
+  cwd: string,
+): Promise<CodeIntelResult> {
+  const model = await buildArchitectureModel(cwd);
+  if (!model) {
+    return {
+      content:
+        "No project structure detected. This directory has no recognizable project metadata or source files.",
+      details: {
+        type: "brief" as const,
+        data: {
+          confidence: "unavailable",
+          focusTarget: null,
+          startHere: [],
+          publicSurfaces: [],
+          dependencySummary: null,
+          omittedCount: 0,
+          nextQueries: [
+            "Add a package.json or pnpm-workspace.yaml to enable architecture analysis",
+          ],
+        },
+      },
+    };
+  }
+
+  if (params.file && params.line != null && params.character != null) {
+    const content = await executeAnchoredBrief(params, cwd, model);
+    const relPath = path.relative(cwd, normalizePath(params.file ?? "", cwd));
+    const mod = findModuleForPath(model, path.resolve(cwd, relPath));
+    return {
+      content,
+      details: {
+        type: "brief" as const,
+        data: {
+          confidence: "structural",
+          focusTarget: `${relPath}:${params.line}:${params.character}`,
+          startHere: [],
+          publicSurfaces: [],
+          dependencySummary: mod && model ? { moduleCount: 1, edgeCount: 0 } : null,
+          omittedCount: 0,
+          nextQueries: [
+            `\`code_intel callers\` with \`file: "${relPath}", line: ${params.line}, character: ${params.character}\` for call sites`,
+            `\`code_intel affected\` with \`file: "${relPath}", line: ${params.line}, character: ${params.character}\` for impact analysis`,
+          ],
+        },
+      },
+    };
+  }
+
+  if (params.path) {
+    const result = generateFocusedBrief(model, normalizePath(params.path, cwd));
+    return { content: result.content, details: { type: "brief" as const, data: result.details } };
+  }
+
+  if (params.file) {
+    const result = generateFocusedBrief(model, normalizePath(params.file, cwd));
+    return { content: result.content, details: { type: "brief" as const, data: result.details } };
+  }
+
+  const result = generateProjectBrief(model);
+  return { content: result.content, details: { type: "brief" as const, data: result.details } };
+}
+
+async function executeAnchoredBrief(
+  params: ActionParams,
+  cwd: string,
+  model: NonNullable<Awaited<ReturnType<typeof buildArchitectureModel>>>,
+): Promise<string> {
+  const file = normalizePath(params.file ?? "", cwd);
+  const line1 = params.line ?? 1;
+  const char1 = params.character ?? 1;
+  const relPath = path.relative(cwd, file);
+
+  if (!fs.existsSync(file)) {
+    return `**Error:** File not found: \`${params.file}\``;
+  }
+
+  const lines: string[] = [];
+  lines.push(`# Anchored Brief: ${relPath}:${line1}:${char1}`);
+  lines.push("");
+
+  await addTreeSitterContext({ lines, relPath, line1, char1, cwd });
+  addModuleContext(lines, model, file);
+  addNextQueries(lines, relPath, line1, char1);
+
+  return lines.join("\n");
+}
+
+interface TreeSitterContextInput {
+  lines: string[];
+  relPath: string;
+  line1: number;
+  char1: number;
+  cwd: string;
+}
+
+async function addTreeSitterContext(input: TreeSitterContextInput): Promise<void> {
+  const { lines, relPath, line1, char1, cwd } = input;
+  let tsSession: ReturnType<typeof createTreeSitterSession> | null = null;
+  try {
+    tsSession = createTreeSitterSession(cwd);
+    await addNodeContext(lines, tsSession, relPath, { line: line1, char: char1 });
+    await addOutlineContext(lines, tsSession, relPath, line1);
+    await addImportsContext(lines, tsSession, relPath);
+    await addExportsContext(lines, tsSession, relPath);
+  } catch {
+    // Tree-sitter not available
+  } finally {
+    tsSession?.dispose();
+  }
+}
+
+async function addNodeContext(
+  lines: string[],
+  ts: ReturnType<typeof createTreeSitterSession>,
+  relPath: string,
+  pos: { line: number; char: number },
+): Promise<void> {
+  const result = await ts.nodeAt(relPath, pos.line, pos.char);
+  if (result.kind !== "success") return;
+  const node = result.data;
+  lines.push(
+    `**Node:** \`${node.type}\` at ${relPath}:${node.range.startLine}:${node.range.startCharacter}`,
+  );
+  if (node.text && node.text.length <= 200) {
+    lines.push("```");
+    lines.push(node.text);
+    lines.push("```");
+  }
+  lines.push("");
+}
+
+async function addOutlineContext(
+  lines: string[],
+  ts: ReturnType<typeof createTreeSitterSession>,
+  relPath: string,
+  line1: number,
+): Promise<void> {
+  const result = await ts.outline(relPath);
+  if (result.kind !== "success") return;
+  const outline = result.data;
+
+  const enclosing = outline.find(
+    (item) => item.range.startLine <= line1 && item.range.endLine >= line1,
+  );
+  if (enclosing) {
+    lines.push(`**Enclosing symbol:** \`${enclosing.name}\` (${enclosing.kind})`);
+    lines.push(`- Range: ${relPath}:${enclosing.range.startLine}–${enclosing.range.endLine}`);
+    lines.push("");
+  }
+
+  if (outline.length > 0) {
+    lines.push("## File Outline");
+    const shown = outline.slice(0, 15);
+    for (const item of shown) {
+      const prefix = getOutlinePrefix(item.kind);
+      lines.push(`- ${prefix} \`${item.name}\` (${item.kind}) L${item.range.startLine}`);
+    }
+    if (outline.length > 15) {
+      lines.push(`- _+${outline.length - 15} more declarations_`);
+    }
+    lines.push("");
+  }
+}
+
+function getOutlinePrefix(kind: string): string {
+  if (kind === "function" || kind === "method") return "ƒ";
+  if (kind === "class") return "◆";
+  return "·";
+}
+
+async function addImportsContext(
+  lines: string[],
+  ts: ReturnType<typeof createTreeSitterSession>,
+  relPath: string,
+): Promise<void> {
+  const result = await ts.imports(relPath);
+  if (result.kind !== "success" || result.data.length === 0) return;
+  lines.push("## Imports");
+  const shown = result.data.slice(0, 10);
+  for (const imp of shown) {
+    lines.push(`- \`${imp.moduleSpecifier}\``);
+  }
+  if (result.data.length > 10) {
+    lines.push(`- _+${result.data.length - 10} more_`);
+  }
+  lines.push("");
+}
+
+async function addExportsContext(
+  lines: string[],
+  ts: ReturnType<typeof createTreeSitterSession>,
+  relPath: string,
+): Promise<void> {
+  const result = await ts.exports(relPath);
+  if (result.kind !== "success" || result.data.length === 0) return;
+  lines.push("## Exports");
+  const shown = result.data.slice(0, 10);
+  for (const exp of shown) {
+    lines.push(`- \`${exp.name}\` (${exp.kind})`);
+  }
+  if (result.data.length > 10) {
+    lines.push(`- _+${result.data.length - 10} more_`);
+  }
+  lines.push("");
+}
+
+function addModuleContext(
+  lines: string[],
+  model: NonNullable<Awaited<ReturnType<typeof buildArchitectureModel>>>,
+  file: string,
+): void {
+  const mod = findModuleForPath(model, file);
+  if (mod) {
+    const shortName = mod.name.replace(/^@[^/]+\//, "");
+    lines.push(`_Module: ${shortName} (\`${mod.relativePath}\`)_`);
+    lines.push("");
+  }
+}
+
+function addNextQueries(lines: string[], relPath: string, line1: number, char1: number): void {
+  lines.push("## Next");
+  lines.push(
+    `- \`code_intel callers\` with \`file: "${relPath}", line: ${line1}, character: ${char1}\` for call sites`,
+  );
+  lines.push(
+    `- \`code_intel affected\` with \`file: "${relPath}", line: ${line1}, character: ${char1}\` for impact analysis`,
+  );
+  lines.push("");
+}

package/src/actions/callees-action.ts

@@ -0,0 +1,134 @@
+// Callees action — structural outgoing call map via Tree-sitter.
+// Orchestrates target resolution and formatting; delegates grammar-aware
+// extraction to @mrclrchtr/supi-tree-sitter.
+
+import * as path from "node:path";
+import { createTreeSitterSession } from "@mrclrchtr/supi-tree-sitter";
+import { resolveTarget } from "../resolve-target.ts";
+import type { ActionParams } from "../tool-actions.ts";
+import type { CodeIntelResult, SearchDetails } from "../types.ts";
+
+export async function executeCalleesAction(
+  params: ActionParams,
+  cwd: string,
+): Promise<CodeIntelResult> {
+  const target = await resolveTarget(params, cwd);
+  if (typeof target === "string") {
+    return {
+      content: target,
+      details: {
+        type: "search" as const,
+        data: {
+          confidence: "unavailable",
+          scope: null,
+          candidateCount: 0,
+          omittedCount: 0,
+          nextQueries: ["Provide `file`, `line`, `character` or a `symbol` to resolve the target"],
+        },
+      },
+    };
+  }
+
+  const relPath = path.relative(cwd, target.file);
+  let tsSession: ReturnType<typeof createTreeSitterSession> | null = null;
+
+  try {
+    tsSession = createTreeSitterSession(cwd);
+    const result = await tsSession.calleesAt(relPath, target.displayLine, target.displayCharacter);
+
+    if (result.kind !== "success") {
+      return {
+        content: noCalleesMessage(relPath, target.displayLine, target.displayCharacter),
+        details: {
+          type: "search" as const,
+          data: {
+            confidence: "unavailable",
+            scope: null,
+            candidateCount: 0,
+            omittedCount: 0,
+            nextQueries: ["Use `lsp` for type-aware analysis on this file"],
+          },
+        },
+      };
+    }
+
+    const { enclosingScope, callees } = result.data;
+
+    if (callees.length === 0) {
+      return {
+        content: noCalleesMessage(relPath, target.displayLine, target.displayCharacter),
+        details: {
+          type: "search" as const,
+          data: {
+            confidence: "structural",
+            scope: null,
+            candidateCount: 0,
+            omittedCount: 0,
+            nextQueries: [
+              'Use `tree_sitter` with `action: "outline"` to explore the enclosing function',
+            ],
+          },
+        },
+      };
+    }
+
+    const content = formatCallees(callees, enclosingScope.name, relPath, params.maxResults ?? 8);
+    const details: SearchDetails = {
+      confidence: "structural",
+      scope: null,
+      candidateCount: callees.length,
+      omittedCount: Math.max(0, callees.length - (params.maxResults ?? 8)),
+      nextQueries: ["Use `lsp` for precise type information on callees"],
+    };
+    return { content, details: { type: "search" as const, data: details } };
+  } catch {
+    return {
+      content: noCalleesMessage(relPath, target.displayLine, target.displayCharacter),
+      details: {
+        type: "search" as const,
+        data: {
+          confidence: "unavailable",
+          scope: null,
+          candidateCount: 0,
+          omittedCount: 0,
+          nextQueries: ["Use `lsp` for type-aware analysis on this file"],
+        },
+      },
+    };
+  } finally {
+    tsSession?.dispose();
+  }
+}
+
+function formatCallees(
+  callees: Array<{ name: string; range: { startLine: number } }>,
+  enclosingName: string,
+  relPath: string,
+  maxResults: number,
+): string {
+  const lines: string[] = [];
+  lines.push(`# Callees of \`${enclosingName}\` (structural)`);
+  lines.push("");
+  lines.push(
+    `**${callees.length} outgoing call${callees.length > 1 ? "s" : ""}** from \`${enclosingName}\` in \`${relPath}\``,
+  );
+  lines.push("");
+
+  const shown = callees.slice(0, maxResults);
+  for (const c of shown) {
+    lines.push(`- \`${c.name}\` (L${c.range.startLine})`);
+  }
+  if (callees.length > maxResults) {
+    lines.push(`- _+${callees.length - maxResults} more_`);
+  }
+  lines.push("");
+  lines.push(
+    "_Structural analysis — may include unresolved or qualified names. Use `lsp` for precise type information._",
+  );
+  lines.push("");
+  return lines.join("\n");
+}
+
+function noCalleesMessage(relPath: string, line: number, char: number): string {
+  return `No callee data available for ${relPath}:${line}:${char}.\n\nUse \`tree_sitter\` with \`action: "callees"\` for structural drill-down.`;
+}