@stupidloud/codegraph 0.8.1 → 0.9.9

package/dist/db/index.js

@@ -38,14 +38,35 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.DATABASE_FILENAME = exports.DatabaseConnection = exports.WASM_FALLBACK_FIX_RECIPE = void 0;
+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");
-var sqlite_adapter_2 = require("./sqlite-adapter");
-Object.defineProperty(exports, "WASM_FALLBACK_FIX_RECIPE", { enumerable: true, get: function () { return sqlite_adapter_2.WASM_FALLBACK_FIX_RECIPE; } });
+/**
+ * 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
  */
@@ -69,17 +90,7 @@ class DatabaseConnection {
         }
         // Create and configure database
         const { db, backend } = (0, sqlite_adapter_1.createDatabase)(dbPath);
-        // Enable foreign keys and WAL mode for better performance
-        db.pragma('foreign_keys = ON');
-        db.pragma('journal_mode = WAL');
-        // Wait up to 2 minutes if database is locked by another process
-        // (indexing operations can hold locks for extended periods)
-        db.pragma('busy_timeout = 120000');
-        // Performance tuning
-        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
+        configureConnection(db);
         // Run schema initialization
         const schemaPath = path.join(__dirname, 'schema.sql');
         const schema = fs.readFileSync(schemaPath, 'utf-8');
@@ -99,17 +110,7 @@ class DatabaseConnection {
             throw new Error(`Database not found: ${dbPath}`);
         }
         const { db, backend } = (0, sqlite_adapter_1.createDatabase)(dbPath);
-        // Enable foreign keys and WAL mode
-        db.pragma('foreign_keys = ON');
-        db.pragma('journal_mode = WAL');
-        // Wait up to 2 minutes if database is locked by another process
-        // (indexing operations can hold locks for extended periods)
-        db.pragma('busy_timeout = 120000');
-        // Performance tuning
-        db.pragma('synchronous = NORMAL');
-        db.pragma('cache_size = -64000');
-        db.pragma('temp_store = MEMORY');
-        db.pragma('mmap_size = 268435456');
+        configureConnection(db);
         // Check and run migrations if needed
         const conn = new DatabaseConnection(db, dbPath, backend);
         const currentVersion = (0, migrations_1.getCurrentVersion)(db);
