pi-plans 0.2.0 → 0.3.1

package/src/code-graph/parsers/tree-sitter.ts

@@ -0,0 +1,316 @@
+/**
+ * Shared tree-sitter JSON helpers. Each language backend wraps a parser
+ * instance and converts the tree into our normalized function / render units.
+ */
+
+import type {
+	FunctionRecord,
+	ParseDiagnostic,
+	RenderUnit,
+} from "../types.ts";
+import { hashText, makeLocation, type ParserBackend, type ParsedFile } from "../parser.ts";
+
+interface RawNode {
+	type: string;
+	startIndex: number;
+	endIndex: number;
+	startPosition: { row: number; column: number };
+	endPosition: { row: number; column: number };
+	namedChildren: RawNode[];
+	children: RawNode[];
+	text?: string;
+	parent?: RawNode;
+	isMissing?: boolean;
+	hasError?: boolean;
+}
+
+type Tree = {
+	rootNode: RawNode;
+};
+
+type Language = unknown;
+
+interface ParserLike {
+	parse(input: string | Buffer): Tree;
+	setLanguage(language: Language): void;
+}
+
+export interface TreeSitterBackendOptions {
+	ParserCtor: new () => ParserLike;
+	language: unknown;
+	languageId: FunctionRecord["kind"] extends string ? FunctionRecord["language"] : never;
+}
+
+const KINDS: Record<string, FunctionRecord["kind"]> = {
+	function_declaration: "declaration",
+	function: "declaration",
+	method_definition: "method",
+	generator_function_declaration: "generator",
+	arrow_function: "arrow",
+	function_expression: "expression",
+	lambda: "lambda",
+	async_function: "async",
+};
+
+function detectKind(node: RawNode): FunctionRecord["kind"] {
+	if (node.type === "method_definition") {
+		const accessor = (node.children ?? []).find((child) => child.type === "get" || child.type === "set");
+		if (accessor) return "accessor";
+	}
+	if (KINDS[node.type]) return KINDS[node.type];
+	if (node.type === "method_definition") return "method";
+	return "declaration";
+}
+
+function collectDiagnostics(node: RawNode, acc: ParseDiagnostic[]): void {
+	if (node.hasError || node.isMissing) {
+		acc.push({
+			message: node.isMissing ? `missing ${node.type}` : "syntax error",
+			severity: node.isMissing ? "missing" : "error",
+			startByte: node.startIndex,
+			endByte: node.endIndex,
+		});
+	}
+	for (const child of node.children ?? []) collectDiagnostics(child, acc);
+}
+
+function classContainer(node: RawNode): string | undefined {
+	if (!node.parent) return undefined;
+	let p: RawNode | undefined = node.parent;
+	while (p) {
+		if (p.type === "class_declaration" || p.type === "class_definition" || p.type === "class" || p.type === "interface_declaration") {
+			return nameOfClass(p) ?? "<anonymous>";
+		}
+		p = p.parent;
+	}
+	return undefined;
+}
+
+function nameOfClass(node: RawNode): string | undefined {
+	const child = (node.children ?? []).find(
+		(c) => c.type === "identifier" || c.type === "name" || c.type === "type_identifier",
+	);
+	return child?.text;
+}
+
+function functionName(node: RawNode): string | null {
+	const child = (node.children ?? []).find(
+		(c) => c.type === "identifier" || c.type === "name" || c.type === "property_identifier",
+	);
+	return child?.text ?? null;
+}
+
+function qualifiedName(node: RawNode, parentName: string | null, anonymousOrdinals?: Map<string, number>): string {
+	const named = functionName(node);
+	let id = named;
+	if (!id) {
+		const scope = parentName ?? classContainer(node) ?? "<module>";
+		const key = `${scope}\0${node.type}`;
+		const ordinal = (anonymousOrdinals?.get(key) ?? 0) + 1;
+		anonymousOrdinals?.set(key, ordinal);
+		id = `<anonymous:${node.type}#${ordinal}>`;
+	}
+	if (parentName) return `${parentName}.${id}`;
+	const container = classContainer(node);
+	return container ? `${container}.${id}` : id;
+}
+
+function isOverloadSignatureNode(node: RawNode): boolean {
+	return (
+		node.type === "function_signature" ||
+		node.type === "method_signature" ||
+		node.type === "abstract_method_signature" ||
+		node.type === "declare_function"
+	);
+}
+
+function collectOverloadSignatures(node: RawNode, text: string, out: Map<string, string[]>): void {
+	if (isOverloadSignatureNode(node)) {
+		const name = functionName(node);
+		if (name) {
+			const base = qualifiedName(node, null);
+			const signatures = out.get(base) ?? [];
+			signatures.push(text.slice(node.startIndex, node.endIndex));
+			out.set(base, signatures);
+		}
+	}
+	for (const child of node.children ?? []) collectOverloadSignatures(child, text, out);
+}
+
+function locator(node: RawNode) {
+	return makeLocation(
+		node.startIndex,
+		node.endIndex,
+		node.startPosition.row + 1,
+		node.startPosition.column,
+		node.endPosition.row + 1,
+		node.endPosition.column,
+	);
+}
+
+export abstract class TreeSitterBackend implements ParserBackend {
+	abstract readonly language: FunctionRecord["language"];
+	protected readonly ParserCtor: new () => ParserLike;
+	protected readonly grammar: unknown;
+
+	constructor(opts: TreeSitterBackendOptions) {
+		this.ParserCtor = opts.ParserCtor;
+		this.grammar = opts.language;
+	}
+
+	protected withParser<T>(fn: (parser: ParserLike) => T): T {
+		const parser = new this.ParserCtor();
+		parser.setLanguage(this.grammar);
+		return fn(parser);
+	}
+
+	parse(source: Buffer | string): ParsedFile {
+		const text = typeof source === "string" ? source : source.toString("utf8");
+		const buf = Buffer.from(text, "utf8");
+		return this.withParser((parser) => {
+			const tree = parser.parse(text);
+			const diagnostics: ParseDiagnostic[] = [];
+			collectDiagnostics(tree.rootNode, diagnostics);
+			const overloads = new Map<string, string[]>();
+			collectOverloadSignatures(tree.rootNode, text, overloads);
+			const functions: FunctionRecord[] = [];
+			const renderUnits: RenderUnit[] = [
+				{
+					kind: "raw",
+					startByte: 0,
+					endByte: buf.length,
+					moveSupported: false,
+				},
+			];
+			const anonymousOrdinals = new Map<string, number>();
+			this.collect(tree.rootNode, text, buf, functions, renderUnits, null, anonymousOrdinals);
+			for (const fn of functions) {
+				const signatures = overloads.get(fn.functionName);
+				if (signatures?.length) fn.overloadSignatures = signatures;
+			}
+			return {
+				language: this.language,
+				renderUnits,
+				functions,
+				diagnostics,
+			};
+		});
+	}
+
+	private collect(
+		node: RawNode,
+		text: string,
+		_buf: Buffer,
+		functions: FunctionRecord[],
+		renderUnits: RenderUnit[],
+		parentName: string | null,
+		anonymousOrdinals: Map<string, number>,
+	): void {
+		for (const child of node.children ?? []) {
+			this.visitNode(child, text, functions, renderUnits, parentName, anonymousOrdinals);
+		}
+	}
+
+	protected visitNode(
+		node: RawNode,
+		text: string,
+		functions: FunctionRecord[],
+		renderUnits: RenderUnit[],
+		parentName: string | null,
+		anonymousOrdinals: Map<string, number>,
+	): void {
+		if (this.isCallable(node.type)) {
+			const name = functionName(node);
+			const qualified = qualifiedName(node, parentName, anonymousOrdinals);
+			const callableText = text.slice(node.startIndex, node.endIndex);
+			const container = classContainer(node);
+			functions.push({
+				fileDir: "",
+				fileName: "",
+				functionName: qualified,
+				language: this.language,
+				kind: detectKind(node),
+				fullCode: callableText,
+				fullCodeHash: hashText(callableText),
+				renderCode: callableText,
+				renderCodeHash: hashText(callableText),
+				parent: parentName ?? undefined,
+				container,
+				moveSupported: !!(name && container !== undefined ? true : false),
+				isPrimary: true,
+				overloadSignatures: undefined,
+				provenance: locator(node),
+				summary: null,
+				version: 1,
+			});
+			renderUnits.push({
+				kind: node.type === "method_definition" ? "method" : node.type === "arrow_function" ? "arrow" : "function",
+				startByte: node.startIndex,
+				endByte: node.endIndex,
+				label: qualified,
+				moveSupported: !!name,
+				children: this.collectNested(node, text, functions, renderUnits, qualified, anonymousOrdinals),
+			});
+			return;
+		}
+		this.collect(node, text, Buffer.from(text, "utf8"), functions, renderUnits, parentName, anonymousOrdinals);
+	}
+
+	protected collectNested(
+		node: RawNode,
+		text: string,
+		functions: FunctionRecord[],
+		renderUnits: RenderUnit[],
+		parentName: string,
+		anonymousOrdinals: Map<string, number>,
+	): RenderUnit[] {
+		const nested: RenderUnit[] = [];
+		for (const child of node.children ?? []) {
+			if (this.isCallable(child.type)) {
+				const name = functionName(child);
+				const qualified = qualifiedName(child, parentName, anonymousOrdinals);
+				const callableText = text.slice(child.startIndex, child.endIndex);
+				const container = classContainer(child);
+				functions.push({
+					fileDir: "",
+					fileName: "",
+					functionName: qualified,
+					language: this.language,
+					kind: detectKind(child),
+					fullCode: callableText,
+					fullCodeHash: hashText(callableText),
+					renderCode: callableText,
+					renderCodeHash: hashText(callableText),
+					parent: parentName,
+					container,
+					moveSupported: !!name,
+					isPrimary: true,
+					provenance: locator(child),
+					summary: null,
+					version: 1,
+				});
+				nested.push({
+					kind: child.type === "method_definition" ? "method" : child.type === "arrow_function" ? "arrow" : "function",
+					startByte: child.startIndex,
+					endByte: child.endIndex,
+					label: qualified,
+					moveSupported: !!name,
+				});
+			} else if (child.children) {
+				for (const sub of child.children ?? []) this.visitNode(sub, text, functions, renderUnits, parentName, anonymousOrdinals);
+			}
+		}
+		return nested;
+	}
+
+	protected isCallable(type: string): boolean {
+		return (
+			type === "function_declaration" ||
+			type === "method_definition" ||
+			type === "generator_function_declaration" ||
+			type === "arrow_function" ||
+			type === "function_expression" ||
+			type === "lambda"
+		);
+	}
+}

