@mrclrchtr/supi-code-intelligence 0.1.0 → 1.1.2

package/README.md

@@ -33,12 +33,15 @@ Scopes: project (no params), package/directory (`path`), file (`file`), or ancho
 
 - Project-level brief: module listing, dependency graph, "start here" recommendations, suggested next queries
 - Focused brief (`path` or anchored symbol): stripped-down version with a single module or symbol focus
+- Non-module directory briefs now recurse into descendant structure, summarize nested source files, and include lightweight public-surface / import-export summaries for JS/TS trees
 - Now includes git context (branch, dirty files, last commit) when inside a git repository
+- Can surface optional priority signals such as diagnostics, low coverage, and unused-code hints when available
 - Metadata returned: `BriefDetails` with confidence, focus target, public surfaces, dependency summary
 
 ### `callers` — Find call sites for a symbol
 
 - LSP-first (references query), falls back to heuristic text search (word-boundary ripgrep)
+- File-only requests now expand across discovered exported targets when possible, so you can ask for callers of a module surface without coordinates
 - Results grouped by file with ranked, contextual call sites
 - Confidence labeling: `semantic` (LSP), `heuristic` (text search)
 
@@ -60,6 +63,8 @@ Before changing exported APIs, shared helpers, config surfaces, or cross-package
 - Downstream dependents (transitive)
 - Risk level: `low` | `medium` | `high`
 - Likely test files
+- File-only requests now expand across discovered exported targets when possible
+- Optional priority signals highlight diagnostics, low coverage, and unused-code hints when available
 - Returns `AffectedDetails` metadata
 
 ### `index` — Factual project map
@@ -83,6 +88,9 @@ Optimized for common agent lookups:
 
 - `pattern` is treated as a **literal string by default**
 - Set `regex: true` to opt into raw ripgrep regex semantics
+- Structured JS/TS searches support `kind: "definition" | "export" | "import"` to avoid regex look-around hacks when you care about declarations instead of raw text lines
+- Definition/export searches include duplicate-definition summaries when the same symbol appears in multiple files
+- Structured scans are capped and may return a partial-result warning when the scope is too large or times out; narrow `path` or `pattern` for complete coverage
 - Malformed regex input returns an explicit error instead of a misleading "No matches found"
 - Nearby matches in the same file deduplicate overlapping context lines to reduce token waste
 - Results grouped with file and context lines
@@ -93,6 +101,7 @@ Examples:
 ```json
 { "action": "pattern", "pattern": "sendMessage({", "path": "packages/" }
 { "action": "pattern", "pattern": "register(Settings|Config)", "path": "packages/", "regex": true }
+{ "action": "pattern", "pattern": "payment", "kind": "definition", "path": "src/" }
 { "action": "pattern", "pattern": "createServerFn", "summary": true }
 ```
 
@@ -139,9 +148,9 @@ For no-result and error states, `details` carries `confidence: "unavailable"` or
 `confidence: "heuristic"` with appropriately zeroed counts, so consumers always
 get structured metadata back.
 
-- **`brief`** → `BriefDetails` (confidence, focus target, start-here suggestions, public surfaces, dependency summary, omitted count, next queries)
+- **`brief`** → `BriefDetails` (confidence, focus target, start-here suggestions, public surfaces, dependency summary, omitted count, next queries, optional priority signals)
 - **`search`** → `SearchDetails` (callers/callees/implementations/pattern: confidence, scope, candidate count, omitted count)
-- **`affected`** → `AffectedDetails` (direct count, downstream count, risk level, likely tests, check-next list)
+- **`affected`** → `AffectedDetails` (direct count, downstream count, risk level, likely tests, check-next list, optional priority signals)
 
 ## Parameter Validation
 
@@ -149,6 +158,7 @@ The tool enforces these rules and returns explicit error messages:
 
 - `line`/`character` require `file`, not `path` — `path` is for scope/focus, `file` anchors a position
 - `file` that points to a directory is rejected — use `path` for directory scoping
+- `pattern.kind` must be one of `definition`, `export`, or `import`
 - Unknown actions are rejected with a list of supported actions
 
 ## Architecture
