Merge pull request #41 from vndv/fix/remove-deprecated-tools-and-normalize-files-path

fix: remove deprecated CodeGraph tools and normalize codegraph_files …

Author: vndv

.changeset/fix-codegraph-files-path.md

@@ -0,0 +1,5 @@
+---
+"@vndv/pi-codegraph": patch
+---
+
+Normalize `codegraph_files` `path` filters to root-relative POSIX prefixes and append a deterministic hint when no files match, preventing agents from concluding a directory does not exist. Fixes #40.

.changeset/remove-removed-codegraph-tools.md

@@ -0,0 +1,5 @@
+---
+"@vndv/pi-codegraph": patch
+---
+
+Remove `codegraph_context` and `codegraph_trace` tools, which upstream CodeGraph dropped in v0.9.9+, and update guidance to use `codegraph_explore` instead. Fixes #37.

README.md

@@ -8,7 +8,7 @@
 
 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.
 
 ---
 
@@ -36,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 |
@@ -126,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.
 
 ---

__tests__/codegraph.test.ts

@@ -1,12 +1,14 @@
 import { describe, expect, it, vi } from "vitest";
 import { EventEmitter } from "node:events";
 import { PassThrough } from "node:stream";
+import os from "node:os";
+import path from "node:path";
 
 vi.mock("node:child_process", () => ({
   spawn: vi.fn(() => createMockProcess()),
 }));
 
-function createMockProcess() {
+function createMockProcess(returnResult?: { content?: any[]; isError?: boolean }) {
   const child = new EventEmitter() as any;
   child.stdin = new PassThrough();
   child.stdout = new PassThrough();
@@ -24,10 +26,11 @@ function createMockProcess() {
         child.stdout.write(JSON.stringify({ jsonrpc: "2.0", id: msg.id, result: {} }) + "\n");
       }
       if (msg.method === "tools/call") {
+        const result = returnResult ?? { content: [{ type: "text", text: `called ${msg.params.name}` }] };
         child.stdout.write(JSON.stringify({
           jsonrpc: "2.0",
           id: msg.id,
-          result: { content: [{ type: "text", text: `called ${msg.params.name}` }] },
+          result,
         }) + "\n");
       }
     }
@@ -40,9 +43,9 @@ describe("pi-codegraph extension", () => {
   it("exports all CodeGraph tool names", async () => {
     const mod = await import("../extensions/codegraph.js");
 
-    expect(mod.codegraphToolNames).toContain("codegraph_context");
-    expect(mod.codegraphToolNames).toContain("codegraph_trace");
-    expect(mod.codegraphToolNames).toHaveLength(10);
+    expect(mod.codegraphToolNames).not.toContain("codegraph_context");
+    expect(mod.codegraphToolNames).not.toContain("codegraph_trace");
+    expect(mod.codegraphToolNames).toHaveLength(8);
   });
 
   it("proxies tool calls through CodeGraph MCP", async () => {
@@ -74,4 +77,108 @@ describe("pi-codegraph extension", () => {
     expect(diagnostic).not.toContain("123456");
     expect(diagnostic).not.toContain("hidden");
   });
+
+  describe("normalizeFilesPath", () => {
+    it("returns undefined for empty/undefined input", async () => {
+      const { normalizeFilesPath } = await import("../extensions/codegraph.js");
+
+      expect(normalizeFilesPath()).toBeUndefined();
+      expect(normalizeFilesPath("")).toBeUndefined();
+    });
+
+    it("expands ~ to the home directory", async () => {
+      const { normalizeFilesPath } = await import("../extensions/codegraph.js");
+      vi.spyOn(os, "homedir").mockReturnValue("/home/user");
+
+      expect(normalizeFilesPath("~/project/src/components", "/home/user/project")).toBe("src/components");
+      expect(normalizeFilesPath("~/project", "/home/user/project")).toBeUndefined();
+    });
+
+    it("converts an absolute path inside the project to a repo-relative POSIX prefix", async () => {
+      const { normalizeFilesPath } = await import("../extensions/codegraph.js");
+
+      expect(normalizeFilesPath(path.join(process.cwd(), "src/components"), process.cwd())).toBe("src/components");
+    });
+
+    it("drops the filter when the path equals the project root", async () => {
+      const { normalizeFilesPath } = await import("../extensions/codegraph.js");
+
+      expect(normalizeFilesPath(process.cwd(), process.cwd())).toBeUndefined();
+    });
+
+    it("leaves relative inputs and out-of-project absolute paths untouched", async () => {
+      const { normalizeFilesPath } = await import("../extensions/codegraph.js");
+
+      expect(normalizeFilesPath("components", "/project")).toBe("components");
+      expect(normalizeFilesPath("/outside/project", "/project")).toBe("/outside/project");
+    });
+  });
+
+  describe("annotateFilesResult", () => {
+    it("appends a hint to the bare empty marker when a path filter was supplied", async () => {
+      const { annotateFilesResult } = await import("../extensions/codegraph.js");
+
+      const result = annotateFilesResult("No files found matching the criteria.", "components");
+      expect(result).toContain("Hint:");
+      expect(result).toContain("root-relative POSIX prefix");
+      expect(result).toContain('"components"');
+    });
+
+    it("returns non-empty text unchanged", async () => {
+      const { annotateFilesResult } = await import("../extensions/codegraph.js");
+
+      expect(annotateFilesResult("src/Button.ts", "components")).toBe("src/Button.ts");
+    });
+
+    it("returns the empty marker unchanged when no path filter was supplied", async () => {
+      const { annotateFilesResult } = await import("../extensions/codegraph.js");
+
+      expect(annotateFilesResult("No files found matching the criteria.")).toBe(
+        "No files found matching the criteria.",
+      );
+    });
+  });
+
+  it("normalizes codegraph_files path before forwarding to the MCP server", async () => {
+    const { spawn } = await import("node:child_process");
+    const { callCodeGraphTool } = await import("../extensions/codegraph.js");
+    let capturedArgs: Record<string, unknown> | undefined;
+
+    vi.mocked(spawn).mockImplementationOnce(() => {
+      const child = new EventEmitter() as any;
+      child.stdin = new PassThrough();
+      child.stdout = new PassThrough();
+      child.stderr = new PassThrough();
+      child.killed = false;
+      child.kill = vi.fn(() => { child.killed = true; });
+
+      child.stdin.on("data", (chunk: Buffer) => {
+        const lines = chunk.toString("utf-8").trim().split("\n").filter(Boolean);
+        for (const line of lines) {
+          const msg = JSON.parse(line);
+          if (msg.method === "initialize") {
+            child.stdout.write(JSON.stringify({ jsonrpc: "2.0", id: msg.id, result: {} }) + "\n");
+          }
+          if (msg.method === "tools/call") {
+            capturedArgs = msg.params.arguments;
+            child.stdout.write(JSON.stringify({
+              jsonrpc: "2.0",
+              id: msg.id,
+              result: { content: [{ type: "text", text: "src/Button.ts" }] },
+            }) + "\n");
+          }
+        }
+      });
+
+      return child;
+    });
+
+    await callCodeGraphTool("codegraph_files", {
+      projectPath: process.cwd(),
+      path: path.join(process.cwd(), "src"),
+    });
+
+    expect(capturedArgs).toBeDefined();
+    expect(capturedArgs!.path).toBe("src");
+  });
 });

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,16 +384,17 @@ 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 {
   pi.on("before_agent_start", async (event) => {
     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");