milens 0.6.3 → 0.6.4

package/dist/store/db.js

@@ -7,6 +7,10 @@ const __dirname = dirname(fileURLToPath(import.meta.url));
 export class Database {
     db;
     stmts;
+    /** Access the raw better-sqlite3 connection (for AnnotationStore etc.) */
+    get connection() {
+        return this.db;
+    }
     constructor(dbPath) {
         this.db = new BetterSqlite3(dbPath);
         this.db.pragma('journal_mode = WAL');
@@ -21,48 +25,62 @@ export class Database {
     prepareStatements() {
         return {
             checkHash: this.db.prepare('SELECT hash FROM file_hashes WHERE path = ?'),
-            upsertHash: this.db.prepare(`INSERT INTO file_hashes (path, hash) VALUES (?, ?)
+            upsertHash: this.db.prepare(`INSERT INTO file_hashes (path, hash) VALUES (?, ?)
          ON CONFLICT(path) DO UPDATE SET hash = excluded.hash, analyzed_at = datetime('now')`),
-            insertSym: this.db.prepare(`INSERT OR REPLACE INTO symbols (id, name, kind, file_path, start_line, end_line, exported, parent_id, signature, role, heat)
+            insertSym: this.db.prepare(`INSERT OR REPLACE INTO symbols (id, name, kind, file_path, start_line, end_line, exported, parent_id, signature, role, heat)
          VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`),
             updateMeta: this.db.prepare(`UPDATE symbols SET role = ?, heat = ? WHERE id = ?`),
             upsertZone: this.db.prepare(`UPDATE file_hashes SET zone = ? WHERE path = ?`),
-            insertLink: this.db.prepare(`INSERT OR REPLACE INTO links (id, from_id, to_id, type, confidence, line_number)
+            insertLink: this.db.prepare(`INSERT OR REPLACE INTO links (id, from_id, to_id, type, confidence, line_number)
          VALUES (?, ?, ?, ?, ?, ?)`),
-            searchFts: this.db.prepare(`SELECT s.* FROM symbol_fts f
-         JOIN symbols s ON s.rowid = f.rowid
-         WHERE symbol_fts MATCH ?
+            searchFts: this.db.prepare(`SELECT s.* FROM symbol_fts f
+         JOIN symbols s ON s.rowid = f.rowid
+         WHERE symbol_fts MATCH ?
          ORDER BY rank LIMIT ?`),
             byName: this.db.prepare('SELECT * FROM symbols WHERE name = ?'),
             byId: this.db.prepare('SELECT * FROM symbols WHERE id = ?'),
             byFile: this.db.prepare('SELECT * FROM symbols WHERE file_path = ?'),
             linksIn: this.db.prepare('SELECT * FROM links WHERE to_id = ?'),
             linksOut: this.db.prepare('SELECT * FROM links WHERE from_id = ?'),
-            upstream: this.db.prepare(`
-        WITH RECURSIVE upstream(id, depth, via) AS (
-          SELECT from_id, 1, type FROM links WHERE to_id = ? AND type IN ('calls', 'imports', 'extends', 'implements')
-          UNION
-          SELECT l.from_id, u.depth + 1, l.type
-          FROM links l JOIN upstream u ON l.to_id = u.id
-          WHERE u.depth < ? AND l.type IN ('calls', 'imports', 'extends', 'implements')
-        )
-        SELECT DISTINCT s.*, u.depth, u.via FROM upstream u JOIN symbols s ON s.id = u.id ORDER BY u.depth
+            upstream: this.db.prepare(`
+        WITH RECURSIVE upstream(id, depth, via) AS (
+          SELECT from_id, 1, type FROM links WHERE to_id = ? AND type IN ('calls', 'imports', 'extends', 'implements')
+          UNION
+          SELECT l.from_id, u.depth + 1, l.type
+          FROM links l JOIN upstream u ON l.to_id = u.id
+          WHERE u.depth < ? AND l.type IN ('calls', 'imports', 'extends', 'implements')
+        )
+        SELECT DISTINCT s.*, u.depth, u.via FROM upstream u JOIN symbols s ON s.id = u.id ORDER BY u.depth
       `),
-            downstream: this.db.prepare(`
-        WITH RECURSIVE downstream(id, depth, via) AS (
-          SELECT to_id, 1, type FROM links WHERE from_id = ? AND type IN ('calls', 'imports', 'extends', 'implements')
-          UNION
-          SELECT l.to_id, d.depth + 1, l.type
-          FROM links l JOIN downstream d ON l.from_id = d.id
-          WHERE d.depth < ? AND l.type IN ('calls', 'imports', 'extends', 'implements')
-        )
-        SELECT DISTINCT s.*, d.depth, d.via FROM downstream d JOIN symbols s ON s.id = d.id ORDER BY d.depth
+            downstream: this.db.prepare(`
+        WITH RECURSIVE downstream(id, depth, via) AS (
+          SELECT to_id, 1, type FROM links WHERE from_id = ? AND type IN ('calls', 'imports', 'extends', 'implements')
+          UNION
+          SELECT l.to_id, d.depth + 1, l.type
+          FROM links l JOIN downstream d ON l.from_id = d.id
+          WHERE d.depth < ? AND l.type IN ('calls', 'imports', 'extends', 'implements')
+        )
+        SELECT DISTINCT s.*, d.depth, d.via FROM downstream d JOIN symbols s ON s.id = d.id ORDER BY d.depth
       `),
             countSymbols: this.db.prepare('SELECT COUNT(*) as c FROM symbols'),
             countLinks: this.db.prepare('SELECT COUNT(*) as c FROM links'),
             countFiles: this.db.prepare('SELECT COUNT(*) as c FROM file_hashes'),
-            deleteFileLinks: this.db.prepare('DELETE FROM links WHERE from_id IN (SELECT id FROM symbols WHERE file_path = ?) OR to_id IN (SELECT id FROM symbols WHERE file_path = ?)'),
+            deleteFileLinks: this.db.prepare('DELETE FROM links WHERE from_id IN (SELECT id FROM symbols WHERE file_path = ?)'),
             deleteFileSymbols: this.db.prepare('DELETE FROM symbols WHERE file_path = ?'),
+            topHubs: this.db.prepare('SELECT * FROM symbols WHERE exported = 1 ORDER BY heat DESC LIMIT ?'),
+            testCoverageGaps: this.db.prepare(`
+        SELECT s.* FROM symbols s
+        WHERE s.exported = 1 AND s.heat > 0
+        AND s.id NOT IN (
+          SELECT DISTINCT l.to_id FROM links l
+          JOIN symbols src ON src.id = l.from_id
+          WHERE (src.file_path LIKE '%/test/%' OR src.file_path LIKE '%\\test\\%'
+                 OR src.file_path LIKE '%.test.%' OR src.file_path LIKE '%.spec.%')
+        )
+        ORDER BY s.heat DESC
+        LIMIT ?
+      `),
+            annotationCount: this.db.prepare('SELECT COUNT(*) as c FROM annotations'),
         };
     }
     applySchema() {
@@ -153,35 +171,6 @@ export class Database {
         const rows = this.stmts.linksOut.all(symbolId);
         return rows.map(rowToLink);
     }
-    /** Batch link counts for multiple symbol IDs (avoids N+1 queries) */
-    getLinkCountsForSymbols(symbolIds) {
-        if (symbolIds.length === 0)
-            return new Map();
-        const placeholders = symbolIds.map(() => '?').join(',');
-        const inRows = this.db.prepare(`SELECT to_id as id, COUNT(*) as c FROM links WHERE to_id IN (${placeholders}) AND type != 'contains' GROUP BY to_id`).all(...symbolIds);
-        const outRows = this.db.prepare(`SELECT from_id as id, COUNT(*) as c FROM links WHERE from_id IN (${placeholders}) AND type != 'contains' GROUP BY from_id`).all(...symbolIds);
-        const result = new Map();
-        for (const id of symbolIds)
-            result.set(id, { incoming: 0, outgoing: 0 });
-        for (const r of inRows)
-            result.get(r.id).incoming = r.c;
-        for (const r of outRows)
-            result.get(r.id).outgoing = r.c;
-        return result;
-    }
-    /** Batch: get symbol IDs that have at least one incoming link from a test file. */
-    getTestedSymbolIds(symbolIds, isTestFile) {
-        if (symbolIds.length === 0)
-            return new Set();
-        const placeholders = symbolIds.map(() => '?').join(',');
-        const rows = this.db.prepare(`SELECT DISTINCT l.to_id, s.file_path FROM links l JOIN symbols s ON s.id = l.from_id WHERE l.to_id IN (${placeholders})`).all(...symbolIds);
-        const tested = new Set();
-        for (const r of rows) {
-            if (isTestFile(r.file_path))
-                tested.add(r.to_id);
-        }
-        return tested;
-    }
     findUpstream(symbolId, maxDepth = 3) {
         const rows = this.stmts.upstream.all(symbolId, maxDepth);
         return rows.map(r => ({ symbol: rowToSymbol(r), depth: r.depth, via: r.via }));
@@ -200,47 +189,25 @@ export class Database {
         const rows = this.db.prepare('SELECT * FROM symbols').all();
         return rows.map(rowToSymbol);
     }
-    getTopSymbolsByHeat(limit = 10) {
-        const rows = this.db.prepare(`SELECT * FROM symbols WHERE heat > 0 AND kind != 'section' ORDER BY heat DESC LIMIT ?`).all(limit);
-        return rows.map(rowToSymbol);
-    }
     getAllLinks() {
         const rows = this.db.prepare('SELECT * FROM links').all();
         return rows.map(rowToLink);
     }
     findDeadCode(kind, limit = 50) {
-        // Exclude: section symbols (markdown headings), test fixtures (not real production code),
-        // framework entry-point files (consumed by runtime, not imported by project code),
-        // and config files (consumed by CLI tooling)
-        const excludeClause = `AND s.kind != 'section'
-      AND s.file_path NOT LIKE 'test/fixtures/%'
-      AND s.file_path NOT LIKE '%/page.ts' AND s.file_path NOT LIKE '%/page.tsx'
-      AND s.file_path NOT LIKE '%/page.js' AND s.file_path NOT LIKE '%/page.jsx'
-      AND s.file_path NOT LIKE '%/layout.ts' AND s.file_path NOT LIKE '%/layout.tsx'
-      AND s.file_path NOT LIKE '%/layout.js' AND s.file_path NOT LIKE '%/layout.jsx'
-      AND s.file_path NOT LIKE '%/loading.ts' AND s.file_path NOT LIKE '%/loading.tsx'
-      AND s.file_path NOT LIKE '%/error.ts' AND s.file_path NOT LIKE '%/error.tsx'
-      AND s.file_path NOT LIKE '%/not-found.ts' AND s.file_path NOT LIKE '%/not-found.tsx'
-      AND s.file_path NOT LIKE '%/template.ts' AND s.file_path NOT LIKE '%/template.tsx'
-      AND s.file_path NOT LIKE '%/route.ts' AND s.file_path NOT LIKE '%/route.tsx'
-      AND s.file_path NOT LIKE '%/route.js' AND s.file_path NOT LIKE '%/route.jsx'
-      AND s.file_path NOT LIKE '%/default.ts' AND s.file_path NOT LIKE '%/default.tsx'
-      AND s.file_path NOT LIKE '%/global-error.ts' AND s.file_path NOT LIKE '%/global-error.tsx'
-      AND s.file_path NOT LIKE '%/middleware.ts' AND s.file_path NOT LIKE '%/middleware.js'
-      AND s.file_path NOT LIKE '%.config.ts' AND s.file_path NOT LIKE '%.config.js'
-      AND s.file_path NOT LIKE '%.config.mjs' AND s.file_path NOT LIKE '%.config.cjs'
-      AND s.file_path NOT LIKE '%/+page.svelte' AND s.file_path NOT LIKE '%/+page.ts'
-      AND s.file_path NOT LIKE '%/+page.server.ts' AND s.file_path NOT LIKE '%/+layout.svelte'
-      AND s.file_path NOT LIKE '%/+layout.ts' AND s.file_path NOT LIKE '%/+layout.server.ts'
-      AND s.file_path NOT LIKE '%/+server.ts'`;
+        const frameworkExclude = `AND s.file_path NOT LIKE 'app/%/page.%' AND s.file_path NOT LIKE 'app/%/layout.%'
+      AND s.file_path NOT LIKE 'app/page.%' AND s.file_path NOT LIKE 'app/layout.%'
+      AND s.file_path NOT LIKE 'app/api/%/route.%' AND s.file_path NOT LIKE 'jest.config.%'
+      AND s.file_path NOT LIKE 'src/routes/+page.%' AND s.file_path NOT LIKE 'src/routes/+layout.%'`;
         const sql = kind
-            ? `SELECT s.* FROM symbols s
-         LEFT JOIN links l ON l.to_id = s.id AND l.type != 'contains'
-         WHERE s.exported = 1 AND s.kind = ? ${excludeClause} AND l.id IS NULL
+            ? `SELECT s.* FROM symbols s
+         LEFT JOIN links l ON l.to_id = s.id AND l.type != 'contains'
+         WHERE s.exported = 1 AND s.kind = ? AND l.id IS NULL
+         ${frameworkExclude}
          LIMIT ?`
-            : `SELECT s.* FROM symbols s
-         LEFT JOIN links l ON l.to_id = s.id AND l.type != 'contains'
-         WHERE s.exported = 1 ${excludeClause} AND l.id IS NULL
+            : `SELECT s.* FROM symbols s
+         LEFT JOIN links l ON l.to_id = s.id AND l.type != 'contains'
+         WHERE s.exported = 1 AND l.id IS NULL
+         ${frameworkExclude}
          LIMIT ?`;
         const rows = kind
             ? this.db.prepare(sql).all(kind, limit)
@@ -248,25 +215,25 @@ export class Database {
         return rows.map(rowToSymbol);
     }
     getTypeHierarchy(symbolId) {
-        const ancestors = this.db.prepare(`
-      WITH RECURSIVE up(id, depth) AS (
-        SELECT to_id, 1 FROM links WHERE from_id = ? AND type IN ('extends', 'implements')
-        UNION
-        SELECT l.to_id, u.depth + 1
-        FROM links l JOIN up u ON l.from_id = u.id
-        WHERE l.type IN ('extends', 'implements') AND u.depth < 10
-      )
-      SELECT DISTINCT s.*, u.depth FROM up u JOIN symbols s ON s.id = u.id ORDER BY u.depth
+        const ancestors = this.db.prepare(`
+      WITH RECURSIVE up(id, depth) AS (
+        SELECT to_id, 1 FROM links WHERE from_id = ? AND type IN ('extends', 'implements')
+        UNION
+        SELECT l.to_id, u.depth + 1
+        FROM links l JOIN up u ON l.from_id = u.id
+        WHERE l.type IN ('extends', 'implements') AND u.depth < 10
+      )
+      SELECT DISTINCT s.*, u.depth FROM up u JOIN symbols s ON s.id = u.id ORDER BY u.depth
     `).all(symbolId);
-        const descendants = this.db.prepare(`
-      WITH RECURSIVE down(id, depth) AS (
-        SELECT from_id, 1 FROM links WHERE to_id = ? AND type IN ('extends', 'implements')
-        UNION
-        SELECT l.from_id, d.depth + 1
-        FROM links l JOIN down d ON l.to_id = d.id
-        WHERE l.type IN ('extends', 'implements') AND d.depth < 10
-      )
-      SELECT DISTINCT s.*, d.depth FROM down d JOIN symbols s ON s.id = d.id ORDER BY d.depth
+        const descendants = this.db.prepare(`
+      WITH RECURSIVE down(id, depth) AS (
+        SELECT from_id, 1 FROM links WHERE to_id = ? AND type IN ('extends', 'implements')
+        UNION
+        SELECT l.from_id, d.depth + 1
+        FROM links l JOIN down d ON l.to_id = d.id
+        WHERE l.type IN ('extends', 'implements') AND d.depth < 10
+      )
+      SELECT DISTINCT s.*, d.depth FROM down d JOIN symbols s ON s.id = d.id ORDER BY d.depth
     `).all(symbolId);
         return {
             ancestors: ancestors.map(r => ({ symbol: rowToSymbol(r), depth: r.depth })),
@@ -280,40 +247,27 @@ export class Database {
             return null;
         const fromId = fromSyms[0].id;
         const toIds = new Set(toSyms.map(s => s.id));
-        // BFS with parent tracking to reconstruct shortest path
-        const rows = this.db.prepare(`
-      WITH RECURSIVE path(id, depth, via, parent_id) AS (
-        SELECT to_id, 1, type, from_id FROM links WHERE from_id = ? AND type != 'contains'
-        UNION
-        SELECT l.to_id, p.depth + 1, l.type, l.from_id
-        FROM links l JOIN path p ON l.from_id = p.id
-        WHERE l.type != 'contains' AND p.depth < ?
-      )
-      SELECT s.*, p.depth, p.via, p.parent_id FROM path p JOIN symbols s ON s.id = p.id ORDER BY p.depth
+        // BFS outgoing from source
+        const rows = this.db.prepare(`
+      WITH RECURSIVE path(id, depth, via) AS (
+        SELECT to_id, 1, type FROM links WHERE from_id = ? AND type != 'contains'
+        UNION
+        SELECT l.to_id, p.depth + 1, l.type
+        FROM links l JOIN path p ON l.from_id = p.id
+        WHERE l.type != 'contains' AND p.depth < ?
+      )
+      SELECT DISTINCT s.*, p.depth, p.via FROM path p JOIN symbols s ON s.id = p.id ORDER BY p.depth
     `).all(fromId, maxDepth);
-        // Find first row matching target
-        const targetRow = rows.find(r => toIds.has(r.id));
-        if (!targetRow)
-            return null;
-        // Build lookup: id → { row, parent_id }
-        const byId = new Map();
+        const result = [];
         for (const r of rows) {
-            if (!byId.has(r.id)) {
-                byId.set(r.id, { row: r, parentId: r.parent_id });
-            }
+            result.push({ symbol: rowToSymbol(r), depth: r.depth, via: r.via });
+            if (toIds.has(r.id))
+                break;
         }
-        // Walk backwards from target to source to reconstruct the actual path
-        const chain = [];
-        const visited = new Set();
-        let cur = targetRow;
-        while (cur && cur.id !== fromId && !visited.has(cur.id)) {
-            visited.add(cur.id);
-            chain.push({ symbol: rowToSymbol(cur), depth: cur.depth, via: cur.via });
-            const parent = byId.get(cur.parent_id);
-            cur = parent ? parent.row : null;
-        }
-        chain.reverse();
-        return chain;
+        const found = result.find(r => toIds.has(r.symbol.id));
+        if (!found)
+            return null;
+        return result.filter(r => r.depth <= found.depth);
     }
     getChangedFiles() {
         const rows = this.db.prepare('SELECT DISTINCT file_path FROM symbols').all();
@@ -321,7 +275,7 @@ export class Database {
     }
     // ── Maintenance ──
     deleteFileData(filePath) {
-        this.stmts.deleteFileLinks.run(filePath, filePath);
+        this.stmts.deleteFileLinks.run(filePath);
         this.stmts.deleteFileSymbols.run(filePath);
     }
     rebuildSearch() {
@@ -355,14 +309,14 @@ export class Database {
         };
     }
     getConfidenceDistribution() {
-        const rows = this.db.prepare(`
-      SELECT
-        SUM(CASE WHEN confidence >= 0.9 THEN 1 ELSE 0 END) as high,
-        SUM(CASE WHEN confidence >= 0.7 AND confidence < 0.9 THEN 1 ELSE 0 END) as medium,
-        SUM(CASE WHEN confidence < 0.7 THEN 1 ELSE 0 END) as low,
-        COUNT(*) as total
-      FROM links
-      WHERE type != 'contains'
+        const rows = this.db.prepare(`
+      SELECT
+        SUM(CASE WHEN confidence >= 0.9 THEN 1 ELSE 0 END) as high,
+        SUM(CASE WHEN confidence >= 0.7 AND confidence < 0.9 THEN 1 ELSE 0 END) as medium,
+        SUM(CASE WHEN confidence < 0.7 THEN 1 ELSE 0 END) as low,
+        COUNT(*) as total
+      FROM links
+      WHERE type != 'contains'
     `).get();
         return {
             high: rows?.high ?? 0,
@@ -376,14 +330,6 @@ export class Database {
         // Walk upstream following only 'calls' links to find paths from entrypoints
         const paths = [];
         const visited = new Set();
-        const symCache = new Map();
-        const cachedFindSymbol = (id) => {
-            if (symCache.has(id))
-                return symCache.get(id);
-            const sym = this.findSymbolById(id);
-            symCache.set(id, sym);
-            return sym;
-        };
         const dfs = (currentId, currentPath, depth) => {
             if (depth > maxDepth)
                 return;
@@ -391,7 +337,7 @@ export class Database {
                 return;
             visited.add(currentId);
             const incoming = this.getIncomingLinks(currentId).filter(l => l.type === 'calls' || l.type === 'imports');
-            const sym = cachedFindSymbol(currentId);
+            const sym = this.findSymbolById(currentId);
             if (incoming.length === 0 && sym?.exported) {
                 // Reached an entrypoint — save this path
                 paths.push({ path: [...currentPath] });
@@ -399,10 +345,17 @@ export class Database {
                 return;
             }
             for (const link of incoming) {
-                const fromSym = cachedFindSymbol(link.fromId);
+                const fromSym = this.findSymbolById(link.fromId);
                 if (!fromSym)
                     continue;
-                dfs(link.fromId, [{ symbol: fromSym, via: link.type }, ...currentPath], depth + 1);
+                // Skip module-level _top imports — go to their real callers
+                if (fromSym.name === '_top' && fromSym.kind === 'module') {
+                    // Recurse from the _top module's incoming callers
+                    dfs(link.fromId, [{ symbol: fromSym, via: link.type }, ...currentPath], depth + 1);
+                }
+                else {
+                    dfs(link.fromId, [{ symbol: fromSym, via: link.type }, ...currentPath], depth + 1);
+                }
             }
             visited.delete(currentId);
         };
@@ -416,34 +369,34 @@ export class Database {
     // ── Route/endpoint detection via link patterns ──
     getEntrypoints() {
         // Symbols with role='entrypoint' OR exported + 0 incoming non-contains links
-        const rows = this.db.prepare(`
-      SELECT s.* FROM symbols s
-      WHERE s.exported = 1
-        AND s.role = 'entrypoint'
-      ORDER BY s.heat DESC
-      LIMIT 50
+        const rows = this.db.prepare(`
+      SELECT s.* FROM symbols s
+      WHERE s.exported = 1
+        AND s.role = 'entrypoint'
+      ORDER BY s.heat DESC
+      LIMIT 50
     `).all();
         return rows.map(rowToSymbol);
     }
     // ── Domain clustering stats ──
     getDomainStats() {
-        const rows = this.db.prepare(`
-      SELECT fh.zone AS domain, COUNT(DISTINCT fh.path) AS file_count,
-             COUNT(s.id) AS symbol_count
-      FROM file_hashes fh
-      LEFT JOIN symbols s ON s.file_path = fh.path
-      WHERE fh.zone IS NOT NULL
-      GROUP BY fh.zone
-      ORDER BY symbol_count DESC
+        const rows = this.db.prepare(`
+      SELECT fh.zone AS domain, COUNT(DISTINCT fh.path) AS file_count,
+             COUNT(s.id) AS symbol_count
+      FROM file_hashes fh
+      LEFT JOIN symbols s ON s.file_path = fh.path
+      WHERE fh.zone IS NOT NULL
+      GROUP BY fh.zone
+      ORDER BY symbol_count DESC
     `).all();
         return rows.map((r) => ({ domain: r.domain, files: r.file_count, symbols: r.symbol_count }));
     }
     // ── Staleness detection ──
     getStaleFiles(hoursOld = 24) {
-        const rows = this.db.prepare(`
-      SELECT path FROM file_hashes
-      WHERE analyzed_at < datetime('now', '-' || ? || ' hours')
-      ORDER BY analyzed_at ASC
+        const rows = this.db.prepare(`
+      SELECT path FROM file_hashes
+      WHERE analyzed_at < datetime('now', '-' || ? || ' hours')
+      ORDER BY analyzed_at ASC
     `).all(hoursOld);
         return rows.map((r) => r.path);
     }
@@ -466,40 +419,46 @@ export class Database {
     }
     // ── Tool usage tracking ──
     logToolUsage(tool, durationMs, tokensOut, tokensSaved, repo) {
-        this.db.prepare(`INSERT INTO tool_usage (tool, duration_ms, tokens_out, tokens_saved, repo)
+        this.db.prepare(`INSERT INTO tool_usage (tool, duration_ms, tokens_out, tokens_saved, repo)
        VALUES (?, ?, ?, ?, ?)`).run(tool, durationMs, tokensOut, tokensSaved, repo ?? null);
     }
-    getToolUsageStats() {
-        const totals = this.db.prepare(`
-      SELECT COUNT(*) as total_calls,
-             COALESCE(SUM(tokens_saved), 0) as total_saved,
-             COALESCE(SUM(tokens_out), 0) as total_out,
-             COALESCE(SUM(duration_ms), 0) as total_ms
-      FROM tool_usage
-    `).get();
-        const byTool = this.db.prepare(`
-      SELECT tool, COUNT(*) as calls,
-             COALESCE(SUM(tokens_saved), 0) as tokens_saved,
-             COALESCE(SUM(tokens_out), 0) as tokens_out,
-             CAST(COALESCE(AVG(duration_ms), 0) AS INTEGER) as avg_ms
-      FROM tool_usage
-      GROUP BY tool
-      ORDER BY calls DESC
-    `).all();
-        const byDay = this.db.prepare(`
-      SELECT date(called_at) as date, COUNT(*) as calls,
-             COALESCE(SUM(tokens_saved), 0) as tokens_saved
-      FROM tool_usage
-      GROUP BY date(called_at)
-      ORDER BY date DESC
-      LIMIT 30
-    `).all();
-        const recentCalls = this.db.prepare(`
-      SELECT tool, called_at, duration_ms, tokens_saved
-      FROM tool_usage
-      ORDER BY id DESC
-      LIMIT 50
-    `).all();
+    getToolUsageStats(repo) {
+        const repoFilter = repo ? `WHERE repo = ?` : '';
+        const repoParam = repo ? [repo] : [];
+        const totals = this.db.prepare(`
+      SELECT COUNT(*) as total_calls,
+             COALESCE(SUM(tokens_saved), 0) as total_saved,
+             COALESCE(SUM(tokens_out), 0) as total_out,
+             COALESCE(SUM(duration_ms), 0) as total_ms
+      FROM tool_usage
+      ${repoFilter}
+    `).get(...repoParam);
+        const byTool = this.db.prepare(`
+      SELECT tool, COUNT(*) as calls,
+             COALESCE(SUM(tokens_saved), 0) as tokens_saved,
+             COALESCE(SUM(tokens_out), 0) as tokens_out,
+             CAST(COALESCE(AVG(duration_ms), 0) AS INTEGER) as avg_ms
+      FROM tool_usage
+      ${repoFilter}
+      GROUP BY tool
+      ORDER BY calls DESC
+    `).all(...repoParam);
+        const byDay = this.db.prepare(`
+      SELECT date(called_at) as date, COUNT(*) as calls,
+             COALESCE(SUM(tokens_saved), 0) as tokens_saved
+      FROM tool_usage
+      ${repoFilter}
+      GROUP BY date(called_at)
+      ORDER BY date DESC
+      LIMIT 30
+    `).all(...repoParam);
+        const recentCalls = this.db.prepare(`
+      SELECT tool, called_at, duration_ms, tokens_saved
+      FROM tool_usage
+      ${repoFilter}
+      ORDER BY id DESC
+      LIMIT 50
+    `).all(...repoParam);
         return {
             totalCalls: totals.total_calls,
             totalTokensSaved: totals.total_saved,
@@ -515,16 +474,168 @@ export class Database {
             })),
         };
     }
-    // ── Annotations (agent code memory) ──
+    // ── Test file detection ──
+    isTestFile(filePath) {
+        return /[/\\]test[/\\]/.test(filePath) || /\.(test|spec)\./.test(filePath);
+    }
+    // ── Heat / hubs ──
+    getTopHubs(limit) {
+        const rows = this.stmts.topHubs.all(limit);
+        return rows.map(rowToSymbol);
+    }
+    // ── Test coverage ──
+    getSymbolTestCoverage(symbolId) {
+        const incomingLinks = this.getIncomingLinks(symbolId);
+        for (const link of incomingLinks) {
+            const sourceSymbol = this.findSymbolById(link.fromId);
+            if (sourceSymbol && this.isTestFile(sourceSymbol.filePath)) {
+                return true;
+            }
+        }
+        return false;
+    }
+    getTestedSymbolIds(candidateIds, isTestFileFn) {
+        if (candidateIds.length === 0)
+            return new Set();
+        const placeholders = candidateIds.map(() => '?').join(',');
+        const rows = this.db.prepare(`
+      SELECT DISTINCT l.to_id
+      FROM links l JOIN symbols src ON src.id = l.from_id
+      WHERE l.to_id IN (${placeholders}) AND l.type != 'contains'
+    `).all(...candidateIds);
+        const testedIds = new Set();
+        for (const row of rows) {
+            const src = this.findSymbolById(row.to_id);
+            if (src && isTestFileFn(src.filePath))
+                continue;
+            // Check each from_id for test files
+            const links = this.getIncomingLinks(row.to_id);
+            for (const l of links) {
+                if (l.type === 'contains')
+                    continue;
+                const from = this.findSymbolById(l.fromId);
+                if (from && isTestFileFn(from.filePath)) {
+                    testedIds.add(row.to_id);
+                    break;
+                }
+            }
+        }
+        // Also include ids not in the result set (no incoming links)
+        const inResult = new Set(rows.map(r => r.to_id));
+        for (const id of candidateIds) {
+            if (!inResult.has(id))
+                continue; // doesn't exist
+        }
+        return testedIds;
+    }
+    getTestCoverageGaps(limit) {
+        const rows = this.stmts.testCoverageGaps.all(limit);
+        return rows.map(rowToSymbol);
+    }
+    getTestImpact(changedSymbolIds) {
+        if (changedSymbolIds.length === 0)
+            return { testFiles: [], changedSymbols: [] };
+        const placeholders = changedSymbolIds.map(() => '?').join(',');
+        const testFilesDirect = this.db.prepare(`
+      SELECT DISTINCT src.file_path
+      FROM links l
+      JOIN symbols src ON src.id = l.from_id
+      WHERE l.to_id IN (${placeholders})
+        AND (src.file_path LIKE '%/test/%' OR src.file_path LIKE '%\\test\\%'
+             OR src.file_path LIKE '%.test.%' OR src.file_path LIKE '%.spec.%')
+    `).all(...changedSymbolIds);
+        const testFilesUpstream = this.db.prepare(`
+      WITH RECURSIVE upstream(id, depth) AS (
+        SELECT from_id, 1 FROM links WHERE to_id IN (${placeholders})
+          AND type IN ('calls', 'imports', 'extends', 'implements')
+        UNION
+        SELECT l.from_id, u.depth + 1
+        FROM links l JOIN upstream u ON l.to_id = u.id
+        WHERE l.type IN ('calls', 'imports', 'extends', 'implements') AND u.depth < 5
+      )
+      SELECT DISTINCT s.file_path FROM upstream u
+      JOIN symbols s ON s.id = u.id
+      WHERE (s.file_path LIKE '%/test/%' OR s.file_path LIKE '%\\test\\%'
+             OR s.file_path LIKE '%.test.%' OR s.file_path LIKE '%.spec.%')
+    `).all(...changedSymbolIds);
+        const allTestFiles = [...new Set([
+                ...testFilesDirect.map((r) => r.file_path),
+                ...testFilesUpstream.map((r) => r.file_path),
+            ])];
+        const changedSymbols = changedSymbolIds.filter(id => this.getSymbolTestCoverage(id));
+        return { testFiles: allTestFiles, changedSymbols };
+    }
+    // ── Codebase summary ──
+    getCodebaseSummary() {
+        const stats = this.getStats();
+        const coverage = this.getTestCoverage();
+        const domains = this.getDomainStats();
+        const topHubs = this.getTopHubs(10);
+        const coveragePct = coverage.exportedProductionSymbols > 0
+            ? Math.round((coverage.testedSymbols / coverage.exportedProductionSymbols) * 100)
+            : 0;
+        return {
+            symbols: stats.symbols,
+            links: stats.links,
+            files: stats.files,
+            coveragePct,
+            testedSymbols: coverage.testedSymbols,
+            exportedSymbols: coverage.exportedProductionSymbols,
+            domains,
+            topHubs,
+        };
+    }
+    // ── Topological similarity ──
+    findTopologicallySimilar(symbolId, limit = 10) {
+        const target = this.findSymbolById(symbolId);
+        if (!target)
+            return [];
+        const incoming = this.getIncomingLinks(symbolId).filter(l => l.type !== 'contains');
+        const outgoing = this.getOutgoingLinks(symbolId).filter(l => l.type !== 'contains');
+        const targetLinks = new Set();
+        for (const link of incoming)
+            targetLinks.add(link.fromId);
+        for (const link of outgoing)
+            targetLinks.add(link.toId);
+        const siblings = this.getSymbolsByFile(target.filePath).filter(s => s.id !== symbolId);
+        const results = [];
+        for (const sibling of siblings) {
+            const sibIncoming = this.getIncomingLinks(sibling.id).filter(l => l.type !== 'contains');
+            const sibOutgoing = this.getOutgoingLinks(sibling.id).filter(l => l.type !== 'contains');
+            const siblingLinks = new Set();
+            for (const link of sibIncoming)
+                siblingLinks.add(link.fromId);
+            for (const link of sibOutgoing)
+                siblingLinks.add(link.toId);
+            let intersection = 0;
+            for (const id of targetLinks) {
+                if (siblingLinks.has(id))
+                    intersection++;
+            }
+            const union = new Set([...targetLinks, ...siblingLinks]).size;
+            const similarity = union > 0 ? intersection / union : 0;
+            if (similarity >= 0.3) {
+                results.push({ symbol: sibling, similarity: Math.round(similarity * 100) / 100 });
+            }
+        }
+        return results.sort((a, b) => b.similarity - a.similarity).slice(0, limit);
+    }
+    // ── Annotations ──
+    getAnnotationCount() {
+        const row = this.stmts.annotationCount.get();
+        return row.c;
+    }
+    // ── Annotation/session API ──
+    getRawDb() { return this.db; }
     addAnnotation(symbolId, key, value, agent, sessionId, ttlHours) {
         const expiresAt = ttlHours
             ? new Date(Date.now() + ttlHours * 3600_000).toISOString().replace('T', ' ').slice(0, 19)
             : null;
-        const result = this.db.prepare(`INSERT INTO annotations (symbol_id, key, value, agent, session_id, expires_at)
+        const result = this.db.prepare(`INSERT INTO annotations (symbol_id, key, value, agent, session_id, expires_at)
        VALUES (?, ?, ?, ?, ?, ?)`).run(symbolId, key, value, agent ?? null, sessionId ?? null, expiresAt);
         return result.lastInsertRowid;
     }
-    getAnnotations(filters) {
+    getAnnotations(filters = {}) {
         const clauses = ["(expires_at IS NULL OR expires_at > datetime('now'))"];
         const params = [];
         if (filters.symbolId) {
@@ -543,47 +654,29 @@ export class Database {
             clauses.push('session_id = ?');
             params.push(filters.sessionId);
         }
-        const where = `WHERE ${clauses.join(' AND ')}`;
-        const limit = filters.limit ?? 50;
-        const rows = this.db.prepare(`SELECT id, symbol_id, key, value, agent, session_id, created_at
-       FROM annotations ${where}
-       ORDER BY created_at DESC LIMIT ?`).all(...params, limit);
-        return rows.map(r => ({
-            id: r.id,
-            symbolId: r.symbol_id,
-            key: r.key,
-            value: r.value,
-            agent: r.agent,
-            sessionId: r.session_id,
-            createdAt: r.created_at,
-        }));
+        const sql = `SELECT *, symbol_id as symbolId, created_at as createdAt FROM annotations WHERE ${clauses.join(' AND ')} ORDER BY created_at DESC` + (filters.limit ? ` LIMIT ${filters.limit}` : '');
+        const rows = this.db.prepare(sql).all(...params);
+        return rows.map((r) => ({ id: r.id, symbolId: r.symbol_id, key: r.key, value: r.value, agent: r.agent, sessionId: r.session_id, createdAt: r.created_at }));
     }
     getAnnotationsForSymbol(symbolId) {
-        const rows = this.db.prepare(`SELECT key, value, agent, created_at FROM annotations
-       WHERE symbol_id = ? AND (expires_at IS NULL OR expires_at > datetime('now'))
-       ORDER BY created_at DESC`).all(symbolId);
-        return rows.map(r => ({ key: r.key, value: r.value, agent: r.agent, createdAt: r.created_at }));
+        return this.getAnnotations({ symbolId });
     }
     cleanupExpiredAnnotations() {
-        const result = this.db.prepare(`DELETE FROM annotations WHERE expires_at IS NOT NULL AND expires_at <= datetime('now')`).run();
+        const result = this.db.prepare("DELETE FROM annotations WHERE expires_at IS NOT NULL AND expires_at <= datetime('now')").run();
         return result.changes;
     }
-    // ── Agent sessions ──
     startSession(id, agent, context) {
-        this.db.prepare(`INSERT INTO agent_sessions (id, agent, context_json, status) VALUES (?, ?, ?, 'active')`).run(id, agent, context ?? null);
+        this.db.prepare('INSERT OR REPLACE INTO agent_sessions (id, agent, status, started_at, context_json) VALUES (?, ?, ?, datetime(\'now\'), ?)')
+            .run(id, agent, 'active', context ?? null);
     }
     getSession(id) {
-        const row = this.db.prepare('SELECT * FROM agent_sessions WHERE id = ?').get(id);
+        const row = this.db.prepare('SELECT *, started_at as startedAt, ended_at as endedAt, context_json as context FROM agent_sessions WHERE id = ?').get(id);
         if (!row)
             return null;
-        return { id: row.id, agent: row.agent, startedAt: row.started_at, endedAt: row.ended_at, context: row.context_json, status: row.status };
+        return { id: row.id, agent: row.agent, status: row.status, startedAt: row.started_at, endedAt: row.ended_at, context: row.context };
     }
-    endSession(id, status = 'completed') {
-        this.db.prepare(`UPDATE agent_sessions SET ended_at = datetime('now'), status = ? WHERE id = ?`).run(status, id);
-    }
-    /** Expose raw handle for subsystems (e.g. EmbeddingStore) that need direct access. */
-    getRawDb() {
-        return this.db;
+    endSession(id, status) {
+        this.db.prepare("UPDATE agent_sessions SET status = ?, ended_at = datetime('now') WHERE id = ?").run(status, id);
     }
     transaction(fn) {
         return this.db.transaction(fn)();