pi-graphnav 0.0.0-stage → 0.2.0

package/extensions/core/project.ts

@@ -0,0 +1,172 @@
+/**
+ * Which project CodeGraph serves, and what keeping its index current takes.
+ *
+ * Pure, except where a function takes the file system or a process runner as a parameter.
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join, parse, resolve } from "node:path";
+
+export interface Project {
+	root: string;
+	/** A `.codegraph/` directory exists at the root. */
+	hasIndexDir: boolean;
+	/** The root is a git work tree (so `init` there is expected, not a surprise). */
+	isRepo: boolean;
+}
+
+/**
+ * The project for `cwd`: the nearest directory with `.codegraph/`, else the nearest git
+ * work tree. Never the home directory or a file-system root: indexing those is never wanted.
+ */
+export function findProject(cwd: string, exists: (p: string) => boolean = existsSync, home: string = homedir()): Project | undefined {
+	let gitRoot: string | undefined;
+	let dir = resolve(cwd);
+	for (;;) {
+		if (dir === home || dir === parse(dir).root) break;
+		if (exists(join(dir, ".codegraph"))) return { root: dir, hasIndexDir: true, isRepo: exists(join(dir, ".git")) };
+		if (gitRoot === undefined && exists(join(dir, ".git"))) gitRoot = dir;
+		const up = dirname(dir);
+		if (up === dir) break;
+		dir = up;
+	}
+	return gitRoot === undefined ? undefined : { root: gitRoot, hasIndexDir: false, isRepo: true };
+}
+
+/** What `codegraph status -j` says, reduced to what matters here. */
+export interface IndexStatus {
+	initialized: boolean;
+	/** `complete`, `indexing`, … (`unknown` when the field is missing). */
+	state: string;
+	files: number;
+	pending: number;
+	reindexRecommended: boolean;
+	/** The index was built by another CodeGraph version than the one installed. */
+	versionMismatch: boolean;
+}
+
+const num = (v: unknown): number => (typeof v === "number" && Number.isFinite(v) ? v : 0);
+
+/** Parse `codegraph status -j`. Garbage (an old CodeGraph, a crash) reads as "not initialized". */
+export function parseStatus(json: string): IndexStatus {
+	let raw: any;
+	try {
+		raw = JSON.parse(json);
+	} catch {
+		raw = undefined;
+	}
+	const r = typeof raw === "object" && raw !== null ? raw : {};
+	const index = typeof r.index === "object" && r.index !== null ? r.index : {};
+	const pending = typeof r.pendingChanges === "object" && r.pendingChanges !== null ? r.pendingChanges : {};
+	return {
+		initialized: r.initialized === true,
+		state: typeof index.state === "string" ? index.state : "unknown",
+		files: num(r.fileCount),
+		pending: num(pending.added) + num(pending.modified) + num(pending.removed),
+		reindexRecommended: index.reindexRecommended === true,
+		versionMismatch:
+			typeof index.builtWithVersion === "string" && typeof r.version === "string" && index.builtWithVersion !== r.version,
+	};
+}
+
+export type IndexAction = "init" | "index" | "sync" | "none" | "skip";
+
+/** Is a live process holding `.codegraph/codegraph.lock` (an index run in progress right now)? */
+export function lockHeld(
+	root: string,
+	read: (p: string) => string | undefined = (p) => {
+		try {
+			return readFileSync(p, "utf8");
+		} catch {
+			return undefined;
+		}
+	},
+	alive: (pid: number) => boolean = pidAlive,
+): boolean {
+	const pid = Number.parseInt(read(join(root, ".codegraph", "codegraph.lock")) ?? "", 10);
+	return Number.isInteger(pid) && pid > 0 && alive(pid);
+}
+
+export function pidAlive(pid: number): boolean {
+	try {
+		process.kill(pid, 0);
+		return true;
+	} catch (e) {
+		// EPERM: it exists, it is just not ours.
+		return (e as NodeJS.ErrnoException).code === "EPERM";
+	}
+}
+
+/**
+ * What brings the index up to date: `init` when there is none (only in a git work tree, and
+ * only when allowed), a full `index` when it is stale or broken, `sync` for pending changes.
+ *
+ * State `indexing` with no live lock holder is a run that was killed half-way: the index is
+ * truncated and only a full `index` repairs it. With a live holder another process is
+ * indexing right now: leave it alone.
+ */
+export function planIndex(status: IndexStatus, project: Project, opts: { autoInit: boolean; locked?: boolean }): IndexAction {
+	if (!status.initialized) return opts.autoInit && project.isRepo ? "init" : "skip";
+	if (status.state === "indexing") return opts.locked ? "none" : "index";
+	if (status.reindexRecommended || status.versionMismatch || status.state === "partial" || status.state === "failed") return "index";
+	if (status.pending > 0) return "sync";
+	return "none";
+}
+
+/** A failure that a stale lock explains: `codegraph unlock`, then one more try. */
+export const lockProblem = (output: string): boolean => /\block(ed)?\b|lock file|database is locked/i.test(output);
+
+/** The CLI arguments for an action. */
+export function actionArgs(action: Exclude<IndexAction, "none" | "skip">): string[] {
+	switch (action) {
+		case "init":
+			return ["init", "-i", "-y"];
+		case "index":
+			return ["index", "-q"];
+		case "sync":
+			return ["sync", "-q"];
+	}
+}
+
+/** Runs `codegraph <args>` in `cwd`; resolves with the exit code and output, never rejects. */
+export type Runner = (args: string[], cwd: string) => Promise<{ code: number; stdout: string; stderr: string }>;
+
+export interface EnsureResult {
+	action: IndexAction;
+	status: IndexStatus;
+	/** Set when CodeGraph is missing or a step failed. */
+	error?: string;
+}
+
+/** Bring the index of `project` up to date: status, then init/index/sync as planned, then status again. */
+export async function ensureIndex(
+	project: Project,
+	run: Runner,
+	opts: { autoInit: boolean; locked?: (root: string) => boolean },
+): Promise<EnsureResult> {
+	const first = await run(["status", "-j"], project.root);
+	if (first.code === 127) return { action: "skip", status: parseStatus(""), error: "the codegraph CLI is not installed (npm i -g @colbymchenry/codegraph)" };
+	const status = parseStatus(first.stdout);
+	const action = planIndex(status, project, { autoInit: opts.autoInit, locked: (opts.locked ?? lockHeld)(project.root) });
+	if (action === "none" || action === "skip") return { action, status };
+	const res = await runUnlocking(run, actionArgs(action), project.root);
+	const after = parseStatus((await run(["status", "-j"], project.root)).stdout);
+	if (res.code !== 0) return { action, status: after, error: `codegraph ${action} failed (exit ${res.code}): ${lastLine(res.stderr || res.stdout)}` };
+	return { action, status: after };
+}
+
+/** Run an index action; when it fails on a stale lock, `codegraph unlock` and try once more. */
+export async function runUnlocking(run: Runner, args: string[], root: string): ReturnType<Runner> {
+	const res = await run(args, root);
+	if (res.code === 0 || res.code === 127 || !lockProblem(res.stderr + res.stdout)) return res;
+	await run(["unlock"], root);
+	return run(args, root);
+}
+
+const lastLine = (s: string): string =>
+	s
+		.replace(/\u001b\[[0-9;]*m/g, "")
+		.trim()
+		.split("\n")
+		.pop()!
+		.slice(0, 300);

package/extensions/core/resilience.ts

@@ -0,0 +1,91 @@
+/**
+ * Resilience around the CodeGraph server, built on arrow-resilience-kit:
+ *
+ * - a circuit breaker per project: after `threshold` failed calls in a row CodeGraph counts
+ *   as unavailable for `resetMs`; calls then fail fast, and the gate stops sending the agent
+ *   to a tool that does not answer;
+ * - one retry when the server process died under a call (a crash, not a slow query): the
+ *   retry starts a fresh process.
+ *
+ * Aborts and CodeGraph's own "no such symbol" answers are not failures.
+ */
+import { CircuitBreaker, Retry } from "arrow-resilience-kit";
+import { ServerExitError } from "./mcp.ts";
+
+export const UNAVAILABLE =
+	"CodeGraph is unavailable for this project right now (its last calls failed); use rg/read meanwhile. It is retried automatically.";
+
+/** The server process went away under the call: worth one retry with a fresh process. */
+export const isCrash = (e: unknown): boolean => e instanceof ServerExitError || (e instanceof Error && /\bEPIPE\b|\bECONNRESET\b/.test(e.message));
+
+/** Failures that count against CodeGraph's health. An abort is the user's doing, not CodeGraph's. */
+export const countsAsFailure = (e: unknown): boolean => !(e instanceof Error && /^Aborted$/.test(e.message));
+
+const isOpenError = (e: unknown): boolean =>
+	(e as { constructor?: { name?: string } })?.constructor?.name === "CircuitBreakerOpenException" || /circuit breaker is open/i.test(String((e as Error)?.message));
+
+export interface GuardOptions {
+	/** Failed calls in a row before CodeGraph counts as unavailable. */
+	threshold: number;
+	/** How long it then stays unavailable before a trial call. */
+	resetMs: number;
+	/** Called when availability changes (to refresh the status line). */
+	onChange?: (available: boolean) => void;
+	now?: () => number;
+}
+
+export class Guard {
+	private openedAt: number | undefined;
+
+	private constructor(
+		private readonly breaker: CircuitBreaker,
+		private readonly opts: GuardOptions,
+	) {
+		breaker.onStateChange((from, to) => {
+			if (to === "Open") {
+				this.openedAt = this.clock();
+				opts.onChange?.(false);
+				// Tell the status line when the pause is over, even if nothing calls CodeGraph meanwhile.
+				const t = setTimeout(() => opts.onChange?.(!this.open), opts.resetMs);
+				(t as { unref?: () => void }).unref?.();
+			} else if (to === "Closed" && from !== "Closed") {
+				this.openedAt = undefined;
+				opts.onChange?.(true);
+			}
+		});
+	}
+
+	static async create(opts: GuardOptions): Promise<Guard> {
+		return new Guard(await CircuitBreaker.create(opts.threshold, opts.resetMs, 1, 1), opts);
+	}
+
+	private clock(): number {
+		return (this.opts.now ?? Date.now)();
+	}
+
+	/** CodeGraph counts as unavailable: its calls failed `threshold` times in a row, and `resetMs` has not passed. */
+	get open(): boolean {
+		return this.openedAt !== undefined && this.clock() - this.openedAt < this.opts.resetMs;
+	}
+
+	/** Run a call: retried once after a crash, counted by the breaker, failing fast while unavailable. */
+	async run<T>(block: () => Promise<T>): Promise<T> {
+		let excused: { error: unknown } | undefined;
+		try {
+			return await this.breaker.execute(async () => {
+				try {
+					return await Retry.withBackoff(block, { retries: 1, baseMillis: 0, shouldRetry: isCrash });
+				} catch (e) {
+					if (countsAsFailure(e)) throw e;
+					excused = { error: e };
+					return undefined as T;
+				}
+			});
+		} catch (e) {
+			if (isOpenError(e)) throw new Error(UNAVAILABLE);
+			throw e;
+		} finally {
+			if (excused) throw excused.error;
+		}
+	}
+}

package/extensions/core/tools.ts

@@ -0,0 +1,142 @@
+/**
+ * The `codegraph_*` tools: names, parameters and the guidance the model sees.
+ *
+ * The names match the CodeGraph MCP server's tools, so calls pass straight through.
+ */
+import { Type } from "@earendil-works/pi-ai";
+
+const projectPath = Type.Optional(
+	Type.String({ description: "Absolute path of another indexed project. Defaults to the current project." }),
+);
+
+const kind = Type.Optional(
+	Type.Union(
+		["function", "method", "class", "interface", "type", "variable", "route", "component"].map((k) => Type.Literal(k)),
+		{ description: "Only symbols of this kind." },
+	),
+);
+
+export const TOOLS = [
+	{
+		name: "codegraph_explore",
+		label: "CodeGraph Explore",
+		description:
+			"Start here for any question about how code works, where something lives or what to change: returns the source of the relevant symbols, grouped by file, with the call paths between them. Accepts symbol names, file names or plain code terms.",
+		snippet: "Explore an area of the codebase: relevant symbols' source and call paths in one call",
+		parameters: Type.Object({
+			query: Type.String({ description: "Symbols, files or code terms, e.g. \"parseConfig loadSettings\"." }),
+			maxFiles: Type.Optional(Type.Number({ description: "Most files to return (default 12)." })),
+			projectPath,
+		}),
+	},
+	{
+		name: "codegraph_search",
+		label: "CodeGraph Search",
+		description: "Find symbols by name (or part of one): kind, file and line of each definition. Use instead of grep for a symbol.",
+		snippet: "Find where a symbol is defined (instead of rg/grep)",
+		parameters: Type.Object({
+			query: Type.String({ description: "Symbol name or part of one." }),
+			kind,
+			limit: Type.Optional(Type.Number({ description: "Most results (default 10)." })),
+			projectPath,
+		}),
+	},
+	{
+		name: "codegraph_node",
+		label: "CodeGraph Node",
+		description: "One symbol in detail: signature, location, callers and callees; with includeCode its source.",
+		snippet: "One symbol's details, callers and callees",
+		parameters: Type.Object({
+			symbol: Type.String({ description: "Symbol name." }),
+			includeCode: Type.Optional(Type.Boolean({ description: "Include the source (default false)." })),
+			projectPath,
+		}),
+	},
+	{
+		name: "codegraph_callers",
+		label: "CodeGraph Callers",
+		description: "Every function or method that calls a symbol: its usages, without grepping.",
+		snippet: "Who calls a symbol (its usages)",
+		parameters: Type.Object({
+			symbol: Type.String({ description: "Symbol name." }),
+			limit: Type.Optional(Type.Number({ description: "Most results (default 20)." })),
+			projectPath,
+		}),
+	},
+	{
+		name: "codegraph_callees",
+		label: "CodeGraph Callees",
+		description: "Every function or method a symbol calls.",
+		snippet: "What a symbol calls",
+		parameters: Type.Object({
+			symbol: Type.String({ description: "Symbol name." }),
+			limit: Type.Optional(Type.Number({ description: "Most results (default 20)." })),
+			projectPath,
+		}),
+	},
+	{
+		name: "codegraph_impact",
+		label: "CodeGraph Impact",
+		description: "What a change to a symbol affects, transitively. Call it before changing a signature or behaviour.",
+		snippet: "What breaks if a symbol changes",
+		parameters: Type.Object({
+			symbol: Type.String({ description: "Symbol name." }),
+			depth: Type.Optional(Type.Number({ description: "How many levels to follow (default 2)." })),
+			projectPath,
+		}),
+	},
+	{
+		name: "codegraph_files",
+		label: "CodeGraph Files",
+		description: "The project's indexed files as a tree, flat list or grouped by language, with symbol counts.",
+		snippet: "Project file structure from the index",
+		parameters: Type.Object({
+			path: Type.Optional(Type.String({ description: "Only files under this root-relative prefix, e.g. \"src/core\"." })),
+			pattern: Type.Optional(Type.String({ description: "Glob on file paths, e.g. \"*.test.ts\"." })),
+			format: Type.Optional(Type.Union([Type.Literal("tree"), Type.Literal("flat"), Type.Literal("grouped")])),
+			includeMetadata: Type.Optional(Type.Boolean()),
+			maxDepth: Type.Optional(Type.Number()),
+			projectPath,
+		}),
+	},
+	{
+		name: "codegraph_status",
+		label: "CodeGraph Status",
+		description: "Index statistics for the project: files, symbols, last update.",
+		snippet: "Index status",
+		parameters: Type.Object({ projectPath }),
+	},
+] as const;
+
+export type ToolName = (typeof TOOLS)[number]["name"];
+export const TOOL_NAMES: readonly string[] = TOOLS.map((t) => t.name);
+export const isCodeGraphTool = (name: string): boolean => TOOL_NAMES.includes(name);
+
+/** Guidelines added to the system prompt while the tools are active (static: they never break the prompt cache). */
+export const GUIDELINES = [
+	"Understand code through CodeGraph first: codegraph_explore for how something works or where to change it, codegraph_search to find a definition, codegraph_callers/codegraph_callees for relations, codegraph_impact before changing a signature, codegraph_files for structure.",
+	"Do not grep (rg, grep, git grep) for symbol names: such searches are redirected to CodeGraph. Text search is for string literals, comments, config and docs, or after CodeGraph came up empty.",
+	"Read a file once CodeGraph has told you where to look, with offset/limit around the reported lines.",
+];
+
+/** Largest result handed to the model; the rest is cut with a note. */
+export const MAX_RESULT_CHARS = 60_000;
+
+export function resultText(result: { content?: { type: string; text?: string }[] } | undefined): string {
+	const text = (result?.content ?? [])
+		.filter((p) => p?.type === "text" && typeof p.text === "string")
+		.map((p) => p.text)
+		.join("\n");
+	if (text.length <= MAX_RESULT_CHARS) return text || "(no result)";
+	return `${text.slice(0, MAX_RESULT_CHARS)}\n\n[cut at ${MAX_RESULT_CHARS} characters: narrow the query, lower maxFiles/limit or pass a path]`;
+}
+
+/** `codegraph_files` wants a root-relative POSIX prefix; accept an absolute path inside the project too. */
+export function normalizeFilesPath(path: unknown, root: string): string | undefined {
+	if (typeof path !== "string" || path.trim() === "") return undefined;
+	let p = path.trim().replace(/\\/g, "/");
+	const r = root.replace(/\\/g, "/").replace(/\/$/, "");
+	if (p === r) return undefined;
+	if (p.startsWith(`${r}/`)) p = p.slice(r.length + 1).replace(/^(?:\.?\/)+/, "");
+	return p.replace(/^\.\/(?:\.?\/)*/, "").replace(/\/$/, "") || undefined;
+}