pi-plans 0.2.0 → 0.3.1

package/src/code-graph/materialize.ts

@@ -0,0 +1,166 @@
+/**
+ * DB-to-source materialization. `files.source_text` is the canonical content
+ * for every row. Files whose `pending_kind` is set (DB-first mutations) are
+ * applied with convergence semantics: 'update' writes/creates the file;
+ * 'delete' removes the disk file and purges its DB rows. Pending-NULL files
+ * keep the stale-hash guard and are never rewritten from manifest entries —
+ * render-unit texts are not a faithful mirror of the source (empty texts,
+ * overlapping spans), so reassembly from `file_entries` is unsafe.
+ */
+
+import * as fs from "node:fs";
+import * as path from "node:path";
+import * as os from "node:os";
+import { Store } from "./store.ts";
+
+export interface MaterializeOptions {
+	store: Store;
+	worktreeRoot: string;
+	force?: boolean;
+}
+
+export interface MaterializeReport {
+	files: Array<{
+		fileDir: string;
+		fileName: string;
+		absolutePath: string;
+		status: "ok" | "stale" | "error" | "deleted" | "skipped-missing";
+		reason?: string;
+	}>;
+}
+
+function loadSourceText(store: Store, fileDir: string, fileName: string): { text: string; hash: string } | null {
+	const row = store
+		.read(() =>
+			store.db
+				.prepare(
+					`SELECT source_text, source_hash FROM files WHERE file_dir = ? AND file_name = ?`,
+				)
+				.get(fileDir, fileName),
+		) as { source_text: string; source_hash: string } | undefined;
+	return row ? { text: row.source_text, hash: row.source_hash } : null;
+}
+
+function hashText(text: string): string {
+	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");
+}
+
+export function materializeFile(
+	store: Store,
+	worktreeRoot: string,
+	fileDir: string,
+	fileName: string,
+	opts: { force?: boolean } = {},
+): { status: "ok" | "stale" | "error" | "deleted" | "skipped-missing"; reason?: string; written?: string } {
+	const file = loadSourceText(store, fileDir, fileName);
+	if (!file) return { status: "error", reason: "file not indexed" };
+	const absolute = path.join(worktreeRoot, fileDir === "." ? fileName : path.join(fileDir, fileName));
+	const pendingKind = store.read(() =>
+		store.db.prepare(`SELECT pending_kind FROM files WHERE file_dir = ? AND file_name = ?`).get(fileDir, fileName),
+	) as { pending_kind: string | null } | undefined;
+	const pending = pendingKind?.pending_kind ?? null;
+
+	if (pending === "delete") {
+		try {
+			if (fs.existsSync(absolute)) fs.rmSync(absolute);
+		} catch (error) {
+			return { status: "error", reason: (error as Error).message };
+		}
+		store.tx(() => {
+			store.db.prepare(`DELETE FROM file_entries WHERE file_dir = ? AND file_name = ?`).run(fileDir, fileName);
+			store.db.prepare(`DELETE FROM call_edges WHERE from_file_dir = ? AND from_file_name = ?`).run(fileDir, fileName);
+			store.db.prepare(`DELETE FROM functions WHERE file_dir = ? AND file_name = ?`).run(fileDir, fileName);
+			store.db.prepare(`DELETE FROM files WHERE file_dir = ? AND file_name = ?`).run(fileDir, fileName);
+		});
+		return { status: "deleted", written: absolute };
+	}
+
+	let currentText: string | null = null;
+	try {
+		currentText = fs.readFileSync(absolute, "utf8");
+	} catch {
+		currentText = null;
+	}
+	if (pending === "update") {
+		// DB-first convergence: files.source_text IS the canonical new content
+		// (mutations maintain it; the loop-end reindex rebuilds the manifest).
+		// Write (or create) regardless of the on-disk hash.
+		const write = writeAtomically(absolute, file.text);
+		if (write.error) return { status: "error", reason: write.error };
+		store.tx(() => {
+			store.db
+				.prepare(`UPDATE files SET pending_kind = NULL, updated_at = ? WHERE file_dir = ? AND file_name = ?`)
+				.run(new Date().toISOString(), fileDir, fileName);
+		});
+		return { status: "ok", written: absolute };
+	}
+	if (currentText === null) {
+		// Pending-NULL and missing on disk: never resurrect deletions.
+		return { status: "skipped-missing", reason: "file missing on disk and not pending; skipped (not resurrected)" };
+	}
+	const currentHash = hashText(currentText);
+	if (currentHash !== file.hash) {
+		if (!opts.force) {
+			return { status: "stale", reason: `current hash ${currentHash} != indexed hash ${file.hash}` };
+		}
+		// Force converge from the canonical DB content, not the manifest.
+		const write = writeAtomically(absolute, file.text);
+		if (write.error) return { status: "error", reason: write.error };
+		return { status: "ok", written: absolute };
+	}
+	// Disk already matches the canonical source_text: nothing to converge.
+	// Never rewrite pending-NULL files from manifest entries — render-unit
+	// texts are empty/overlapping for real indexes, so reassembly corrupts.
+	return { status: "ok" };
+}
+
+function writeAtomically(absolute: string, output: string): { error?: string } {
+	try {
+		fs.mkdirSync(path.dirname(absolute), { recursive: true });
+		const tmp = path.join(os.tmpdir(), `code-graph-apply-${process.pid}-${Date.now()}-${path.basename(absolute)}`);
+		fs.writeFileSync(tmp, output);
+		try {
+			fs.renameSync(tmp, absolute);
+		} catch (error) {
+			try {
+				fs.unlinkSync(tmp);
+			} catch {
+				/* ignore */
+			}
+			return { error: (error as Error).message };
+		}
+		return {};
+	} catch (error) {
+		return { error: (error as Error).message };
+	}
+}
+
+export function materialize(opts: MaterializeOptions): MaterializeReport {
+	const rows = opts.store
+		.read(() =>
+			opts.store.db
+				.prepare(
+					`SELECT file_dir, file_name FROM files ORDER BY file_dir, file_name`,
+				)
+				.all(),
+		) as Array<{ file_dir: string; file_name: string }>;
+	const files: MaterializeReport["files"] = [];
+	for (const row of rows) {
+		const result = materializeFile(opts.store, opts.worktreeRoot, row.file_dir, row.file_name, {
+			force: opts.force === true,
+		});
+		files.push({
+			fileDir: row.file_dir,
+			fileName: row.file_name,
+			absolutePath: path.join(opts.worktreeRoot, row.file_dir === "." ? row.file_name : path.join(row.file_dir, row.file_name)),
+			status: result.status,
+			reason: result.reason,
+		});
+	}
+	return { files };
+}