package/src/code-graph/paths.ts

@@ -0,0 +1,85 @@
+/**
+ * Canonical worktree root and relative POSIX path helpers for the code-graph
+ * module. Strictly forbids absolute paths, `..`, and Windows separators.
+ */
+
+import { spawnSync } from "node:child_process";
+import * as path from "node:path";
+import { resolveStateRootOrNull } from "../state.ts";
+
+export interface WorktreePaths {
+	worktreeRoot: string;
+	gitCommonDir: string;
+	stateRoot: string;
+	codeGraphDb: string;
+}
+
+export class PathError extends Error {}
+
+function runGit(cwd: string, args: string[]): { code: number; stdout: string } {
+	const env: Record<string, string | undefined> = { ...process.env };
+	for (const key of ["GIT_DIR", "GIT_COMMON_DIR", "GIT_WORK_TREE"]) delete env[key];
+	const result = spawnSync("git", args, { cwd, env, encoding: "utf8" });
+	return { code: result.status ?? 1, stdout: result.stdout ?? "" };
+}
+
+export function resolveCanonicalWorktree(workdir: string): WorktreePaths {
+	const toplevel = runGit(workdir, ["rev-parse", "--show-toplevel"]);
+	if (toplevel.code !== 0) {
+		throw new PathError(`workdir is not inside a git work tree: ${workdir}`);
+	}
+	const common = runGit(workdir, ["rev-parse", "--git-common-dir"]);
+	if (common.code !== 0) {
+		throw new PathError(`git common dir unavailable for ${workdir}`);
+	}
+	const worktreeRoot = path.resolve(toplevel.stdout.trim());
+	const gitCommonDir = path.resolve(workdir, common.stdout.trim());
+	const stateRoot = path.join(gitCommonDir, "pi_plans");
+	if (!resolveStateRootOrNull(workdir)) {
+		throw new PathError(`pi-plans state missing; run a planning init first`);
+	}
+	return {
+		worktreeRoot,
+		gitCommonDir,
+		stateRoot,
+		codeGraphDb: path.join(stateRoot, "code_graph.db"),
+	};
+}
+
+export function normalizeRelative(worktreeRoot: string, target: string): { fileDir: string; fileName: string } {
+	const abs = path.resolve(target);
+	if (!abs.startsWith(worktreeRoot + path.sep) && abs !== worktreeRoot) {
+		throw new PathError(`path ${target} is outside worktree root ${worktreeRoot}`);
+	}
+	const rel = abs === worktreeRoot ? "." : path.relative(worktreeRoot, abs);
+	if (rel.startsWith("..") || path.isAbsolute(rel)) {
+		throw new PathError(`path ${target} escapes the worktree root`);
+	}
+	const posix = rel.split(path.sep).join("/");
+	const parts = posix.split("/");
+	const fileName = parts[parts.length - 1];
+	const fileDir = parts.length === 1 ? "." : parts.slice(0, -1).join("/");
+	return { fileDir, fileName };
+}
+
+export function isIgnoredDir(name: string): boolean {
+	const ignored = new Set([
+		"node_modules",
+		"dist",
+		"build",
+		".next",
+		".nuxt",
+		"out",
+		"coverage",
+		"target",
+		"venv",
+		".venv",
+		"__pycache__",
+		".pytest_cache",
+		".tox",
+		".mypy_cache",
+	]);
+	if (ignored.has(name)) return true;
+	if (name.startsWith(".") && name !== ".") return true;
+	return false;
+}

