pi-plans 0.2.0 → 0.3.1

package/src/code-graph/schema.ts

@@ -0,0 +1,135 @@
+/**
+ * Schema definition and migrations for the code-graph SQLite database. The
+ * database is intentionally normalized — JSON views are derived from the
+ * edge tables at query time and never stored alongside them.
+ */
+
+export const CURRENT_SCHEMA_VERSION = 2;
+
+export const SCHEMA_STATEMENTS: string[] = [
+	`CREATE TABLE IF NOT EXISTS graph_meta (
+		schema_version INTEGER PRIMARY KEY,
+		worktree_root TEXT NOT NULL,
+		git_common_dir TEXT NOT NULL,
+		parser_versions TEXT NOT NULL,
+		updated_at TEXT NOT NULL
+	)`,
+	`CREATE TABLE IF NOT EXISTS files (
+		file_dir TEXT NOT NULL,
+		file_name TEXT NOT NULL,
+		language TEXT NOT NULL,
+		source_hash TEXT NOT NULL,
+		source_text TEXT NOT NULL,
+		pending_kind TEXT,
+		updated_at TEXT NOT NULL,
+		PRIMARY KEY (file_dir, file_name)
+	)`,
+	`CREATE TABLE IF NOT EXISTS file_entries (
+		id INTEGER PRIMARY KEY AUTOINCREMENT,
+		file_dir TEXT NOT NULL,
+		file_name TEXT NOT NULL,
+		ordinal INTEGER NOT NULL,
+		kind TEXT NOT NULL,
+		function_name TEXT,
+		start_byte INTEGER NOT NULL,
+		end_byte INTEGER NOT NULL,
+		text TEXT NOT NULL,
+		UNIQUE (file_dir, file_name, ordinal)
+	)`,
+	`CREATE INDEX IF NOT EXISTS idx_file_entries_file ON file_entries (file_dir, file_name, ordinal)`,
+	`CREATE TABLE IF NOT EXISTS functions (
+		file_dir TEXT NOT NULL,
+		file_name TEXT NOT NULL,
+		function_name TEXT NOT NULL,
+		language TEXT NOT NULL,
+		kind TEXT NOT NULL,
+		full_code TEXT NOT NULL,
+		full_code_hash TEXT NOT NULL,
+		render_code TEXT NOT NULL,
+		render_code_hash TEXT NOT NULL,
+		parent TEXT,
+		container TEXT,
+		move_supported INTEGER NOT NULL,
+		is_primary INTEGER NOT NULL,
+		overload_signatures TEXT,
+		provenance_start_byte INTEGER NOT NULL,
+		provenance_end_byte INTEGER NOT NULL,
+		provenance_start_line INTEGER NOT NULL,
+		provenance_start_col INTEGER NOT NULL,
+		provenance_end_line INTEGER NOT NULL,
+		provenance_end_col INTEGER NOT NULL,
+		summary_description TEXT,
+		summary_inputs TEXT,
+		summary_outputs TEXT,
+		summary_status TEXT,
+		summary_model TEXT,
+		summary_schema_version INTEGER,
+		summary_effective_effort TEXT,
+		summary_error TEXT,
+		summary_updated_at TEXT,
+		version INTEGER NOT NULL DEFAULT 1,
+		PRIMARY KEY (file_dir, file_name, function_name)
+	)`,
+	`CREATE TABLE IF NOT EXISTS call_edges (
+		id INTEGER PRIMARY KEY AUTOINCREMENT,
+		from_file_dir TEXT NOT NULL,
+		from_file_name TEXT NOT NULL,
+		from_function TEXT NOT NULL,
+		to_file_dir TEXT,
+		to_file_name TEXT,
+		to_function TEXT,
+		to_callee_text TEXT NOT NULL,
+		kind TEXT NOT NULL,
+		resolution TEXT NOT NULL,
+		reason TEXT,
+		provenance_start_byte INTEGER NOT NULL,
+		provenance_end_byte INTEGER NOT NULL,
+		provenance_start_line INTEGER NOT NULL,
+		provenance_start_col INTEGER NOT NULL,
+		provenance_end_line INTEGER NOT NULL,
+		provenance_end_col INTEGER NOT NULL
+	)`,
+	`CREATE INDEX IF NOT EXISTS idx_call_edges_from ON call_edges (from_file_dir, from_file_name, from_function)`,
+	`CREATE INDEX IF NOT EXISTS idx_call_edges_to ON call_edges (to_file_dir, to_file_name, to_function)`,
+	`CREATE TABLE IF NOT EXISTS change_log (
+		id INTEGER PRIMARY KEY AUTOINCREMENT,
+		kind TEXT NOT NULL,
+		detail TEXT NOT NULL,
+		recorded_at TEXT NOT NULL
+	)`,
+	`CREATE TABLE IF NOT EXISTS reindex_conflicts (
+		id INTEGER PRIMARY KEY AUTOINCREMENT,
+		file_dir TEXT NOT NULL,
+		file_name TEXT NOT NULL,
+		kind TEXT NOT NULL,
+		detail TEXT NOT NULL,
+		recorded_at TEXT NOT NULL
+	)`,
+	`CREATE TABLE IF NOT EXISTS code_graph_snapshot (
+		id INTEGER PRIMARY KEY AUTOINCREMENT,
+		head_commit TEXT NOT NULL,
+		uncommitted_paths TEXT NOT NULL,
+		recorded_at TEXT NOT NULL
+	)`,
+];
+
+export const FUNCTION_RECORDS_VIEW = `
+CREATE VIEW IF NOT EXISTS function_records AS
+SELECT
+	f.file_dir AS file_dir,
+	f.file_name AS file_name,
+	f.function_name AS function_name,
+	f.language AS language,
+	f.kind AS kind,
+	f.parent AS parent,
+	f.container AS container,
+	f.move_supported AS move_supported,
+	f.is_primary AS is_primary,
+	f.provenance_start_byte AS provenance_start_byte,
+	f.provenance_end_byte AS provenance_end_byte,
+	(SELECT json_group_array(json_object('file_dir', e.from_file_dir, 'file_name', e.from_file_name, 'function_name', e.from_function))
+		FROM call_edges e WHERE e.to_file_dir = f.file_dir AND e.to_file_name = f.file_name AND e.to_function = f.function_name AND e.resolution = 'resolved') AS in_links_json,
+	(SELECT json_group_array(json_object('file_dir', e.to_file_dir, 'file_name', e.to_file_name, 'function_name', e.to_function))
+		FROM call_edges e WHERE e.from_file_dir = f.file_dir AND e.from_file_name = f.file_name AND e.from_function = f.function_name AND e.resolution = 'resolved') AS out_links_json
+FROM functions f
+`;

