cgraphx 1.1.0 → 1.2.0

package/dist/resolution/stdlib-blocklist.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"stdlib-blocklist.js","sourceRoot":"","sources":["../../src/resolution/stdlib-blocklist.ts"],"names":[],"mappings":"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"}

package/dist/search/ast-helpers.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Shared small AST helpers used across the search subsystem
+ * (call-sites / context / slice / related / impact).
+ *
+ * Extracted in iteration-3 B-1 to eliminate cross-file duplication.
+ * Pure refactoring — no behavior change.
+ */
+import type { Node as SyntaxNode } from 'web-tree-sitter';
+/**
+ * Find the `modifiers` positional child wrapper of a declaration node.
+ *
+ * Tree-sitter-java groups annotations + modifier keywords into a `modifiers`
+ * wrapper, but it is NOT exposed as a named field — must iterate children by
+ * type. Used by `extractAnnotations` and `extractModifiers`.
+ */
+export declare function findModifiersChild(node: SyntaxNode): SyntaxNode | null;
+/**
+ * Walk the entire subtree rooted at `node` in document order, invoking `fn`
+ * on every node (including `node` itself). Pre-order traversal.
+ */
+export declare function walkTree(node: SyntaxNode, fn: (n: SyntaxNode) => void): void;
+/**
+ * Extract annotation short-names from a declaration's `modifiers` child.
+ *
+ * Tree-sitter-java: `modifiers` is a positional child wrapper (NOT a named
+ * field), holding annotation + modifier nodes. Returns normalized short-names
+ * prefixed with `@` (e.g. `@Override`, `@Service`), package prefix stripped.
+ */
+export declare function extractAnnotations(node: SyntaxNode): string[];
+/**
+ * Extract modifier keywords (public/private/static/final/abstract/etc.) from
+ * a declaration's `modifiers` child. Modifier keywords appear as either
+ * `modifier` nodes or bare text tokens; both forms are covered.
+ */
+export declare function extractModifiers(node: SyntaxNode): string[];
+/**
+ * Extract a short declaration snippet: the declaration line + up to 2 more
+ * lines (capped at 3 total) starting from the node's start row. Used by the
+ * slice command to preview matched declarations.
+ */
+export declare function extractDeclSnippet(content: string, node: SyntaxNode): string;
+//# sourceMappingURL=ast-helpers.d.ts.map

package/dist/search/ast-helpers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ast-helpers.d.ts","sourceRoot":"","sources":["../../src/search/ast-helpers.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,IAAI,IAAI,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAE1D;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,UAAU,GAAG,UAAU,GAAG,IAAI,CAKtE;AAED;;;GAGG;AACH,wBAAgB,QAAQ,CAAC,IAAI,EAAE,UAAU,EAAE,EAAE,EAAE,CAAC,CAAC,EAAE,UAAU,KAAK,IAAI,GAAG,IAAI,CAM5E;AAED;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,UAAU,GAAG,MAAM,EAAE,CAgB7D;AAYD;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,UAAU,GAAG,MAAM,EAAE,CAW3D;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,UAAU,GAAG,MAAM,CAK5E"}

package/dist/search/ast-helpers.js

