@mrclrchtr/supi-tree-sitter 6.3.0 → 7.0.0

package/node_modules/@mrclrchtr/supi-code-runtime/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mrclrchtr/supi-code-runtime",
-  "version": "6.3.0",
+  "version": "7.0.0",
   "description": "Shared workspace context and capability contracts for code intelligence",
   "license": "MIT",
   "repository": {

package/node_modules/@mrclrchtr/supi-code-runtime/src/types.ts

@@ -234,7 +234,14 @@ export type CalleeDepth = "direct" | "deep";
  */
 export interface CalleesData {
   enclosingScope: { name: string; startLine: number; endLine: number };
-  callees: Array<{ name: string; startLine: number }>;
+  /** Distinct call sites with 1-based UTF-16 start coordinates. */
+  callees: Array<{
+    name: string;
+    /** Optional syntax-shortened label for presentation; does not replace `name`. */
+    displayName?: string;
+    startLine: number;
+    startCharacter: number;
+  }>;
   depth: CalleeDepth;
 }
 

package/node_modules/@mrclrchtr/supi-core/README.md

@@ -21,6 +21,7 @@ pnpm add @mrclrchtr/supi-core
 ## Package surfaces
 
 - `@mrclrchtr/supi-core/api` — reusable helpers for other packages and extensions
+- `@mrclrchtr/supi-core/llm` — PI-owned direct model requests and JSON helpers
 - `@mrclrchtr/supi-core/report` — shared text/report rendering helpers for TUI and plain-text summaries
 
 ## What you get from the API
@@ -48,6 +49,13 @@ Config file locations:
 
 - `wrapExtensionContext()` — wrap injected text in SuPi's `<extension-context>` tag
 
+### Model requests
+
+- `completeModelRequest(ctx, model, context, options)` — complete through PI's model registry with stable feature affinity. PI owns auth and endpoint resolution.
+- `callWithJsonResponse()` — retry a registry request, extract JSON, and validate it with TypeBox.
+
+`completeModelRequest()` requires a stable `affinityScope`. It keeps cache retention defaults, does not include prompt content in the affinity ID, and adds OpenCode headers only when the provider or exact model endpoint matches OpenCode. Pass `maxTokens: model.maxTokens` when a caller needs the model's declared output cap without using PI private modules.
+
 ### Shared registries
 
 - context-provider registry for `/supi-context`

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

@@ -1,6 +1,6 @@
 {
   "name": "@mrclrchtr/supi-core",
-  "version": "6.3.0",
+  "version": "7.0.0",
   "description": "Shared settings, configuration, reporting, and session infrastructure",
   "license": "MIT",
   "repository": {

package/node_modules/@mrclrchtr/supi-core/src/footer-registry.ts

@@ -2,17 +2,24 @@
 //
 // Extensions register pre-styled text chunks with a placement hint
 // ("stats" for the metrics line, "status" for the extension status line).
-// The custom footer in supi-extras (or PI's built-in footer) reads these
-// contributions and renders them alongside the built-in metrics.
+// The custom footer in supi-extras reads these contributions and renders them
+// alongside the built-in metrics. Extensions can use PI's status API as a
+// fallback when the custom footer is not installed.
 
 import { createRegistry } from "./registry-utils.ts";
 
+/** Event emitted when a dynamic footer contribution needs a new render. */
+export const FOOTER_INVALIDATE_EVENT = "supi:footer:invalidate";
+
 /** Where the contribution should appear in the footer. */
 export type FooterPlacement = "stats" | "stats-end" | "status";
 
 /** A single footer contribution registered by an extension. */
 export interface FooterContribution {
-  /** Unique key for this contribution. Re-registering with the same key replaces it. */
+  /**
+   * Unique key for this contribution. Re-registering with the same key replaces it.
+   * A same-key Pi status is treated as this contribution's built-in-footer fallback.
+   */
   key: string;
   /** Which footer line this belongs on. */
   placement: FooterPlacement;

package/node_modules/@mrclrchtr/supi-core/src/index.ts

@@ -15,6 +15,8 @@ export * from "./debug.ts";
 // biome-ignore lint/performance/noReExportAll: intentional convenience barrel
 export * from "./footer-registry.ts";
 // biome-ignore lint/performance/noReExportAll: intentional convenience barrel
+export * from "./llm.ts";
+// biome-ignore lint/performance/noReExportAll: intentional convenience barrel
 export * from "./model-selection.ts";
 // biome-ignore lint/performance/noReExportAll: intentional convenience barrel
 export * from "./path.ts";

package/node_modules/@mrclrchtr/supi-core/src/llm.ts

@@ -1,12 +1,131 @@
-import { complete } from "@earendil-works/pi-ai/compat";
+import { createHash } from "node:crypto";
+import type {
+  Api,
+  AssistantMessage,
+  Context,
+  Model,
+  ModelsApiStreamOptions,
+  ProviderHeaders,
+} from "@earendil-works/pi-ai";
 import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
 import type { TSchema } from "typebox";
 import { Value } from "typebox/value";
 
 // Shared LLM utilities for SuPi extensions.
 //
-// Provides retry logic, structured LLM call helpers, and other
-// common patterns for extensions that interact with AI models.
+// Provides PI-owned model requests, retry logic, structured LLM call helpers,
+// and other common patterns for extensions that interact with AI models.
+
+const MODEL_REQUEST_NAMESPACE = "supi-direct-model-request-v1";
+
+/**
+ * Options for {@link completeModelRequest}.
+ *
+ * Authentication, provider environment, and session identity stay under PI
+ * control. The feature supplies a stable scope for its prompt stream.
+ */
+export type CompleteModelRequestOptions<TApi extends Api = Api> = Omit<
+  ModelsApiStreamOptions<TApi>,
+  "apiKey" | "env" | "sessionId"
+> & {
+  /** Stable feature scope. Do not include prompt, turn, or retry data. */
+  affinityScope: string;
+  /** PI owns these fields, including for APIs with open-ended option types. */
+  apiKey?: never;
+  env?: never;
+  sessionId?: never;
+};
+
+function createModelRequestAffinityId(
+  sessionId: string,
+  affinityScope: string,
+  model: Model<Api>,
+): string {
+  const material = JSON.stringify([
+    MODEL_REQUEST_NAMESPACE,
+    sessionId,
+    affinityScope,
+    model.provider,
+    model.id,
+  ]);
+  const digest = createHash("sha256").update(material, "utf8").digest("hex");
+  return `supi-${digest.slice(0, 56)}`;
+}
+
+function isOpenCodeModel(model: Model<Api>): boolean {
+  if (model.provider === "opencode" || model.provider === "opencode-go") return true;
+
+  try {
+    return new URL(model.baseUrl).hostname === "opencode.ai";
+  } catch {
+    return false;
+  }
+}
+
+function hasHeader(headers: ProviderHeaders, name: string): boolean {
+  const lowerName = name.toLowerCase();
+  return Object.keys(headers).some((headerName) => headerName.toLowerCase() === lowerName);
+}
+
+function addOpenCodeDefaultHeaders(
+  model: Model<Api>,
+  affinityId: string,
+  headers: ProviderHeaders,
+): ProviderHeaders {
+  if (!isOpenCodeModel(model)) return headers;
+
+  const result = { ...headers };
+  if (!hasHeader(result, "x-opencode-session")) {
+    result["x-opencode-session"] = affinityId;
+  }
+  if (!hasHeader(result, "x-opencode-client")) {
+    result["x-opencode-client"] = "pi";
+  }
+  return result;
+}
+
+/**
+ * Complete a direct request through PI's model registry.
+ *
+ * PI resolves authentication, provider headers, environment, and the
+ * effective endpoint. This helper adds one stable opaque session identity for
+ * the feature prompt stream and applies the OpenCode compatibility defaults.
+ * It does not retry, validate output, or present errors.
+ *
+ * When `maxTokens` is omitted, the underlying registry receives no explicit
+ * output cap. A caller that needs the selected model's declared cap can pass
+ * `maxTokens: model.maxTokens` without importing PI internals.
+ */
+export async function completeModelRequest<TApi extends Api>(
+  ctx: ExtensionContext,
+  model: Model<TApi>,
+  context: Context,
+  options: CompleteModelRequestOptions<TApi>,
+): Promise<AssistantMessage> {
+  const { affinityScope, transformHeaders: callerTransformHeaders, ...requestOptions } = options;
+  const safeRequestOptions = { ...requestOptions };
+  delete safeRequestOptions.apiKey;
+  delete safeRequestOptions.env;
+  delete safeRequestOptions.sessionId;
+
+  const affinityId = createModelRequestAffinityId(
+    ctx.sessionManager.getSessionId(),
+    affinityScope,
+    model,
+  );
+  const transformHeaders = async (headers: ProviderHeaders): Promise<ProviderHeaders> => {
+    const transformed = callerTransformHeaders ? await callerTransformHeaders(headers) : headers;
+    return addOpenCodeDefaultHeaders(model, affinityId, transformed);
+  };
+
+  // Restore PI's conditional provider-option type after removing owned fields.
+  return ctx.modelRegistry.complete(model, context, {
+    ...safeRequestOptions,
+    signal: safeRequestOptions.signal ?? ctx.signal,
+    sessionId: affinityId,
+    transformHeaders,
+  } as unknown as ModelsApiStreamOptions<TApi>);
+}
 
 /**
  * Options for {@link withRetry}.
@@ -122,6 +241,8 @@ export function extractJsonFromResponse<T extends TSchema>(
 export interface CallWithJsonResponseOptions {
   /** The prompt to send to the LLM. */
   prompt: string;
+  /** Stable feature scope for request affinity. Do not include prompt or retry data. */
+  affinityScope: string;
   /** Optional data context appended to the prompt. */
   dataContext?: string;
   /** Maximum tokens for the response. Default: 4096 */
@@ -135,8 +256,9 @@ export interface CallWithJsonResponseOptions {
 /**
  * Call the LLM with a prompt and validate the JSON response against a TypeBox schema.
  *
- * Handles model resolution, auth, retry via `withRetry`, text extraction,
- * JSON regex matching, and TypeBox validation.
+ * Handles model resolution, retry via `withRetry`, text extraction, JSON
+ * matching, and TypeBox validation. The request itself stays under PI
+ * registry authority through {@link completeModelRequest}.
  *
  * Returns `null` when:
  * - No model is available
@@ -145,7 +267,7 @@ export interface CallWithJsonResponseOptions {
  * - JSON doesn't match the schema
  * - The request is aborted
  *
- * @param ctx - The extension context for model resolution and auth.
+ * @param ctx - The extension context for model selection and PI registry access.
  * @param options - Call options including prompt, schema, and retry config.
  * @param schema - TypeBox schema to validate the JSON response against.
  * @returns The parsed and validated result, or `null`.
@@ -155,14 +277,18 @@ export async function callWithJsonResponse<T extends TSchema>(
   options: CallWithJsonResponseOptions,
   schema: T,
 ): Promise<{ parsed: import("typebox").Static<T> } | null> {
-  const { prompt, dataContext, maxTokens = 4096, systemPrompt = "", retries = 2 } = options;
+  const {
+    prompt,
+    affinityScope,
+    dataContext,
+    maxTokens = 4096,
+    systemPrompt = "",
+    retries = 2,
+  } = options;
 
   const model = ctx.model ?? ctx.modelRegistry.getAvailable()[0] ?? null;
   if (!model) return null;
 
-  const auth = await ctx.modelRegistry.getApiKeyAndHeaders(model);
-  if (!auth.ok || !auth.apiKey) return null;
-
   const fullPrompt = dataContext
     ? `${prompt}
 
@@ -171,8 +297,9 @@ ${dataContext}`
     : prompt;
 
   const response = await withRetry(
-    async () => {
-      return complete(
+    async () =>
+      completeModelRequest(
+        ctx,
         model,
         {
           systemPrompt,
@@ -185,13 +312,11 @@ ${dataContext}`
           ],
         },
         {
-          apiKey: auth.apiKey,
-          headers: auth.headers,
+          affinityScope,
           signal: ctx.signal,
           maxTokens,
         },
-      );
-    },
+      ),
     { retries, baseDelayMs: 1000, signal: ctx.signal },
   );
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mrclrchtr/supi-tree-sitter",
-  "version": "6.3.0",
+  "version": "7.0.0",
   "description": "Structural AST analysis for SuPi code intelligence",
   "license": "MIT",
   "repository": {
@@ -36,8 +36,8 @@
   "dependencies": {
     "jiti": "^2.7.0",
     "web-tree-sitter": "^0.27.0",
-    "@mrclrchtr/supi-code-runtime": "6.3.0",
-    "@mrclrchtr/supi-core": "6.3.0"
+    "@mrclrchtr/supi-code-runtime": "7.0.0",
+    "@mrclrchtr/supi-core": "7.0.0"
   },
   "bundledDependencies": [
     "@mrclrchtr/supi-code-runtime",

package/src/provider/tree-sitter-provider.ts

@@ -145,7 +145,9 @@ function mapCalleesAtResult(result: CalleesAtResult): CalleesData {
     },
     callees: result.callees.map((c) => ({
       name: c.name,
+      ...(c.displayName === undefined ? {} : { displayName: c.displayName }),
       startLine: c.range.startLine,
+      startCharacter: c.range.startCharacter,
     })),
     depth: result.depth,
   };

package/src/tool/callee-display-name.ts

@@ -0,0 +1,165 @@
+import type { SyntaxNodeLike } from "../syntax-node.ts";
+import type { GrammarId } from "../types.ts";
+import { normalizeCallName } from "./call-name.ts";
+
+type CalleeSyntaxChild = SyntaxNodeLike & {
+  readonly isExtra: boolean;
+};
+
+type CalleeSyntaxNode = SyntaxNodeLike & {
+  readonly namedChildren: CalleeSyntaxChild[];
+};
+
+type SourcePoint = { row: number; column: number };
+
+type TextReplacement = { start: number; end: number };
+
+type CalleeDisplayNameOptions = {
+  node: SyntaxNodeLike;
+  grammarId: GrammarId;
+  nodeType: string;
+  source: string;
+  sourceLineStarts: readonly number[];
+};
+
+const CALL_NODE_TYPES = new Set([
+  "call_expression",
+  "call",
+  "method_invocation",
+  "new_expression",
+  "object_creation_expression",
+]);
+
+const ARGUMENT_LIST_TYPES = new Set(["arguments", "argument_list", "value_arguments"]);
+
+const RECEIVER_FIELDS = [
+  "function",
+  "constructor",
+  "object",
+  "receiver",
+  "operand",
+  "value",
+  "lhs",
+  "argument",
+] as const;
+
+const RECEIVER_WRAPPER_TYPES = new Set(["navigation_expression", "parenthesized_expression"]);
+
+/**
+ * Create a syntax-shortened label for one structural callee capture.
+ *
+ * The full normalized name remains the identity-bearing value. This helper
+ * only replaces argument-list nodes on the receiver chain with `(…)`; it does
+ * not inspect arbitrary expression text to find parentheses.
+ */
+export function createCalleeDisplayName({
+  node,
+  grammarId,
+  nodeType,
+  source,
+  sourceLineStarts,
+}: CalleeDisplayNameOptions): string | undefined {
+  const replacements: TextReplacement[] = [];
+  collectReceiverArgumentLists(node, replacements, sourceLineStarts);
+  const selected = selectNonOverlappingReplacements(replacements);
+  const start = sourceOffset(node.startPosition, sourceLineStarts);
+  const end = sourceOffset(node.endPosition, sourceLineStarts);
+  if (start < 0 || end < start || end > source.length) return undefined;
+
+  let rendered = source.slice(start, end);
+  for (let index = selected.length - 1; index >= 0; index -= 1) {
+    const replacement = selected[index];
+    if (!replacement || replacement.start < start || replacement.end > end) continue;
+    const relativeStart = replacement.start - start;
+    const relativeEnd = replacement.end - start;
+    rendered = `${rendered.slice(0, relativeStart)}(…)${rendered.slice(relativeEnd)}`;
+  }
+
+  const displayName = normalizeCallName(rendered, grammarId, nodeType);
+  return displayName.length > 0 ? displayName : undefined;
+}
+
+function collectReceiverArgumentLists(
+  node: SyntaxNodeLike,
+  replacements: TextReplacement[],
+  sourceLineStarts: readonly number[],
+): void {
+  const argumentList = findArgumentList(node);
+  if (argumentList && hasNamedChildren(argumentList)) {
+    const start = sourceOffset(argumentList.startPosition, sourceLineStarts);
+    const end = sourceOffset(argumentList.endPosition, sourceLineStarts);
+    if (start >= 0 && end >= start) replacements.push({ start, end });
+  }
+
+  for (const receiver of receiverNodes(node)) {
+    collectReceiverArgumentLists(receiver, replacements, sourceLineStarts);
+  }
+}
+
+function findArgumentList(node: SyntaxNodeLike): SyntaxNodeLike | null {
+  if (!CALL_NODE_TYPES.has(node.type)) return null;
+
+  const field = node.childForFieldName("arguments");
+  if (field) return field;
+
+  const directArgumentList = node.children.find((child) => ARGUMENT_LIST_TYPES.has(child.type));
+  if (directArgumentList) return directArgumentList;
+
+  if (node.type !== "call_expression") return null;
+  const callSuffix = node.children.find((child) => child.type === "call_suffix");
+  return callSuffix?.children.find((child) => child.type === "value_arguments") ?? null;
+}
+
+function receiverNodes(node: SyntaxNodeLike): SyntaxNodeLike[] {
+  for (const fieldName of RECEIVER_FIELDS) {
+    const field = node.childForFieldName(fieldName);
+    if (field) return [field];
+  }
+
+  if (node.type === "call_expression") {
+    return namedChildren(node).filter(
+      (child) => child.type !== "call_suffix" && !ARGUMENT_LIST_TYPES.has(child.type),
+    );
+  }
+
+  if (!RECEIVER_WRAPPER_TYPES.has(node.type)) return [];
+  return namedChildren(node).filter((child) => !ARGUMENT_LIST_TYPES.has(child.type));
+}
+
+function namedChildren(node: SyntaxNodeLike): CalleeSyntaxChild[] {
+  return (node as CalleeSyntaxNode).namedChildren ?? [];
+}
+
+function hasNamedChildren(node: SyntaxNodeLike): boolean {
+  return namedChildren(node).some((child) => !child.isExtra);
+}
+
+function selectNonOverlappingReplacements(
+  replacements: readonly TextReplacement[],
+): TextReplacement[] {
+  const selected: TextReplacement[] = [];
+  const ordered = [...replacements].sort(
+    (left, right) => left.start - right.start || right.end - left.end,
+  );
+
+  for (const replacement of ordered) {
+    const previous = selected[selected.length - 1];
+    if (previous && replacement.start < previous.end) continue;
+    selected.push(replacement);
+  }
+  return selected;
+}
+
+/** Build source offsets for Tree-sitter rows without decoding expression text. */
+export function createSourceLineStarts(source: string): number[] {
+  const lineStarts = [0];
+  for (let index = 0; index < source.length; index += 1) {
+    if (source[index] === "\n") lineStarts.push(index + 1);
+  }
+  return lineStarts;
+}
+
+function sourceOffset(point: SourcePoint, lineStarts: readonly number[]): number {
+  const lineStart = lineStarts[point.row];
+  return lineStart === undefined ? -1 : lineStart + point.column;
+}

package/src/tool/callees.ts

@@ -1,11 +1,14 @@
+// biome-ignore-all lint/style/noExcessiveLinesPerFile: callee scope filtering and syntax display mapping stay together.
 // Structural callee extraction — enclosing-scope lookup with per-language queries.
 
 import type { CodeRequestControl } from "@mrclrchtr/supi-code-runtime/api";
 import { validatePublicPositionBounds } from "../coordinates.ts";
 import { detectGrammar } from "../language.ts";
+import type { SyntaxNodeLike } from "../syntax-node.ts";
 import type { GrammarId, SourceRange, TreeSitterResult } from "../types.ts";
 import { queryParsedFile, type TreeSitterRuntime } from "../worker/runtime.ts";
 import { normalizeCallName } from "./call-name.ts";
+import { createCalleeDisplayName, createSourceLineStarts } from "./callee-display-name.ts";
 import { extractScopeName } from "./scope.ts";
 
 /** Result shape returned by lookupCalleesAt. */
@@ -16,6 +19,7 @@ export interface CalleesAtResult {
   };
   callees: Array<{
     name: string;
+    displayName?: string;
     range: SourceRange;
   }>;
   depth: "direct" | "deep";
@@ -138,7 +142,7 @@ function findEnclosingScope(
  * 3. Runs a grammar-specific callee query.
  * 4. Filters to captures within that enclosing scope.
  * 5. Excludes nested function/method/callback scopes that do not contain the anchor.
- * 6. Deduplicates by name.
+ * 6. Deduplicates identical capture ranges and returns captures in source order.
  */
 // biome-ignore lint/complexity/useMaxParams: provider function needs runtime + coordinates + depth
 export async function lookupCalleesAt(
@@ -212,6 +216,7 @@ export async function lookupCalleesAt(
       scopes,
       tsPoint,
       depth,
+      source,
     );
 
     const enclosingRange = nodeToSourceRange(enclosingNode);
@@ -318,7 +323,8 @@ function filterCalleeCaptures(
   scopeTypes: ReadonlySet<string>,
   anchor: { row: number; column: number },
   depth: "direct" | "deep" = "direct",
-): Array<{ name: string; range: SourceRange }> {
+  source: string,
+): Array<{ name: string; displayName?: string; range: SourceRange }> {
   const excludeRanges: Array<{
     startRow: number;
     startColumn: number;
@@ -329,8 +335,11 @@ function filterCalleeCaptures(
     collectInnerScopes(enclosingNode, scopeTypes, anchor, excludeRanges);
   }
 
-  const seen = new Set<string>();
-  const callees: Array<{ name: string; range: SourceRange }> = [];
+  const seenRanges = new Set<string>();
+  const callees: Array<{ name: string; displayName?: string; range: SourceRange }> = [];
+  const sourceLineStarts = createSourceLineStarts(source);
+  const syntaxNodes = new Map<string, SyntaxNodeLike>();
+  indexSyntaxNodes(enclosingNode as NamedSyntaxNode, syntaxNodes);
 
   const enclosingStartRow = enclosingNode.startPosition.row;
   const enclosingEndRow = enclosingNode.endPosition.row;
@@ -366,17 +375,66 @@ function filterCalleeCaptures(
     }
 
     const name = normalizeCallName(capture.text, grammarId, capture.nodeType);
-    if (name.length === 0 || seen.has(name)) continue;
-    seen.add(name);
-
-    callees.push({ name, range: capture.range });
+    const rangeKey = sourceRangeKey(capture.range);
+    if (name.length === 0 || seenRanges.has(rangeKey)) continue;
+    seenRanges.add(rangeKey);
+
+    const syntaxNode = syntaxNodes.get(captureNodeKey(capture));
+    const displayName = syntaxNode
+      ? createCalleeDisplayName({
+          node: syntaxNode,
+          grammarId,
+          nodeType: capture.nodeType,
+          source,
+          sourceLineStarts,
+        })
+      : undefined;
+    callees.push({
+      name,
+      ...(displayName === undefined ? {} : { displayName }),
+      range: capture.range,
+    });
   }
 
-  return callees;
+  return callees.sort((left, right) => compareSourceRanges(left.range, right.range));
 }
 
 // ── Internal helpers ──────────────────────────────────────────────────
 
+function sourceRangeKey(range: SourceRange): string {
+  return `${range.startLine}:${range.startCharacter}:${range.endLine}:${range.endCharacter}`;
+}
+
+type NamedSyntaxNode = SyntaxNodeLike & { namedChildren: NamedSyntaxNode[] };
+
+/** Query captures use named nodes. Skip anonymous tokens and avoid recursive indexing. */
+function indexSyntaxNodes(node: NamedSyntaxNode, index: Map<string, SyntaxNodeLike>): void {
+  const pending = [node];
+  while (pending.length > 0) {
+    const current = pending.pop();
+    if (!current) break;
+    index.set(syntaxNodeKey(current), current);
+    for (const child of current.namedChildren) pending.push(child);
+  }
+}
+
+function syntaxNodeKey(node: SyntaxNodeLike): string {
+  return `${node.type}:${node.startPosition.row}:${node.startPosition.column}:${node.endPosition.row}:${node.endPosition.column}`;
+}
+
+function captureNodeKey(capture: { nodeType: string; range: SourceRange }): string {
+  return `${capture.nodeType}:${capture.range.startLine - 1}:${capture.range.startCharacter - 1}:${capture.range.endLine - 1}:${capture.range.endCharacter - 1}`;
+}
+
+function compareSourceRanges(left: SourceRange, right: SourceRange): number {
+  return (
+    left.startLine - right.startLine ||
+    left.startCharacter - right.startCharacter ||
+    left.endLine - right.endLine ||
+    left.endCharacter - right.endCharacter
+  );
+}
+
 /** Convert a tree-sitter node to a SourceRange using the source text for
  * UTF-16 column conversion. */
 function nodeToSourceRange(node: {

package/src/types.ts

@@ -56,6 +56,8 @@ export interface CalleesAtResult {
   };
   callees: Array<{
     name: string;
+    /** Optional syntax-shortened label for presentation; does not replace `name`. */
+    displayName?: string;
     range: SourceRange;
   }>;
   depth: "direct" | "deep";