package/src/code-graph/screening.ts

@@ -0,0 +1,82 @@
+/**
+ * Read-only screening queries that exclude full_code from the response.
+ * Used by the agent-facing tool and `/graph-status`.
+ */
+
+import { Store } from "./store.ts";
+import type { FunctionScreening, Language } from "./types.ts";
+
+export interface ScreeningOptions {
+	store: Store;
+	language?: Language;
+	functionNameLike?: string;
+	limit?: number;
+}
+
+export function screeningQuery(opts: ScreeningOptions): FunctionScreening[] {
+	const conditions: string[] = [];
+	const params: Array<string | number> = [];
+	if (opts.language) {
+		conditions.push("f.language = ?");
+		params.push(opts.language);
+	}
+	if (opts.functionNameLike) {
+		conditions.push("f.function_name LIKE ?");
+		params.push(`%${opts.functionNameLike}%`);
+	}
+	const where = conditions.length ? `WHERE ${conditions.join(" AND ")}` : "";
+	const limit = Math.max(1, Math.min(opts.limit ?? 100, 500));
+	const rows = opts.store
+		.read(() =>
+			opts.store.db
+				.prepare(
+					`SELECT
+						f.file_dir AS file_dir,
+						f.file_name AS file_name,
+						f.function_name AS function_name,
+						f.language AS language,
+						f.kind AS kind,
+						f.summary_description AS description,
+						f.summary_inputs AS inputs_json,
+						f.summary_outputs AS outputs_json,
+						f.summary_status AS summary_status,
+						f.version AS version,
+						(SELECT json_group_array(json_object('file_dir', e.from_file_dir, 'file_name', e.from_file_name, 'function_name', e.from_function))
+							FROM call_edges e WHERE e.to_file_dir = f.file_dir AND e.to_file_name = f.file_name AND e.to_function = f.function_name AND e.resolution = 'resolved') AS in_json,
+						(SELECT json_group_array(json_object('file_dir', e.to_file_dir, 'file_name', e.to_file_name, 'function_name', e.to_function))
+							FROM call_edges e WHERE e.from_file_dir = f.file_dir AND e.from_file_name = f.file_name AND e.from_function = f.function_name AND e.resolution = 'resolved') AS out_json
+					FROM functions f
+					${where}
+					ORDER BY f.file_dir, f.file_name, f.function_name
+					LIMIT ${limit}`,
+				)
+				.all(...params),
+		) as Array<{
+			file_dir: string;
+			file_name: string;
+			function_name: string;
+			language: Language;
+			kind: string;
+			description: string | null;
+			inputs_json: string | null;
+			outputs_json: string | null;
+			summary_status: string | null;
+			version: number;
+			in_json: string | null;
+			out_json: string | null;
+		}>;
+	return rows.map((row) => ({
+		fileDir: row.file_dir,
+		fileName: row.file_name,
+		functionName: row.function_name,
+		language: row.language,
+		kind: row.kind as FunctionScreening["kind"],
+		description: row.description,
+		inputs: row.inputs_json ? (JSON.parse(row.inputs_json) as string[]) : null,
+		outputs: row.outputs_json ? (JSON.parse(row.outputs_json) as string[]) : null,
+		version: row.version,
+		summaryStatus: row.summary_status as FunctionScreening["summaryStatus"],
+		inLinks: row.in_json ? (JSON.parse(row.in_json) as FunctionScreening["inLinks"]) : [],
+		outLinks: row.out_json ? (JSON.parse(row.out_json) as FunctionScreening["outLinks"]) : [],
+	}));
+}

