codemode-lsp 0.1.2 → 0.2.0

package/README.md

@@ -65,14 +65,20 @@ returns `{ result, logs, changes }`:
 - **changes** — every file that hit disk, as `{ file, kind, diff }` with a
   unified diff against the pre-script content. Empty for read-only scripts.
 
-The API surface is 16 functions plus `getDiagnostics`: 8 read ops (`readFile`,
+The API surface is 18 functions plus `getDiagnostics`: 10 read ops (`readFile`,
 `getSymbolBody`, `getSymbols`, `findSymbol`, `findReferences`,
-`goToDefinition`, `searchText`, `listFiles`) and 7 write ops (`renameSymbol`,
-`replaceSymbolBody`, `insertBeforeSymbol`, `insertAfterSymbol`,
-`deleteSymbol`, `writeFile`, `deleteFile`). Symbols are addressed by
+`goToDefinition`, `incomingCalls`, `outgoingCalls`, `searchText`, `listFiles`)
+and 7 write ops (`renameSymbol`, `replaceSymbolBody`, `insertBeforeSymbol`,
+`insertAfterSymbol`, `deleteSymbol`, `writeFile`, `deleteFile`). The call
+hierarchy ops return only true calls — attributed to the enclosing function,
+resolved across modules — where `findReferences` mixes calls with imports and
+re-exports. Symbols are addressed by
 slash-separated paths (`MyClass/myMethod`) discovered via `getSymbols`. The
 full type definitions are embedded in the tool description, generated straight
-from the source (`bun run generate:types`).
+from the source (`bun run generate:types`). If a client truncates the
+description, the script `await lsp.help()` returns the complete reference —
+the description's first lines advertise this, so an agent can always recover
+the full API without probing.
 
 See `PRD.md` for the complete spec.
 

package/dist/index.js

@@ -39506,16 +39506,26 @@ ${prefix}has no matching children.` : "")}`);
   }
   return resolved;
 }