@@ -138,6 +139,24 @@ class DatabaseConnection {
     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
      */
@@ -173,6 +192,37 @@ class DatabaseConnection {
         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
      */

package/dist/db/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/db/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/db/index.ts"],"names":[],"mappings":"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"}

package/dist/db/queries.d.ts

@@ -38,6 +38,23 @@ export declare class QueryBuilder {
      * Get a node by ID
      */
     getNodeById(id: string): Node | null;
+    /**
+     * Batch lookup: fetch many nodes by ID in a single SQL round-trip.
+     *
+     * Replaces the N+1 pattern in graph traversal where every edge would
+     * trigger its own `getNodeById` call. For a function with 50 callers
+     * this collapses 50 point reads into one IN-list query (~10-50x
+     * faster end-to-end).
+     *
+     * Returns a Map keyed by id so callers can preserve their own ordering
+     * (typically the order edges were returned from the graph). Missing IDs
+     * are simply absent from the map.
+     *
+     * Cache-aware: ids already in the LRU cache are served from memory and
+     * the SQL query only touches the misses.
+     */
+    getNodesByIds(ids: readonly string[]): Map<string, Node>;
+    private getExistingNodeIds;
     /**
      * Add a node to the cache, evicting oldest if needed
      */
@@ -50,10 +67,81 @@ export declare class QueryBuilder {
      * Get all nodes in a file
      */
     getNodesByFile(filePath: string): Node[];
+    /**
+     * Find the file that holds the densest concentration of the project's
+     * internal call graph — the "core" file. Used by context-builder to
+     * boost ranking of symbols in that file's directory (so e.g. sinatra
+     * queries surface `lib/sinatra/base.rb`'s `route!` instead of
+     * `sinatra-contrib/lib/sinatra/multi_route.rb`'s `route` extension).
+     *
+     * Returns null if no file has a meaningful concentration (e.g. spread
+     * evenly across many files, or empty index).
+     *
+     * "Internal" = source and target are in the same file. Cross-file
+     * edges aren't useful here — they don't tell us which file is the
+     * functional center.
+     *
+     * Excludes test/spec files from candidacy via path-pattern. The agent's
+     * typical question is "how does X work", not "how is X tested", so
+     * boosting a test file's directory would be a misfire.
+     */
+    getDominantFile(): {
+        filePath: string;
+        edgeCount: number;
+        nextEdgeCount: number;
+    } | null;
+    /**
+     * Find the file that holds the densest concentration of the project's
+     * `route` nodes (framework-emitted: Express/Gin/Flask/Rails/Drupal/etc.).
+     * Used by handleContext on small repos to inline the project's routing
+     * config when the agent's query is about request flow — eliminating the
+     * "Glob + Read routes.rb" pattern that beats codegraph on tiny realworld
+     * template repos.
+     *
+     * Excludes test/generated files from candidacy. Returns null if there
+     * are fewer than 3 non-test routes total, or if no file holds at least
+     * 30% of them (diffuse routing → no single answer file).
+     */
+    getTopRouteFile(): {
+        filePath: string;
+        routeCount: number;
+        totalRoutes: number;
+    } | null;
+    /**
+     * Build a URL → handler manifest from the index. Each route node's
+     * `references` edge points at the function/method that handles the
+     * request. We join them in one pass; the agent gets the canonical
+     * routing answer ("POST /users/login → AuthController#login") without
+     * having to parse the framework's route DSL itself.
+     *
+     * Also returns the file with the most handler endpoints — used as the
+     * "top handler file" to inline source for, so the agent has both the
+     * mapping AND the handler implementations.
+     */
+    getRoutingManifest(limit?: number): {
+        entries: Array<{
+            url: string;
+            handler: string;
+            handlerFile: string;
+            handlerLine: number;
+            handlerKind: string;
+        }>;
+        topHandlerFile: string | null;
+        topHandlerFileCount: number;
+        totalRoutes: number;
+    } | null;
     /**
      * Get all nodes of a specific kind
      */
     getNodesByKind(kind: NodeKind): Node[];
+    /**
+     * Stream every node of a kind one at a time (lazy) instead of materializing
+     * them all like {@link getNodesByKind}. For unbounded kinds (`function`,
+     * `method`) on a symbol-dense project the full array is gigabytes; the
+     * dynamic-edge synthesizers only scan-and-filter, so they iterate to keep
+     * memory O(1) in the node count rather than O(nodes) (#610).
+     */
+    iterateNodesByKind(kind: NodeKind): IterableIterator<Node>;
     /**
      * Get all nodes in the database
      */
@@ -166,6 +254,11 @@ export declare class QueryBuilder {
      * Get all tracked files
      */
     getAllFiles(): FileRecord[];
+    /**
+     * Most recent index timestamp (ms since epoch) across all tracked files, or
+     * null when nothing is indexed yet. One indexed aggregate, no per-row scan. (#329)
+     */
+    getLastIndexedAt(): number | null;
     /**
      * Get files that need re-indexing (hash changed)
      */
@@ -229,6 +322,17 @@ export declare class QueryBuilder {
         referenceName: string;
         referenceKind: string;
     }>): void;
+    /**
+     * Lightweight (nodes, edges) count snapshot. Used around an index/sync
+     * run to compute true additions across extraction + resolution +
+     * synthesis — the per-phase counter in the orchestrator only sees
+     * extraction's contribution, which is why the CLI summary under-reported
+     * the edge count (resolution + synthesizer edges were invisible).
+     */
+    getNodeAndEdgeCount(): {
+        nodes: number;
+        edges: number;
+    };
     /**
      * Get graph statistics
      */

package/dist/db/queries.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"queries.d.ts","sourceRoot":"","sources":["../../src/db/queries.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"queries.d.ts","sourceRoot":"","sources":["../../src/db/queries.ts"],"names":[],"mappings":"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"}