package/src/code-graph/mode.ts

@@ -0,0 +1,28 @@
+/**
+ * Shared graph-enabled tri-state resolution. Both the graph-aware file-tool
+ * wrappers (tools/) and the execution prompt injection (src/exec.ts) must read
+ * the SAME state through this helper, so the injected guidance and the actual
+ * tool behavior can never diverge.
+ *
+ * Three states, deliberately not a boolean:
+ *   - "enabled"             — graph_enabled === true: wrappers and graph reads active.
+ *   - "off"                 — flag explicitly false/absent: native tools, no markers
+ *                             (the injected prompt already announces the disabled state).
+ *   - "config-unavailable"  — state root missing config or config.json unreadable:
+ *                             treated as an unexpected fallback and surfaced with a
+ *                             marker line (never silently collapsed into "off").
+ */
+
+import { loadConfig, resolveStateRootOrNull } from "../state.ts";
+
+export type GraphMode = "enabled" | "off" | "config-unavailable";
+
+export function resolveGraphMode(workdir: string): GraphMode {
+	const stateRoot = resolveStateRootOrNull(workdir);
+	if (!stateRoot) return "off";
+	try {
+		return loadConfig(stateRoot).graph_enabled === true ? "enabled" : "off";
+	} catch {
+		return "config-unavailable";
+	}
+}

package/src/code-graph/mutations.ts