@@ -0,0 +1,106 @@
+"use strict";
+/**
+ * Shared small AST helpers used across the search subsystem
+ * (call-sites / context / slice / related / impact).
+ *
+ * Extracted in iteration-3 B-1 to eliminate cross-file duplication.
+ * Pure refactoring — no behavior change.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.findModifiersChild = findModifiersChild;
+exports.walkTree = walkTree;
+exports.extractAnnotations = extractAnnotations;
+exports.extractModifiers = extractModifiers;
+exports.extractDeclSnippet = extractDeclSnippet;
+/**
+ * Find the `modifiers` positional child wrapper of a declaration node.
+ *
+ * Tree-sitter-java groups annotations + modifier keywords into a `modifiers`
+ * wrapper, but it is NOT exposed as a named field — must iterate children by
+ * type. Used by `extractAnnotations` and `extractModifiers`.
+ */
+function findModifiersChild(node) {
+    for (const child of node.children) {
+        if (child?.type === 'modifiers')
+            return child;
+    }
+    return null;
+}
+/**
+ * Walk the entire subtree rooted at `node` in document order, invoking `fn`
+ * on every node (including `node` itself). Pre-order traversal.
+ */
+function walkTree(node, fn) {
+    fn(node);
+    for (let i = 0; i < node.childCount; i++) {
+        const child = node.child(i);
+        if (child)
+            walkTree(child, fn);
+    }
+}
+/**
+ * Extract annotation short-names from a declaration's `modifiers` child.
+ *
+ * Tree-sitter-java: `modifiers` is a positional child wrapper (NOT a named
+ * field), holding annotation + modifier nodes. Returns normalized short-names
+ * prefixed with `@` (e.g. `@Override`, `@Service`), package prefix stripped.
+ */
+function extractAnnotations(node) {
+    const out = [];
+    const modifiers = findModifiersChild(node);
+    if (!modifiers)
+        return out;
+    for (const child of modifiers.children) {
+        if (!child)
+            continue;
+        if (child.type === 'annotation' || child.type === 'marker_annotation') {
+            const name = child.childForFieldName('name')?.text;
+            if (name) {
+                // Normalize: strip package prefix, prefix with @
+                const shortName = name.split('.').pop() ?? name;
+                out.push(`@${shortName}`);
+            }
+        }
+    }
+    return out;
+}
+/**
+ * Modifier keyword set used by `extractModifiers` to recognize bare modifier
+ * keywords that tree-sitter-java may emit as plain tokens rather than as
+ * `modifier` nodes.
+ */
+const MODIFIER_KEYWORDS = new Set([
+    'public', 'private', 'protected', 'static', 'final', 'abstract',
+    'synchronized', 'volatile', 'transient', 'native', 'strictfp', 'default',
+]);
+/**
+ * Extract modifier keywords (public/private/static/final/abstract/etc.) from
+ * a declaration's `modifiers` child. Modifier keywords appear as either
+ * `modifier` nodes or bare text tokens; both forms are covered.
+ */
+function extractModifiers(node) {
+    const out = [];
+    const modifiers = findModifiersChild(node);
+    if (!modifiers)
+        return out;
+    for (const child of modifiers.children) {
+        if (!child)
+            continue;
+        if (child.type === 'modifier' || MODIFIER_KEYWORDS.has(child.text)) {
+            out.push(child.text);
+        }
+    }
+    return out;
+}
+/**
+ * Extract a short declaration snippet: the declaration line + up to 2 more
+ * lines (capped at 3 total) starting from the node's start row. Used by the
+ * slice command to preview matched declarations.
+ */
+function extractDeclSnippet(content, node) {
+    const startRow = node.startPosition.row;
+    const lines = content.split('\n');
+    const end = Math.min(startRow + 3, lines.length);
+    return lines.slice(startRow, end).join('\n').trim();
+}
+//# sourceMappingURL=ast-helpers.js.map

package/dist/search/ast-helpers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ast-helpers.js","sourceRoot":"","sources":["../../src/search/ast-helpers.ts"],"names":[],"mappings":"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"}

package/dist/search/call-sites.d.ts

