merge: resolve conflicts with origin/main in ROADMAP.md

Take main's corrected #57 section anchors; keep HEAD's v2.7.0 version reference.

Impact: 10 functions changed, 11 affected

Author: carlos-alm

docs/roadmap/ROADMAP.md

@@ -1110,7 +1110,7 @@ With analysis data loss fixed, optimize the 1-file rebuild path end-to-end. Curr
 
 **Goal:** Migrate the codebase from plain JavaScript to TypeScript, leveraging the clean module boundaries established in Phase 3. Incremental module-by-module migration starting from leaf modules inward.
 
-**Why after Phase 3:** The architectural refactoring creates small, well-bounded modules with explicit interfaces (Repository, Engine, BaseExtractor, Pipeline stages, Command objects). These are natural type boundaries -- typing monolithic 2,000-line files that are about to be split would be double work.
+**Why after Phase 4:** The architectural refactoring (Phase 3) creates small, well-bounded modules with explicit interfaces. Phase 4 moves the remaining hot-path visitor code to Rust — doing TS migration first would mean rewriting those visitors to TypeScript only to delete them when porting to Rust. With both phases complete, the JS layer is purely orchestration and presentation, which is the ideal surface for TypeScript.
 
 ### 5.1 -- Project Setup
 
@@ -1227,14 +1227,14 @@ Migrate top-level orchestration and entry points:
 - No coverage thresholds enforced in CI (coverage report runs locally only)
 - Embedding tests in separate workflow requiring HuggingFace token
 - 312 `setTimeout`/`sleep` instances in tests — potential flakiness under load