-function containingSymbolPath(symbols, position) {
+var CALLABLE_KIND_NAMES = new Set(["function", "method", "constructor"]);
+function containingFunctionPath(symbols, position) {
+  const chain = [];
   function visit(candidates) {
     for (const candidate of candidates) {
       if (!positionContains(candidate.range, position))
         continue;
-      return visit(candidate.children) ?? candidate;
+      chain.push(candidate);
+      visit(candidate.children);
+      return;
     }
-    return;
   }
-  return visit(buildResolvedSymbolTree(addressableSymbols(symbols)))?.path;
+  visit(buildResolvedSymbolTree(addressableSymbols(symbols)));
+  for (let i = chain.length - 1;i >= 0; i -= 1) {
+    const candidate = chain[i];
+    if (candidate && CALLABLE_KIND_NAMES.has(candidate.kind)) {
+      return candidate.path;
+    }
+  }
+  return chain[chain.length - 1]?.path;
 }
 function symbolPathForRange(symbols, range) {
   function visit(candidates) {
@@ -39859,6 +39869,76 @@ class LspApi {
     }
     return this.locationToApiLocation(first);
   }
+  async incomingCalls(file2, symbolPath) {
+    const item = await this.callHierarchyItemFor("incomingCalls(file, symbolPath)", 'await lsp.incomingCalls("src/auth.ts", "AuthService/validate")', file2, symbolPath);
+    const calls = await this.client.incomingCalls(item);
+    const results = [];
+    for (const call of calls) {
+      const info = await this.callHierarchyItemToInfo(call.from, call.fromRanges, call.from.uri);
+      if (info)
+        results.push(info);
+    }
+    return results;
+  }
+  async outgoingCalls(file2, symbolPath) {
+    const item = await this.callHierarchyItemFor("outgoingCalls(file, symbolPath)", 'await lsp.outgoingCalls("src/payments.ts", "recordPayment")', file2, symbolPath);
+    const calls = await this.client.outgoingCalls(item);
+    const results = [];
+    for (const call of calls) {
+      const info = await this.callHierarchyItemToInfo(call.to, call.fromRanges, item.uri);
+      if (info)
+        results.push(info);
+    }
+    return results;
+  }
+  async callHierarchyItemFor(signature, example, file2, symbolPath) {
+    this.requireStrings(signature, example, { file: file2, symbolPath });
+    const resolved = this.resolveWorkspacePath(file2);
+    const symbol2 = resolveSymbolPath({
+      file: resolved.relPath,
+      symbolPath,
+      symbols: await this.documentSymbols(resolved)
+    });
+    const items = await this.client.prepareCallHierarchy({
+      uri: resolved.uri,
+      position: symbol2.selectionRange.start
+    });
+    const item = items[0];
+    if (!item) {
+      throw new Error(`"${symbolPath}" in "${resolved.relPath}" has no call hierarchy — the symbol must be callable (a function, method, or constructor; its kind is "${symbol2.kind}"). Pick a function-like symbol from getSymbols("${resolved.relPath}").`);
+    }
+    return item;
+  }
+  async callHierarchyItemToInfo(item, fromRanges, rangesUri) {
+    const itemPath = this.workspacePathFromUri(item.uri);
+    if (!itemPath)
+      return;
+    const rangesPath = this.workspacePathFromUri(rangesUri);
+    const rangesText = rangesPath ? this.readTextSafe(rangesPath) : "";
+    let symbolPath;
+    try {
+      const symbols = await this.documentSymbols(itemPath);
+      symbolPath = symbolPathForRange(symbols, item.selectionRange) ?? containingFunctionPath(symbols, item.selectionRange.start);
+    } catch {
+      symbolPath = undefined;
+    }
+    return {
+      file: itemPath.relPath,
+      symbolPath: symbolPath ?? item.name,
+      name: item.name,
+      kind: symbolKindName(item.kind),
+      callSites: [
+        ...new Map(fromRanges.map((range) => [
+          `${range.start.line}:${range.start.character}`,
+          {
+            line: range.start.line + 1,
+            column: range.start.character + 1,
+            context: rangesPath ? lineContext(rangesText, range.start.line) : ""
+          }
+        ])).values()
+      ]
+    };
+  }
   async searchText(pattern, glob) {
     this.requireStrings("searchText(pattern, glob?)", 'await lsp.searchText("new NotFoundError\\\\(", "src/**") — the pattern is a regex; escape metacharacters for literal text', { pattern });
     if (glob !== undefined && glob !== null && typeof glob !== "string") {
@@ -40203,7 +40283,7 @@ ${text}`
   async containingPathForLocation(workspacePath, location) {
     try {
       const symbols = await this.documentSymbols(workspacePath);
-      return containingSymbolPath(symbols, location.range.start);
+      return containingFunctionPath(symbols, location.range.start);
     } catch {
       return;
     }
@@ -40397,6 +40477,21 @@ class LspClient {
     const result = await this.request("textDocument/definition", { textDocument: { uri: params.uri }, position: params.position });
     return normalizeDefinition(result);
   }
+  async prepareCallHierarchy(params) {
+    await this.ensureAlive();
+    const result = await this.request("textDocument/prepareCallHierarchy", { textDocument: { uri: params.uri }, position: params.position });
+    return result ?? [];
+  }
+  async incomingCalls(item) {
+    await this.ensureAlive();
+    const result = await this.request("callHierarchy/incomingCalls", { item });
+    return result ?? [];
+  }
+  async outgoingCalls(item) {
+    await this.ensureAlive();
+    const result = await this.request("callHierarchy/outgoingCalls", { item });
+    return result ?? [];
+  }
   openTextDocument(abs) {
     const uri = pathToFileURL2(abs).href;
     if (this.openVersions.has(uri))
@@ -40606,6 +40701,7 @@ class LspClient {
           definition: { linkSupport: false },
           references: {},
           rename: { prepareSupport: true },
+          callHierarchy: {},
           synchronization: { didSave: false, willSave: false },
           publishDiagnostics: {}
         },
@@ -46035,6 +46131,8 @@ var READ_OP_NAMES = [
   "findSymbol",
   "findReferences",
   "goToDefinition",
+  "incomingCalls",
+  "outgoingCalls",
   "searchText",
   "listFiles",
   "getDiagnostics"
@@ -46274,6 +46372,8 @@ async function runSandbox(code, options) {
   };
   const opNames = options.readonly ? [...READ_OP_NAMES] : [...READ_OP_NAMES, ...WRITE_OP_NAMES];
   sandbox.lsp = buildTracedLsp(options.lsp, trace, makeSandboxError, wrapAsync, opNames);
+  const helpText = options.helpText ?? "No extended help is available; the tool description is the full reference.";
+  sandbox.lsp.help = wrapAsync(async () => helpText);
   const { source, uncapturedLastStatement } = normalizeCode(code);
   const wrapped = `(async () => {
 ${source}
@@ -46358,12 +46458,32 @@ interface Reference {
   column: number;
   /** The actual line of code containing the reference. */
   context: string;
-  /** Path of the symbol containing the reference (a reusable handle); "" at top level. */
+  /** Path of the nearest enclosing function/method (a reusable handle); "" at top level. */
   symbolPath: string;
   /** Always false in v1 — the language server does not classify accesses. */
   isWriteAccess: boolean;
 }
 
+interface CallInfo {
+  /** The other function: the caller (incomingCalls) or the callee (outgoingCalls). */
+  file: string;
+  /** Its symbol path — round-trips into other lsp.* calls together with \`file\`. */
+  symbolPath: string;
+  name: string;
+  kind: string;
+  /** Call sites in the caller's body (so in \`file\` for incomingCalls, in the queried symbol's file for outgoingCalls). */
+  callSites: CallSite[];
+}
+
+interface CallSite {
+  /** 1-based. */
+  line: number;
+  /** 1-based. */
+  column: number;
+  /** The line of code containing the call. */
+  context: string;
+}
+
 interface Location {
   file: string;
   /** 1-based. */
@@ -46416,12 +46536,16 @@ var LSP_READ_OP_SIGNATURES = `  /** File contents as a raw string (no line numbe
   getSymbolBody(file: string, symbolPath: string): Promise<string>;
   /** Document symbol tree (file outline). Every path is a usable handle. */
   getSymbols(file: string): Promise<SymbolInfo[]>;
-  /** Workspace-wide symbol search; the index warms lazily, so early calls may be empty — getSymbols(file) is exhaustive. */
+  /** Workspace-wide symbol search; matches substrings, so filter for exact \`name\`. The index warms lazily — early calls may be empty; getSymbols(file) is exhaustive. */
   findSymbol(query: string): Promise<WorkspaceSymbolInfo[]>;
   /** All references to a symbol across the workspace (incl. the declaration). */
   findReferences(file: string, symbolPath: string): Promise<Reference[]>;
-  /** Jump to a symbol's definition. */
+  /** Jump to the definition of a symbol DEFINED in \`file\` — imports/callees in a body are not addressable; resolve those names with findSymbol. */
   goToDefinition(file: string, symbolPath: string): Promise<Location>;
+  /** Functions that CALL this symbol — true calls only (no imports/re-exports), each attributed to its enclosing function with exact call sites. */
+  incomingCalls(file: string, symbolPath: string): Promise<CallInfo[]>;
+  /** Functions this symbol's body CALLS, each resolved to its definition (follows imports across modules); workspace functions only — library calls are omitted. */
+  outgoingCalls(file: string, symbolPath: string): Promise<CallInfo[]>;
   /** Regex search across project files — escape metacharacters for literal text; optional second arg is a glob string. */
   searchText(pattern: string, glob?: string): Promise<SearchResult[]>;
   /** Project files matching a glob; no glob = all files, a directory name means everything under it. */
@@ -46455,6 +46579,17 @@ for (const file of files) {
   outline.push({ file, symbols: symbols.map((s) => s.kind + " " + s.path) });
 }
 outline;`
+  },
+  {
+    title: "Trace the call graph",
+    writes: false,
+    code: `// Who calls findUser, and what does findUser call?
+const callers = await lsp.incomingCalls("src/users.ts", "findUser");
+const callees = await lsp.outgoingCalls("src/users.ts", "findUser");
+({
+  calledBy: callers.map((c) => c.file + "::" + c.symbolPath),
+  calls: callees.map((c) => c.file + "::" + c.symbolPath),
+});`
   },
   {
     title: "Batch refactor: migrate every caller",
@@ -46490,10 +46625,16 @@ function renderLspTypes(readonly3) {
   const interfaces = readonly3 ? LSP_COMMON_INTERFACES : `${LSP_COMMON_INTERFACES}
 
 ${LSP_WRITE_INTERFACES}`;
-  const ops = readonly3 ? LSP_READ_OP_SIGNATURES : `${LSP_READ_OP_SIGNATURES}
+  const helpOp = `  /** This full API reference as a string — call it if this description was truncated. */
+  help(): Promise<string>;`;
+  const ops = readonly3 ? `${LSP_READ_OP_SIGNATURES}
+
+${helpOp}` : `${LSP_READ_OP_SIGNATURES}
 
   // Write operations — buffered, applied atomically when the script succeeds.
-${LSP_WRITE_OP_SIGNATURES}`;
+${LSP_WRITE_OP_SIGNATURES}
+
+${helpOp}`;
   return `declare const lsp: {
 ${ops}
 };
@@ -46501,6 +46642,8 @@ ${ops}
 ${interfaces}`;
 }
 var TEMPLATE = `Execute JavaScript to perform semantic code operations via LSP (TypeScript).
+If this description looks truncated, run the script \`await lsp.help()\` — it
+returns this complete reference. Ops — {{opInventory}}.
 
 Write one script that chains lsp.* calls — filter, loop, and branch in code
 instead of across many tool calls. The sandbox provides \`lsp\`,
@@ -46530,6 +46673,17 @@ script's last expression, JSON-serialized.
   the write ops.
 - \`searchText\` patterns are regexes — escape metacharacters for literal text:
   \`searchText("new NotFoundError\\\\(")\`.
+- To trace calls, use \`incomingCalls\`/\`outgoingCalls\` — they return only TRUE
+  calls, attributed to the enclosing function. \`findReferences\` mixes calls
+  with imports, re-exports, and type references.
+- \`goToDefinition\` only addresses symbols DEFINED in the given file — it cannot
+  follow an imported or called name into another module. To resolve a name to
+  its definition anywhere in the workspace, use \`findSymbol(name)\` and filter
+  for an exact \`name\` match (it also returns substring matches), or
+  \`outgoingCalls\` on the containing function.
+- \`result\` is capped at 50,000 chars (logs at 10,000). Aggregate INSIDE the
+  script — return counts, top-N lists, and compact summaries, never a raw
+  inventory of files/symbols/references.
 - File paths are relative to the workspace root; anything outside it is
   rejected.
 - Diagnostics cover files touched this session only, never the whole project.
@@ -46558,7 +46712,8 @@ ${example.code}
 \`\`\``).join(`
 
 `);
-  return TEMPLATE.replace("{{types}}", renderLspTypes(readonly3)).replace("{{writeSemantics}}", readonly3 ? READONLY_SEMANTICS : WRITE_SEMANTICS).replace("{{examples}}", examples);
+  const opInventory = readonly3 ? `read: ${READ_OP_NAMES.join(", ")}` : `read: ${READ_OP_NAMES.join(", ")}; write: ${WRITE_OP_NAMES.join(", ")}`;
+  return TEMPLATE.replace("{{opInventory}}", opInventory).replace("{{types}}", renderLspTypes(readonly3)).replace("{{writeSemantics}}", readonly3 ? READONLY_SEMANTICS : WRITE_SEMANTICS).replace("{{examples}}", examples);
 }
 
 // src/mcp-server.ts
@@ -46595,7 +46750,8 @@ function createExecuteRunner(deps) {
         const { result, logs } = await runSandbox(code, {
           lsp: deps.api,
           timeoutMs: deps.timeoutMs,
-          readonly: deps.readonly
+          readonly: deps.readonly,
+          helpText: deps.helpText ?? buildToolDescription(deps.readonly ?? false)
         });
         const flushed = buffer.flush();
         const changes = flushed.map((change) => ({
@@ -46659,20 +46815,22 @@ function createServer(options = {}) {
   warmup.catch(() => {
     return;
   });
+  const description = buildToolDescription(readonly3);
   const { execute } = createExecuteRunner({
     api: api2,
     client,
     timeoutMs,
     warmup,
     rootDir,
-    readonly: readonly3
+    readonly: readonly3,
+    helpText: description
   });
   const server = new McpServer({
     name: "codemode-lsp",
     version: "0.1.0"
   });
   server.registerTool("execute", {
-    description: buildToolDescription(readonly3),
+    description,
     inputSchema: {
       code: exports_external.string().describe("JavaScript to run in the LSP sandbox. The last expression is the return value.")
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "codemode-lsp",
-  "version": "0.1.2",
+  "version": "0.2.0",
   "description": "MCP server exposing a single code-mode tool backed by LSP",
   "keywords": [
     "mcp",