@@ -192,9 +202,10 @@ export type { AffectedDetails, BriefDetails, CodeIntelResult, ConfidenceMode, Di
 These seven guidelines are injected into the system prompt:
 
 > - Use `code_intel brief` before editing an unfamiliar package, directory, or file to get architecture context and reduce blind reads.
-> - Use `code_intel affected` before changing exported APIs, shared helpers, config surfaces, or cross-package contracts to check blast radius and risk.
-> - Use `code_intel callers` before modifying a function to verify all call sites; use `callees` and `implementations` for dependency and interface analysis.
-> - Use `code_intel pattern` for bounded, scope-aware text search when the question is textual rather than semantic; it treats patterns as literal strings by default and supports `regex: true` when needed.
+> - Use `code_intel affected` before changing exported APIs, shared helpers, config surfaces, or cross-package contracts to check blast radius and risk; file-only requests now expand across exported targets when possible.
+> - Use `code_intel callers` before modifying a function to verify all call sites; use `callees` and `implementations` for dependency and interface analysis, and use file-only `callers` when you need the export surface of a module.
+> - Use `code_intel pattern` for bounded, scope-aware text search when the question is textual rather than semantic; it treats patterns as literal strings by default, supports `regex: true`, and supports `kind: "definition" | "export" | "import"` for structured searches.
+> - Use `code_intel brief` and `code_intel affected` priority signals to notice diagnostics, low coverage, or unused-code hints before editing risky files.
 > - Use `code_intel index` for a factual project map (file counts, directory structure, landmark files) when you need to orient yourself in a new codebase.
 > - After `code_intel` narrows the target, use raw `lsp` and `tree_sitter` tools for precise drill-down on exact symbols, types, or AST nodes.
 > - Do not prefer `code_intel` over direct file reads or lower-level tools for trivial, already-localized edits or exact symbol/AST drill-down tasks.

package/node_modules/@mrclrchtr/supi-core/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mrclrchtr/supi-core",
-  "version": "0.1.0",
+  "version": "1.1.2",
   "description": "SuPi core — shared infrastructure for SuPi extensions (XML context tags, config system)",
   "license": "MIT",
   "repository": {
@@ -22,9 +22,5 @@
     "@earendil-works/pi-coding-agent": "*",
     "@earendil-works/pi-tui": "*"
   },
-  "devDependencies": {
-    "@types/node": "^25.6.0",
-    "vitest": "^4.1.4"
-  },
   "main": "src/index.ts"
 }

package/node_modules/@mrclrchtr/supi-lsp/node_modules/@mrclrchtr/supi-core/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mrclrchtr/supi-core",
-  "version": "0.1.0",
+  "version": "1.1.2",
   "description": "SuPi core — shared infrastructure for SuPi extensions (XML context tags, config system)",
   "license": "MIT",
   "repository": {
@@ -22,9 +22,5 @@
     "@earendil-works/pi-coding-agent": "*",
     "@earendil-works/pi-tui": "*"
   },
-  "devDependencies": {
-    "@types/node": "^25.6.0",
-    "vitest": "^4.1.4"
-  },
   "main": "src/index.ts"
 }

package/node_modules/@mrclrchtr/supi-lsp/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mrclrchtr/supi-lsp",
-  "version": "0.1.0",
+  "version": "1.1.2",
   "description": "SuPi LSP extension — Language Server Protocol integration for pi",
   "license": "MIT",
   "repository": {
@@ -21,7 +21,7 @@
     "!__tests__"
   ],
   "dependencies": {
-    "@mrclrchtr/supi-core": "workspace:*"
+    "@mrclrchtr/supi-core": "1.1.2"
   },
   "bundledDependencies": [
     "@mrclrchtr/supi-core"
@@ -32,10 +32,6 @@
     "@earendil-works/pi-tui": "*",
     "typebox": "*"
   },
