milens 0.6.2 → 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 = ?)'),
             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() {
@@ -176,38 +194,20 @@ export class Database {
         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)
@@ -215,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 })),
@@ -248,15 +248,15 @@ export class Database {
         const fromId = fromSyms[0].id;
         const toIds = new Set(toSyms.map(s => s.id));
         // 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
+        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);
         const result = [];
         for (const r of rows) {
@@ -309,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,
@@ -369,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);
     }
@@ -419,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,
@@ -468,6 +474,210 @@ export class Database {
             })),
         };
     }
+    // ── 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)
+       VALUES (?, ?, ?, ?, ?, ?)`).run(symbolId, key, value, agent ?? null, sessionId ?? null, expiresAt);
+        return result.lastInsertRowid;
+    }
+    getAnnotations(filters = {}) {
+        const clauses = ["(expires_at IS NULL OR expires_at > datetime('now'))"];
+        const params = [];
+        if (filters.symbolId) {
+            clauses.push('symbol_id = ?');
+            params.push(filters.symbolId);
+        }
+        if (filters.key) {
+            clauses.push('key = ?');
+            params.push(filters.key);
+        }
+        if (filters.agent) {
+            clauses.push('agent = ?');
+            params.push(filters.agent);
+        }
+        if (filters.sessionId) {
+            clauses.push('session_id = ?');
+            params.push(filters.sessionId);
+        }
+        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) {
+        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();
+        return result.changes;
+    }
+    startSession(id, agent, context) {
+        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 *, 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, status: row.status, startedAt: row.started_at, endedAt: row.ended_at, context: row.context };
+    }
+    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)();
     }