pi-plans 0.2.0 → 0.3.0

package/src/code-graph/parser.ts

@@ -0,0 +1,51 @@
+/**
+ * Parser backend interface. Each backend returns a list of render units plus a
+ * list of (callable) function records. Callable spans do not overlap with
+ * each other; overlapping spans are flattened through the parent linkage.
+ */
+
+import type {
+	FunctionRecord,
+	Language,
+	ParseDiagnostic,
+	RenderUnit,
+	SourceLocation,
+} from "./types.ts";
+
+export interface ParsedFile {
+	language: Language;
+	renderUnits: RenderUnit[];
+	functions: FunctionRecord[];
+	diagnostics: ParseDiagnostic[];
+}
+
+export interface ParserBackend {
+	readonly language: Language;
+	parse(source: Buffer | string): ParsedFile;
+}
+
+export interface ParserContext {
+	ParserCtor: new () => unknown;
+	grammar: unknown;
+}
+
+export function makeLocation(
+	startByte: number,
+	endByte: number,
+	startLine: number,
+	startColumn: number,
+	endLine: number,
+	endColumn: number,
+): SourceLocation {
+	return { startByte, endByte, startLine, startColumn, endLine, endColumn };
+}
+
+export function hashText(text: string): string {
+	// Simple non-cryptographic hash, fast and stable for fingerprinting.
+	let h = 0x811c9dc5;
+	for (let i = 0; i < text.length; i++) {
+		h ^= text.charCodeAt(i);
+		h = Math.imul(h, 0x01000193);
+	}
+	return (h >>> 0).toString(16).padStart(8, "0");
+}

package/src/code-graph/parsers/javascript.ts

@@ -0,0 +1,35 @@
+/**
+ * JavaScript / ECMAScript backend. Implements JS function declaration,
+ * expression, arrow, method, generator and async functions.
+ */
+
+import { TreeSitterBackend } from "./tree-sitter.ts";
+import type { FunctionRecord, Language } from "../types.ts";
+
+export interface JavaScriptGrammar {
+	default?: unknown;
+	[key: string]: unknown;
+}
+
+export class JavaScriptBackend extends TreeSitterBackend {
+	readonly language: Language = "javascript";
+}
+
+export class TypeScriptBackend extends TreeSitterBackend {
+	readonly language: Language = "typescript";
+}
+
+export class TsxBackend extends TreeSitterBackend {
+	readonly language: Language = "tsx";
+}
+
+export function makeBackend(
+	language: "javascript" | "typescript" | "tsx",
+	ParserCtor: new () => unknown,
+	grammar: unknown,
+): TreeSitterBackend {
+	const opts = { ParserCtor: ParserCtor as never, language: grammar };
+	if (language === "javascript") return new JavaScriptBackend(opts);
+	if (language === "typescript") return new TypeScriptBackend(opts);
+	return new TsxBackend(opts);
+}

package/src/code-graph/parsers/python.ts