@@ -0,0 +1,398 @@
+/**
+ * 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.
+ */
+import type { Node as SyntaxNode } from 'web-tree-sitter';
+import type { Language } from '../types';
+export interface CallSite {
+    /** Method name as written at the call site (e.g. "createOrder"). */
+    methodName: string;
+    /** Receiver text if any (e.g. "orderService" in "orderService.createOrder()"). null for unqualified calls. */
+    receiverText: string | null;
+    /** File path relative to projectRoot. */
+    filePath: string;
+    /** 1-based line number. */
+    line: number;
+    /** 0-based column. */
+    column: number;
+    /** Enclosing class/interface/enum/record name, if inside one. */
+    containingClass: string | null;
+    /** Enclosing method/constructor name, if inside one. */
+    containingMethod: string | null;
+    /** Trimmed source snippet (≤ 3 lines around the call). */
+    snippet: string;
+    /** Confidence label — lets the agent judge without fake-precise numbers. */
+    confidence: 'high' | 'probable' | 'possible';
+    /** Human-readable reason for the confidence label. */
+    reason: string;
+    /**
+     * Cross-boundary signal — set when the receiver is a field injected by
+     * Spring/CDI (@Resource / @Autowired / @Inject). Such calls cross module
+     * or service boundaries (often via HTTP/RPC stubs), so they are the high-
+     * value hops when tracing a flow. Absent → not an injected-field call.
+     */
+    crossBoundary?: {
+        kind: 'injected';
+        fieldType: string;
+        annotation: string;
+    };
+    /**
+     * Same-class business-verb signal — set when receiverText is null
+     * (unqualified call), the method name matches a business-verb regex,
+     * AND the method is declared in the same class as the calling method
+     * (sibling business method). Closes the "(unqualified) put/toString
+     * buries real siblings" gap surfaced by snr-probe sample 3.
+     */
+    sameClassBiz?: boolean;
+    /**
+     * SNR score (signal-to-noise rank) — higher = more likely the agent
+     * needs to follow this hop. Computed by computeSnrScore() per spec §2.
+     * Set after extraction, before sort.
+     */
+    snrScore?: number;
+    /**
+     * Tier assigned by applyTieredBudget(): 'essential' (always emitted,
+     * one-line), 'recommended' (essential + 1–2 line snippet), or
+     * 'optional' (recommended + body + imports).
+     */
+    tier?: 'essential' | 'recommended' | 'optional';
+}
+export interface SearchCallOptions {
+    /** Max call sites to return after ranking. Default 20. */
+    topK?: number;
+    /**
+     * Max call sites per distinct receiver (clustering). Default 3.
+     *
+     * High-frequency methods (isNotEmpty, valueOf, nonNull, ...) get called by
+     * many different receivers. Without clustering, topK just returns the most-
+     * common receiver's first K calls — the agent sees 20 CollectionUtils.isNotEmpty
+     * and misses StringUtils.isNotEmpty entirely. topPerReceiver ensures each
+     * receiver gets representation up to this cap, so the agent sees the call
+     * distribution across receivers in one query.
+     */
+    topPerReceiver?: number;
+    /** Approximate char budget for the total result. Default 4000. */
+    budget?: number;
+    /** Filter by receiver text (e.g. "orderService" to find only `orderService.X()`). */
+    receiver?: string;
+    /** Languages to scan. Default ['java', 'kotlin']. */
+    languages?: Language[];
+    /** Directory globs to exclude (in addition to built-in defaults). */
+    excludeDirs?: string[];
+}
+export interface SearchCallResult {
+    query: string;
+    kind: 'call';
+    totalFound: number;
+    returned: number;
+    /** Number of distinct receivers in the full result set (before clustering). */
+    distinctReceivers: number;
+    /**
+     * Per-receiver summary — how many calls each receiver has total, and how
+     * many were returned after clustering. Receivers with `returned: 0` were
+     * truncated by topK — listed so the agent knows they exist.
+     *
+     * `maxSnrScore` is the highest SNR score among this receiver's call sites
+     * (after sort, that's group[0].snrScore). Exposed so the formatter can order
+     * groups by signal strength rather than by size. Absent only if the group
+     * is somehow empty (shouldn't happen in practice).
+     */
+    receivers: Array<{
+        receiver: string | null;
+        total: number;
+        returned: number;
+        maxSnrScore?: number;
+    }>;
+    omitted: {
+        /** AST excludes these by construction — reported as 0 for transparency. */
+        commentMatches: number;
+        stringMatches: number;
+        /** Files skipped because they didn't contain the methodName as text (pre-parse filter). */
+        skippedFiles: number;
+        /** Call sites filtered out by `receiver` option. */
+        filteredByReceiver: number;
+        /** Call sites cut by topK. */
+        truncatedByTopK: number;
+        /** Call sites cut by budget. */
+        truncatedByBudget: number;
+    };
+    callSites: CallSite[];
+}
+export declare const DEFAULT_EXCLUDE_DIRS: Set<string>;
+export declare function searchCallSites(projectRoot: string, methodName: string, options?: SearchCallOptions): Promise<SearchCallResult>;
+/**
+ * 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.
+ */
+export declare function compareCallSitesTiebreak(a: CallSite, b: CallSite): number;
+export declare function listJavaFamilyFiles(projectRoot: string, excludeDirs: Set<string>): Promise<string[]>;
+/**
+ * Format the result as agent-friendly markdown. Compact by default to keep
+ * token cost low — agent gets signal density without reading whole files.
+ */
+export declare function formatCallSitesResult(result: SearchCallResult, options?: {
+    explain?: boolean;
+}): string;
+export interface CalleeOptions {
+    topK?: number;
+    topPerReceiver?: number;
+    budget?: number;
+    languages?: Language[];
+    /**
+     * Force at least the 'recommended' tier for every emitted callee
+     * (1–2 line snippet + enclosing context). Deprecated alias retained
+     * for back-compat — `-b` large enough achieves the same effect now.
+     */
+    withSnippet?: boolean;
+    /**
+     * Force the 'optional' tier for every emitted callee (full body +
+     * imports). Ignores the budget ceiling. New in the SNR/tiered-budget
+     * round per spec §4.2.
+     */
+    full?: boolean;
+}
+export interface CalleeResult {
+    /** Original symbol input. */
+    symbol: string;
+    /** Resolved Class#method. */
+    methodQualifiedName: string;
+    /** File where the method is defined (relative to projectRoot). */
+    filePath: string;
+    /** Method body range. */
+    startLine: number;
+    endLine: number;
+    totalFound: number;
+    returned: number;
+    distinctReceivers: number;
+    receivers: Array<{
+        receiver: string | null;
+        total: number;
+        returned: number;
+        /** Present when this receiver is an injected field — group is a cross-boundary candidate. */
+        crossBoundary?: {
+            fieldType: string;
+            annotation: string;
+        };
+        /** True when at least one call in this group is a same-class biz-verb call. */
+        sameClassBiz?: boolean;
+        /** Highest SNR score among this receiver's calls — drives group ordering. */
+        topSnrScore?: number;
+    }>;
+    /** All injected fields declared in the method's enclosing class. */
+    injectedFields: Array<{
+        fieldName: string;
+        fieldType: string;
+        annotation: string;
+    }>;
+    omitted: {
+        truncatedByTopK: number;
+        truncatedByBudget: number;
+    };
+    callees: CallSite[];
+}
+/**
+ * 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)
+ */
+export declare function resolveMethodSymbol(projectRoot: string, symbol: string, languages: Language[]): Promise<{
+    file: string;
+    methodNode: SyntaxNode;
+    methodQualifiedName: string;
+}>;
+/**
+ * Find the nearest enclosing named type declaration (class/interface/enum/record)
+ * for a node. Returns the declaration node itself, not just its name.
+ */
+export declare function findEnclosingClassType(node: SyntaxNode): SyntaxNode | 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).
+ */
+export declare function extractInjectedFields(classNode: SyntaxNode): Map<string, {
+    fieldName: string;
+    fieldType: string;
+    annotation: string;
+}>;
+/**
+ * Find source files that textually look like they declare `class className`.
+ * Uses a fast regex pre-filter; AST verification happens later in findMethodInClass.
+ */
+export declare function findFilesWithClass(projectRoot: string, className: string): Promise<string[]>;
+/** True if any camelCase segment of `name` starts with a biz verb. */
+export declare function containsBizVerbSegment(name: string): boolean;
+/**
+ * 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.
+ */
+export declare function rootIdentifier(receiver: string): string;
+/**
+ * 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".
+ */
+export declare function computeSnrScore(site: CallSite): number;
+/**
+ * SNR score breakdown — re-derives the score while tracking which rules
+ * fired. Used by the `--explain` flag on `calls` / `impact` so an agent can
+ * see why a callee ranked where it did. Total is always equal to
+ * `computeSnrScore(site)` (the former delegates to this).
+ *
+ * `receiver` is the receiver-axis contribution, `method` is the method-name-
+ * axis contribution. `matchedRules` names every rule that fired (signal and
+ * noise alike), in the order applied. xBdy short-circuits with a single
+ * `xBdy` rule.
+ */
+export interface SnrBreakdown {
+    receiver: number;
+    method: number;
+    total: number;
+    matchedRules: string[];
+}
+export declare function computeSnrBreakdown(site: CallSite): SnrBreakdown;
+/**
+ * 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.
+ */
+export declare function formatSnrBreakdown(site: CallSite): string;
+/**
+ * Compare two callees by SNR score desc, then by filePath depth asc (shallower
+ * = more central), then by line asc (call order). Stable tiebreaker chain.
+ */
+export declare function compareBySnr(a: CallSite, b: CallSite): number;
+/**
+ * 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.
+ */
+export declare function collectSameClassMethodNames(classNode: SyntaxNode): Set<string>;
+/**
+ * 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.
+ */
+export declare function markSameClassBiz(callees: CallSite[], siblingNames: Set<string>): CallSite[];
+/**
+ * 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.
+ */
+export declare function searchCallees(projectRoot: string, symbol: string, options?: CalleeOptions): Promise<CalleeResult>;
+export interface TieredBudgetResult {
+    tiered: CallSite[];
+    truncatedByBudget: number;
+}
+/**
+ * Assign each callee a `tier` ('essential' | 'recommended' | 'optional')
+ * according to spec §3.2.
+ *
+ * `sorted` MUST be pre-sorted by SNR desc (use compareBySnr).
+ */
+export declare function applyTieredBudget(sorted: CallSite[], budget: number, opts?: {
+    forceRecommended?: boolean;
+    forceOptional?: boolean;
+}): TieredBudgetResult;
+/**
+ * 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).
+ */
+export declare function formatCalleesResult(result: CalleeResult, options?: {
+    explain?: boolean;
+}): string;
+//# sourceMappingURL=call-sites.d.ts.map

package/dist/search/call-sites.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"call-sites.d.ts","sourceRoot":"","sources":["../../src/search/call-sites.ts"],"names":[],"mappings":"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"}