ai-mind-map 1.14.0 → 1.15.0

package/dist/knowledge-graph/graph.js

@@ -50,8 +50,9 @@ CREATE INDEX IF NOT EXISTS idx_nodes_type ON nodes(type);
 CREATE INDEX IF NOT EXISTS idx_nodes_name ON nodes(name);
 CREATE INDEX IF NOT EXISTS idx_nodes_language ON nodes(language);
 CREATE INDEX IF NOT EXISTS idx_nodes_hash ON nodes(hash);
-CREATE INDEX IF NOT EXISTS idx_edges_sourceId ON edges(sourceId);
-CREATE INDEX IF NOT EXISTS idx_edges_targetId ON edges(targetId);
+-- Composite indexes for common edge queries (type is always in WHERE clause)
+CREATE INDEX IF NOT EXISTS idx_edges_source_type ON edges(sourceId, type);
+CREATE INDEX IF NOT EXISTS idx_edges_target_type ON edges(targetId, type);
 CREATE INDEX IF NOT EXISTS idx_edges_type ON edges(type);
 
 -- FTS5 virtual table for full-text search across names, signatures, and doc comments
@@ -123,7 +124,7 @@ CREATE VIRTUAL TABLE IF NOT EXISTS content_fts USING fts5(
   tokenize='unicode61'
 );
 `;
-const SCHEMA_VERSION = '5';
+const SCHEMA_VERSION = '6';
 // ============================================================
 // KnowledgeGraph Class
 // ============================================================
@@ -135,6 +136,23 @@ const SCHEMA_VERSION = '5';
  */
 export class KnowledgeGraph {
     db;
+    // Cached prepared statements for hot-path queries (parse once, reuse forever)
+    _stmtCache = new Map();
+    /** Get or create a cached prepared statement */
+    stmt(sql) {
+        let s = this._stmtCache.get(sql);
+        if (!s) {
+            s = this.db.prepare(sql);
+            this._stmtCache.set(sql, s);
+        }
+        return s;
+    }
+    // In-memory adjacency cache for ultra-fast graph traversal
+    adjOut = new Map(); // nodeId → type → targetIds
+    adjIn = new Map(); // nodeId → type → sourceIds
+    adjDirty = true; // Rebuilt on first query after index
+    // Stats cache with 5-second TTL
+    _statsCache = null;
     /**
      * Create or open a knowledge graph database.
      *
@@ -232,7 +250,7 @@ export class KnowledgeGraph {
      * Used by changelog engine to diff old vs new nodes during re-indexing.
      */
     getNodesForFile(filePath) {
-        const rows = this.db.prepare('SELECT * FROM nodes WHERE filePath = ?').all(filePath);
+        const rows = this.stmt('SELECT * FROM nodes WHERE filePath = ?').all(filePath);
         return rows.map((r) => this.rowToNode(r));
     }
     // ============================================================
@@ -360,21 +378,21 @@ export class KnowledgeGraph {
      * Get a node by its ID.
      */
     getNode(id) {
-        const row = this.db.prepare('SELECT * FROM nodes WHERE id = ?').get(id);
+        const row = this.stmt('SELECT * FROM nodes WHERE id = ?').get(id);
         return row ? this.rowToNode(row) : null;
     }
     /**
      * Get nodes by name (may return multiple matches across files).
      */
     getNodesByName(name) {
-        const rows = this.db.prepare('SELECT * FROM nodes WHERE name = ?').all(name);
+        const rows = this.stmt('SELECT * FROM nodes WHERE name = ?').all(name);
         return rows.map((r) => this.rowToNode(r));
     }
     /**
      * Get all nodes of a specific type.
      */
     getNodesByType(type) {
-        const rows = this.db.prepare('SELECT * FROM nodes WHERE type = ?').all(type);
+        const rows = this.stmt('SELECT * FROM nodes WHERE type = ?').all(type);
         return rows.map((r) => this.rowToNode(r));
     }
     /**
@@ -460,7 +478,7 @@ export class KnowledgeGraph {
      * Get all edges originating from a node.
      */
     getOutEdges(nodeId) {
-        const rows = this.db.prepare('SELECT * FROM edges WHERE sourceId = ?').all(nodeId);
+        const rows = this.stmt('SELECT * FROM edges WHERE sourceId = ?').all(nodeId);
         return rows.map(r => ({
             sourceId: r.sourceId,
             targetId: r.targetId,
@@ -472,7 +490,7 @@ export class KnowledgeGraph {
      * Get all edges pointing to a node.
      */
     getInEdges(nodeId) {
-        const rows = this.db.prepare('SELECT * FROM edges WHERE targetId = ?').all(nodeId);
+        const rows = this.stmt('SELECT * FROM edges WHERE targetId = ?').all(nodeId);
         return rows.map(r => ({
             sourceId: r.sourceId,
             targetId: r.targetId,
@@ -484,7 +502,7 @@ export class KnowledgeGraph {
      * Get edges of a specific type originating from a node.
      */
     getOutEdgesByType(nodeId, type) {
-        const rows = this.db.prepare('SELECT * FROM edges WHERE sourceId = ? AND type = ?').all(nodeId, type);
+        const rows = this.stmt('SELECT * FROM edges WHERE sourceId = ? AND type = ?').all(nodeId, type);
         return rows.map(r => ({
             sourceId: r.sourceId,
             targetId: r.targetId,
@@ -496,7 +514,7 @@ export class KnowledgeGraph {
      * Get edges of a specific type pointing to a node.
      */
     getInEdgesByType(nodeId, type) {
-        const rows = this.db.prepare('SELECT * FROM edges WHERE targetId = ? AND type = ?').all(nodeId, type);
+        const rows = this.stmt('SELECT * FROM edges WHERE targetId = ? AND type = ?').all(nodeId, type);
         return rows.map(r => ({
             sourceId: r.sourceId,
             targetId: r.targetId,
@@ -511,7 +529,7 @@ export class KnowledgeGraph {
      * Find all nodes that call a given node (callers / "who calls this?").
      */
     findCallers(nodeId) {
-        const rows = this.db.prepare(`
+        const rows = this.stmt(`
       SELECT n.* FROM nodes n
       JOIN edges e ON n.id = e.sourceId
       WHERE e.targetId = ? AND e.type = 'calls'
@@ -522,7 +540,7 @@ export class KnowledgeGraph {
      * Find all nodes that a given node calls (callees / "what does this call?").
      */
     findCallees(nodeId) {
-        const rows = this.db.prepare(`
+        const rows = this.stmt(`
       SELECT n.* FROM nodes n
       JOIN edges e ON n.id = e.targetId
       WHERE e.sourceId = ? AND e.type = 'calls'
@@ -536,44 +554,26 @@ export class KnowledgeGraph {
      * @param maxDepth - Maximum traversal depth (default 10)
      */
     findAncestors(nodeId, maxDepth = 10) {
-        const visited = new Set();
-        const result = [];
-        const queue = [{ id: nodeId, depth: 0 }];
-        while (queue.length > 0) {
-            const current = queue.shift();
-            if (current.depth >= maxDepth || visited.has(current.id))
-                continue;
-            visited.add(current.id);
-            // inherits/implements: sourceId=child, targetId=parent → follow targetId
-            const inheritEdges = this.db.prepare(`
-        SELECT e.targetId FROM edges e
-        WHERE e.sourceId = ? AND e.type IN ('inherits', 'implements')
-      `).all(current.id);
-            for (const { targetId } of inheritEdges) {
-                if (!visited.has(targetId)) {
-                    const node = this.getNode(targetId);
-                    if (node) {
-                        result.push(node);
-                        queue.push({ id: targetId, depth: current.depth + 1 });
-                    }
-                }
-            }
-            // contains: sourceId=parent, targetId=child → find parent via targetId=current
-            const containsEdges = this.db.prepare(`
-        SELECT e.sourceId FROM edges e
-        WHERE e.targetId = ? AND e.type = 'contains'
-      `).all(current.id);
-            for (const { sourceId } of containsEdges) {
-                if (!visited.has(sourceId)) {
-                    const node = this.getNode(sourceId);
-                    if (node) {
-                        result.push(node);
-                        queue.push({ id: sourceId, depth: current.depth + 1 });
-                    }
-                }
-            }
-        }
-        return result;
+        // Single recursive CTE replaces N+1 JavaScript BFS loop
+        const rows = this.db.prepare(`
+      WITH RECURSIVE anc(id, depth) AS (
+        SELECT @nodeId, 0
+        UNION
+        SELECT e.targetId, anc.depth + 1
+        FROM edges e
+        JOIN anc ON e.sourceId = anc.id
+        WHERE anc.depth < @maxDepth AND e.type IN ('inherits', 'implements')
+        UNION
+        SELECT e.sourceId, anc.depth + 1
+        FROM edges e
+        JOIN anc ON e.targetId = anc.id
+        WHERE anc.depth < @maxDepth AND e.type = 'contains'
+      )
+      SELECT DISTINCT n.* FROM nodes n
+      JOIN anc ON n.id = anc.id
+      WHERE n.id != @nodeId
+    `).all({ nodeId, maxDepth });
+        return rows.map((r) => this.rowToNode(r));
     }
     /**
      * Find descendants (child classes, implementors, contained members) — traverse downward.
@@ -582,44 +582,26 @@ export class KnowledgeGraph {
      * @param maxDepth - Maximum traversal depth (default 10)
      */
     findDescendants(nodeId, maxDepth = 10) {
-        const visited = new Set();
-        const result = [];
-        const queue = [{ id: nodeId, depth: 0 }];
-        while (queue.length > 0) {
-            const current = queue.shift();
-            if (current.depth >= maxDepth || visited.has(current.id))
-                continue;
-            visited.add(current.id);
-            // contains: sourceId=parent, targetId=child → follow targetId
-            const containsEdges = this.db.prepare(`
-        SELECT e.targetId FROM edges e
-        WHERE e.sourceId = ? AND e.type = 'contains'
-      `).all(current.id);
-            for (const { targetId } of containsEdges) {
-                if (!visited.has(targetId)) {
-                    const node = this.getNode(targetId);
-                    if (node) {
-                        result.push(node);
-                        queue.push({ id: targetId, depth: current.depth + 1 });
-                    }
-                }
-            }
-            // inherits/implements: sourceId=child, targetId=parent → find children via targetId=current
-            const inheritEdges = this.db.prepare(`
-        SELECT e.sourceId FROM edges e
-        WHERE e.targetId = ? AND e.type IN ('inherits', 'implements')
-      `).all(current.id);
-            for (const { sourceId } of inheritEdges) {
-                if (!visited.has(sourceId)) {
-                    const node = this.getNode(sourceId);
-                    if (node) {
-                        result.push(node);
-                        queue.push({ id: sourceId, depth: current.depth + 1 });
-                    }
-                }
-            }
-        }
-        return result;
+        // Single recursive CTE replaces N+1 JavaScript BFS loop
+        const rows = this.db.prepare(`
+      WITH RECURSIVE desc_tree(id, depth) AS (
+        SELECT @nodeId, 0
+        UNION
+        SELECT e.targetId, desc_tree.depth + 1
+        FROM edges e
+        JOIN desc_tree ON e.sourceId = desc_tree.id
+        WHERE desc_tree.depth < @maxDepth AND e.type = 'contains'
+        UNION
+        SELECT e.sourceId, desc_tree.depth + 1
+        FROM edges e
+        JOIN desc_tree ON e.targetId = desc_tree.id
+        WHERE desc_tree.depth < @maxDepth AND e.type IN ('inherits', 'implements')
+      )
+      SELECT DISTINCT n.* FROM nodes n
+      JOIN desc_tree ON n.id = desc_tree.id
+      WHERE n.id != @nodeId
+    `).all({ nodeId, maxDepth });
+        return rows.map((r) => this.rowToNode(r));
     }
     /**
      * Blast radius analysis: find all nodes transitively affected if a node changes.
@@ -631,32 +613,23 @@ export class KnowledgeGraph {
      * @returns All nodes that depend on the changed node
      */
     blastRadius(nodeId, maxDepth = 5) {
-        const visited = new Set();
-        const result = [];
-        const dependencyTypes = ['calls', 'imports', 'inherits', 'implements', 'uses', 'depends_on'];
-        const typeFilter = dependencyTypes.map(t => `'${t}'`).join(',');
-        const queue = [{ id: nodeId, depth: 0 }];
-        while (queue.length > 0) {
-            const current = queue.shift();
-            if (current.depth >= maxDepth || visited.has(current.id))
-                continue;
-            visited.add(current.id);
-            // Find nodes that depend ON this node (reverse dependency)
-            const dependents = this.db.prepare(`
-        SELECT e.sourceId FROM edges e
-        WHERE e.targetId = ? AND e.type IN (${typeFilter})
-      `).all(current.id);
-            for (const { sourceId } of dependents) {
-                if (!visited.has(sourceId)) {
-                    const node = this.getNode(sourceId);
-                    if (node) {
-                        result.push(node);
-                        queue.push({ id: sourceId, depth: current.depth + 1 });
-                    }
-                }
-            }
-        }
-        return result;
+        // Single recursive CTE replaces N+1 JavaScript BFS loop
+        // Traces reverse dependencies: who depends on this node, transitively
+        const rows = this.db.prepare(`
+      WITH RECURSIVE blast(id, depth) AS (
+        SELECT @nodeId, 0
+        UNION
+        SELECT e.sourceId, blast.depth + 1
+        FROM edges e
+        JOIN blast ON e.targetId = blast.id
+        WHERE blast.depth < @maxDepth
+          AND e.type IN ('calls','imports','inherits','implements','uses','depends_on')
+      )
+      SELECT DISTINCT n.* FROM nodes n
+      JOIN blast ON n.id = blast.id
+      WHERE n.id != @nodeId
+    `).all({ nodeId, maxDepth });
+        return rows.map((r) => this.rowToNode(r));
     }
     // ============================================================
     // Full-Text Search
@@ -828,14 +801,14 @@ export class KnowledgeGraph {
      * Get the content hash for a file node (used for change detection).
      */
     getFileHash(filePath) {
-        const row = this.db.prepare("SELECT hash FROM nodes WHERE filePath = ? AND type = 'file' LIMIT 1").get(filePath);
+        const row = this.stmt("SELECT hash FROM nodes WHERE filePath = ? AND type = 'file' LIMIT 1").get(filePath);
         return row?.hash ?? null;
     }
     /**
      * Get all indexed file paths.
      */
     getIndexedFiles() {
-        const rows = this.db.prepare("SELECT DISTINCT filePath FROM nodes WHERE type = 'file' ORDER BY filePath").all();
+        const rows = this.stmt("SELECT DISTINCT filePath FROM nodes WHERE type = 'file' ORDER BY filePath").all();
         return rows.map(r => r.filePath);
     }
     /**
@@ -895,25 +868,32 @@ export class KnowledgeGraph {
      * Get graph statistics.
      */
     getStats() {
-        const totalNodes = this.db.prepare('SELECT COUNT(*) as count FROM nodes').get().count;
-        const totalEdges = this.db.prepare('SELECT COUNT(*) as count FROM edges').get().count;
-        const totalFiles = this.db.prepare("SELECT COUNT(*) as count FROM nodes WHERE type = 'file'").get().count;
-        const nodesByTypeRows = this.db.prepare('SELECT type, COUNT(*) as count FROM nodes GROUP BY type').all();
+        // Return cached stats if <5 seconds old (avoids 6 COUNT queries per tool response)
+        const now = Date.now();
+        if (this._statsCache && now - this._statsCache.time < 5000) {
+            return this._statsCache.data;
+        }
+        const totalNodes = this.stmt('SELECT COUNT(*) as count FROM nodes').get().count;
+        const totalEdges = this.stmt('SELECT COUNT(*) as count FROM edges').get().count;
+        const totalFiles = this.stmt("SELECT COUNT(*) as count FROM nodes WHERE type = 'file'").get().count;
+        const nodesByTypeRows = this.stmt('SELECT type, COUNT(*) as count FROM nodes GROUP BY type').all();
         const nodesByType = {};
         for (const { type, count } of nodesByTypeRows) {
             nodesByType[type] = count;
         }
-        const edgesByTypeRows = this.db.prepare('SELECT type, COUNT(*) as count FROM edges GROUP BY type').all();
+        const edgesByTypeRows = this.stmt('SELECT type, COUNT(*) as count FROM edges GROUP BY type').all();
         const edgesByType = {};
         for (const { type, count } of edgesByTypeRows) {
             edgesByType[type] = count;
         }
-        const langRows = this.db.prepare("SELECT language, COUNT(*) as count FROM nodes WHERE type = 'file' GROUP BY language").all();
+        const langRows = this.stmt("SELECT language, COUNT(*) as count FROM nodes WHERE type = 'file' GROUP BY language").all();
         const languageBreakdown = {};
         for (const { language, count } of langRows) {
             languageBreakdown[language] = count;
         }
-        return { totalNodes, totalEdges, totalFiles, nodesByType, edgesByType, languageBreakdown };
+        const result = { totalNodes, totalEdges, totalFiles, nodesByType, edgesByType, languageBreakdown };
+        this._statsCache = { data: result, time: now };
+        return result;
     }
     // ============================================================
     // Bulk Operations
@@ -930,6 +910,8 @@ export class KnowledgeGraph {
             this.upsertNodes(nodes);
             this.upsertEdges(edges);
         })();
+        this.adjDirty = true;
+        this._statsCache = null;
     }
     /**
      * Replace data for MANY files in a single transaction.
@@ -1013,6 +995,8 @@ export class KnowledgeGraph {
                 }
             }
         })();
+        this.adjDirty = true;
+        this._statsCache = null;
     }
     /**
      * Optimized insert for full reindex (no existing data, skip conflict checks).
@@ -1075,13 +1059,14 @@ export class KnowledgeGraph {
                 }
             }
         })();
+        this.adjDirty = true;
+        this._statsCache = null;
     }
     /**
      * Get all node IDs in the graph (used for PageRank).
      */
     getAllNodeIds() {
-        const rows = this.db.prepare('SELECT id FROM nodes').all();
-        return rows.map(r => r.id);
+        return this.stmt('SELECT id FROM nodes').pluck().all();
     }
     /**
      * Get all edges in the graph (used for PageRank adjacency matrix).
@@ -1122,6 +1107,8 @@ export class KnowledgeGraph {
             this.db.prepare('DELETE FROM edges').run();
             this.db.prepare('DELETE FROM nodes').run();
         })();
+        this.adjDirty = true;
+        this._statsCache = null;
     }
     /**
      * Clear only nodes and edges belonging to files under a specific project root.
@@ -1150,6 +1137,8 @@ export class KnowledgeGraph {
             this.db.prepare('DELETE FROM file_index WHERE file_path LIKE ? OR file_path LIKE ?').run(`${prefix}%`, `${altPrefix}%`);
             return del.changes;
         })();
+        this.adjDirty = true;
+        this._statsCache = null;
         return result;
     }
     // ============================================================
@@ -1248,7 +1237,7 @@ export class KnowledgeGraph {
      * Get stored file index entry for staleness comparison.
      */
     getFileIndexEntry(filePath) {
-        return this.db.prepare('SELECT mtime_ms, size_bytes, content_hash, indexed_at FROM file_index WHERE file_path = ?').get(filePath) ?? null;
+        return this.stmt('SELECT mtime_ms, size_bytes, content_hash, indexed_at FROM file_index WHERE file_path = ?').get(filePath) ?? null;
     }
     /**
      * Upsert a file index entry after indexing.
@@ -1275,7 +1264,7 @@ export class KnowledgeGraph {
      * Count tracked files in file_index.
      */
     getFileIndexCount() {
-        return this.db.prepare('SELECT COUNT(*) as c FROM file_index').get()?.c ?? 0;
+        return this.stmt('SELECT COUNT(*) as c FROM file_index').get()?.c ?? 0;
     }
     /**
      * Remove orphaned edges (edges pointing to non-existent nodes).
@@ -1328,9 +1317,12 @@ export class KnowledgeGraph {
         this.db.exec('DROP INDEX IF EXISTS idx_nodes_name');
         this.db.exec('DROP INDEX IF EXISTS idx_nodes_language');
         this.db.exec('DROP INDEX IF EXISTS idx_nodes_hash');
+        this.db.exec('DROP INDEX IF EXISTS idx_edges_source_type');
+        this.db.exec('DROP INDEX IF EXISTS idx_edges_target_type');
+        this.db.exec('DROP INDEX IF EXISTS idx_edges_type');
+        // Also drop old single-column indexes if they exist from previous versions
         this.db.exec('DROP INDEX IF EXISTS idx_edges_sourceId');
         this.db.exec('DROP INDEX IF EXISTS idx_edges_targetId');
-        this.db.exec('DROP INDEX IF EXISTS idx_edges_type');
     }
     /** Recreate all performance indexes */
     recreateIndexes() {
@@ -1339,8 +1331,8 @@ export class KnowledgeGraph {
         this.db.exec('CREATE INDEX IF NOT EXISTS idx_nodes_name ON nodes(name)');
         this.db.exec('CREATE INDEX IF NOT EXISTS idx_nodes_language ON nodes(language)');
         this.db.exec('CREATE INDEX IF NOT EXISTS idx_nodes_hash ON nodes(hash)');
-        this.db.exec('CREATE INDEX IF NOT EXISTS idx_edges_sourceId ON edges(sourceId)');
-        this.db.exec('CREATE INDEX IF NOT EXISTS idx_edges_targetId ON edges(targetId)');
+        this.db.exec('CREATE INDEX IF NOT EXISTS idx_edges_source_type ON edges(sourceId, type)');
+        this.db.exec('CREATE INDEX IF NOT EXISTS idx_edges_target_type ON edges(targetId, type)');
         this.db.exec('CREATE INDEX IF NOT EXISTS idx_edges_type ON edges(type)');
     }
     /** Enter bulk insert mode - relaxes safety for maximum speed */
@@ -1355,6 +1347,7 @@ export class KnowledgeGraph {
     }
     /** Exit bulk insert mode - restores safety and rebuilds indexes/FTS */
     exitBulkMode() {
+        this.invalidateAdjCache();
         this.recreateIndexes();
         this.recreateFtsTriggers();
         this.rebuildFts();
@@ -1365,6 +1358,92 @@ export class KnowledgeGraph {
         this.db.pragma('wal_checkpoint(TRUNCATE)');
         this.db.pragma('wal_autocheckpoint = 1000');
     }
+    /**
+     * Build in-memory adjacency cache for ultra-fast graph traversal.
+     * Called automatically on first traversal query after index.
+     * ~2MB RAM for 13K edges — negligible.
+     */
+    buildAdjacencyCache() {
+        this.adjOut.clear();
+        this.adjIn.clear();
+        const rows = this.stmt('SELECT sourceId, targetId, type FROM edges').all();
+        for (const r of rows) {
+            // Forward: sourceId → type → [targetIds]
+            if (!this.adjOut.has(r.sourceId))
+                this.adjOut.set(r.sourceId, new Map());
+            const fwd = this.adjOut.get(r.sourceId);
+            if (!fwd.has(r.type))
+                fwd.set(r.type, []);
+            fwd.get(r.type).push(r.targetId);
+            // Reverse: targetId → type → [sourceIds]
+            if (!this.adjIn.has(r.targetId))
+                this.adjIn.set(r.targetId, new Map());
+            const rev = this.adjIn.get(r.targetId);
+            if (!rev.has(r.type))
+                rev.set(r.type, []);
+            rev.get(r.type).push(r.sourceId);
+        }
+        this.adjDirty = false;
+    }
+    /** Invalidate adjacency cache (call after any edge mutation) */
+    invalidateAdjCache() {
+        this.adjDirty = true;
+        this._statsCache = null;
+        this._stmtCache.clear(); // Also clear stmt cache on schema changes
+    }
+    /** Get callers from adjacency cache (in-memory, sub-microsecond) */
+    getCallersFromCache(nodeId) {
+        if (this.adjDirty)
+            this.buildAdjacencyCache();
+        return this.adjIn.get(nodeId)?.get('calls') ?? [];
+    }
+    /** Get callees from adjacency cache (in-memory, sub-microsecond) */
+    getCalleesFromCache(nodeId) {
+        if (this.adjDirty)
+            this.buildAdjacencyCache();
+        return this.adjOut.get(nodeId)?.get('calls') ?? [];
+    }
+    /** Get reverse dependencies from adjacency cache for blast radius */
+    getReverseDepsFromCache(nodeId, types) {
+        if (this.adjDirty)
+            this.buildAdjacencyCache();
+        const byType = this.adjIn.get(nodeId);
+        if (!byType)
+            return [];
+        const result = [];
+        for (const t of types) {
+            const ids = byType.get(t);
+            if (ids)
+                result.push(...ids);
+        }
+        return result;
+    }
+    /**
+     * Shortest path between two nodes via dependency edges.
+     * Returns the path as an array of node IDs, or empty if no path exists.
+     */
+    shortestPath(startId, endId, maxDepth = 10) {
+        try {
+            const rows = this.db.prepare(`
+        WITH RECURSIVE path(id, depth, route) AS (
+          SELECT ?1, 0, ?1
+          UNION ALL
+          SELECT e.targetId, path.depth + 1, path.route || '>' || e.targetId
+          FROM edges e
+          JOIN path ON e.sourceId = path.id
+          WHERE path.depth < ?3
+            AND e.type IN ('calls','imports','inherits','implements','uses','depends_on')
+            AND instr(path.route, e.targetId) = 0
+        )
+        SELECT route FROM path WHERE id = ?2
+        ORDER BY depth LIMIT 1
+      `).get(startId, endId, maxDepth);
+            return rows ? rows.route.split('>') : [];
+        }
+        catch {
+            return [];
+        }
+    }
     /**
      * Close the database connection.
      */