@saluzi/codegraph 0.1.0

package/dist/db/index.d.ts

@@ -0,0 +1,101 @@
+/**
+ * Database Layer
+ *
+ * Handles SQLite database initialization and connection management.
+ */
+import { SqliteDatabase, SqliteBackend } from './sqlite-adapter'
+import { SchemaVersion } from '../types'
+export { SqliteDatabase, SqliteBackend } from './sqlite-adapter'
+/**
+ * Database connection wrapper with lifecycle management
+ */
+export declare class DatabaseConnection {
+  private db
+  private dbPath
+  private backend
+  private constructor()
+  /**
+   * Initialize a new database at the given path
+   */
+  static initialize(dbPath: string): DatabaseConnection
+  /**
+   * Open an existing database
+   */
+  static open(dbPath: string): DatabaseConnection
+  /**
+   * Get the underlying database instance
+   */
+  getDb(): SqliteDatabase
+  /**
+   * Get the SQLite backend serving this connection. Per-instance so
+   * MCP cross-project queries report the right backend even when
+   * multiple project DBs are open in the same process.
+   */
+  getBackend(): SqliteBackend
+  /**
+   * Get database file path
+   */
+  getPath(): string
+  /**
+   * The journal mode actually in effect (e.g. 'wal', 'delete').
+   *
+   * SQLite silently keeps the prior mode if WAL can't be enabled — e.g. on
+   * filesystems without shared-memory support (some network/virtualized mounts,
+   * WSL2 /mnt), and always on the wasm backend. So the effective mode can differ
+   * from what `configureConnection` requested. Surfaced in `codegraph status` so
+   * a "database is locked" report is triageable: 'wal' ⇒ readers never block on a
+   * writer; anything else ⇒ they can. See issue #238.
+   */
+  getJournalMode(): string
+  /**
+   * Get current schema version
+   */
+  getSchemaVersion(): SchemaVersion | null
+  /**
+   * Execute a function within a transaction
+   */
+  transaction<T>(fn: () => T): T
+  /**
+   * Get database file size in bytes
+   */
+  getSize(): number
+  /**
+   * Optimize database (vacuum and analyze)
+   */
+  optimize(): void
+  /**
+   * Lightweight, non-blocking maintenance to run after bulk writes
+   * (indexAll, sync). Two operations:
+   *
+   *   - `PRAGMA optimize` — incremental ANALYZE; SQLite only re-analyzes
+   *     tables whose row counts changed materially since the last
+   *     ANALYZE. Without it, the query planner has no statistics on the
+   *     freshly-bulk-loaded tables and can pick suboptimal indexes.
+   *
+   *   - `PRAGMA wal_checkpoint(PASSIVE)` — fold pending WAL pages back
+   *     into the main database file so the WAL file doesn't grow
+   *     unboundedly between automatic checkpoints (auto-fires at 1000
+   *     pages by default; large indexAll runs blow past that).
+   *
+   * Both operations are silently swallowed on failure — they're a
+   * best-effort optimization, never load-bearing for correctness.
+   */
+  runMaintenance(): void
+  /**
+   * Close the database connection
+   */
+  close(): void
+  /**
+   * Check if the database connection is open
+   */
+  isOpen(): boolean
+}
+/**
+ * Default database filename
+ */
+export declare const DATABASE_FILENAME = 'codegraph.db'
+/**
+ * Get the default database path for a project
+ */
+export declare function getDatabasePath(projectRoot: string): string
+//# sourceMappingURL=index.d.ts.map

package/dist/db/index.js