package/src/code-graph/prompts.ts

@@ -0,0 +1,18 @@
+/**
+ * Graph prompt blocks injected into planner/refiner/executor contexts,
+ * conditional on the graph mode. Enabled blocks are hard rules, not hints:
+ * indexed code files must be read at function level; `full` is the only
+ * whole-file exit.
+ */
+
+export function graphBlockForRefiner(enabled: boolean): string {
+	return enabled
+		? "Code graph: indexed code files MUST be read via the function digest or code_graph (screening, get-function) — no whole-file reads; full:true only as a last resort. Graph-aware read/edit are active."
+		: "Code graph disabled: use Read/grep/ls for code context.";
+}
+
+export function graphBlockForExecutor(enabled: boolean): string {
+	return enabled
+		? "Code graph loop: indexed code files read as a function digest by default — never whole-file; drill in via offset/limit or code_graph get-function, full:true is the only whole-file exit. Edit via graph-aware edit (DB-first), then code_graph apply (its result includes the post-apply drift summary) → plans final-commit."
+		: "Code graph disabled: edit source files directly with edit/write.";
+}

package/src/code-graph/resolver.ts

@@ -0,0 +1,69 @@
+/**
+ * Conservative static call resolution. Captures call expressions of the form
+ * `name(...)` and `obj.method(...)` inside the same file; cross-file
+ * resolution is limited to relative imports and explicit module exports.
+ */
+
+import type { SourceLocation } from "./types.ts";
+import type { DiscoveredFile } from "./discovery.ts";
+
+export interface CallSite {
+	fromFunction: string;
+	calleeText: string;
+	kind: "call" | "definition" | "import";
+	resolution: "resolved" | "ambiguous" | "unresolved";
+	target?: { fileDir: string; fileName: string; functionName: string };
+	reason?: string;
+	provenance: SourceLocation;
+}
+
+const CALL_PATTERN = /\b([a-zA-Z_$][\w$]*)(?:\.([a-zA-Z_$][\w$]*))?\s*\(/g;
+
+export function resolveCalls(fromFunction: string, code: string, file: DiscoveredFile, out: CallSite[]): void {
+	for (const match of code.matchAll(CALL_PATTERN)) {
+		const head = match[1];
+		const member = match[2];
+		const start = match.index ?? 0;
+		const calleeText = match[0];
+		out.push({
+			fromFunction,
+			calleeText,
+			kind: "call",
+			resolution: "unresolved",
+			reason: "conservative resolution: same-file or relative import only",
+			provenance: locationOf(code, start, calleeText.length),
+		});
+		void head;
+		void member;
+		void file;
+	}
+	for (const match of code.matchAll(/^\s*(?:import|from)\s+([\w./-]+)/gm)) {
+		const start = match.index ?? 0;
+		out.push({
+			fromFunction,
+			calleeText: match[0],
+			kind: "import",
+			resolution: "unresolved",
+			reason: "import resolution deferred to module graph (not implemented in v1)",
+			provenance: locationOf(code, start, match[0].length),
+		});
+	}
+}
+
+function locationOf(code: string, byteStart: number, length: number): SourceLocation {
+	const before = code.slice(0, byteStart);
+	const startLine = before.split("\n").length;
+	const startColumn = before.length - before.lastIndexOf("\n");
+	const targetText = code.slice(byteStart, byteStart + length);
+	const endLine = startLine + targetText.split("\n").length - 1;
+	const endColumn =
+		targetText.split("\n").pop()?.length ?? startColumn;
+	return {
+		startByte: byteStart,
+		endByte: byteStart + length,
+		startLine,
+		startColumn,
+		endLine,
+		endColumn,
+	};
+}

package/src/code-graph/runtime.ts

@@ -0,0 +1,158 @@
+/**
+ * Lazy runtime guards for the code-graph module. Imports happen on first use
+ * so that a missing parser dependency or unsupported Node version cannot
+ * prevent the rest of pi-plans from registering.
+ *
+ * The module never throws at import time; every consumer calls one of the
+ * `ensure*` helpers and inspects the resulting status object.
+ */
+
+import { execSync } from "node:child_process";
+
+export type RuntimeIssue =
+	| { kind: "node-version"; detail: string }
+	| { kind: "sqlite-import"; detail: string }
+	| { kind: "parser-import"; detail: string; package: string }
+	| { kind: "runtime-unsupported"; detail: string };
+
+export interface RuntimeStatus {
+	nodeVersion: string;
+	nodeMajor: number;
+	hasExperimentalSqliteFlag: boolean;
+	graphEffectiveFloorMet: boolean;
+	parserAvailable: boolean;
+	sqliteAvailable: boolean;
+	bunDetected: boolean;
+	issues: RuntimeIssue[];
+}
+
+const MAJOR = Number(process.versions.node.split(".")[0]);
+const MINOR = Number(process.versions.node.split(".")[1] ?? "0");
+
+export const IS_BUN = typeof (process as { versions?: { bun?: string } }).versions?.bun === "string";
+
+function flagHasExperimentalSqlite(): boolean {
+	try {
+		const out = execSync(process.execPath, ["--experimental-sqlite", "-e", "1"], { encoding: "utf8" });
+		return out === "1";
+	} catch {
+		try {
+			const out = execSync(process.execPath, ["-e", "process.features.sqlite ?? \"off\""], { encoding: "utf8" }).trim();
+			return out !== "off" && out !== "undefined" && out !== "\"off\"";
+		} catch {
+			return false;
+		}
+	}
+}
+
+async function importSqlite(): Promise<unknown> {
+	return await import("node:sqlite");
+}
+
+async function importParser(): Promise<unknown> {
+	const mod = await import("tree-sitter");
+	const js = await import("tree-sitter-javascript");
+	const ts = await import("tree-sitter-typescript");
+	const py = await import("tree-sitter-python");
+	return { default: mod.default ?? mod, js: js.default ?? js, ts: ts.default ?? ts, py: py.default ?? py };
+}
+
+export async function detectRuntimeStatus(): Promise<RuntimeStatus> {
+	const issues: RuntimeIssue[] = [];
+	if (IS_BUN) {
+		issues.push({
+			kind: "runtime-unsupported",
+			detail: "graph feature is Node-only; detected Bun runtime",
+		});
+	}
+	const nodeVersion = process.versions.node;
+	const graphEffectiveFloorMet = IS_BUN
+		? false
+		: (MAJOR === 22 && MINOR >= 13) || MAJOR > 22;
+	const hasFlag = flagHasExperimentalSqlite();
+	const sqliteAvailable = await importSqlite()
+		.then(() => true)
+		.catch((err: Error) => {
+			issues.push({ kind: "sqlite-import", detail: err.message });
+			return false;
+		});
+	if (!sqliteAvailable && !hasFlag && !IS_BUN) {
+		issues.push({
+			kind: "node-version",
+			detail: `node:sqlite requires Node >=22.13 or --experimental-sqlite; current ${nodeVersion}`,
+		});
+	}
+	const parserAvailable = await importParser()
+		.then(() => true)
+		.catch((err: Error) => {
+			issues.push({
+				kind: "parser-import",
+				package: "tree-sitter",
+				detail: err.message,
+			});
+			return false;
+		});
+	return {
+		nodeVersion,
+		nodeMajor: MAJOR,
+		hasExperimentalSqliteFlag: hasFlag,
+		graphEffectiveFloorMet,
+		parserAvailable,
+		sqliteAvailable,
+		bunDetected: IS_BUN,
+		issues,
+	};
+}
+
+export interface GraphRuntime {
+	sqlite: typeof import("node:sqlite");
+	parser: {
+		Parser: typeof import("tree-sitter").default;
+		javascript: unknown;
+		typescript: unknown;
+		tsx: unknown;
+		python: unknown;
+	};
+}
+
+let cached: GraphRuntime | null = null;
+
+export async function loadGraphRuntime(): Promise<{ runtime: GraphRuntime; status: RuntimeStatus }> {
+	if (cached) return { runtime: cached, status: await detectRuntimeStatus() };
+	const sqlite = await importSqlite();
+	const ParserMod = await import("tree-sitter");
+	const jsMod = await import("tree-sitter-javascript");
+	const tsMod = await import("tree-sitter-typescript");
+	const pyMod = await import("tree-sitter-python");
+	const Parser = (ParserMod as { default?: unknown }).default ?? ParserMod;
+	const runtime: GraphRuntime = {
+		sqlite: sqlite as typeof import("node:sqlite"),
+		parser: {
+			Parser: Parser as typeof import("tree-sitter").default,
+			javascript: (jsMod as { default?: unknown }).default ?? jsMod,
+			typescript: (tsMod as { default?: { typescript: unknown; tsx: unknown } }).default?.typescript ?? tsMod,
+			tsx: (tsMod as { default?: { tsx: unknown } }).default?.tsx ?? tsMod,
+			python: (pyMod as { default?: unknown }).default ?? pyMod,
+		},
+	};
+	cached = runtime;
+	return { runtime, status: await detectRuntimeStatus() };
+}
+
+export function describeRuntimeIssues(status: RuntimeStatus): string[] {
+	if (status.issues.length === 0) return [];
+	return status.issues.map((issue) => {
+		switch (issue.kind) {
+			case "node-version":
+				return `Node version: ${issue.detail}`;
+			case "sqlite-import":
+				return `node:sqlite import failed: ${issue.detail}`;
+			case "parser-import":
+				return `parser import failed (${issue.package}): ${issue.detail}`;
+			case "runtime-unsupported":
+				return `runtime: ${issue.detail}`;
+			default:
+				return "unknown runtime issue";
+		}
+	});
+}