cgraphx 1.1.0 → 1.2.0

package/dist/search/call-sites.js

@@ -0,0 +1,1433 @@
+"use strict";
+/**
+ * Call site search — finds method-invocation sites by name across the project.
+ *
+ * Designed as an agent-facing "structured grep": returns call sites with AST
+ * context (containing class/method), not raw text matches. AST naturally
+ * excludes comments/strings (they're not method_invocation nodes), so the
+ * output is signal-dense for agent consumption — saves the agent the
+ * comment/string/overload filtering that grep forces it to do.
+ *
+ * Does NOT depend on cgraphx's resolve pipeline. Walks source files directly
+ * via tree-sitter, so it works on any project (indexed or not) and avoids the
+ * resolve-accuracy issues that broke L3 scope-bounded on Java dotted names.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_EXCLUDE_DIRS = void 0;
+exports.searchCallSites = searchCallSites;
+exports.compareCallSitesTiebreak = compareCallSitesTiebreak;
+exports.listJavaFamilyFiles = listJavaFamilyFiles;
+exports.formatCallSitesResult = formatCallSitesResult;
+exports.resolveMethodSymbol = resolveMethodSymbol;
+exports.findEnclosingClassType = findEnclosingClassType;
+exports.extractInjectedFields = extractInjectedFields;
+exports.findFilesWithClass = findFilesWithClass;
+exports.containsBizVerbSegment = containsBizVerbSegment;
+exports.rootIdentifier = rootIdentifier;
+exports.computeSnrScore = computeSnrScore;
+exports.computeSnrBreakdown = computeSnrBreakdown;
+exports.formatSnrBreakdown = formatSnrBreakdown;
+exports.compareBySnr = compareBySnr;
+exports.collectSameClassMethodNames = collectSameClassMethodNames;
+exports.markSameClassBiz = markSameClassBiz;
+exports.searchCallees = searchCallees;
+exports.applyTieredBudget = applyTieredBudget;
+exports.formatCalleesResult = formatCalleesResult;
+const fs_1 = require("fs");
+const path = __importStar(require("path"));
+const grammars_1 = require("../extraction/grammars");
+const ast_helpers_1 = require("./ast-helpers");
+const snr_constants_1 = require("./snr-constants");
+// ---------------------------------------------------------------------------
+// Built-in file-scan exclusions (targeted at Java/JVM build output + noise)
+// ---------------------------------------------------------------------------
+exports.DEFAULT_EXCLUDE_DIRS = new Set([
+    '.git',
+    '.cgraphx',
+    '.idea',
+    '.vscode',
+    'node_modules',
+    'target', // Maven
+    'build', // Gradle
+    'out', // IntelliJ out
+    '.gradle',
+    '.mvn',
+    'dist',
+    '__pycache__',
+    '.cache',
+]);
+const JAVA_FAMILY_EXTENSIONS = new Set(['.java', '.kt', '.kts']);
+// ---------------------------------------------------------------------------
+// Main entry
+// ---------------------------------------------------------------------------
+async function searchCallSites(projectRoot, methodName, options = {}) {
+    const { topK = 20, topPerReceiver = 3, budget = 4000, receiver, languages = ['java', 'kotlin'], excludeDirs = [], } = options;
+    // initGrammars() only initializes the WASM runtime; loadGrammarsForLanguages
+    // actually loads the Java/Kotlin grammar WASM. Without this, getParser()
+    // returns null and we silently find 0 call sites.
+    await (0, grammars_1.loadGrammarsForLanguages)(languages);
+    const excludeSet = new Set([...exports.DEFAULT_EXCLUDE_DIRS, ...excludeDirs]);
+    // 1. Walk project, collect Java-family files
+    const allFiles = await listJavaFamilyFiles(projectRoot, excludeSet);
+    // 2. Pre-parse text filter: only parse files that contain methodName as text.
+    // Reading the file is unavoidable (we need content to parse), so we do the
+    // text check on the same read and skip parse if no match.
+    const candidateFiles = [];
+    let skippedFiles = 0;
+    for (const file of allFiles) {
+        let content;
+        try {
+            content = await fs_1.promises.readFile(file, 'utf-8');
+        }
+        catch {
+            skippedFiles++;
+            continue;
+        }
+        if (!content.includes(methodName)) {
+            skippedFiles++;
+            continue;
+        }
+        const language = (0, grammars_1.detectLanguage)(file, content);
+        if (!languages.includes(language)) {
+            skippedFiles++;
+            continue;
+        }
+        candidateFiles.push({ file, content, language });
+    }
+    // 3. Parse each candidate + extract method_invocation nodes matching methodName.
+    //    extractMethodInvocationsWithSnr walks the tree once per file and computes
+    //    xBdy / sameClassBiz / snrScore inline (mirrors the callees path) so the
+    //    downstream cluster + sort can be SNR-driven. Injected-field and sibling-
+    //    method lookups are cached per enclosing class node to avoid re-walking
+    //    the same class body for every method_invocation inside it.
+    const allCallSites = [];
+    for (const { file, content, language } of candidateFiles) {
+        const parser = (0, grammars_1.getParser)(language);
+        if (!parser)
+            continue;
+        const tree = parser.parse(content);
+        if (!tree)
+            continue;
+        const sites = extractMethodInvocationsWithSnr(tree.rootNode, content, methodName, projectRoot, file);
+        allCallSites.push(...sites);
+    }
+    // 4. Receiver filter (optional)
+    let filtered = allCallSites;
+    let filteredByReceiver = 0;
+    if (receiver) {
+        const before = filtered.length;
+        filtered = filtered.filter((s) => s.receiverText === receiver);
+        filteredByReceiver = before - filtered.length;
+    }
+    // 5. Cluster by receiver (high-frequency methods get called by many
+    // receivers; without clustering, topK returns only the most-common
+    // receiver's first K calls — agent sees 20 CollectionUtils.isNotEmpty
+    // and misses StringUtils.isNotEmpty). Each receiver gets up to
+    // `topPerReceiver` representatives, capped by global `topK`.
+    const distinctReceivers = new Set(filtered.map((s) => s.receiverText)).size;
+    const byReceiver = new Map();
+    for (const site of filtered) {
+        const key = site.receiverText;
+        const group = byReceiver.get(key) ?? [];
+        group.push(site);
+        byReceiver.set(key, group);
+    }
+    // Sort each group internally by SNR desc (was: confidence > path depth).
+    // Same ranking as callees mode — `compareBySnr` tiebreaks on filePath depth
+    // asc + line asc per spec §2.4.
+    for (const group of byReceiver.values()) {
+        group.sort(compareBySnr);
+    }
+    // Receivers ordered by their top caller's SNR score (was: group size desc).
+    // xBdy callers score +100 so xBdy groups naturally rise to the top; a
+    // receiver like `customerOrderService` (injected service field) outranks
+    // `Objects`/`CollectionUtils` noise even when the noise group is larger.
+    const sortedReceivers = [...byReceiver.entries()].sort((a, b) => {
+        const aTop = a[1][0]?.snrScore ?? -Infinity;
+        const bTop = b[1][0]?.snrScore ?? -Infinity;
+        if (aTop !== bTop)
+            return bTop - aTop;
+        return b[1].length - a[1].length; // tiebreak: larger group first
+    });
+    const receivers = [];
+    const topSites = [];
+    for (const [receiverKey, group] of sortedReceivers) {
+        const maxSnrScore = group[0]?.snrScore;
+        if (topSites.length >= topK) {
+            receivers.push({ receiver: receiverKey, total: group.length, returned: 0, maxSnrScore });
+            continue;
+        }
+        const take = Math.min(topPerReceiver, group.length, topK - topSites.length);
+        topSites.push(...group.slice(0, take));
+        receivers.push({ receiver: receiverKey, total: group.length, returned: take, maxSnrScore });
+    }
+    const truncatedByTopK = Math.max(0, filtered.length - topSites.length);
+    // 7. Budget (estimated by JSON size per site)
+    let usedBudget = 0;
+    const budgeted = [];
+    let truncatedByBudget = 0;
+    for (const site of topSites) {
+        const siteSize = estimateSiteSize(site);
+        if (usedBudget + siteSize > budget && budgeted.length > 0) {
+            truncatedByBudget = topSites.length - budgeted.length;
+            break;
+        }
+        budgeted.push(site);
+        usedBudget += siteSize;
+    }
+    return {
+        query: methodName,
+        kind: 'call',
+        totalFound: allCallSites.length,
+        returned: budgeted.length,
+        distinctReceivers,
+        receivers,
+        omitted: {
+            commentMatches: 0,
+            stringMatches: 0,
+            skippedFiles,
+            filteredByReceiver,
+            truncatedByTopK,
+            truncatedByBudget,
+        },
+        callSites: budgeted,
+    };
+}
+// ---------------------------------------------------------------------------
+// AST extraction
+// ---------------------------------------------------------------------------
+/**
+ * Walk the tree, find `method_invocation` nodes whose `name` field matches,
+ * and build CallSite records with enclosing class/method context.
+ *
+ * Java/Kotlin grammar uses `method_invocation` with `object` (receiver) and
+ * `name` (method) fields — see cgraphx/src/extraction/tree-sitter.ts:3440.
+ */
+function extractMethodInvocations(root, content, methodName, projectRoot, filePath) {
+    const sites = [];
+    const relativePath = path.relative(projectRoot, filePath).replace(/\\/g, '/');
+    (0, ast_helpers_1.walkTree)(root, (node) => {
+        if (node.type !== 'method_invocation')
+            return;
+        const nameNode = node.childForFieldName('name');
+        if (!nameNode)
+            return;
+        // methodName === null = wildcard (callees mode collects all invocations
+        // regardless of name; callers mode filters to a specific name).
+        if (methodName !== null && nameNode.text !== methodName)
+            return;
+        const objectNode = node.childForFieldName('object');
+        const receiverText = objectNode?.text ?? null;
+        sites.push({
+            methodName: nameNode.text,
+            receiverText,
+            filePath: relativePath,
+            line: node.startPosition.row + 1,
+            column: node.startPosition.column,
+            containingClass: findAncestorName(node, [
+                'class_declaration',
+                'interface_declaration',
+                'enum_declaration',
+                'record_declaration',
+                'annotation_type_declaration',
+            ]),
+            containingMethod: findAncestorName(node, [
+                'method_declaration',
+                'constructor_declaration',
+                'compact_constructor_declaration',
+            ]),
+            snippet: extractSnippet(content, node.startPosition.row, node.endPosition.row),
+            confidence: receiverText ? 'high' : 'probable',
+            reason: receiverText
+                ? `method invocation with receiver '${receiverText}'`
+                : 'unqualified method invocation (no receiver — likely same-class or static)',
+        });
+    });
+    return sites;
+}
+function findAncestorName(node, ancestorTypes) {
+    let cur = node.parent;
+    while (cur) {
+        if (ancestorTypes.includes(cur.type)) {
+            const nameChild = cur.childForFieldName('name');
+            if (nameChild)
+                return nameChild.text;
+        }
+        cur = cur.parent;
+    }
+    return null;
+}
+/**
+ * Same shape as `extractMethodInvocations` (same pre-order walk, same CallSite
+ * fields), but additionally computes `crossBoundary`, `sameClassBiz`, and
+ * `snrScore` on each site — used by callers mode (`searchCallSites`) so the
+ * downstream cluster + sort can be SNR-driven, identical to callees mode.
+ *
+ * The callees path (`searchCallees`) resolves a single method body and enriches
+ * inline; this variant is for the callers path which walks the whole project
+ * and needs per-file, per-class enrichment.
+ *
+ * Injected-field maps and sibling-method-name sets are cached per enclosing
+ * class node (a single file may host many classes — outer, inner, nested — and
+ * every method_invocation inside one class shares its body's lookup).
+ */
+function extractMethodInvocationsWithSnr(root, content, methodName, projectRoot, filePath) {
+    const sites = [];
+    const relativePath = path.relative(projectRoot, filePath).replace(/\\/g, '/');
+    const injectedFieldsByClass = new WeakMap();
+    const siblingNamesByClass = new WeakMap();
+    (0, ast_helpers_1.walkTree)(root, (node) => {
+        if (node.type !== 'method_invocation')
+            return;
+        const nameNode = node.childForFieldName('name');
+        if (!nameNode)
+            return;
+        if (methodName !== null && nameNode.text !== methodName)
+            return;
+        const objectNode = node.childForFieldName('object');
+        const receiverText = objectNode?.text ?? null;
+        // Resolve the enclosing class once for this call site, then look up (or
+        // populate) the per-class caches for injected fields + sibling method names.
+        const classNode = findEnclosingClassType(node);
+        let injectedFields;
+        let siblingNames;
+        if (classNode) {
+            injectedFields = injectedFieldsByClass.get(classNode);
+            if (!injectedFields) {
+                injectedFields = extractInjectedFields(classNode);
+                injectedFieldsByClass.set(classNode, injectedFields);
+            }
+            siblingNames = siblingNamesByClass.get(classNode);
+            if (!siblingNames) {
+                siblingNames = collectSameClassMethodNames(classNode);
+                siblingNamesByClass.set(classNode, siblingNames);
+            }
+        }
+        // xBdy: receiver matches an injected field declared in the enclosing class.
+        // (Symmetric to the callees path — a call like `customerOrderService.sceneCommit()`
+        // where `customerOrderService` is an @Resource/@Autowired/@Inject field crosses
+        // a module/service boundary and is a high-signal hop for tracing.)
+        let crossBoundary;
+        if (receiverText && injectedFields) {
+            const injected = injectedFields.get(receiverText);
+            if (injected) {
+                crossBoundary = {
+                    kind: 'injected',
+                    fieldType: injected.fieldType,
+                    annotation: injected.annotation,
+                };
+            }
+        }
+        // sameClassBiz: unqualified call whose name is a biz-verb declared as a
+        // sibling method in the same class. Only checked when NOT xBdy (xBdy
+        // short-circuits in computeSnrScore anyway, and we don't want to falsely
+        // tag an xBdy field call as sameClassBiz).
+        let sameClassBiz;
+        if (!crossBoundary &&
+            (receiverText === null || receiverText === '') &&
+            siblingNames &&
+            containsBizVerbSegment(nameNode.text) &&
+            siblingNames.has(nameNode.text)) {
+            sameClassBiz = true;
+        }
+        const site = {
+            methodName: nameNode.text,
+            receiverText,
+            filePath: relativePath,
+            line: node.startPosition.row + 1,
+            column: node.startPosition.column,
+            containingClass: findAncestorName(node, [
+                'class_declaration',
+                'interface_declaration',
+                'enum_declaration',
+                'record_declaration',
+                'annotation_type_declaration',
+            ]),
+            containingMethod: findAncestorName(node, [
+                'method_declaration',
+                'constructor_declaration',
+                'compact_constructor_declaration',
+            ]),
+            snippet: extractSnippet(content, node.startPosition.row, node.endPosition.row),
+            confidence: receiverText ? 'high' : 'probable',
+            reason: receiverText
+                ? `method invocation with receiver '${receiverText}'`
+                : 'unqualified method invocation (no receiver — likely same-class or static)',
+        };
+        if (crossBoundary)
+            site.crossBoundary = crossBoundary;
+        if (sameClassBiz)
+            site.sameClassBiz = sameClassBiz;
+        site.snrScore = computeSnrScore(site);
+        sites.push(site);
+    });
+    return sites;
+}
+function extractSnippet(content, startRow, endRow) {
+    const lines = content.split('\n');
+    // Cap snippet at 3 lines; method_invocation usually fits on 1-2 lines.
+    const maxLines = 3;
+    const sliceEnd = Math.min(endRow + 1, startRow + maxLines);
+    const snippetLines = lines.slice(startRow, sliceEnd);
+    return snippetLines.join('\n').trim();
+}
+// ---------------------------------------------------------------------------
+// Ranking + budgeting
+// ---------------------------------------------------------------------------
+/**
+ * Tiebreaker-only comparator for callers-mode call sites.
+ *
+ * Previously this was the primary ranking for `searchCallSites` (confidence +
+ * path-depth, as `compareCallSites`). After iteration-3 B-2 callers switched
+ * to SNR-driven ranking via `compareBySnr`, the SNR tiebreaker chain
+ * (filePath depth asc + filePath localeCompare + line asc, per spec §2.4)
+ * already covers every case this comparator handled, so the callers path no
+ * longer calls it.
+ *
+ * Exported as a pure tiebreaker for any external/manual sort that wants a
+ * stable order without caring about SNR — symmetric to `compareBySnr` minus
+ * the SNR primary key.
+ */
+function compareCallSitesTiebreak(a, b) {
+    // Shallower path = likely more central (controller/service > impl/detail)
+    const aDepth = a.filePath.split('/').length;
+    const bDepth = b.filePath.split('/').length;
+    if (aDepth !== bDepth)
+        return aDepth - bDepth;
+    // Stable tiebreak by file:line
+    if (a.filePath !== b.filePath)
+        return a.filePath.localeCompare(b.filePath);
+    return a.line - b.line;
+}
+function estimateSiteSize(site) {
+    // Rough: snippet dominates. Count snippet + fixed overhead per field.
+    return site.snippet.length + 200;
+}
+// ---------------------------------------------------------------------------
+// File walk
+// ---------------------------------------------------------------------------
+async function listJavaFamilyFiles(projectRoot, excludeDirs) {
+    const results = [];
+    await walkDir(projectRoot, projectRoot, excludeDirs, results);
+    return results;
+}
+async function walkDir(root, currentDir, excludeDirs, results) {
+    let entries;
+    try {
+        entries = await fs_1.promises.readdir(currentDir, { withFileTypes: true });
+    }
+    catch {
+        return;
+    }
+    for (const entry of entries) {
+        if (entry.isDirectory()) {
+            if (excludeDirs.has(entry.name))
+                continue;
+            // Skip hidden dirs (except none — we exclude all starting with '.')
+            if (entry.name.startsWith('.') && entry.name !== '.')
+                continue;
+            await walkDir(root, path.join(currentDir, entry.name), excludeDirs, results);
+        }
+        else if (entry.isFile()) {
+            const ext = path.extname(entry.name).toLowerCase();
+            if (JAVA_FAMILY_EXTENSIONS.has(ext)) {
+                results.push(path.join(currentDir, entry.name));
+            }
+        }
+    }
+}
+// ---------------------------------------------------------------------------
+// Formatting (CLI / MCP consume these)
+// ---------------------------------------------------------------------------
+/**
+ * Format the result as agent-friendly markdown. Compact by default to keep
+ * token cost low — agent gets signal density without reading whole files.
+ */
+function formatCallSitesResult(result, options) {
+    const lines = [];
+    const receiverWord = result.distinctReceivers === 1 ? 'receiver' : 'receivers';
+    lines.push(`**Call sites for \`${result.query}\` (${result.totalFound} found across ${result.distinctReceivers} ${receiverWord}, returning ${result.returned})**`);
+    // Group callSites by receiver — they're already clustered + ordered by
+    // SNR in searchCallSites: receiver groups sorted by the group's top caller
+    // SNR score (xBdy injected-service callers first, noise groups last), and
+    // within each group callers are sorted by SNR desc. We just walk and split
+    // on receiver change.
+    let currentReceiver = undefined;
+    for (const site of result.callSites) {
+        if (site.receiverText !== currentReceiver) {
+            const summary = result.receivers.find((r) => r.receiver === site.receiverText);
+            const label = site.receiverText ?? '(unqualified)';
+            const totalStr = summary
+                ? ` (${summary.total} ${summary.total === 1 ? 'call' : 'calls'}${summary.returned < summary.total ? `, top ${summary.returned}` : ''})`
+                : '';
+            lines.push('');
+            lines.push(`### ${label}.${site.methodName}${totalStr}`);
+            currentReceiver = site.receiverText;
+        }
+        const loc = `${site.filePath}:${site.line}`;
+        const ctx = [];
+        if (site.containingMethod) {
+            ctx.push(site.containingClass ? `${site.containingClass}#${site.containingMethod}` : `#${site.containingMethod}`);
+        }
+        else if (site.containingClass) {
+            ctx.push(site.containingClass);
+        }
+        const ctxStr = ctx.length > 0 ? `  _in ${ctx.join(' :: ')}_` : '';
+        lines.push(`- \`${site.confidence}\` — ${site.reason}`);
+        lines.push(`  \`${loc}\`${ctxStr}`);
+        if (site.snippet) {
+            const snippetLines = site.snippet.split('\n').slice(0, 3);
+            for (const sl of snippetLines) {
+                lines.push(`  > ${sl}`);
+            }
+        }
+        if (options?.explain) {
+            lines.push(`  _score: ${formatSnrBreakdown(site)}_`);
+        }
+    }
+    // Omitted summary — transparency so agent knows what was filtered
+    const o = result.omitted;
+    const omittedParts = [];
+    if (o.skippedFiles > 0)
+        omittedParts.push(`${o.skippedFiles} files without text match`);
+    if (o.filteredByReceiver > 0)
+        omittedParts.push(`${o.filteredByReceiver} filtered by receiver`);
+    if (o.truncatedByTopK > 0)
+        omittedParts.push(`${o.truncatedByTopK} past topK`);
+    if (o.truncatedByBudget > 0)
+        omittedParts.push(`${o.truncatedByBudget} truncated by budget`);
+    if (omittedParts.length > 0) {
+        lines.push('');
+        lines.push(`_Omitted: ${omittedParts.join(' · ')}_`);
+    }
+    // Other receivers truncated by topK — surfaced so the agent knows they
+    // exist without re-querying. Tells the agent "if you need calls from these
+    // receivers, re-query with --receiver X".
+    const unreturnedReceivers = result.receivers.filter((r) => r.returned === 0);
+    if (unreturnedReceivers.length > 0) {
+        lines.push('');
+        const summary = unreturnedReceivers
+            .map((r) => `${r.receiver ?? '(unqualified)'} (${r.total})`)
+            .join(' · ');
+        lines.push(`_Other receivers (topK reached, use \`-r <receiver>\` to drill in): ${summary}_`);
+    }
+    lines.push('');
+    lines.push('_Note: AST-based — comments and string literals are excluded by construction (reported as 0)._');
+    return lines.join('\n');
+}
+/**
+ * Resolve a symbol reference to its AST method_declaration node.
+ *
+ * Supported formats:
+ *   - `file:line`        — absolute precision; finds the method_declaration containing that line
+ *   - `Class#method`     — text-search for `class Class`, then AST-verifies the method inside
+ *   - `pkg.Class#method` — same as above, pkg is currently ignored (text search by Class name only)
+ */
+async function resolveMethodSymbol(projectRoot, symbol, languages) {
+    // Case 1: file:line
+    const lineMatch = symbol.match(/^(.+):(\d+)$/);
+    if (lineMatch) {
+        const [, relPath, lineStr] = lineMatch;
+        if (!relPath || !lineStr) {
+            throw new Error(`Invalid file:line symbol: "${symbol}"`);
+        }
+        const file = path.resolve(projectRoot, relPath);
+        const content = await fs_1.promises.readFile(file, 'utf-8');
+        const language = (0, grammars_1.detectLanguage)(file, content);
+        if (!languages.includes(language)) {
+            throw new Error(`File ${relPath} is ${language}, not in supported ${languages.join('/')}`);
+        }
+        await (0, grammars_1.loadGrammarsForLanguages)([language]);
+        const parser = (0, grammars_1.getParser)(language);
+        if (!parser)
+            throw new Error(`No parser available for ${language}`);
+        const tree = parser.parse(content);
+        if (!tree)
+            throw new Error(`Failed to parse ${relPath}`);
+        const line = parseInt(lineStr, 10);
+        const methodNode = findMethodDeclarationContaining(tree.rootNode, line);
+        if (!methodNode) {
+            throw new Error(`No method_declaration contains line ${line} in ${relPath}`);
+        }
+        return {
+            file,
+            methodNode,
+            methodQualifiedName: qualifyMethod(methodNode),
+        };
+    }
+    // Case 2: Class#method
+    const hashMatch = symbol.match(/^(?:([\w.]+)\.)?(\w+)#(\w+)$/);
+    if (hashMatch) {
+        const [, , className, methodName] = hashMatch;
+        if (!className || !methodName) {
+            throw new Error(`Invalid Class#method symbol: "${symbol}"`);
+        }
+        const candidateFiles = await findFilesWithClass(projectRoot, className);
+        await (0, grammars_1.loadGrammarsForLanguages)(languages);
+        let lastErr = null;
+        for (const file of candidateFiles) {
+            let content;
+            try {
+                content = await fs_1.promises.readFile(file, 'utf-8');
+            }
+            catch {
+                continue;
+            }
+            const language = (0, grammars_1.detectLanguage)(file, content);
+            if (!languages.includes(language))
+                continue;
+            const parser = (0, grammars_1.getParser)(language);
+            if (!parser)
+                continue;
+            const tree = parser.parse(content);
+            if (!tree)
+                continue;
+            const methodNode = findMethodInClass(tree.rootNode, className, methodName);
+            if (methodNode) {
+                return {
+                    file,
+                    methodNode,
+                    methodQualifiedName: `${className}#${methodName}`,
+                };
+            }
+            lastErr = new Error(`Class ${className} found in ${file} but method ${methodName} not declared`);
+        }
+        throw lastErr ?? new Error(`Class ${className} not found in any source file`);
+    }
+    throw new Error(`Unrecognized symbol format: "${symbol}". Use "file:line" (e.g., src/Foo.java:82) or "Class#method" (e.g., Foo#bar).`);
+}
+/**
+ * Find the deepest method_declaration whose range contains `line`.
+ * Tolerates nested methods (anonymous classes / lambdas) by preferring the inner-most.
+ */
+function findMethodDeclarationContaining(root, line) {
+    let best = null;
+    (0, ast_helpers_1.walkTree)(root, (n) => {
+        if (n.type === 'method_declaration' ||
+            n.type === 'constructor_declaration' ||
+            n.type === 'compact_constructor_declaration') {
+            const startLine = n.startPosition.row + 1;
+            const endLine = n.endPosition.row + 1;
+            if (line >= startLine && line <= endLine) {
+                // Deepest = latest-starting (inner-most for nested)
+                if (!best || n.startPosition.row > best.startPosition.row) {
+                    best = n;
+                }
+            }
+        }
+    });
+    return best;
+}
+/**
+ * Find a method_declaration named `methodName` inside any class/interface/enum/record
+ * named `className`. Walks all type-declaration kinds so that interface methods
+ * (`IFoo#bar`) resolve correctly, not just concrete-class methods.
+ */
+function findMethodInClass(root, className, methodName) {
+    let found = null;
+    (0, ast_helpers_1.walkTree)(root, (n) => {
+        if (found)
+            return;
+        if (n.type !== 'class_declaration' &&
+            n.type !== 'interface_declaration' &&
+            n.type !== 'enum_declaration' &&
+            n.type !== 'record_declaration')
+            return;
+        const nameNode = n.childForFieldName('name');
+        if (!nameNode || nameNode.text !== className)
+            return;
+        (0, ast_helpers_1.walkTree)(n, (m) => {
+            if (found)
+                return;
+            if (m.type !== 'method_declaration' && m.type !== 'constructor_declaration')
+                return;
+            const mNameNode = m.childForFieldName('name');
+            if (mNameNode && mNameNode.text === methodName) {
+                found = m;
+            }
+        });
+    });
+    return found;
+}
+function qualifyMethod(methodNode) {
+    const classNode = findAncestorName(methodNode, [
+        'class_declaration',
+        'interface_declaration',
+        'enum_declaration',
+        'record_declaration',
+    ]);
+    const nameNode = methodNode.childForFieldName('name');
+    const methodName = nameNode?.text ?? '<anonymous>';
+    return classNode ? `${classNode}#${methodName}` : methodName;
+}
+/**
+ * Find the nearest enclosing named type declaration (class/interface/enum/record)
+ * for a node. Returns the declaration node itself, not just its name.
+ */
+function findEnclosingClassType(node) {
+    let cur = node.parent;
+    while (cur) {
+        if (cur.type === 'class_declaration' ||
+            cur.type === 'interface_declaration' ||
+            cur.type === 'enum_declaration' ||
+            cur.type === 'record_declaration') {
+            return cur;
+        }
+        cur = cur.parent;
+    }
+    return null;
+}
+/**
+ * Walk a class body, find every field_declaration whose modifiers carry an
+ * injection annotation (@Resource / @Autowired / @Inject), and return a map
+ * keyed by field name. Used to mark cross-boundary callees.
+ *
+ * Java/Kotlin grammar: `field_declaration` has `modifiers` (list of modifier
+ * + annotation nodes) and `type`, and contains one or more `variable_declarator`
+ * nodes (each with a `name`). Multiple declarators share the same type+annotation.
+ *
+ * Annotations we recognize (Java):
+ *   - jakarta/javax.annotation.Resource — JSR-250
+ *   - org.springframework.beans.factory.annotation.Autowired — Spring
+ *   - jakarta.inject.Inject — JSR-330
+ *
+ * Kotlin equivalent (kotlinx injected via spring) uses the same annotation types
+ * on `property_declaration`; we don't yet handle Kotlin property syntax, so
+ * Kotlin injection is under-detected — fine for the Java-first hx use case.
+ *
+ * The annotation short-name set lives in ./snr-constants.ts (INJECTION_ANNOTATIONS).
+ */
+function extractInjectedFields(classNode) {
+    const result = new Map();
+    (0, ast_helpers_1.walkTree)(classNode, (n) => {
+        if (n.type !== 'field_declaration')
+            return;
+        // tree-sitter-java: field_declaration has `type` as a named field, but
+        // `modifiers` is a positional child node (type 'modifiers'), not a named
+        // field — childForFieldName('modifiers') returns null. Iterate children.
+        let modifiersNode = null;
+        for (const child of n.children) {
+            if (child?.type === 'modifiers') {
+                modifiersNode = child;
+                break;
+            }
+        }
+        if (!modifiersNode)
+            return;
+        let annotation = null;
+        for (const child of modifiersNode.children) {
+            if (!child)
+                continue;
+            if (child.type !== 'annotation' && child.type !== 'marker_annotation')
+                continue;
+            const nameNode = child.childForFieldName('name');
+            if (!nameNode)
+                continue;
+            // Spring/javax annotations may be fully-qualified in some codebases;
+            // take the last segment for the lookup.
+            const shortName = nameNode.text.split('.').pop() ?? nameNode.text;
+            if (snr_constants_1.INJECTION_ANNOTATIONS.has(shortName)) {
+                annotation = shortName;
+                break;
+            }
+        }
+        if (!annotation)
+            return;
+        const typeNode = n.childForFieldName('type');
+        if (!typeNode)
+            return;
+        const fieldType = typeNode.text;
+        (0, ast_helpers_1.walkTree)(n, (v) => {
+            if (v.type !== 'variable_declarator')
+                return;
+            const nameNode = v.childForFieldName('name');
+            if (!nameNode || nameNode.type !== 'identifier')
+                return;
+            result.set(nameNode.text, { fieldName: nameNode.text, fieldType, annotation });
+        });
+    });
+    return result;
+}
+/**
+ * Find source files that textually look like they declare `class className`.
+ * Uses a fast regex pre-filter; AST verification happens later in findMethodInClass.
+ */
+async function findFilesWithClass(projectRoot, className) {
+    const allFiles = await listJavaFamilyFiles(projectRoot, exports.DEFAULT_EXCLUDE_DIRS);
+    const candidates = [];
+    const pattern = new RegExp(`\\b(class|interface|enum|record)\\s+${escapeRegex(className)}\\b`);
+    for (const file of allFiles) {
+        try {
+            const content = await fs_1.promises.readFile(file, 'utf-8');
+            if (pattern.test(content)) {
+                candidates.push(file);
+            }
+        }
+        catch {
+            // skip unreadable
+        }
+    }
+    return candidates;
+}
+function escapeRegex(s) {
+    return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+// ===========================================================================
+// SNR scoring (spec §2)
+//
+// Per-callee score that ranks "agent would need to follow this hop" higher
+// than "boilerplate the agent can ignore". Validated against 6 hx samples
+// (see docs/features/2026-07-01-calls-command/snr-probe.md).
+// ===========================================================================
+// RE_BIZ_VERB and the rest of the SNR-scoring regex/Set constants now live
+// in ./snr-constants.ts (shared with context.ts).
+/**
+ * Split a camelCase / PascalCase identifier into lowercase segments.
+ * `saleOrderSceneGroupCommit` → `['sale', 'order', 'scene', 'group', 'commit']`.
+ *
+ * Used by same-class biz detection (§2.3) so methods whose biz verb appears
+ * as an inner segment — `saleOrderSceneGroupCommit` contains `scene` and
+ * `commit` — still get tagged. The strict `^biz-verb` prefix in RE_BIZ_VERB
+ * would miss these. Probe sample 3 surfaced exactly this case.
+ */
+function camelCaseSegments(name) {
+    return name.split(/(?=[A-Z])/).map((s) => s.toLowerCase());
+}
+/** True if any camelCase segment of `name` starts with a biz verb. */
+function containsBizVerbSegment(name) {
+    return camelCaseSegments(name).some((s) => snr_constants_1.RE_BIZ_VERB.test(s));
+}
+/**
+ * Param / local VO variable names observed across the hx corpus. Matched as
+ * exact root identifier (after `rootIdentifier()` extraction). Generalized
+ * `param/params/vo/dto/resp/req/result/response/exception/e/ex/err` cover
+ * most local-var patterns; hx-specific names kept for fidelity but the
+ * heuristic generalizes via the suffix-match in `looksLikeVO`.
+ */
+const PARAM_VO_NAMES = new Set([
+    'reqVo', 'rspVo', 'reqVo1', 'rspVo1',
+    'req', 'rsp', 'request', 'response', 'resp',
+    'result', 'finalResult', 'curResult', 'responseVo', 'errRspVo',
+    'baseInfo', 'orderInfo', 'prod', 'ord', 'safe',
+    'custOrder', 'customerOrder', 'sysCustomerOrder',
+    'cartDelReqVo', 'chargeInfo', 'chargeInfoByCustOrderNbr', 'pkgGrpReqVo',
+    'confirmRspVo', 'createCustomerOrderRspVo', 'createCustomerOrderReqVo',
+    'reqReceiptVo', 'acctInfo', 'newAcctInfo', 'respAcctInfo',
+    'exception', 'e', 'ex', 'err', 't',
+    'param', 'params', 'map', 'vo', 'dto',
+]);
+/**
+ * Static-const access pattern: `UpperCamel.UPPER_SNAKE`. Catches `SoMDA.X`,
+ * `BizCodeType.X`, `ErrIntfResultCode.X`, `SomeEnum.X`. The all-caps second
+ * segment distinguishes from `UpperCamel.lowerMethod(` calls.
+ */
+const RE_STATIC_CONST = /^[A-Z][a-zA-Z0-9]*\.[A-Z][A-Z0-9_]+/;
+/**
+ * Stream-chain receiver: contains `.stream()` or a `.map(/.filter(/...` call
+ * (the opening paren distinguishes from getter `getX`).
+ */
+function isStreamChain(receiver) {
+    return (receiver.includes('.stream()') ||
+        /\.(map|filter|collect|forEach|reduce|flatMap|sorted|distinct|limit|peek)\s*\(/.test(receiver));
+}
+/**
+ * Literal receiver: starts (after whitespace/parens) with a quote or digit.
+ * Catches `"Y".equals(...)`, `0`, etc.
+ */
+function isLiteral(receiver) {
+    return /^[\s(]*["'`\d]/.test(receiver);
+}
+/**
+ * Extract the root identifier from a (possibly chained/cast) receiver.
+ * `((BxError) e)` → `e`; `sysCustomerOrder.getOrderInfo()` → `sysCustomerOrder`;
+ * `prods` → `prods`. Returns the LAST identifier in the first dot-segment,
+ * which correctly skips cast type names.
+ */
+function rootIdentifier(receiver) {
+    const firstPart = receiver.split('.')[0] ?? '';
+    const idents = firstPart.match(/[a-zA-Z_$][a-zA-Z0-9_$]*/g);
+    if (!idents || idents.length === 0)
+        return '';
+    return idents[idents.length - 1] ?? '';
+}
+/**
+ * Compute the SNR score for a callee (spec §2).
+ *
+ * Receiver features are mutually exclusive and applied first; method-name
+ * features apply on top UNLESS the receiver is xBdy (short-circuit per §2.1).
+ *
+ * xBdy callees short-circuit to +100 — every other consideration is noise
+ * relative to "this is an injected business collaborator".
+ */
+function computeSnrScore(site) {
+    return computeSnrBreakdown(site).total;
+}
+function computeSnrBreakdown(site) {
+    // xBdy short-circuit
+    if (site.crossBoundary) {
+        return { receiver: 100, method: 0, total: 100, matchedRules: ['xBdy'] };
+    }
+    let receiverScore = 0;
+    let methodScore = 0;
+    const matchedRules = [];
+    const receiver = site.receiverText ?? '';
+    const method = site.methodName;
+    // === Receiver features (mutually exclusive) ===
+    if (site.sameClassBiz) {
+        receiverScore += 50; // sibling biz-verb in same class
+        matchedRules.push('sibling');
+    }
+    else if (receiver === '') {
+        receiverScore += 10; // unqualified, not biz — likely this.helper() or static import
+        matchedRules.push('unqualified');
+    }
+    else if (isStreamChain(receiver)) {
+        receiverScore -= 60;
+        matchedRules.push('streamOp');
+    }
+    else if (isLiteral(receiver)) {
+        receiverScore -= 40;
+        matchedRules.push('literal');
+    }
+    else {
+        const root = rootIdentifier(receiver);
+        if (snr_constants_1.RE_JDK_STDLIB.test(root)) {
+            receiverScore -= 60;
+            matchedRules.push('jdkStdlib');
+        }
+        else if (snr_constants_1.RE_APACHE_UTIL.test(root)) {
+            receiverScore -= 60;
+            matchedRules.push('apacheUtil');
+        }
+        else if (snr_constants_1.RE_GUAVA.test(root)) {
+            receiverScore -= 60;
+            matchedRules.push('guavaUtil');
+        }
+        else if (root === 'log' || /Logger$/.test(root)) {
+            receiverScore -= 60;
+            matchedRules.push('logCall');
+        }
+        else if (PARAM_VO_NAMES.has(root)) {
+            receiverScore -= 30;
+            matchedRules.push('paramVo');
+        }
+        else if (RE_STATIC_CONST.test(receiver)) {
+            receiverScore -= 40;
+            matchedRules.push('staticConst');
+        }
+        else if (/Util$|Helper$/.test(root)) {
+            receiverScore -= 50;
+            matchedRules.push('utilClass');
+        }
+        else if (/(Service|Client|Api|Mapper|Repository|Facade|Gateway|Busi)$/i.test(root)) {
+            receiverScore += 60;
+            matchedRules.push('serviceIsh');
+        }
+        // else: neutral (score += 0)
+    }
+    // === Method-name features (apply to all non-xBdy, including sameClassBiz) ===
+    // sameClassBiz implies biz-verb (per §2.3), so the biz-verb branch naturally
+    // adds +30 on top of the +50 from sameClassBiz — sameClassBiz callee totals +80.
+    if (snr_constants_1.OBJECT_METHODS.has(method)) {
+        methodScore -= 80;
+        matchedRules.push('objectMethod');
+    }
+    else if (snr_constants_1.MAP_OPS.has(method)) {
+        methodScore -= 25;
+        matchedRules.push('mapOp');
+    }
+    else if (snr_constants_1.RE_GETTER.test(method)) {
+        methodScore -= 20;
+        matchedRules.push('getter');
+    }
+    else if (snr_constants_1.RE_SETTER.test(method)) {
+        methodScore -= 20;
+        matchedRules.push('setter');
+    }
+    else if (snr_constants_1.RE_BOOL_GETTER.test(method)) {
+        methodScore -= 15;
+        matchedRules.push('boolGetter');
+    }
+    else if (snr_constants_1.RE_BIZ_VERB.test(method)) {
+        methodScore += 30;
+        matchedRules.push('bizVerb');
+    }
+    return {
+        receiver: receiverScore,
+        method: methodScore,
+        total: receiverScore + methodScore,
+        matchedRules,
+    };
+}
+/**
+ * Format an SNR breakdown as a single-line score explanation for the
+ * `--explain` flag. Shape:
+ *   `+100 xBdy = 100`
+ *   `+60 serviceIsh +30 bizVerb = 90`
+ *   `-60 jdkStdlib -80 objectMethod = -140`
+ *   `+10 unqualified -25 mapOp = -15`
+ *
+ * Neutral axes (no rule fired) are omitted to keep the breakdown scannable.
+ *
+ * Only fires on non-impact call sites — impact call sites have hop decay and
+ * use `formatImpactSnrBreakdown` instead.
+ */
+function formatSnrBreakdown(site) {
+    const bd = computeSnrBreakdown(site);
+    const receiverRules = bd.matchedRules.filter(isReceiverRule);
+    const methodRules = bd.matchedRules.filter(isMethodRule);
+    const parts = [];
+    // xBdy short-circuits, so receiver is the only axis that matters.
+    if (receiverRules.length > 0) {
+        parts.push(formatScoreComponent(bd.receiver, receiverRules));
+    }
+    if (methodRules.length > 0) {
+        parts.push(formatScoreComponent(bd.method, methodRules));
+    }
+    // Edge case: both axes neutral (score 0, no rules) — show `+0` so the
+    // line isn't empty.
+    if (parts.length === 0) {
+        parts.push('+0');
+    }
+    return `${parts.join(' ')} = ${bd.total}`;
+}
+/**
+ * Format a score component as `[+|-]<points> <rule1,rule2>`.
+ */
+function formatScoreComponent(score, rules) {
+    const sign = score >= 0 ? '+' : '';
+    const rulesStr = rules.length > 0 ? ` ${rules.join(',')}` : '';
+    return `${sign}${score}${rulesStr}`;
+}
+/**
+ * Receiver-axis rules — those applied first (mutually exclusive). Used to
+ * split the breakdown into receiver / method halves for display.
+ */
+const RECEIVER_RULES = new Set([
+    'xBdy',
+    'sibling',
+    'unqualified',
+    'streamOp',
+    'literal',
+    'jdkStdlib',
+    'apacheUtil',
+    'guavaUtil',
+    'logCall',
+    'paramVo',
+    'staticConst',
+    'utilClass',
+    'serviceIsh',
+]);
+function isReceiverRule(rule) {
+    return RECEIVER_RULES.has(rule);
+}
+function isMethodRule(rule) {
+    return !RECEIVER_RULES.has(rule);
+}
+/**
+ * Compare two callees by SNR score desc, then by filePath depth asc (shallower
+ * = more central), then by line asc (call order). Stable tiebreaker chain.
+ */
+function compareBySnr(a, b) {
+    const sa = a.snrScore ?? 0;
+    const sb = b.snrScore ?? 0;
+    if (sa !== sb)
+        return sb - sa;
+    const da = a.filePath.split('/').length;
+    const db = b.filePath.split('/').length;
+    if (da !== db)
+        return da - db;
+    if (a.filePath !== b.filePath)
+        return a.filePath.localeCompare(b.filePath);
+    return a.line - b.line;
+}
+/**
+ * Collect names of all method/constructor declarations directly in a class body.
+ * Used by same-class biz-verb detection (§2.3) — when an unqualified call's
+ * method name is in this set AND matches a biz-verb regex, mark the callee as
+ * `sameClassBiz: true`.
+ *
+ * Walks only direct children of the class_body (no nested-class descent) so
+ * that a method declared in an inner class isn't mistaken for a sibling of
+ * the outer class's methods.
+ */
+function collectSameClassMethodNames(classNode) {
+    const names = new Set();
+    // Find the class_body child of the class_declaration.
+    let body = null;
+    for (const child of classNode.children) {
+        if (child?.type === 'class_body' || child?.type === 'enum_body' || child?.type === 'interface_body' || child?.type === 'record_body') {
+            body = child;
+            break;
+        }
+    }
+    if (!body)
+        return names;
+    // Direct children only (no descent) — avoids catching inner-class methods.
+    for (const child of body.children) {
+        if (!child)
+            continue;
+        if (child.type === 'method_declaration' ||
+            child.type === 'constructor_declaration' ||
+            child.type === 'compact_constructor_declaration') {
+            const nameNode = child.childForFieldName('name');
+            if (nameNode)
+                names.add(nameNode.text);
+        }
+    }
+    return names;
+}
+/**
+ * Mark `sameClassBiz: true` on each callee that satisfies §2.3:
+ *   - receiverText is null (unqualified call)
+ *   - methodName contains a biz-verb segment (camelCase-aware — catches
+ *     `saleOrderSceneGroupCommit`, which the strict prefix regex misses)
+ *   - methodName is declared in the same class
+ *
+ * Returns a new array (does not mutate input). Exported for unit tests;
+ * production path inlines the same logic in `searchCallees` to avoid the
+ * extra array copy.
+ */
+function markSameClassBiz(callees, siblingNames) {
+    return callees.map((c) => {
+        if ((c.receiverText === null || c.receiverText === '') &&
+            containsBizVerbSegment(c.methodName) &&
+            siblingNames.has(c.methodName)) {
+            return { ...c, sameClassBiz: true };
+        }
+        return c;
+    });
+}
+/**
+ * Find callees of a method — what does it call internally?
+ * Walks the method body and collects every method_invocation, clustered by receiver.
+ *
+ * Ranking (spec §2):
+ *   1. crossBoundary (`@Resource`/`@Autowired`/`@Inject`) — SNR +100
+ *   2. sameClassBiz (unqualified + biz-verb + declared in same class) — SNR +50
+ *   3. service-ish receiver name — SNR +60
+ *   4. JDK/Apache stdlib, stream chains, param/local VO — negative scores
+ *   5. method-name patterns stacked on top (except for xBdy which short-circuits)
+ *
+ * Cross-boundary detection walks the enclosing class for injected field
+ * declarations; same-class biz detection walks it for sibling method names.
+ * Both feed into `computeSnrScore`, which is what the sort uses.
+ *
+ * Tiered budget (spec §3): essential tier always emitted for every kept
+ * callee; recommended/optional tiers filled in SNR order while budget
+ * remains. `withSnippet` forces minimum recommended tier; `full` forces
+ * optional tier and ignores the budget ceiling.
+ */
+async function searchCallees(projectRoot, symbol, options = {}) {
+    const { topK = 20, topPerReceiver = 3, budget = 4000, languages = ['java', 'kotlin'], withSnippet = false, full = false, } = options;
+    // 1. Resolve symbol → method_declaration AST node
+    const resolved = await resolveMethodSymbol(projectRoot, symbol, languages);
+    const content = await fs_1.promises.readFile(resolved.file, 'utf-8');
+    // 2. Walk the method body, collect ALL method_invocation (wildcard)
+    const rawCallees = extractMethodInvocations(resolved.methodNode, content, null, // null = wildcard (collect every method_invocation in the body)
+    projectRoot, resolved.file);
+    // 3. Cross-boundary + same-class biz detection
+    const classNode = findEnclosingClassType(resolved.methodNode);
+    const injectedFields = classNode
+        ? extractInjectedFields(classNode)
+        : new Map();
+    const siblingNames = classNode ? collectSameClassMethodNames(classNode) : new Set();
+    const allCallees = rawCallees.map((site) => {
+        // xBdy
+        if (site.receiverText) {
+            const injected = injectedFields.get(site.receiverText);
+            if (injected) {
+                site.crossBoundary = {
+                    kind: 'injected',
+                    fieldType: injected.fieldType,
+                    annotation: injected.annotation,
+                };
+            }
+        }
+        // sameClassBiz (only if NOT xBdy — xBdy short-circuits in computeSnrScore anyway,
+        // but we also don't want to falsely tag an xBdy field call as sameClassBiz).
+        if (!site.crossBoundary &&
+            (site.receiverText === null || site.receiverText === '') &&
+            containsBizVerbSegment(site.methodName) &&
+            siblingNames.has(site.methodName)) {
+            site.sameClassBiz = true;
+        }
+        // SNR score
+        site.snrScore = computeSnrScore(site);
+        return site;
+    });
+    // 4. Cluster by receiver
+    const distinctReceivers = new Set(allCallees.map((s) => s.receiverText)).size;
+    const byReceiver = new Map();
+    for (const site of allCallees) {
+        const key = site.receiverText;
+        const group = byReceiver.get(key) ?? [];
+        group.push(site);
+        byReceiver.set(key, group);
+    }
+    // Within each receiver group, sort by SNR desc (was: line asc)
+    for (const group of byReceiver.values()) {
+        group.sort(compareBySnr);
+    }
+    // Receivers ordered by their top callee's SNR score (was: xBdy first, then size).
+    // xBdy callees score +100 so xBdy groups naturally rise to the top; sameClassBiz
+    // groups (+80) come next; high-SNR non-xBdy groups follow; pure-noise groups
+    // (e.g., CollectionUtils) sort to the bottom.
+    const sortedReceivers = [...byReceiver.entries()].sort((a, b) => {
+        const aTop = a[1][0]?.snrScore ?? -Infinity;
+        const bTop = b[1][0]?.snrScore ?? -Infinity;
+        if (aTop !== bTop)
+            return bTop - aTop;
+        return b[1].length - a[1].length; // tiebreak: larger group first
+    });
+    const receivers = [];
+    const topSites = [];
+    for (const [receiverKey, group] of sortedReceivers) {
+        const injected = receiverKey ? injectedFields.get(receiverKey) : undefined;
+        const topSnr = group[0]?.snrScore;
+        const hasSibling = group.some((c) => c.sameClassBiz === true);
+        if (topSites.length >= topK) {
+            receivers.push({
+                receiver: receiverKey,
+                total: group.length,
+                returned: 0,
+                crossBoundary: injected,
+                sameClassBiz: hasSibling || undefined,
+                topSnrScore: topSnr,
+            });
+            continue;
+        }
+        const take = Math.min(topPerReceiver, group.length, topK - topSites.length);
+        topSites.push(...group.slice(0, take));
+        receivers.push({
+            receiver: receiverKey,
+            total: group.length,
+            returned: take,
+            crossBoundary: injected,
+            sameClassBiz: hasSibling || undefined,
+            topSnrScore: topSnr,
+        });
+    }
+    const truncatedByTopK = Math.max(0, allCallees.length - topSites.length);
+    // 5. Sort the global topSites by SNR desc (so tiered-budget pass fills in order)
+    topSites.sort(compareBySnr);
+    // 6. Apply tiered budget (spec §3)
+    const { tiered, truncatedByBudget } = applyTieredBudget(topSites, budget, {
+        forceRecommended: withSnippet,
+        forceOptional: full,
+    });
+    return {
+        symbol,
+        methodQualifiedName: resolved.methodQualifiedName,
+        filePath: path.relative(projectRoot, resolved.file).replace(/\\/g, '/'),
+        startLine: resolved.methodNode.startPosition.row + 1,
+        endLine: resolved.methodNode.endPosition.row + 1,
+        totalFound: allCallees.length,
+        returned: tiered.length,
+        distinctReceivers,
+        receivers,
+        injectedFields: [...injectedFields.values()],
+        omitted: {
+            truncatedByTopK,
+            truncatedByBudget,
+        },
+        callees: tiered,
+    };
+}
+// ===========================================================================
+// Tiered budget (spec §3)
+//
+// Three-layer output allocation: essential → recommended → optional.
+// Pass 1 emits essential for every kept callee; pass 2 upgrades callees to
+// recommended in SNR order while budget remains; pass 3 upgrades to optional.
+// `forceRecommended` (the --snippet alias) and `forceOptional` (--full) override
+// the upgrade passes uniformly.
+// ===========================================================================
+/** Per-tier marginal char cost (spec §3.3). Ratio ~1:3:10 is locked. */
+const TIER_ESSENTIAL_COST = 40;
+const TIER_RECOMMENDED_ADDITIONAL = 120;
+const TIER_OPTIONAL_ADDITIONAL = 400;
+/**
+ * Assign each callee a `tier` ('essential' | 'recommended' | 'optional')
+ * according to spec §3.2.
+ *
+ * `sorted` MUST be pre-sorted by SNR desc (use compareBySnr).
+ */
+function applyTieredBudget(sorted, budget, opts = {}) {
+    // Pass 1: how many callees fit at essential tier?
+    let count = 0;
+    let essentialBudgetUsed = 0;
+    for (let i = 0; i < sorted.length; i++) {
+        if (essentialBudgetUsed + TIER_ESSENTIAL_COST > budget && count > 0)
+            break;
+        essentialBudgetUsed += TIER_ESSENTIAL_COST;
+        count++;
+    }
+    const truncatedByBudget = sorted.length - count;
+    const tiered = sorted.slice(0, count).map((c) => ({ ...c, tier: 'essential' }));
+    // Force flags short-circuit further tier work
+    if (opts.forceOptional) {
+        for (const c of tiered)
+            c.tier = 'optional';
+        return { tiered, truncatedByBudget };
+    }
+    if (opts.forceRecommended) {
+        for (const c of tiered)
+            c.tier = 'recommended';
+        return { tiered, truncatedByBudget };
+    }
+    // Pass 2: upgrade to recommended in SNR order
+    let remaining = budget - essentialBudgetUsed;
+    for (const c of tiered) {
+        if (remaining >= TIER_RECOMMENDED_ADDITIONAL) {
+            c.tier = 'recommended';
+            remaining -= TIER_RECOMMENDED_ADDITIONAL;
+        }
+    }
+    // Pass 3: upgrade recommended → optional in SNR order
+    for (const c of tiered) {
+        if (c.tier !== 'recommended')
+            continue;
+        if (remaining >= TIER_OPTIONAL_ADDITIONAL) {
+            c.tier = 'optional';
+            remaining -= TIER_OPTIONAL_ADDITIONAL;
+        }
+    }
+    return { tiered, truncatedByBudget };
+}
+/**
+ * Format callees result as agent-friendly markdown.
+ *
+ * Three-tier output per spec §3.1:
+ *   essential   — one line per call (always emitted)
+ *   recommended — + 1–2 line snippet + enclosing Class#method
+ *   optional    — same shape as recommended in this MVP (deeper snippet
+ *                 window / imports / field decls deferred — agent can
+ *                 `Read file:line` if it needs that depth)
+ *
+ * Per-callee `tier` is set by `applyTieredBudget` (or forced via the
+ * `withSnippet`/`full` opts on `searchCallees`). Receivers are listed in
+ * SNR order — groups whose top callee scores higher come first, so
+ * xBdy/sibling groups surface at the top and pure-noise groups
+ * (CollectionUtils, Objects) sink to the bottom even when they have many
+ * calls.
+ *
+ * Empty callees (spec §5): methods with 0 internal calls get a friendly
+ * message instead of "0 across 0 receivers, returning 0" (which reads as
+ * an error).
+ */
+function formatCalleesResult(result, options) {
+    const lines = [];
+    lines.push(`**Callees of \`${result.methodQualifiedName}\`**  \`${result.filePath}:${result.startLine}-${result.endLine}\``);
+    // Empty-callees UX (spec §5)
+    if (result.totalFound === 0 || result.callees.length === 0) {
+        const methodName = result.methodQualifiedName.split('#')[1] ?? '<method>';
+        lines.push('');
+        lines.push(`_Method has no internal calls — likely returns a constant, field, or a single delegate._`);
+        lines.push(`_Try \`cgraphx calls ${methodName}\` to find callers, or \`Read ${result.filePath}:${result.startLine}\` to see the body._`);
+        return lines.join('\n');
+    }
+    lines.push(`— ${result.totalFound} internal call${result.totalFound === 1 ? '' : 's'} across ${result.distinctReceivers} receiver${result.distinctReceivers === 1 ? '' : 's'}, returning ${result.returned}`);
+    // Iterate receivers in SNR order (searchCallees already sorted them by topSnrScore).
+    // For each receiver with `returned > 0`, print group header + its callees in SNR order.
+    for (const recvSummary of result.receivers) {
+        if (recvSummary.returned === 0)
+            continue;
+        const recvCallees = result.callees.filter((c) => c.receiverText === recvSummary.receiver);
+        if (recvCallees.length === 0)
+            continue;
+        const label = recvSummary.receiver ?? '(unqualified)';
+        const totalStr = ` (${recvSummary.total} ${recvSummary.total === 1 ? 'call' : 'calls'}${recvSummary.returned < recvSummary.total ? `, top ${recvSummary.returned}` : ''})`;
+        const tagStr = recvSummary.crossBoundary
+            ? ` — \`${recvSummary.crossBoundary.fieldType}\` @${recvSummary.crossBoundary.annotation} **[xBdy]**`
+            : recvSummary.sameClassBiz
+                ? ` **[sibling]**`
+                : '';
+        lines.push('');
+        lines.push(`### ${label}${totalStr}${tagStr}`);
+        for (const c of recvCallees) {
+            // Essential line — always emitted
+            lines.push(`- **${c.methodName}** L${c.line}`);
+            // Recommended / optional tier — snippet + enclosing context
+            if (c.tier === 'recommended' || c.tier === 'optional') {
+                if (c.snippet) {
+                    const snippetLines = c.snippet.split('\n').slice(0, 2);
+                    for (const sl of snippetLines) {
+                        lines.push(`  > ${sl}`);
+                    }
+                }
+                if (c.containingClass && c.containingMethod) {
+                    lines.push(`  _in ${c.containingClass}#${c.containingMethod}_`);
+                }
+                else if (c.containingMethod) {
+                    lines.push(`  _in #${c.containingMethod}_`);
+                }
+            }
+            if (options?.explain) {
+                lines.push(`  _score: ${formatSnrBreakdown(c)}_`);
+            }
+        }
+    }
+    // Omitted summary
+    const o = result.omitted;
+    const omittedParts = [];
+    if (o.truncatedByTopK > 0)
+        omittedParts.push(`${o.truncatedByTopK} past topK`);
+    if (o.truncatedByBudget > 0)
+        omittedParts.push(`${o.truncatedByBudget} truncated by budget`);
+    if (omittedParts.length > 0) {
+        lines.push('');
+        lines.push(`_Omitted: ${omittedParts.join(' · ')}_`);
+    }
+    // Receivers truncated by topK — surfaced so agent knows they exist
+    const unreturnedReceivers = result.receivers.filter((r) => r.returned === 0);
+    if (unreturnedReceivers.length > 0) {
+        lines.push('');
+        const summary = unreturnedReceivers
+            .map((r) => {
+            const tag = r.crossBoundary
+                ? ` [xBdy:${r.crossBoundary.fieldType}]`
+                : r.sameClassBiz
+                    ? ' [sibling]'
+                    : '';
+            return `${r.receiver ?? '(unqualified)'} (${r.total})${tag}`;
+        })
+            .join(' · ');
+        lines.push(`_Other receivers (topK reached): ${summary}_`);
+    }
+    return lines.join('\n');
+}
+//# sourceMappingURL=call-sites.js.map