@@ -0,0 +1,250 @@
+"use strict";
+/**
+ * Database Layer
+ *
+ * Handles SQLite database initialization and connection management.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DATABASE_FILENAME = exports.DatabaseConnection = void 0;
+exports.getDatabasePath = getDatabasePath;
+const sqlite_adapter_1 = require("./sqlite-adapter");
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const migrations_1 = require("./migrations");
+/**
+ * Apply connection-level PRAGMAs. Shared by `initialize` and `open` so the two
+ * paths can't drift.
+ *
+ * `busy_timeout` is set FIRST, before any pragma that might touch the database
+ * file (notably `journal_mode`). If another process holds a write lock at open
+ * time, the later pragmas — and the connection's first query — then wait out
+ * the lock instead of throwing "database is locked" immediately. See issue #238.
+ *
+ * The 5s window (was 120s) rides out a normal incremental sync; the old
+ * 2-minute wait presented as a frozen, hung agent. With WAL, reads never block
+ * on a writer, so this timeout only governs cross-process write contention
+ * (e.g. the git-hook `codegraph sync` running while the MCP server writes).
+ */
+function configureConnection(db) {
+    db.pragma('busy_timeout = 5000'); // MUST be first — see above
+    db.pragma('foreign_keys = ON');
+    db.pragma('journal_mode = WAL'); // node:sqlite supports WAL on every platform
+    db.pragma('synchronous = NORMAL'); // safe with WAL mode
+    db.pragma('cache_size = -64000'); // 64 MB page cache
+    db.pragma('temp_store = MEMORY'); // temp tables in memory
+    db.pragma('mmap_size = 268435456'); // 256 MB memory-mapped I/O
+}
+/**
+ * Database connection wrapper with lifecycle management
+ */
+class DatabaseConnection {
+    db;
+    dbPath;
+    backend;
+    constructor(db, dbPath, backend) {
+        this.db = db;
+        this.dbPath = dbPath;
+        this.backend = backend;
+    }
+    /**
+     * Initialize a new database at the given path
+     */
+    static initialize(dbPath) {
+        // Ensure parent directory exists
+        const dir = path.dirname(dbPath);
+        if (!fs.existsSync(dir)) {
+            fs.mkdirSync(dir, { recursive: true });
+        }
+        // Create and configure database
+        const { db, backend } = (0, sqlite_adapter_1.createDatabase)(dbPath);
+        configureConnection(db);
+        // Run schema initialization
+        const schemaPath = path.join(__dirname, 'schema.sql');
+        const schema = fs.readFileSync(schemaPath, 'utf-8');
+        db.exec(schema);
+        // Record current schema version so migrations aren't re-applied on open
+        const currentVersion = (0, migrations_1.getCurrentVersion)(db);
+        if (currentVersion < migrations_1.CURRENT_SCHEMA_VERSION) {
+            db.prepare('INSERT OR IGNORE INTO schema_versions (version, applied_at, description) VALUES (?, ?, ?)').run(migrations_1.CURRENT_SCHEMA_VERSION, Date.now(), 'Initial schema includes all migrations');
+        }
+        return new DatabaseConnection(db, dbPath, backend);
+    }
+    /**
+     * Open an existing database
+     */
+    static open(dbPath) {
+        if (!fs.existsSync(dbPath)) {
+            throw new Error(`Database not found: ${dbPath}`);
+        }
+        const { db, backend } = (0, sqlite_adapter_1.createDatabase)(dbPath);
+        configureConnection(db);
+        // Check and run migrations if needed
+        const conn = new DatabaseConnection(db, dbPath, backend);
+        const currentVersion = (0, migrations_1.getCurrentVersion)(db);
+        if (currentVersion < migrations_1.CURRENT_SCHEMA_VERSION) {
+            (0, migrations_1.runMigrations)(db, currentVersion);
+        }
+        return conn;
+    }
+    /**
+     * Get the underlying database instance
+     */
+    getDb() {
+        return this.db;
+    }
+    /**
+     * Get the SQLite backend serving this connection. Per-instance so
+     * MCP cross-project queries report the right backend even when
+     * multiple project DBs are open in the same process.
+     */
+    getBackend() {
+        return this.backend;
+    }
+    /**
+     * Get database file path
+     */
+    getPath() {
+        return this.dbPath;
+    }
+    /**
+     * The journal mode actually in effect (e.g. 'wal', 'delete').
+     *
+     * SQLite silently keeps the prior mode if WAL can't be enabled — e.g. on
+     * filesystems without shared-memory support (some network/virtualized mounts,
+     * WSL2 /mnt), and always on the wasm backend. So the effective mode can differ
+     * from what `configureConnection` requested. Surfaced in `codegraph status` so
+     * a "database is locked" report is triageable: 'wal' ⇒ readers never block on a
+     * writer; anything else ⇒ they can. See issue #238.
+     */
+    getJournalMode() {
+        const raw = this.db.pragma('journal_mode');
+        const row = Array.isArray(raw) ? raw[0] : raw;
+        const mode = row && typeof row === 'object'
+            ? row.journal_mode
+            : row;
+        return String(mode ?? '').toLowerCase();
+    }
+    /**
+     * Get current schema version
+     */
+    getSchemaVersion() {
+        const row = this.db
+            .prepare('SELECT version, applied_at, description FROM schema_versions ORDER BY version DESC LIMIT 1')
+            .get();
+        if (!row)
+            return null;
+        return {
+            version: row.version,
+            appliedAt: row.applied_at,
+            description: row.description ?? undefined,
+        };
+    }
+    /**
+     * Execute a function within a transaction
+     */
+    transaction(fn) {
+        return this.db.transaction(fn)();
+    }
+    /**
+     * Get database file size in bytes
+     */
+    getSize() {
+        const stats = fs.statSync(this.dbPath);
+        return stats.size;
+    }
+    /**
+     * Optimize database (vacuum and analyze)
+     */
+    optimize() {
+        this.db.exec('VACUUM');
+        this.db.exec('ANALYZE');
+    }
+    /**
+     * Lightweight, non-blocking maintenance to run after bulk writes
+     * (indexAll, sync). Two operations:
+     *
+     *   - `PRAGMA optimize` — incremental ANALYZE; SQLite only re-analyzes
+     *     tables whose row counts changed materially since the last
+     *     ANALYZE. Without it, the query planner has no statistics on the
+     *     freshly-bulk-loaded tables and can pick suboptimal indexes.
+     *
+     *   - `PRAGMA wal_checkpoint(PASSIVE)` — fold pending WAL pages back
+     *     into the main database file so the WAL file doesn't grow
+     *     unboundedly between automatic checkpoints (auto-fires at 1000
+     *     pages by default; large indexAll runs blow past that).
+     *
+     * Both operations are silently swallowed on failure — they're a
+     * best-effort optimization, never load-bearing for correctness.
+     */
+    runMaintenance() {
+        try {
+            this.db.exec('PRAGMA optimize');
+        }
+        catch {
+            // ignore
+        }
+        try {
+            this.db.exec('PRAGMA wal_checkpoint(PASSIVE)');
+        }
+        catch {
+            // ignore (e.g., not in WAL mode)
+        }
+    }
+    /**
+     * Close the database connection
+     */
+    close() {
+        this.db.close();
+    }
+    /**
+     * Check if the database connection is open
+     */
+    isOpen() {
+        return this.db.open;
+    }
+}
+exports.DatabaseConnection = DatabaseConnection;
+/**
+ * Default database filename
+ */
+exports.DATABASE_FILENAME = 'codegraph.db';
+/**
+ * Get the default database path for a project
+ */
+function getDatabasePath(projectRoot) {
+    return path.join(projectRoot, '.codegraph', exports.DATABASE_FILENAME);
+}
+//# sourceMappingURL=index.js.map

