@liuxincuit/pi-codegraph 0.1.1 → 0.1.2

package/README.md

@@ -49,7 +49,13 @@ pi -e ./extensions/codegraph.ts
 
 ## 功能一览
 
-- **`codegraph_explore` 工具** — 面向智能体的核心代码智能工具。输入符号名或自然语言问题即可查询；可选传 `path` 查询其他已建索引的项目，传 `maxFiles` 限制返回的源码行数。
+- **`codegraph_*` 工具集** — 面向智能体的代码智能工具，均支持 `path` 参数查询其他已建索引的项目：
+  - `codegraph_explore` — 一揽子探索：相关符号逐字源码 + 调用路径 + 影响范围（`maxFiles` 限制返回行数）
+  - `codegraph_query` — 按名称搜索符号（位置 + 签名，可选 `kind`/`limit` 过滤）
+  - `codegraph_node` — 单个符号的源码 + 调用轨迹，可链式追踪调用图
+  - `codegraph_callers` / `codegraph_callees` — 谁调用了它 / 它调用了谁（`limit`）
+  - `codegraph_impact` — 修改符号的影响半径（`depth`）
+  - `codegraph_files` — 从索引查看文件结构（tree/flat/grouped，`pattern`、`maxDepth`）
 - **`/codegraph-init [path]`** — 为项目建立索引（`codegraph init`）。
 - **`/codegraph-sync [path]`** — 手动同步自上次索引以来的改动（`codegraph sync`）。
 - **`/codegraph-status [path]`** — 查看索引状态与统计信息（`codegraph status`）。

package/extensions/codegraph.ts

@@ -8,7 +8,7 @@
 // Upstream: https://github.com/colbymchenry/codegraph
 
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
-import { Type } from "typebox";
+import { TSchema, Type } from "typebox";
 import * as fs from "node:fs/promises";
 import * as path from "node:path";
 import { fileURLToPath } from "node:url";
@@ -79,14 +79,19 @@ function updateStatusBar(ctx: ExtensionContext, state: StatusState) {
 }
 
 // Modeled on upstream's MCP SERVER_INSTRUCTIONS (src/mcp/server-instructions.ts):
