@vndv/pi-codegraph 0.1.6 → 0.1.8

package/README.md

@@ -2,12 +2,13 @@
 ### CodeGraph tools for pi
 
 [![Skylos Grade](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/vndv/pi-codegraph/main/.github/badges/skylos.json)](https://github.com/duriantaco/skylos)
+[![npm downloads](https://img.shields.io/npm/dm/%40vndv%2Fpi-codegraph)](https://www.npmjs.com/package/@vndv/pi-codegraph)
 
 [Install](#install) · [Usage](#usage) · [How it works](#how-it-works)
 
 Ask pi structural questions about your codebase without falling back to slow grep/read loops.
 
-An extension for [pi](https://pi.dev) that gives the agent access to [CodeGraph](https://github.com/colbymchenry/codegraph) tools. CodeGraph indexes your project with tree-sitter, then pi can query symbols, callers, callees, dependency impact, files, and call paths through native extension tools.
+An extension for [pi](https://pi.dev) that gives the agent access to [CodeGraph](https://github.com/colbymchenry/codegraph) tools. CodeGraph indexes your project with tree-sitter, then pi can query symbols, callers, callees, dependency impact, files, and relationships through native extension tools.
 
 ---
 
@@ -17,7 +18,7 @@ An extension for [pi](https://pi.dev) that gives the agent access to [CodeGraph]
 npm install -g @colbymchenry/codegraph
 cd /path/to/project
 codegraph init -i
-pi install npm:@vndv/pi-codegraph@0.1.6
+pi install npm:@vndv/pi-codegraph@0.1.8
 pi
 ```
 
@@ -35,13 +36,11 @@ Extension tools only. There is no MCP setup for pi users to maintain.
 
 | Tool | Description |
 | --- | --- |
-| `codegraph_context` | Broad task context: entry points, related symbols, callers, callees, and key code |
 | `codegraph_search` | Symbol search by name |
 | `codegraph_node` | One symbol's signature, location, source, callers, and callees |
 | `codegraph_files` | Indexed file tree |
 | `codegraph_callers` | Functions or methods that call a symbol |
 | `codegraph_callees` | Functions or methods called by a symbol |
-| `codegraph_trace` | Static call path from one symbol to another |
 | `codegraph_impact` | Impact radius for changing a symbol |
 | `codegraph_explore` | Source for several related symbols grouped by file |
 | `codegraph_status` | Index health and pending sync status |
@@ -53,7 +52,7 @@ Extension tools only. There is no MCP setup for pi users to maintain.
 From npm:
 
 ```bash
-pi install npm:@vndv/pi-codegraph@0.1.6
+pi install npm:@vndv/pi-codegraph@0.1.8
 ```
 
 From GitHub:
@@ -82,7 +81,7 @@ pi list
 
 ## Requirements
 
-Node.js 22 LTS is recommended. CodeGraph blocks Node.js 25 because that Node line has a V8 WASM JIT issue that can crash while compiling tree-sitter grammars.
+Node.js 22.19.0 or newer is required.
 
 CodeGraph must be installed and available on `PATH`:
 
@@ -125,12 +124,10 @@ Use CodeGraph. Show files under internal/services and important symbols.
 
 ### 3. Prefer the right tool
 
-Use `codegraph_context` for broad "how does this work?" questions.
+Use `codegraph_explore` for broad "how does this work?" or "how does X reach Y?" questions.
 
 Use `codegraph_node` when you already know the symbol name.
 
-Use `codegraph_trace` for "how does X reach Y?" flow questions.
-
 Use `codegraph_search` for declarations and symbols, not arbitrary text or constant values.
 
 ---
@@ -162,7 +159,7 @@ That means another developer only needs the npm package, the `codegraph` CLI, an
 Remove the package using the same source shown by `pi list`:
 
 ```bash
-pi remove npm:@vndv/pi-codegraph@0.1.6
+pi remove npm:@vndv/pi-codegraph@0.1.8
 ```
 
 If you installed from GitHub or a local path, remove that exact entry instead:
@@ -199,7 +196,7 @@ codegraph init -i
 
 ### Node.js version is unsupported
 
-Use Node.js 22 LTS:
+Use Node.js 22.19.0 or newer:
 
 ```bash
 nvm install 22

package/extensions/codegraph.ts

@@ -1,5 +1,6 @@
 import { spawn } from "node:child_process";
 import { stat } from "node:fs/promises";
+import os from "node:os";
 import path from "node:path";
 import { pathToFileURL } from "node:url";
 import type { ChildProcessWithoutNullStreams } from "node:child_process";
@@ -34,17 +35,6 @@ const ToolDefinitions = [
       projectPath: OptionalProjectPath,
     }),
   },
-  {
-    name: "codegraph_context",
-    label: "CodeGraph Context",
-    description: "Primary tool for architecture, feature, bug-context, or how-does-X-work questions.",
-    parameters: Type.Object({
-      task: Type.String({ description: "Task, question, or code area to understand." }),
-      maxNodes: Type.Optional(Type.Number({ default: 20 })),
-      includeCode: Type.Optional(Type.Boolean({ default: true })),
-      projectPath: OptionalProjectPath,
-    }),
-  },
   {
     name: "codegraph_callers",
     label: "CodeGraph Callers",
@@ -120,16 +110,6 @@ const ToolDefinitions = [
       projectPath: OptionalProjectPath,
     }),
   },
-  {
-    name: "codegraph_trace",
-    label: "CodeGraph Trace",
-    description: "Trace the call path between two symbols.",
-    parameters: Type.Object({
-      from: Type.String(),
-      to: Type.String(),
-      projectPath: OptionalProjectPath,
-    }),
-  },
 ] as const;
 
 type ToolName = (typeof ToolDefinitions)[number]["name"];
@@ -180,6 +160,34 @@ export async function resolveProjectCwd(projectPath: string | undefined): Promis
   return cwd;
 }
 
+export function normalizeFilesPath(inputPath?: string, projectCwd?: string): string | undefined {
+  if (typeof inputPath !== "string" || inputPath.trim() === "") return undefined;
+
+  const trimmed = inputPath.trim();
+  let expanded = trimmed;
+  if (expanded === "~" || expanded.startsWith("~/") || expanded.startsWith("~\\")) {
+    expanded = path.join(os.homedir(), expanded.slice(1));
+  }
+
+  if (projectCwd && path.isAbsolute(expanded)) {
+    const relative = path.relative(projectCwd, expanded);
+    if (relative === "") return undefined;
+    if (!relative.startsWith("..") && !path.isAbsolute(relative)) {
+      return relative.split(path.sep).join("/");
+    }
+  }
+
+  return trimmed.split(path.sep).join("/");
+}
+
+const EmptyFilesMarker = "No files found matching the criteria.";
+
+export function annotateFilesResult(resultText: string, originalPath?: string): string {
+  if (!originalPath || !resultText.includes(EmptyFilesMarker)) return resultText;
+
+  return `${resultText}\n\nHint: codegraph_files interprets "path" as a root-relative POSIX prefix (e.g. "src/components"). The filter "${originalPath}" did not match any indexed path.`;
+}
+
 export function sanitizeDiagnostic(value: string): string {
   const withoutAnsi = value.replace(/\u001b\[[0-9;]*m/g, "");
   const redacted = withoutAnsi
@@ -332,17 +340,42 @@ async function initializeJsonRpcSession(
   sendNotification("initialized", {});
 }
 
+async function prepareToolArguments(
+  name: ToolName,
+  params: ToolParams,
+): Promise<{ args: ToolParams; originalFilesPath?: string }> {
+  if (name !== "codegraph_files") return { args: params };
+
+  const projectPath = typeof params.projectPath === "string" ? params.projectPath : undefined;
+  const projectCwd = await resolveProjectCwd(projectPath);
+  const originalFilesPath = typeof params.path === "string" ? params.path : undefined;
+  const normalizedPath = normalizeFilesPath(originalFilesPath, projectCwd);
+
+  const args: ToolParams = { ...params };
+  if (normalizedPath === undefined) {
+    delete args.path;
+  } else {
+    args.path = normalizedPath;
+  }
+
+  return { args, originalFilesPath };
+}
+
 export async function callCodeGraphTool(
   name: ToolName,
   params: ToolParams,
   signal?: AbortSignal,
 ): Promise<string> {
-  const projectPath = typeof params.projectPath === "string" ? params.projectPath : undefined;
-  const result = await withCodeGraphMcp(projectPath, signal, (request) =>
-    request("tools/call", {
-      name,
-      arguments: params || {},
-    })
+  const { args, originalFilesPath } = await prepareToolArguments(name, params);
+
+  const result = await withCodeGraphMcp(
+    typeof args.projectPath === "string" ? args.projectPath : undefined,
+    signal,
+    (request) =>
+      request("tools/call", {
+        name,
+        arguments: args,
+      }),
   );
 
   const text = (result?.content || [])
@@ -351,7 +384,8 @@ export async function callCodeGraphTool(
     .join("\n");
 
   if (result?.isError) throw new Error(text || "CodeGraph tool failed.");
-  return text || JSON.stringify(result);
+  const finalText = text || JSON.stringify(result);
+  return name === "codegraph_files" ? annotateFilesResult(finalText, originalFilesPath) : finalText;
 }
 
 export default function codegraphExtension(pi: ExtensionAPI): void {
@@ -359,8 +393,8 @@ export default function codegraphExtension(pi: ExtensionAPI): void {
     const guidance = [
       "CodeGraph tools are available as codegraph_* Pi tools.",
       "For architecture, flow, where-is-symbol, impact, and codebase navigation questions, use CodeGraph tools directly before grep/read.",
-      "Use codegraph_context first for broad questions, codegraph_search for symbol-name lookup, codegraph_files for project structure, codegraph_node for a known symbol, and codegraph_trace for call paths.",
-      "If codegraph_search returns no exact result, try codegraph_context or codegraph_files/codegraph_explore before falling back to grep/read; CodeGraph symbol search may miss literal constants or generated names that still exist in source text.",
+      "Use codegraph_explore first for broad questions, codegraph_search for symbol-name lookup, codegraph_files for project structure, codegraph_node for a known symbol, and codegraph_callers for impact/flow analysis.",
+      "If codegraph_search returns no exact result, try codegraph_explore or codegraph_files/codegraph_node before falling back to grep/read; CodeGraph symbol search may miss literal constants or generated names that still exist in source text.",
       "Only use grep/read after CodeGraph is insufficient or when the user asks for literal text matching.",
     ].join("\n");
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vndv/pi-codegraph",
-  "version": "0.1.6",
+  "version": "0.1.8",
   "description": "CodeGraph tools for Pi Agent.",
   "license": "MIT",
   "type": "module",
@@ -48,7 +48,7 @@
     "version-packages": "changeset version && npm run sync:readme-version && npm install --package-lock-only --ignore-scripts"
   },
   "engines": {
-    "node": ">=22.19.0 <25"
+    "node": ">=22.19.0"
   },
   "publishConfig": {
     "access": "public"