package/dist/db/migrations.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Database Migrations
+ *
+ * Schema versioning and migration support.
+ */
+import { SqliteDatabase } from './sqlite-adapter'
+/**
+ * Current schema version
+ */
+export declare const CURRENT_SCHEMA_VERSION = 4
+/**
+ * Migration definition
+ */
+interface Migration {
+  version: number
+  description: string
+  up: (db: SqliteDatabase) => void
+}
+/**
+ * Get the current schema version from the database
+ */
+export declare function getCurrentVersion(db: SqliteDatabase): number
+/**
+ * Run all pending migrations
+ */
+export declare function runMigrations(
+  db: SqliteDatabase,
+  fromVersion: number,
+): void
+/**
+ * Check if the database needs migration
+ */
+export declare function needsMigration(db: SqliteDatabase): boolean
+/**
+ * Get list of pending migrations
+ */
+export declare function getPendingMigrations(db: SqliteDatabase): Migration[]
+/**
+ * Get migration history from database
+ */
+export declare function getMigrationHistory(db: SqliteDatabase): Array<{
+  version: number
+  appliedAt: number
+  description: string | null
+}>
+export {}
+//# sourceMappingURL=migrations.d.ts.map

package/dist/db/migrations.js

@@ -0,0 +1,131 @@
+"use strict";
+/**
+ * Database Migrations
+ *
+ * Schema versioning and migration support.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CURRENT_SCHEMA_VERSION = void 0;
+exports.getCurrentVersion = getCurrentVersion;
+exports.runMigrations = runMigrations;
+exports.needsMigration = needsMigration;
+exports.getPendingMigrations = getPendingMigrations;
+exports.getMigrationHistory = getMigrationHistory;
+/**
+ * Current schema version
+ */
+exports.CURRENT_SCHEMA_VERSION = 4;
+/**
+ * All migrations in order
+ *
+ * Note: Version 1 is the initial schema, handled by schema.sql
+ * Future migrations go here.
+ */
+const migrations = [
+    {
+        version: 2,
+        description: 'Add project metadata, provenance tracking, and unresolved ref context',
+        up: (db) => {
+            db.exec(`
+        CREATE TABLE IF NOT EXISTS project_metadata (
+          key TEXT PRIMARY KEY,
+          value TEXT NOT NULL,
+          updated_at INTEGER NOT NULL
+        );
+        ALTER TABLE unresolved_refs ADD COLUMN file_path TEXT NOT NULL DEFAULT '';
+        ALTER TABLE unresolved_refs ADD COLUMN language TEXT NOT NULL DEFAULT 'unknown';
+        ALTER TABLE edges ADD COLUMN provenance TEXT DEFAULT NULL;
+        CREATE INDEX IF NOT EXISTS idx_unresolved_file_path ON unresolved_refs(file_path);
+        CREATE INDEX IF NOT EXISTS idx_edges_provenance ON edges(provenance);
+      `);
+        },
+    },
+    {
+        version: 3,
+        description: 'Add lower(name) expression index for memory-efficient case-insensitive lookups',
+        up: (db) => {
+            db.exec(`
+        CREATE INDEX IF NOT EXISTS idx_nodes_lower_name ON nodes(lower(name));
+      `);
+        },
+    },
+    {
+        version: 4,
+        description: 'Drop redundant idx_edges_source / idx_edges_target (covered by source_kind / target_kind composites)',
+        up: (db) => {
+            db.exec(`
+        DROP INDEX IF EXISTS idx_edges_source;
+        DROP INDEX IF EXISTS idx_edges_target;
+      `);
+        },
+    },
+];
+/**
+ * Get the current schema version from the database
+ */
+function getCurrentVersion(db) {
+    try {
+        const row = db
+            .prepare('SELECT MAX(version) as version FROM schema_versions')
+            .get();
+        return row?.version ?? 0;
+    }
+    catch {
+        // Table doesn't exist yet
+        return 0;
+    }
+}
+/**
+ * Record a migration as applied
+ */
+function recordMigration(db, version, description) {
+    db.prepare('INSERT INTO schema_versions (version, applied_at, description) VALUES (?, ?, ?)').run(version, Date.now(), description);
+}
+/**
+ * Run all pending migrations
+ */
+function runMigrations(db, fromVersion) {
+    const pending = migrations.filter((m) => m.version > fromVersion);
+    if (pending.length === 0) {
+        return;
+    }
+    // Sort by version
+    pending.sort((a, b) => a.version - b.version);
+    // Run each migration in a transaction
+    for (const migration of pending) {
+        db.transaction(() => {
+            migration.up(db);
+            recordMigration(db, migration.version, migration.description);
+        })();
+    }
+}
+/**
+ * Check if the database needs migration
+ */
+function needsMigration(db) {
+    const current = getCurrentVersion(db);
+    return current < exports.CURRENT_SCHEMA_VERSION;
+}
+/**
+ * Get list of pending migrations
+ */
+function getPendingMigrations(db) {
+    const current = getCurrentVersion(db);
+    return migrations
+        .filter((m) => m.version > current)
+        .sort((a, b) => a.version - b.version);
+}
+/**
+ * Get migration history from database
+ */
+function getMigrationHistory(db) {
+    const rows = db
+        .prepare('SELECT version, applied_at, description FROM schema_versions ORDER BY version')
+        .all();
+    return rows.map((row) => ({
+        version: row.version,
+        appliedAt: row.applied_at,
+        description: row.description,
+    }));
+}
+//# sourceMappingURL=migrations.js.map