@@ -0,0 +1,160 @@
+/**
+ * Python backend. Recognizes `def`, `async def`, and `lambda` expressions,
+ * class methods, and decorators as parent-relative nested entries.
+ */
+
+import type { ParserBackend, ParsedFile } from "../parser.ts";
+import type { FunctionRecord, ParseDiagnostic, RenderUnit } from "../types.ts";
+import { hashText, makeLocation } from "../parser.ts";
+
+interface PythonNode {
+	type: string;
+	startIndex: number;
+	endIndex: number;
+	startPosition: { row: number; column: number };
+	endPosition: { row: number; column: number };
+	namedChildren: PythonNode[];
+	children: PythonNode[];
+	text?: string;
+	parent?: PythonNode;
+	isMissing?: boolean;
+	hasError?: boolean;
+}
+
+interface ParserLike {
+	parse(input: string | Buffer): { rootNode: PythonNode };
+	setLanguage(language: unknown): void;
+}
+
+export class PythonBackend implements ParserBackend {
+	readonly language = "python" as const;
+	private readonly ParserCtor: new () => ParserLike;
+	private readonly grammar: unknown;
+
+	constructor(ParserCtor: new () => unknown, grammar: unknown) {
+		this.ParserCtor = ParserCtor as never;
+		this.grammar = grammar;
+	}
+
+	parse(source: Buffer | string): ParsedFile {
+		const text = typeof source === "string" ? source : source.toString("utf8");
+		const buf = Buffer.from(text, "utf8");
+		const parser = new this.ParserCtor();
+		parser.setLanguage(this.grammar);
+		const tree = parser.parse(text);
+		const diagnostics: ParseDiagnostic[] = [];
+		const collectDiag = (node: PythonNode) => {
+			if (node.hasError || node.isMissing) {
+				diagnostics.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.namedChildren ?? []) collectDiag(child);
+		};
+		collectDiag(tree.rootNode);
+		const functions: FunctionRecord[] = [];
+		const renderUnits: RenderUnit[] = [
+			{ kind: "raw", startByte: 0, endByte: buf.length, moveSupported: false },
+		];
+		const anonymousOrdinals = new Map<string, number>();
+		const visit = (node: PythonNode, parentName: string | null) => {
+			if (node.type === "decorated_definition") {
+				for (const child of node.namedChildren ?? []) visit(child, parentName);
+				return;
+			}
+			if (node.type === "function_definition" || node.type === "lambda") {
+				const nameNode = (node.namedChildren ?? []).find(
+					(c) => c.type === "identifier" || c.type === "name",
+				);
+				let id = nameNode?.text;
+				if (!id) {
+					const scope = parentName ?? findClass(node) ?? "<module>";
+					const key = `${scope}\0${node.type}`;
+					const ordinal = (anonymousOrdinals.get(key) ?? 0) + 1;
+					anonymousOrdinals.set(key, ordinal);
+					id = `<anonymous:${node.type}#${ordinal}>`;
+				}
+				const qualified = parentName ? `${parentName}.${id}` : id;
+				const callableText = text.slice(node.startIndex, node.endIndex);
+				const container = findClass(node);
+				functions.push({
+					fileDir: "",
+					fileName: "",
+					functionName: qualified,
+					language: "python",
+					kind: node.type === "lambda" ? "lambda" : "declaration",
+					fullCode: callableText,
+					fullCodeHash: hashText(callableText),
+					renderCode: callableText,
+					renderCodeHash: hashText(callableText),
+					parent: parentName ?? undefined,
+					container,
+					moveSupported: node.type !== "lambda" && !!nameNode,
+					isPrimary: true,
+					provenance: locator(node),
+					summary: null,
+					version: 1,
+				});
+				renderUnits.push({
+					kind: node.type === "lambda" ? "lambda" : "function",
+					startByte: node.startIndex,
+					endByte: node.endIndex,
+					label: qualified,
+					moveSupported: node.type !== "lambda",
+					children: [],
+				});
+				return;
+			}
+			if (node.type === "class_definition") {
+				const classNameNode = (node.namedChildren ?? []).find(
+					(c) => c.type === "identifier" || c.type === "name",
+				);
+				const className = classNameNode?.text ?? "<anonymous>";
+				const children: RenderUnit[] = [];
+				for (const child of node.namedChildren ?? []) {
+					if (child.type === "block") {
+						for (const inner of child.namedChildren ?? []) visit(inner, className);
+					}
+				}
+				renderUnits.push({
+					kind: "raw",
+					startByte: node.startIndex,
+					endByte: node.endIndex,
+					label: className,
+					moveSupported: false,
+					children,
+				});
+				return;
+			}
+			for (const child of node.namedChildren ?? []) visit(child, parentName);
+		};
+		visit(tree.rootNode, null);
+		return { language: "python", renderUnits, functions, diagnostics };
+	}
+}
+
+function findClass(node: PythonNode): string | undefined {
+	let p: PythonNode | undefined = node.parent;
+	while (p) {
+		if (p.type === "class_definition") {
+			const nameNode = (p.namedChildren ?? []).find((c) => c.type === "identifier" || c.type === "name");
+			return nameNode?.text ?? "<anonymous>";
+		}
+		p = p.parent;
+	}
+	return undefined;
+}
+
+function locator(node: PythonNode) {
+	return makeLocation(
+		node.startIndex,
+		node.endIndex,
+		node.startPosition.row + 1,
+		node.startPosition.column,
+		node.endPosition.row + 1,
+		node.endPosition.column,
+	);
+}

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 /apply-graph → /graph-drift → plans final-commit."
+		: "Code graph disabled: edit source files directly with edit/write.";
+}