-- No dependency audit step in CI (see also [5.7](#47----supply-chain-security--audit))
+- No dependency audit step in CI (see also [5.7](#57----supply-chain-security--audit))
 
 **Deliverables:**
 
 1. **Coverage gate** -- add `vitest --coverage` to CI with minimum threshold (e.g. 80% lines/branches); fail the pipeline when coverage drops below the threshold
 2. **Unified test workflow** -- merge embedding tests into the main CI workflow using a securely stored `HF_TOKEN` secret; eliminate the separate workflow
 3. **Timer cleanup** -- audit and reduce `setTimeout`/`sleep` usage in tests; replace with deterministic waits (event-based, polling with backoff, or `vi.useFakeTimers()`) to reduce flakiness
-4. > _Dependency audit step is covered by [5.7](#47----supply-chain-security--audit) deliverable 1._
+4. > _Dependency audit step is covered by [5.7](#57----supply-chain-security--audit) deliverable 1._
 
 **Affected files:** `.github/workflows/ci.yml`, `vitest.config.js`, `tests/`
 

src/db/connection.js

@@ -3,6 +3,8 @@ import path from 'node:path';
 import Database from 'better-sqlite3';
 import { warn } from '../infrastructure/logger.js';
 import { DbError } from '../shared/errors.js';
+import { Repository } from './repository/base.js';
+import { SqliteRepository } from './repository/sqlite-repository.js';
 
 function isProcessAlive(pid) {
   try {
@@ -86,3 +88,32 @@ export function openReadonlyOrFail(customPath) {
   }
   return new Database(dbPath, { readonly: true });
 }
+
+/**
+ * Open a Repository from either an injected instance or a DB path.
+ *
+ * When `opts.repo` is a Repository instance, returns it directly (no DB opened).
+ * Otherwise opens a readonly SQLite DB and wraps it in SqliteRepository.
+ *
+ * @param {string} [customDbPath] - Path to graph.db (ignored when opts.repo is set)
+ * @param {object} [opts]
+ * @param {Repository} [opts.repo] - Pre-built Repository to use instead of SQLite
+ * @returns {{ repo: Repository, close(): void }}
+ */
+export function openRepo(customDbPath, opts = {}) {
+  if (opts.repo != null) {
+    if (!(opts.repo instanceof Repository)) {
+      throw new TypeError(
+        `openRepo: opts.repo must be a Repository instance, got ${Object.prototype.toString.call(opts.repo)}`,
+      );
+    }
+    return { repo: opts.repo, close() {} };
+  }
+  const db = openReadonlyOrFail(customDbPath);
+  return {
+    repo: new SqliteRepository(db),
+    close() {
+      db.close();
+    },
+  };
+}

src/db/index.js

@@ -1,5 +1,5 @@
 // Barrel re-export — keeps all existing `import { ... } from '…/db/index.js'` working.
-export { closeDb, findDbPath, openDb, openReadonlyOrFail } from './connection.js';
+export { closeDb, findDbPath, openDb, openReadonlyOrFail, openRepo } from './connection.js';
 export { getBuildMeta, initSchema, MIGRATIONS, setBuildMeta } from './migrations.js';
 export {
   fanInJoinSQL,

src/domain/analysis/symbol-lookup.js

@@ -12,6 +12,7 @@ import {
   findNodesWithFanIn,
   listFunctionNodes,
   openReadonlyOrFail,
+  Repository,
 } from '../../db/index.js';
 import { isTestFile } from '../../infrastructure/test-filter.js';
 import { ALL_SYMBOL_KINDS } from '../../shared/kinds.js';
@@ -23,11 +24,16 @@ const FUNCTION_KINDS = ['function', 'method', 'class'];
 /**
  * Find nodes matching a name query, ranked by relevance.
  * Scoring: exact=100, prefix=60, word-boundary=40, substring=10, plus fan-in tiebreaker.
+ *
+ * @param {object} dbOrRepo - A better-sqlite3 Database or a Repository instance
  */
-export function findMatchingNodes(db, name, opts = {}) {
+export function findMatchingNodes(dbOrRepo, name, opts = {}) {
   const kinds = opts.kind ? [opts.kind] : opts.kinds?.length ? opts.kinds : FUNCTION_KINDS;
 
-  const rows = findNodesWithFanIn(db, `%${name}%`, { kinds, file: opts.file });
+  const isRepo = dbOrRepo instanceof Repository;
+  const rows = isRepo
+    ? dbOrRepo.findNodesWithFanIn(`%${name}%`, { kinds, file: opts.file })
+    : findNodesWithFanIn(dbOrRepo, `%${name}%`, { kinds, file: opts.file });
 
   const nodes = opts.noTests ? rows.filter((n) => !isTestFile(n.file)) : rows;
 

src/features/communities.js

@@ -1,5 +1,5 @@
 import path from 'node:path';
-import { openReadonlyOrFail } from '../db/index.js';
+import { openRepo } from '../db/index.js';
 import { louvainCommunities } from '../graph/algorithms/louvain.js';
 import { buildDependencyGraph } from '../graph/builders/dependency.js';
 import { paginateResult } from '../shared/paginate.js';
@@ -26,15 +26,15 @@ function getDirectory(filePath) {
  * @returns {{ communities: object[], modularity: number, drift: object, summary: object }}
  */
 export function communitiesData(customDbPath, opts = {}) {
-  const db = openReadonlyOrFail(customDbPath);
+  const { repo, close } = openRepo(customDbPath, opts);
   let graph;
   try {
-    graph = buildDependencyGraph(db, {
+    graph = buildDependencyGraph(repo, {
       fileLevel: !opts.functions,
       noTests: opts.noTests,
     });
   } finally {
-    db.close();
+    close();
   }
 
   // Handle empty or trivial graphs

src/features/sequence.js

@@ -6,7 +6,8 @@
  * sequence-diagram conventions.
  */
 
-import { findCallees, openReadonlyOrFail } from '../db/index.js';
+import { openRepo } from '../db/index.js';
+import { SqliteRepository } from '../db/repository/sqlite-repository.js';
 import { findMatchingNodes } from '../domain/queries.js';
 import { isTestFile } from '../infrastructure/test-filter.js';
 import { paginateResult } from '../shared/paginate.js';
@@ -85,19 +86,19 @@ function buildAliases(files) {
  * @returns {{ entry, participants, messages, depth, totalMessages, truncated }}
  */
 export function sequenceData(name, dbPath, opts = {}) {
-  const db = openReadonlyOrFail(dbPath);
+  const { repo, close } = openRepo(dbPath, opts);
   try {
     const maxDepth = opts.depth || 10;
     const noTests = opts.noTests || false;
     const withDataflow = opts.dataflow || false;
 
     // Phase 1: Direct LIKE match
-    let matchNode = findMatchingNodes(db, name, opts)[0] ?? null;
+    let matchNode = findMatchingNodes(repo, name, opts)[0] ?? null;
 
     // Phase 2: Prefix-stripped matching
     if (!matchNode) {
       for (const prefix of FRAMEWORK_ENTRY_PREFIXES) {
-        matchNode = findMatchingNodes(db, `${prefix}${name}`, opts)[0] ?? null;
+        matchNode = findMatchingNodes(repo, `${prefix}${name}`, opts)[0] ?? null;
         if (matchNode) break;
       }
     }
@@ -133,7 +134,7 @@ export function sequenceData(name, dbPath, opts = {}) {
       const nextFrontier = [];
 
       for (const fid of frontier) {
-        const callees = findCallees(db, fid);
+        const callees = repo.findCallees(fid);
 
         const caller = idToNode.get(fid);
 
@@ -163,18 +164,17 @@ export function sequenceData(name, dbPath, opts = {}) {
 
       if (d === maxDepth && frontier.length > 0) {
         // Only mark truncated if at least one frontier node has further callees
-        const hasMoreCalls = frontier.some((fid) => findCallees(db, fid).length > 0);
+        const hasMoreCalls = frontier.some((fid) => repo.findCallees(fid).length > 0);
         if (hasMoreCalls) truncated = true;
       }
     }
 
     // Dataflow annotations: add return arrows
     if (withDataflow && messages.length > 0) {
-      const hasTable = db
-        .prepare("SELECT name FROM sqlite_master WHERE type='table' AND name='dataflow'")
-        .get();
+      const hasTable = repo.hasDataflowTable();
 
-      if (hasTable) {
+      if (hasTable && repo instanceof SqliteRepository) {
+        const db = repo.db;
         // Build name|file lookup for O(1) target node access
         const nodeByNameFile = new Map();
         for (const n of idToNode.values()) {
@@ -281,7 +281,7 @@ export function sequenceData(name, dbPath, opts = {}) {
     }
     return result;
   } finally {
-    db.close();
+    close();
   }
 }
 

src/features/triage.js

@@ -1,4 +1,4 @@
-import { findNodesForTriage, openReadonlyOrFail } from '../db/index.js';
+import { openRepo } from '../db/index.js';
 import { DEFAULT_WEIGHTS, scoreRisk } from '../graph/classifiers/risk.js';
 import { warn } from '../infrastructure/logger.js';
 import { isTestFile } from '../infrastructure/test-filter.js';
@@ -14,7 +14,7 @@ import { paginateResult } from '../shared/paginate.js';
  * @returns {{ items: object[], summary: object, _pagination?: object }}
  */
 export function triageData(customDbPath, opts = {}) {
-  const db = openReadonlyOrFail(customDbPath);
+  const { repo, close } = openRepo(customDbPath, opts);
   try {
     const noTests = opts.noTests || false;
     const fileFilter = opts.file || null;
@@ -26,7 +26,7 @@ export function triageData(customDbPath, opts = {}) {
 
     let rows;
     try {
-      rows = findNodesForTriage(db, {
+      rows = repo.findNodesForTriage({
         noTests,
         file: fileFilter,
         kind: kindFilter,
@@ -115,7 +115,7 @@ export function triageData(customDbPath, opts = {}) {
       offset: opts.offset,
     });
   } finally {
-    db.close();
+    close();
   }
 }
 

src/graph/builders/dependency.js

@@ -3,32 +3,39 @@
  * Replaces inline graph construction in cycles.js, communities.js, viewer.js, export.js.
  */
 
-import { getCallableNodes, getCallEdges, getFileNodesAll, getImportEdges } from '../../db/index.js';
+import {
+  getCallableNodes,
+  getCallEdges,
+  getFileNodesAll,
+  getImportEdges,
+  Repository,
+} from '../../db/index.js';
 import { isTestFile } from '../../infrastructure/test-filter.js';
 import { CodeGraph } from '../model.js';
 
 /**
- * @param {object} db - Open better-sqlite3 database (readonly)
+ * @param {object} dbOrRepo - Open better-sqlite3 database (readonly) or a Repository instance
  * @param {object} [opts]
  * @param {boolean} [opts.fileLevel=true] - File-level (imports) or function-level (calls)
  * @param {boolean} [opts.noTests=false] - Exclude test files
  * @param {number}  [opts.minConfidence] - Minimum edge confidence (function-level only)
  * @returns {CodeGraph}
  */
-export function buildDependencyGraph(db, opts = {}) {
+export function buildDependencyGraph(dbOrRepo, opts = {}) {
   const fileLevel = opts.fileLevel !== false;
   const noTests = opts.noTests || false;
 
   if (fileLevel) {
-    return buildFileLevelGraph(db, noTests);
+    return buildFileLevelGraph(dbOrRepo, noTests);
   }
-  return buildFunctionLevelGraph(db, noTests, opts.minConfidence);
+  return buildFunctionLevelGraph(dbOrRepo, noTests, opts.minConfidence);
 }
 
-function buildFileLevelGraph(db, noTests) {
+function buildFileLevelGraph(dbOrRepo, noTests) {
   const graph = new CodeGraph();
+  const isRepo = dbOrRepo instanceof Repository;
 
-  let nodes = getFileNodesAll(db);
+  let nodes = isRepo ? dbOrRepo.getFileNodesAll() : getFileNodesAll(dbOrRepo);
   if (noTests) nodes = nodes.filter((n) => !isTestFile(n.file));
 
   const nodeIds = new Set();
@@ -37,7 +44,7 @@ function buildFileLevelGraph(db, noTests) {
     nodeIds.add(n.id);
   }
 
-  const edges = getImportEdges(db);
+  const edges = isRepo ? dbOrRepo.getImportEdges() : getImportEdges(dbOrRepo);
   for (const e of edges) {
     if (!nodeIds.has(e.source_id) || !nodeIds.has(e.target_id)) continue;
     const src = String(e.source_id);
@@ -51,10 +58,11 @@ function buildFileLevelGraph(db, noTests) {
   return graph;
 }
 
-function buildFunctionLevelGraph(db, noTests, minConfidence) {
+function buildFunctionLevelGraph(dbOrRepo, noTests, minConfidence) {
   const graph = new CodeGraph();
+  const isRepo = dbOrRepo instanceof Repository;
 
-  let nodes = getCallableNodes(db);
+  let nodes = isRepo ? dbOrRepo.getCallableNodes() : getCallableNodes(dbOrRepo);
   if (noTests) nodes = nodes.filter((n) => !isTestFile(n.file));
 
   const nodeIds = new Set();
@@ -70,11 +78,16 @@ function buildFunctionLevelGraph(db, noTests, minConfidence) {
 
   let edges;
   if (minConfidence != null) {
-    edges = db
-      .prepare("SELECT source_id, target_id FROM edges WHERE kind = 'calls' AND confidence >= ?")
-      .all(minConfidence);
+    if (isRepo) {
+      // minConfidence filtering not supported by Repository — fall back to getCallEdges
+      edges = dbOrRepo.getCallEdges();
+    } else {
+      edges = dbOrRepo
+        .prepare("SELECT source_id, target_id FROM edges WHERE kind = 'calls' AND confidence >= ?")
+        .all(minConfidence);
+    }
   } else {
-    edges = getCallEdges(db);
+    edges = isRepo ? dbOrRepo.getCallEdges() : getCallEdges(dbOrRepo);
   }
 
   for (const e of edges) {