package/src/code-graph/store.ts

@@ -0,0 +1,278 @@
+/**
+ * SQLite handle, prepared statements and BEGIN IMMEDIATE write transactions
+ * for the code-graph module.
+ */
+
+import type { DatabaseSync, StatementSync } from "node:sqlite";
+import { CURRENT_SCHEMA_VERSION, FUNCTION_RECORDS_VIEW, SCHEMA_STATEMENTS } from "./schema.ts";
+import { PathError } from "./paths.ts";
+import type { CodeGraphSnapshot, GraphMeta } from "./types.ts";
+
+export interface StoreOptions {
+	dbPath: string;
+	worktreeRoot: string;
+	gitCommonDir: string;
+	parserVersions?: Record<string, string>;
+	readonly?: boolean;
+}
+
+export class Store {
+	readonly db: DatabaseSync;
+	readonly dbPath: string;
+	readonly worktreeRoot: string;
+	readonly gitCommonDir: string;
+
+	private prepared: Map<string, StatementSync> = new Map();
+	private readonly mode: "rw" | "ro";
+
+	constructor(opts: StoreOptions, sqlite: typeof import("node:sqlite")) {
+		this.dbPath = opts.dbPath;
+		this.worktreeRoot = opts.worktreeRoot;
+		this.gitCommonDir = opts.gitCommonDir;
+		this.mode = opts.readonly ? "ro" : "rw";
+		this.db = new sqlite.DatabaseSync(opts.dbPath, {
+			open: true,
+			readOnly: opts.readonly === true,
+			enableForeignKeyConstraints: true,
+		});
+		this.bootstrap(opts);
+	}
+
+	private bootstrap(opts: StoreOptions): void {
+		this.db.exec("PRAGMA foreign_keys = ON");
+		this.db.exec("PRAGMA journal_mode = WAL");
+		this.db.exec("PRAGMA busy_timeout = 5000");
+		const existing = this.db
+			.prepare("SELECT name FROM sqlite_master WHERE type='table' AND name='graph_meta'")
+			.get();
+		if (!existing) {
+			this.applyMigrations();
+			this.upsertMeta({
+				schemaVersion: CURRENT_SCHEMA_VERSION,
+				worktreeRoot: opts.worktreeRoot,
+				gitCommonDir: opts.gitCommonDir,
+				parserVersions: opts.parserVersions ?? {},
+				updatedAt: new Date().toISOString(),
+			});
+			return;
+		}
+		const row = this.db.prepare("SELECT MAX(schema_version) AS v FROM graph_meta").get() as { v: number } | undefined;
+		const version = row?.v ?? 0;
+		if (version < CURRENT_SCHEMA_VERSION) {
+			this.applyIncrementalMigrations(version, opts);
+			this.upsertMeta({
+				schemaVersion: CURRENT_SCHEMA_VERSION,
+				worktreeRoot: opts.worktreeRoot,
+				gitCommonDir: opts.gitCommonDir,
+				parserVersions: opts.parserVersions ?? {},
+				updatedAt: new Date().toISOString(),
+			});
+		}
+	}
+
+	/** Step-level idempotent incremental migration: each step checks its target
+	 *  artifact (PRAGMA table_info / sqlite_master) before applying, so a crash
+	 *  mid-upgrade can be safely re-entered. schema_version advances only after
+	 *  all steps complete. */
+	private applyIncrementalMigrations(fromVersion: number, opts: StoreOptions): void {
+		this.tx(() => {
+			if (fromVersion < 2) {
+				const snapshotTable = this.db
+					.prepare("SELECT name FROM sqlite_master WHERE type='table' AND name='code_graph_snapshot'")
+					.get();
+				if (!snapshotTable) {
+					this.db.exec(
+						`CREATE TABLE code_graph_snapshot (
+						id INTEGER PRIMARY KEY AUTOINCREMENT,
+						head_commit TEXT NOT NULL,
+						uncommitted_paths TEXT NOT NULL,
+						recorded_at TEXT NOT NULL
+					)`,
+					);
+				}
+				const columns = this.db.prepare("PRAGMA table_info(files)").all() as Array<{ name: string }>;
+				if (!columns.some((column) => column.name === "pending_kind")) {
+					this.db.exec("ALTER TABLE files ADD COLUMN pending_kind TEXT");
+				}
+				const initialSnapshot = this.db
+					.prepare("SELECT COUNT(*) AS c FROM code_graph_snapshot")
+					.get() as { c: number };
+				if (initialSnapshot.c === 0) {
+					this.db
+						.prepare(
+							`INSERT INTO code_graph_snapshot (head_commit, uncommitted_paths, recorded_at)
+							 VALUES (?, ?, ?)`,
+						)
+						.run("", "[]", new Date().toISOString());
+				}
+			}
+			void opts;
+		});
+	}
+
+	private applyMigrations(): void {
+		for (const stmt of SCHEMA_STATEMENTS) this.db.exec(stmt);
+		this.db.exec(FUNCTION_RECORDS_VIEW);
+		this.db
+			.prepare(
+				`INSERT INTO graph_meta (schema_version, worktree_root, git_common_dir, parser_versions, updated_at)
+				 VALUES (?, ?, ?, ?, ?)
+				 ON CONFLICT(schema_version) DO UPDATE SET
+					worktree_root = excluded.worktree_root,
+					git_common_dir = excluded.git_common_dir,
+					parser_versions = excluded.parser_versions,
+					updated_at = excluded.updated_at`,
+			)
+			.run(
+				CURRENT_SCHEMA_VERSION,
+				this.worktreeRoot,
+				this.gitCommonDir,
+				JSON.stringify({}),
+				new Date().toISOString(),
+			);
+	}
+
+	upsertMeta(meta: GraphMeta): void {
+		this.db
+			.prepare(
+				`INSERT INTO graph_meta (schema_version, worktree_root, git_common_dir, parser_versions, updated_at)
+				 VALUES (?, ?, ?, ?, ?)
+				 ON CONFLICT(schema_version) DO UPDATE SET
+					worktree_root = excluded.worktree_root,
+					git_common_dir = excluded.git_common_dir,
+					parser_versions = excluded.parser_versions,
+					updated_at = excluded.updated_at`,
+			)
+			.run(
+				meta.schemaVersion,
+				meta.worktreeRoot,
+				meta.gitCommonDir,
+				JSON.stringify(meta.parserVersions),
+				meta.updatedAt,
+			);
+	}
+
+	upsertSnapshot(headCommit: string, uncommittedPaths: string[]): void {
+		this.tx(() => {
+			this.db
+				.prepare(
+					`INSERT INTO code_graph_snapshot (head_commit, uncommitted_paths, recorded_at)
+					 VALUES (?, ?, ?)`,
+				)
+				.run(headCommit, JSON.stringify(uncommittedPaths), new Date().toISOString());
+		});
+	}
+
+	readLatestSnapshot(): CodeGraphSnapshot | null {
+		const row = this.db
+			.prepare(
+					`SELECT id, head_commit, uncommitted_paths, recorded_at
+				 FROM code_graph_snapshot ORDER BY id DESC LIMIT 1`,
+			)
+			.get() as
+			| { id: number; head_commit: string; uncommitted_paths: string; recorded_at: string }
+			| undefined;
+		if (!row) return null;
+		return {
+			id: row.id,
+			headCommit: row.head_commit,
+			uncommittedPaths: JSON.parse(row.uncommitted_paths) as string[],
+			recordedAt: row.recorded_at,
+		};
+	}
+
+	readMeta(): GraphMeta | null {
+		const row = this.db
+			.prepare(
+				`SELECT schema_version, worktree_root, git_common_dir, parser_versions, updated_at
+				 FROM graph_meta ORDER BY schema_version DESC LIMIT 1`,
+			)
+			.get() as {
+			schema_version: number;
+			worktree_root: string;
+			git_common_dir: string;
+			parser_versions: string;
+			updated_at: string;
+		} | undefined;
+		if (!row) return null;
+		return {
+			schemaVersion: row.schema_version,
+			worktreeRoot: row.worktree_root,
+			gitCommonDir: row.git_common_dir,
+			parserVersions: JSON.parse(row.parser_versions) as Record<string, string>,
+			updatedAt: row.updated_at,
+		};
+	}
+
+	checkWorktree(currentWorktreeRoot: string, currentGitCommonDir: string): void {
+		const meta = this.readMeta();
+		if (!meta) return;
+		if (meta.worktreeRoot !== currentWorktreeRoot || meta.gitCommonDir !== currentGitCommonDir) {
+			throw new PathError(
+				`code_graph.db belongs to ${meta.worktreeRoot} (${meta.gitCommonDir}); current worktree is ${currentWorktreeRoot} (${currentGitCommonDir}). Refusing to share the DB across worktrees.`,
+			);
+		}
+	}
+
+	/** Run a function inside a write transaction. Uses BEGIN IMMEDIATE so that
+	 * reads cannot later upgrade to writes and bypass busy timeouts. */
+	tx<T>(fn: () => T): T {
+		if (this.mode === "ro") throw new Error("store is opened read-only; cannot begin a write transaction");
+		this.db.exec("BEGIN IMMEDIATE");
+		try {
+			const result = fn();
+			this.db.exec("COMMIT");
+			return result;
+		} catch (error) {
+			try {
+				this.db.exec("ROLLBACK");
+			} catch {
+				/* rollback failure is non-fatal after a write error */
+			}
+			throw error;
+		}
+	}
+
+	read<T>(fn: () => T): T {
+		this.db.exec("BEGIN");
+		try {
+			const result = fn();
+			this.db.exec("COMMIT");
+			return result;
+		} catch (error) {
+			try {
+				this.db.exec("ROLLBACK");
+			} catch {
+				/* ignore */
+			}
+			throw error;
+		}
+	}
+
+	prepare(key: string, sql: string): StatementSync {
+		let stmt = this.prepared.get(key);
+		if (!stmt) {
+			stmt = this.db.prepare(sql);
+			this.prepared.set(key, stmt);
+		}
+		return stmt;
+	}
+
+	close(): void {
+		try {
+			this.db.close();
+		} catch {
+			/* best effort */
+		}
+	}
+
+	exists(): boolean {
+		return true;
+	}
+}
+
+/** Helper for tests: run a function inside a fresh in-memory store. */
+export async function openStore(opts: StoreOptions): Promise<Store> {
+	const sqlite = await import("node:sqlite");
+	return new Store(opts, sqlite);
+}