@@ -0,0 +1,160 @@
+/**
+ * DB-first mutation core for the code_graph tool. Each mutation edits graph
+ * rows, marks the file pending_materialization, and appends to change_log.
+ * /apply-graph later converges the worktree to the DB state.
+ */
+
+import { Store } from "./store.ts";
+import { hashText } from "./parser.ts";
+import type { Language } from "./types.ts";
+
+export interface MutationResult {
+	ok: boolean;
+	reason?: string;
+	updated?: string;
+	pending?: "update" | "delete";
+	created?: boolean;
+}
+
+interface ManifestRow {
+	ordinal: number;
+	start_byte: number;
+	end_byte: number;
+	text: string;
+	function_name: string | null;
+}
+
+function loadManifest(store: Store, fileDir: string, fileName: string): ManifestRow[] {
+	return store.read(() =>
+		store.db
+			.prepare(
+				`SELECT ordinal, start_byte, end_byte, text, function_name FROM file_entries
+				 WHERE file_dir = ? AND file_name = ? ORDER BY ordinal ASC`,
+			)
+			.all(fileDir, fileName),
+	) as ManifestRow[];
+}
+
+export function updateFunction(
+	store: Store,
+	opts: { fileDir: string; fileName: string; functionName: string; fullCode: string },
+): MutationResult {
+	const fnRow = store.read(() =>
+		store.db
+			.prepare(
+				`SELECT provenance_start_byte, provenance_end_byte FROM functions
+				 WHERE file_dir = ? AND file_name = ? AND function_name = ? LIMIT 1`,
+			)
+			.get(opts.fileDir, opts.fileName, opts.functionName),
+	) as { provenance_start_byte: number; provenance_end_byte: number } | undefined;
+	if (!fnRow) return { ok: false, reason: "function not found" };
+
+	// Reads hoisted OUT of the tx: Store.read begins its own transaction.
+	const manifest = loadManifest(store, opts.fileDir, opts.fileName);
+	const fileRow = store.read(() =>
+		store.db.prepare(`SELECT source_text FROM files WHERE file_dir = ? AND file_name = ?`).get(opts.fileDir, opts.fileName),
+	) as { source_text: string } | undefined;
+	const matched = manifest.filter((row) => row.function_name === opts.functionName);
+	if (!fileRow || matched.length === 0) {
+		return {
+			ok: false,
+			reason: !fileRow
+				? "file row missing; run /update-graph first"
+				: "no manifest entry matched the function name (qualified/overload names like name#2 may differ); re-check via code_graph get-function",
+		};
+	}
+
+	const newHash = hashText(opts.fullCode);
+	const first = matched[0]!;
+	// Splice by the function's provenance byte range — the authoritative source
+	// of the callable's extent. Manifest entry texts from the current parser are
+	// empty, so reassembly-by-manifest cannot rebuild function bodies; the range
+	// splice is deterministic and reindex-independent.
+	const start = fnRow.provenance_start_byte;
+	const end = fnRow.provenance_end_byte;
+	const rebuilt = fileRow.source_text.slice(0, start) + opts.fullCode + fileRow.source_text.slice(end);
+	const delta = opts.fullCode.length - (end - start);
+	for (const row of manifest) {
+		if (row.ordinal === first.ordinal) row.text = opts.fullCode;
+		else if (row.start_byte >= end) {
+			// Persist the shift so later reassembly aligns; the loop-end reindex
+			// rebuilds entries authoritatively anyway.
+			row.start_byte += delta;
+			row.end_byte += delta;
+		}
+	}
+	store.tx(() => {
+		store.db
+			.prepare(
+				`UPDATE functions SET full_code = ?, full_code_hash = ?, render_code = ?, render_code_hash = ?
+				 WHERE file_dir = ? AND file_name = ? AND function_name = ?`,
+			)
+			.run(opts.fullCode, newHash, opts.fullCode, newHash, opts.fileDir, opts.fileName, opts.functionName);
+		for (const row of manifest) {
+			store.db
+				.prepare(`UPDATE file_entries SET text = ?, start_byte = ?, end_byte = ? WHERE file_dir = ? AND file_name = ? AND ordinal = ?`)
+				.run(row.text, row.start_byte, row.ordinal === first.ordinal ? row.end_byte + delta : row.end_byte, opts.fileDir, opts.fileName, row.ordinal);
+		}
+		store.db
+			.prepare(`UPDATE files SET source_text = ?, source_hash = ?, pending_kind = 'update', updated_at = ? WHERE file_dir = ? AND file_name = ?`)
+			.run(rebuilt, hashText(rebuilt), new Date().toISOString(), opts.fileDir, opts.fileName);
+		store.db
+			.prepare(`INSERT INTO change_log (kind, detail, recorded_at) VALUES (?, ?, ?)`)
+			.run("update-function", `${opts.fileDir}/${opts.fileName}:${opts.functionName}`, new Date().toISOString());
+	});
+	return { ok: true, updated: `${opts.fileDir}/${opts.fileName}:${opts.functionName}`, pending: "update" };
+}
+
+export function updateFile(
+	store: Store,
+	opts: { fileDir: string; fileName: string; text: string; language?: Language },
+): MutationResult {
+	const exists = store.read(() =>
+		store.db.prepare(`SELECT 1 AS one FROM files WHERE file_dir = ? AND file_name = ?`).get(opts.fileDir, opts.fileName),
+	);
+	const now = new Date().toISOString();
+	store.tx(() => {
+		if (exists) {
+			// Whole-file replace: entries would be stale; drop them so the
+			// materializer falls back to source_text. The loop-end reindex rebuilds.
+			store.db.prepare(`DELETE FROM file_entries WHERE file_dir = ? AND file_name = ?`).run(opts.fileDir, opts.fileName);
+			store.db
+				.prepare(`UPDATE files SET source_text = ?, source_hash = ?, pending_kind = 'update', updated_at = ? WHERE file_dir = ? AND file_name = ?`)
+				.run(opts.text, hashText(opts.text), now, opts.fileDir, opts.fileName);
+		} else {
+			store.db
+				.prepare(
+					`INSERT INTO files (file_dir, file_name, language, source_hash, source_text, pending_kind, updated_at)
+					 VALUES (?, ?, ?, ?, ?, 'update', ?)`,
+				)
+				.run(opts.fileDir, opts.fileName, opts.language ?? "javascript", hashText(opts.text), opts.text, now);
+		}
+		store.db
+			.prepare(`INSERT INTO change_log (kind, detail, recorded_at) VALUES (?, ?, ?)`)
+			.run("update-file", `${opts.fileDir}/${opts.fileName}`, now);
+	});
+	return { ok: true, updated: `${opts.fileDir}/${opts.fileName}`, pending: "update", created: !exists };
+}
+
+export function deleteFile(store: Store, opts: { fileDir: string; fileName: string }): MutationResult {
+	const exists = store.read(() =>
+		store.db.prepare(`SELECT 1 AS one FROM files WHERE file_dir = ? AND file_name = ?`).get(opts.fileDir, opts.fileName),
+	);
+	if (!exists) return { ok: false, reason: "file not indexed" };
+	store.tx(() => {
+		store.db.prepare(`UPDATE files SET pending_kind = 'delete' WHERE file_dir = ? AND file_name = ?`).run(opts.fileDir, opts.fileName);
+		store.db
+			.prepare(`INSERT INTO change_log (kind, detail, recorded_at) VALUES (?, ?, ?)`)
+			.run("delete-file", `${opts.fileDir}/${opts.fileName}`, new Date().toISOString());
+	});
+	return { ok: true, updated: `${opts.fileDir}/${opts.fileName}`, pending: "delete" };
+}
+
+export function listPending(store: Store): Array<{ path: string; kind: string }> {
+	const rows = store.read(() =>
+		store.db
+			.prepare(`SELECT file_dir, file_name, pending_kind FROM files WHERE pending_kind IS NOT NULL ORDER BY file_dir, file_name`)
+			.all(),
+	) as Array<{ file_dir: string; file_name: string; pending_kind: string }>;
+	return rows.map((row) => ({ path: `${row.file_dir}/${row.file_name}`, kind: row.pending_kind }));
+}

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,
+	);
+}