-// lead the agent to codegraph_explore BEFORE grep/read, plus anti-patterns and staleness handling.
+// lead the agent to the codegraph_* tools BEFORE grep/read, plus anti-patterns and staleness handling.
 const INDEX_HINT = `# CodeGraph — this project is indexed
 
-A \`.codegraph/\` index exists here: SQLite knowledge graph of every symbol, edge, and file (30+ languages). ONE \`codegraph_explore\` call returns the relevant symbols' verbatim line-numbered source (treat it as already Read — safe to Edit from) PLUS call paths between them and a blast-radius summary of what depends on them.
+A \`.codegraph/\` index exists here: SQLite knowledge graph of every symbol, edge, and file (30+ languages). It answers structural code questions with verbatim, line-numbered source (treat codegraph output as already Read — safe to Edit from).
 
-- For structural questions (how does X work / where is X / who calls Y / what breaks if I change Z), call \`codegraph_explore\` INSTEAD of grep + read — usually ONE call answers the whole question.
-- Call it BEFORE and WHILE writing or editing code: it puts the blast radius in view before you touch a symbol you can name.
-- Flow tracing: name endpoint symbols (e.g. \`mutateElement renderScene\`) to surface the path across dynamic-dispatch hops.
+- For structural questions (how does X work / where is X / who calls Y / what breaks if I change Z), use the codegraph_* tools INSTEAD of grep + read — usually ONE call answers the whole question.
+- Choose the right tool:
+  - \`codegraph_query\` — locate a symbol: locations + signatures only.
+  - \`codegraph_node\` — one symbol's source + caller/callee trail (chain it to follow a call graph).
+  - \`codegraph_callers\` — who calls a symbol. \`codegraph_callees\` — what a symbol calls.
+  - \`codegraph_impact\` — blast radius of changing a symbol (call before editing).
+  - \`codegraph_files\` — indexed file tree (tree/flat/grouped by language).
+  - \`codegraph_explore\` — broad questions: relevant symbols' source + call paths in one shot. Name endpoint symbols (e.g. \`mutateElement renderScene\`) to surface paths across dynamic-dispatch hops.
 - Anti-patterns: don't grep or Read first; don't re-verify codegraph output with grep (AST-derived, more accurate than grep); don't reconstruct a flow by hand.
 - "Already sent earlier in this conversation": pointer means content is already in context — do not re-fetch or Read.
 - Staleness: if tool output contains "⚠️ Some files referenced below were edited since the last index sync", read only those flagged files directly.
@@ -113,9 +118,7 @@ export default async function codegraphExtension(pi: ExtensionAPI) {
 		name: "codegraph_explore",
 		label: "CodeGraph Explore",
 		description:
-			"PRIMARY tool for code questions — call it BEFORE grep/read when the project has a .codegraph/ index. " +
-			"One query returns the relevant symbols' verbatim line-numbered source plus the call paths between them and a blast-radius summary. " +
-			"If the project is not indexed the output says so: continue with built-in tools and suggest the user run /codegraph-init.",
+			"Broad code exploration in one shot: relevant symbols' verbatim line-numbered source, call paths between them, and a blast-radius summary.",
 		promptSnippet:
 			"codegraph_explore: symbol source + call paths in one shot from the project's CodeGraph index",
 		promptGuidelines: [
@@ -128,7 +131,7 @@ export default async function codegraphExtension(pi: ExtensionAPI) {
 			}),
 			path: Type.Optional(
 				Type.String({
-					description: "Project path to query; defaults to the current working directory",
+					description: "Project path (default: cwd)",
 				}),
 			),
 			maxFiles: Type.Optional(
@@ -156,6 +159,193 @@ export default async function codegraphExtension(pi: ExtensionAPI) {
 		},
 	});
 
+	// ── codegraph_* fine-grained tools (CLI parity with the MCP tools) ────
+	// Each maps 1:1 to a codegraph CLI subcommand; `path` selects the project,
+	// defaults to the session cwd (same convention as codegraph_explore).
+	const projectPath = () =>
+		Type.Optional(
+			Type.String({
+				description: "Project path (default: cwd)",
+			}),
+		);
+
+	type CliToolDef = {
+		name: string;
+		label: string;
+		description: string;
+		snippet: string;
+		guidelines: string[];
+		subcommand: string;
+		parameters: TSchema;
+		positional?: (p: Record<string, unknown>) => string[];
+		flags?: (p: Record<string, unknown>) => string[];
+		timeout?: number;
+	};
+
+	function registerCliTool(pi: ExtensionAPI, def: CliToolDef) {
+		pi.registerTool({
+			name: def.name,
+			label: def.label,
+			description: def.description,
+			promptSnippet: def.snippet,
+			promptGuidelines: def.guidelines,
+			parameters: def.parameters,
+			execute: async (_toolCallId, params: Record<string, unknown>, signal, _onUpdate, ctx) => {
+				const cwd = (params.path as string | undefined) ?? ctx.cwd;
+				const args = [
+					def.subcommand,
+					...(def.positional?.(params) ?? []),
+					"-p",
+					cwd,
+					...(def.flags?.(params) ?? []),
+				];
+				const result = await execCg(pi, args, {
+					signal,
+					timeout: def.timeout ?? 60_000,
+				});
+				if (result.killed) return textResult(`codegraph ${def.subcommand} timed out`);
+				// Non-zero exits carry upstream's agent-friendly guidance — pass it through.
+				if (result.code !== 0) return textResult(outputOf(result));
+				return textResult(result.stdout.trim());
+			},
+		});
+	}
+
+	const cliTools: CliToolDef[] = [
+		{
+			name: "codegraph_query",
+			label: "CodeGraph Query",
+			description:
+				"Search symbols by name. Returns locations and signatures only (no source). Use to locate where a symbol is declared.",
+			snippet: "codegraph_query: symbol locations + signatures by name",
+			guidelines: [
+				"To locate where a symbol is declared (kind, file, line), use codegraph_query before grep.",
+			],
+			subcommand: "query",
+			parameters: Type.Object({
+				search: Type.String({ description: "Symbol name or partial name to search" }),
+				kind: Type.Optional(
+					Type.String({
+						description:
+							"Filter by node kind: function, method, class, interface, type, variable, route, component",
+					}),
+				),
+				limit: Type.Optional(Type.Integer({ description: "Maximum results (default 10)" })),
+				path: projectPath(),
+			}),
+			positional: (p) => [p.search as string],
+			flags: (p) => [
+				...(p.kind ? ["--kind", p.kind as string] : []),
+				...(typeof p.limit === "number" && p.limit > 0 ? ["--limit", String(p.limit)] : []),
+			],
+		},
+		{
+			name: "codegraph_node",
+			label: "CodeGraph Node",
+			description:
+				"One symbol's source plus its caller/callee trail. Chain it to follow a call graph across files.",
+			snippet: "codegraph_node: a symbol's source + caller/callee trail",
+			guidelines: [
+				"To deep-dive one known symbol (verbatim source + who it calls / is called by), use codegraph_node.",
+			],
+			subcommand: "node",
+			parameters: Type.Object({
+				name: Type.String({ description: "Symbol name to inspect" }),
+				path: projectPath(),
+			}),
+			positional: (p) => [p.name as string],
+		},
+		{
+			name: "codegraph_callers",
+			label: "CodeGraph Callers",
+			description: "Find all functions or methods that call a specific symbol.",
+			snippet: "codegraph_callers: who calls a symbol",
+			guidelines: [
+				"To find what calls a symbol (reverse dependencies), use codegraph_callers.",
+			],
+			subcommand: "callers",
+			parameters: Type.Object({
+				symbol: Type.String({ description: "Symbol name whose callers to find" }),
+				limit: Type.Optional(Type.Integer({ description: "Maximum results (default 20)" })),
+				path: projectPath(),
+			}),
+			positional: (p) => [p.symbol as string],
+			flags: (p) => [
+				...(typeof p.limit === "number" && p.limit > 0 ? ["--limit", String(p.limit)] : []),
+			],
+		},
+		{
+			name: "codegraph_callees",
+			label: "CodeGraph Callees",
+			description: "Find all functions or methods that a specific symbol calls.",
+			snippet: "codegraph_callees: what a symbol calls",
+			guidelines: [
+				"To find what a symbol calls (its outgoing edges), use codegraph_callees.",
+			],
+			subcommand: "callees",
+			parameters: Type.Object({
+				symbol: Type.String({ description: "Symbol name whose callees to find" }),
+				limit: Type.Optional(Type.Integer({ description: "Maximum results (default 20)" })),
+				path: projectPath(),
+			}),
+			positional: (p) => [p.symbol as string],
+			flags: (p) => [
+				...(typeof p.limit === "number" && p.limit > 0 ? ["--limit", String(p.limit)] : []),
+			],
+		},
+		{
+			name: "codegraph_impact",
+			label: "CodeGraph Impact",
+			description: "Analyze what code is affected by changing a symbol (blast radius).",
+			snippet: "codegraph_impact: blast radius of changing a symbol",
+			guidelines: [
+				"Before editing a symbol, use codegraph_impact to see what depends on it.",
+			],
+			subcommand: "impact",
+			parameters: Type.Object({
+				symbol: Type.String({ description: "Symbol name to analyze impact of changing" }),
+				depth: Type.Optional(Type.Integer({ description: "Traversal depth (default 2)" })),
+				path: projectPath(),
+			}),
+			positional: (p) => [p.symbol as string],
+			flags: (p) => [
+				...(typeof p.depth === "number" && p.depth > 0 ? ["--depth", String(p.depth)] : []),
+			],
+		},
+		{
+			name: "codegraph_files",
+			label: "CodeGraph Files",
+			description:
+				"Show the indexed project's file structure (tree, flat, or grouped by language), with per-file symbol counts.",
+			snippet: "codegraph_files: indexed file tree with symbol counts",
+			guidelines: [
+				"To get a structured view of the project files, use codegraph_files.",
+			],
+			subcommand: "files",
+			parameters: Type.Object({
+				dir: Type.Optional(Type.String({ description: "Subdirectory within the project to show" })),
+				pattern: Type.Optional(Type.String({ description: "Glob pattern to filter files" })),
+				format: Type.Optional(
+					Type.Union([Type.Literal("tree"), Type.Literal("flat"), Type.Literal("grouped")]),
+				),
+				maxDepth: Type.Optional(Type.Integer({ description: "Maximum directory depth for tree format" })),
+				path: projectPath(),
+			}),
+			positional: (p) => (p.dir ? [p.dir as string] : []),
+			flags: (p) => [
+				...(p.pattern ? ["--pattern", p.pattern as string] : []),
+				...(p.format ? ["--format", p.format as string] : []),
+				...(typeof p.maxDepth === "number" && p.maxDepth > 0
+					? ["--max-depth", String(p.maxDepth)]
+					: []),
+			],
+		},
+	];
+
+	for (const tool of cliTools) {
+		registerCliTool(pi, tool);
+	}
+
 	// ── /codegraph-init ────────────────────────────────────────────────────
 	pi.registerCommand("codegraph-init", {
 		description: "Build the CodeGraph index for the current project (codegraph init)",

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@liuxincuit/pi-codegraph",
-	"version": "0.1.1",
+	"version": "0.1.2",
 	"description": "CodeGraph support for pi — symbol source + call paths via the codegraph CLI",
 	"type": "module",
 	"keywords": [

package/skills/codegraph/SKILL.md

@@ -1,27 +1,30 @@
----
-name: codegraph
-description: Query the project's CodeGraph index (symbol source + call paths) via the codegraph_explore tool. Use when answering structural code questions — how X works, where X is, what a change affects — in a project that has a .codegraph/ index.
----
-
-# CodeGraph
-
-The `codegraph_explore` tool answers structural code questions in one shot: the relevant symbols' verbatim line-numbered source, the call paths between them, and a blast-radius summary. It reads the project's CodeGraph index (`.codegraph/`), built and maintained by the `codegraph` CLI.
-
-## When to use
-
-- "How does X work?" / "Where is X?" / "What calls Y?" / "What breaks if I change Z?"
-- Before an edit, to map the symbols you are about to touch and inspect the blast radius.
-- Prefer it over grep/read for structural exploration **when the project has a `.codegraph/` index**.
-
-## How to query
-
-- `query`: symbol names (`CodeGraph open`, `MCPSession`), endpoint flows (`mutateElement renderScene`), or a natural-language question. Naming a file or symbol returns its current line-numbered source.
-- `path`: optional project path. Defaults to the current working directory. In a monorepo, pass the sub-project directory that contains `.codegraph/`.
-- `maxFiles`: optional integer to limit how many file sources are returned.
-
-## Anti-patterns & Guidance
-
-- **Trust AST results.** Don't re-verify codegraph output with grep.
-- **Already sent earlier in this conversation.** When this pointer appears, the lines are already in your session context — scroll back instead of re-fetching or reading the file.
-- **Staleness banner.** If output warns `⚠️ Some files referenced below were edited since the last index sync`, read only those specific files directly; other files in the response remain fresh.
-- **No index, no tool.** If the output says the project isn't indexed, stop calling `codegraph_explore` for that project this session and use built-in tools. Indexing is the user's decision — suggest the user run `/codegraph-init` if appropriate.
+---
+name: codegraph
+description: Query the project's CodeGraph index (symbol source, call paths, blast radius) via the codegraph_* tools. Use when answering structural code questions — how X works, where X is, who calls Y, what a change affects — in a project that has a .codegraph/ index.
+---
+
+# CodeGraph
+
+The `codegraph_*` tools answer structural code questions from the project's CodeGraph index (`.codegraph/`), built and maintained by the `codegraph` CLI. Prefer them over grep/read for structural exploration **when the project has a `.codegraph/` index**.
+
+## Picking a tool
+
+- `codegraph_query` — locate a symbol: locations + signatures only. Start here when you don't know where something is declared.
+- `codegraph_node` — one known symbol's verbatim source + caller/callee trail. Chain it to follow a call graph across files.
+- `codegraph_callers` / `codegraph_callees` — who calls a symbol / what a symbol calls.
+- `codegraph_impact` — blast radius of changing a symbol; call before editing.
+- `codegraph_files` — indexed file tree (tree/flat/grouped by language) with symbol counts.
+- `codegraph_explore` — broad questions: relevant symbols' source + call paths in one shot. Name endpoint symbols (`mutateElement renderScene`) to surface paths across dynamic-dispatch hops.
+
+## How to query
+
+- Every tool accepts `path`: the project to query. Defaults to the current working directory. In a monorepo, pass the sub-project directory that contains `.codegraph/`.
+- `codegraph_query`: `search` (symbol name or partial), optional `kind` (function, method, class, ...) and `limit`.
+- `codegraph_explore`: `query` (symbol names or natural language) and optional `maxFiles` to cap source lines returned.
+
+## Anti-patterns & Guidance
+
+- **Trust AST results.** Don't re-verify codegraph output with grep.
+- **Already sent earlier in this conversation.** When this pointer appears, the lines are already in your session context — scroll back instead of re-fetching or reading the file.
+- **Staleness banner.** If output warns `⚠️ Some files referenced below were edited since the last index sync`, read only those specific files directly; other files in the response remain fresh.
+- **No index, no tool.** If output says the project isn't indexed, stop calling `codegraph_*` for that project this session and use built-in tools. Indexing is the user's decision — suggest the user run `/codegraph-init` if appropriate.