-  "devDependencies": {
-    "vitest": "^4.1.4",
-    "@mrclrchtr/supi-test-utils": "workspace:*"
-  },
   "pi": {
     "extensions": [
       "./src/lsp.ts"

package/node_modules/@mrclrchtr/supi-lsp/src/diagnostics/stale-diagnostics.ts

@@ -31,7 +31,7 @@ export function assessStaleDiagnostics(
   };
 }
 
-function isLikelyStaleDiagnostic(diagnostic: Diagnostic): boolean {
+export function isLikelyStaleDiagnostic(diagnostic: Diagnostic): boolean {
   if (diagnostic.severity === undefined) return false;
   if (diagnostic.code !== undefined) {
     if (typeof diagnostic.code === "number" && MODULE_RESOLUTION_CODES.has(diagnostic.code)) {

package/node_modules/@mrclrchtr/supi-lsp/src/lsp.ts

@@ -29,6 +29,7 @@ import {
   removeLspTool,
 } from "./lsp-state.ts";
 import { LspManager } from "./manager/manager.ts";
+import { forceResyncStaleModuleFiles } from "./manager/manager-stale-resync.ts";
 import { registerLspAwareToolOverrides } from "./overrides.ts";
 import { registerLspMessageRenderer } from "./renderer.ts";
 import { scanMissingServers, scanProjectCapabilities, startDetectedServers } from "./scanner.ts";
@@ -305,6 +306,16 @@ function registerBehaviorHandlers(pi: ExtensionAPI, state: LspRuntimeState): voi
       // Refresh failures must not prevent agent startup
     }
     state.manager.pruneMissingFiles();
+
+    // Force re-open files with module-resolution errors to clear stale
+    // diagnostics that persist when the TS server caches by content hash.
+    // Must run before the diagnostic summary so fresh results are captured.
+    try {
+      await forceResyncStaleModuleFiles(state.manager, ctx.cwd);
+    } catch {
+      // Best-effort: don't fail the agent turn
+    }
+
     refreshProjectServers(state);
     updateLspUi(ctx, state.manager, state.inlineSeverity, state.projectServers);
 

package/node_modules/@mrclrchtr/supi-lsp/src/manager/manager-stale-resync.ts

@@ -0,0 +1,47 @@
+import * as path from "node:path";
+import { isLikelyStaleDiagnostic } from "../diagnostics/stale-diagnostics.ts";
+import type { LspManager } from "./manager.ts";
+
+/**
+ * Force re-open files with module-resolution errors (e.g., "Cannot find module")
+ * to trigger fresh analysis by the language server.
+ *
+ * The TypeScript server caches diagnostics by file content hash. When a new
+ * file is created that resolves an existing file's import, the stale diagnostic
+ * persists because the importing file's content hasn't changed. Re-opening the
+ * file (didClose + didOpen) forces the server to re-resolve all imports.
+ *
+ * Returns true if any files were re-synced.
+ */
+export async function forceResyncStaleModuleFiles(
+  manager: LspManager,
+  cwd: string,
+): Promise<boolean> {
+  const outstanding = manager.getOutstandingDiagnostics(1);
+  const staleFiles: string[] = [];
+
+  for (const entry of outstanding) {
+    if (entry.diagnostics.some((d) => isLikelyStaleDiagnostic(d))) {
+      staleFiles.push(entry.file);
+    }
+  }
+
+  if (staleFiles.length === 0) return false;
+
+  for (const file of staleFiles) {
+    const filePath = path.resolve(cwd, file);
+    // Close the file to clear cached diagnostics and remove from openDocs
+    manager.closeFile(filePath);
+    // Re-open to force the server to re-resolve imports
+    await manager.ensureFileOpen(filePath);
+  }
+
+  // Re-sync and wait for fresh diagnostics after the re-opens
+  try {
+    await manager.refreshOpenDiagnostics({ quietMs: 300, maxWaitMs: 2000 });
+  } catch {
+    // Best-effort: don't fail the agent turn if refresh has issues
+  }
+
+  return true;
+}

package/node_modules/@mrclrchtr/supi-lsp/src/settings-registration.ts

@@ -151,7 +151,7 @@ function buildLspSettingItems(
       id: "exclude",
       label: "Exclude Patterns",
       description:
-        "Gitignore patterns to suppress LSP diagnostics (e.g. __tests__/, *.generated.ts)",
+        "Gitignore patterns to suppress LSP diagnostics. Edit .pi/supi/config.json → lsp.exclude (or ~/.pi/agent/supi/config.json for global). Patterns like __tests__/ exclude a directory, *.test.ts wildcards match at any depth, /dist anchors to root.",
       currentValue: settings.exclude.length > 0 ? settings.exclude.join(", ") : "none",
       submenu: (_currentValue, done) => createExcludeSubmenu(scope, cwd, settings, done),
     },

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

@@ -1,6 +1,6 @@
 {
   "name": "@mrclrchtr/supi-tree-sitter",
-  "version": "0.1.0",
+  "version": "1.1.2",
   "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,18 @@
     "@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.0",
-    "tree-sitter-bash": "^0.23.0",
-    "tree-sitter-c": "^0.23.0",
-    "tree-sitter-cli": "0.22.6",
-    "tree-sitter-cpp": "^0.23.0",
-    "tree-sitter-go": "^0.23.0",
-    "tree-sitter-html": "^0.23.0",
-    "tree-sitter-java": "^0.23.0",
-    "tree-sitter-javascript": "^0.23.0",
-    "tree-sitter-kotlin": "^0.3.8",
-    "tree-sitter-python": "^0.23.0",
-    "tree-sitter-ruby": "^0.23.0",
-    "tree-sitter-rust": "^0.23.0",
-    "tree-sitter-typescript": "^0.23.0",
-    "vitest": "^4.1.4",
-    "@mrclrchtr/supi-test-utils": "workspace:*"
-  },
   "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.1.0",
+  "version": "1.1.2",
   "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.2",
+    "@mrclrchtr/supi-lsp": "1.1.2",
+    "@mrclrchtr/supi-tree-sitter": "1.1.2"
   },
   "bundledDependencies": [
     "@mrclrchtr/supi-core",
@@ -33,11 +33,6 @@
     "@earendil-works/pi-coding-agent": "*",
     "typebox": "*"
   },
-  "devDependencies": {
-    "@types/node": "^25.6.0",
-    "vitest": "^4.1.4",
-    "@mrclrchtr/supi-test-utils": "workspace:*"
-  },
   "pi": {
     "extensions": [
       "./src/code-intelligence.ts"

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;