@monoes/monograph 1.2.0 → 1.2.1

package/src/search/hybrid-query.ts

@@ -31,6 +31,10 @@ export interface HybridResult extends RankedResult {
   filePath: string | null;
   label: string;
   score: number;
+  /** First line of the symbol in its source file (1-based, null if unknown). */
+  startLine?: number | null;
+  /** Last line of the symbol in its source file (1-based, null if unknown). */
+  endLine?: number | null;
 }
 
 /**
@@ -61,6 +65,8 @@ export async function hybridQuery(
     filePath: r.filePath,
     label: r.label,
     score: r.rank,
+    startLine: r.startLine,
+    endLine: r.endLine,
   }));
 
   // ── Decide whether to add vector results ──────────────────────────────────
@@ -121,7 +127,7 @@ export async function hybridQuery(
     const placeholders = unknownIds.map(() => '?').join(',');
     const rows = db
       .prepare(
-        `SELECT id, name, norm_label, file_path, label FROM nodes WHERE id IN (${placeholders})`,
+        `SELECT id, name, norm_label, file_path, label, start_line, end_line FROM nodes WHERE id IN (${placeholders})`,
       )
       .all(...unknownIds) as {
       id: string;
@@ -129,6 +135,8 @@ export async function hybridQuery(
       norm_label: string;
       file_path: string | null;
       label: string;
+      start_line: number | null;
+      end_line: number | null;
     }[];
 
     const rowMap = new Map(rows.map((r) => [r.id, r]));
@@ -140,6 +148,8 @@ export async function hybridQuery(
           item.normLabel = row.norm_label;
           item.filePath = row.file_path;
           item.label = row.label;
+          (item as HybridResult).startLine = row.start_line;
+          (item as HybridResult).endLine = row.end_line;
         }
       }
     }

package/src/staleness/git-staleness.ts

@@ -24,12 +24,12 @@ export function checkStaleness(db: MonographDb, repoPath: string): StalenessRepo
     return { isStale: false, indexedAt: null, indexedCommit: null, currentCommit: null, changedSince: [], staleSince: null };
   }
 
-  // Display short SHA (7 chars) for the interface field; compare full SHAs for correctness
+  // Display short SHA (7 chars) for the interface field; compare short SHAs for staleness
   const indexedCommitShort = indexedCommitFull ? indexedCommitFull.slice(0, 7) : null;
   const currentCommitShort = currentCommit ? currentCommit.slice(0, 7) : null;
 
-  // 3. If no stored commit or full SHAs match, not stale
-  if (!indexedCommitFull || indexedCommitFull === currentCommit) {
+  // 3. If no stored commit or short SHAs match, not stale
+  if (!indexedCommitFull || indexedCommitShort === currentCommitShort) {
     return { isStale: false, indexedAt: null, indexedCommit: indexedCommitShort, currentCommit: currentCommitShort, changedSince: [], staleSince: null };
   }
 

package/src/storage/db.ts

@@ -37,6 +37,17 @@ function applyMigrations(db: MonographDb): void {
   db.exec(FTS_SYNC_TRIGGERS);
   db.exec(CREATE_EMBEDDINGS);
   db.exec(CREATE_WIKI_PAGES);
+
+  // Schema version table — tracks incremental column additions.
+  db.exec(`CREATE TABLE IF NOT EXISTS schema_version (version INTEGER PRIMARY KEY)`);
+  const row = db.prepare('SELECT MAX(version) AS v FROM schema_version').get() as { v: number | null };
+  const current = row?.v ?? 0;
+
+  if (current < 1) {
+    // v1: added `reason TEXT` to edges
+    try { db.exec('ALTER TABLE edges ADD COLUMN reason TEXT'); } catch { /* already present */ }
+    db.prepare('INSERT OR REPLACE INTO schema_version VALUES (1)').run();
+  }
 }
 
 /** Write to a .tmp file then rename for atomic replacement. */

package/src/storage/edge-store.ts

@@ -17,15 +17,48 @@ export function insertEdge(db: Database.Database, edge: MonographEdge): void {
   );
 }
 
+const INSERT_EDGE_SQL = `
+    INSERT OR REPLACE INTO edges (id, source_id, target_id, relation, confidence, confidence_score, reason, evidence)
+    VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+  `;
+
 export function insertEdges(db: Database.Database, edges: MonographEdge[]): void {
+  if (edges.length === 0) return;
+  // Prepare once and reuse across all rows — avoids N redundant prepare calls
+  const stmt = db.prepare(INSERT_EDGE_SQL);
   const insertMany = db.transaction((rows: MonographEdge[]) => {
     for (const e of rows) {
-      insertEdge(db, e);
+      stmt.run(
+        e.id,
+        e.sourceId,
+        e.targetId,
+        e.relation,
+        e.confidence,
+        e.confidenceScore,
+        e.reason ?? null,
+        e.evidence != null ? JSON.stringify(e.evidence) : null,
+      );
     }
   });
   insertMany(edges);
 }
 
+/** Batch-fetch edges for multiple source IDs using a single SQL IN query. Batches at 50 IDs. */
+export function getEdgesForSources(db: Database.Database, sourceIds: string[]): MonographEdge[] {
+  if (sourceIds.length === 0) return [];
+  const BATCH = 50;
+  const results: MonographEdge[] = [];
+  for (let i = 0; i < sourceIds.length; i += BATCH) {
+    const chunk = sourceIds.slice(i, i + BATCH);
+    const placeholders = chunk.map(() => '?').join(',');
+    const rows = db
+      .prepare(`SELECT * FROM edges WHERE source_id IN (${placeholders})`)
+      .all(...chunk) as Record<string, unknown>[];
+    for (const row of rows) results.push(rowToEdge(row));
+  }
+  return results;
+}
+
 export function getEdgesForSource(db: Database.Database, sourceId: string): MonographEdge[] {
   const rows = db
     .prepare('SELECT * FROM edges WHERE source_id = ?')

package/src/storage/embedding-store.ts

@@ -6,18 +6,25 @@ import type Database from 'better-sqlite3';
  * Vectors are stored as BLOBs (raw Float32Array bytes) and reconstructed on read.
  */
 
+/**
+ * Ensure the embeddings table has the content_hash column introduced in a later
+ * schema version. Call this ONCE before a batch of upserts rather than inside
+ * upsertEmbedding itself to avoid running ALTER TABLE on every row write.
+ */
+export function ensureEmbeddingSchema(db: Database.Database): void {
+  try {
+    db.exec('ALTER TABLE embeddings ADD COLUMN content_hash TEXT');
+  } catch {
+    // Column already exists — ignore.
+  }
+}
+
 export function upsertEmbedding(
   db: Database.Database,
   nodeId: string,
   vector: Float32Array,
   contentHash?: string,
 ): void {
-  // Migrate existing DBs that may not have the content_hash column yet.
-  try {
-    db.exec('ALTER TABLE embeddings ADD COLUMN content_hash TEXT');
-  } catch {
-    // Column already exists — ignore.
-  }
   const buf = Buffer.from(vector.buffer, vector.byteOffset, vector.byteLength);
   db
     .prepare(
@@ -26,6 +33,31 @@ export function upsertEmbedding(
     .run(nodeId, buf, contentHash ?? null);
 }
 
+/**
+ * Bulk-upsert multiple embeddings in a single transaction.
+ * Calls ensureEmbeddingSchema once before writing, then wraps all inserts in
+ * a transaction for 10-100x faster throughput vs per-row upsertEmbedding calls.
+ */
+export function batchUpsertEmbeddings(
+  db: Database.Database,
+  entries: Array<{ nodeId: string; vector: Float32Array; contentHash?: string }>,
+): void {
+  if (entries.length === 0) return;
+  ensureEmbeddingSchema(db);
+  const stmt = db.prepare(
+    'INSERT OR REPLACE INTO embeddings (node_id, vector, content_hash) VALUES (?, ?, ?)',
+  );
+  const insertMany = db.transaction(
+    (rows: Array<{ nodeId: string; vector: Float32Array; contentHash?: string }>) => {
+      for (const e of rows) {
+        const buf = Buffer.from(e.vector.buffer, e.vector.byteOffset, e.vector.byteLength);
+        stmt.run(e.nodeId, buf, e.contentHash ?? null);
+      }
+    },
+  );
+  insertMany(entries);
+}
+
 export function getEmbeddingContentHash(db: Database.Database, nodeId: string): string | null {
   const row = db
     .prepare('SELECT content_hash FROM embeddings WHERE node_id = ?')

package/src/storage/file-cache.ts

@@ -27,34 +27,48 @@ export function updateFileCache(db: MonographDb, entry: FileCacheEntry): void {
   `).run(entry.filePath, entry.contentHash, entry.lastParsed, entry.nodeCount, entry.edgeCount);
 }
 
+/**
+ * Bulk-upsert multiple file cache entries in a single transaction.
+ * Prefer this over calling updateFileCache in a loop for pipeline batch writes.
+ */
+export function batchUpdateFileCache(db: MonographDb, entries: FileCacheEntry[]): void {
+  if (entries.length === 0) return;
+  const stmt = db.prepare(`
+    INSERT OR REPLACE INTO file_cache (file_path, content_hash, last_parsed, node_count, edge_count)
+    VALUES (?, ?, ?, ?, ?)
+  `);
+  const insertMany = db.transaction((rows: FileCacheEntry[]) => {
+    for (const e of rows) {
+      stmt.run(e.filePath, e.contentHash, e.lastParsed, e.nodeCount, e.edgeCount);
+    }
+  });
+  insertMany(entries);
+}
+
 export function getFileCacheStats(db: MonographDb): {
   totalCached: number;
   hitRate: number;
   stalePaths: string[];
 } {
-  const totalCached = (db.prepare('SELECT COUNT(*) as c FROM file_cache').get() as { c: number }).c;
-
-  const totalNodes = (db.prepare(
-    "SELECT COUNT(DISTINCT file_path) as c FROM nodes WHERE file_path IS NOT NULL"
-  ).get() as { c: number }).c;
-
-  const hitRate = totalNodes > 0 ? totalCached / totalNodes : 0;
-
-  // Find stale paths: cached entries whose file no longer exists in nodes table
-  const cachedPaths = db.prepare('SELECT file_path, content_hash FROM file_cache').all() as {
-    file_path: string;
-    content_hash: string;
-  }[];
+  // Single query: count cached entries and distinct indexed file paths in one pass.
+  const counts = db.prepare(`
+    SELECT
+      (SELECT COUNT(*) FROM file_cache) AS total_cached,
+      (SELECT COUNT(DISTINCT file_path) FROM nodes WHERE file_path IS NOT NULL) AS total_indexed
+  `).get() as { total_cached: number; total_indexed: number };
 
-  const indexedPaths = new Set<string>(
-    (db.prepare("SELECT DISTINCT file_path FROM nodes WHERE file_path IS NOT NULL").all() as {
-      file_path: string;
-    }[]).map(r => r.file_path)
-  );
+  const totalCached = counts.total_cached;
+  const hitRate = counts.total_indexed > 0 ? totalCached / counts.total_indexed : 0;
 
-  const stalePaths = cachedPaths
-    .filter(r => !indexedPaths.has(r.file_path))
-    .map(r => r.file_path);
+  // Find stale paths via SQL LEFT JOIN — avoids loading all rows into JS memory.
+  const stalePaths = (db.prepare(`
+    SELECT fc.file_path
+    FROM file_cache fc
+    LEFT JOIN (
+      SELECT DISTINCT file_path FROM nodes WHERE file_path IS NOT NULL
+    ) n ON fc.file_path = n.file_path
+    WHERE n.file_path IS NULL
+  `).all() as { file_path: string }[]).map(r => r.file_path);
 
   return { totalCached, hitRate, stalePaths };
 }

package/src/storage/fts-store.ts

@@ -7,6 +7,10 @@ export interface FtsResult {
   filePath: string | null;
   label: string;
   rank: number;
+  /** First line of the symbol in its source file (1-based, null if unknown). */
+  startLine: number | null;
+  /** Last line of the symbol in its source file (1-based, null if unknown). */
+  endLine: number | null;
 }
 
 export function ftsSearch(
@@ -25,7 +29,7 @@ export function ftsSearch(
 
   let matchSql = `
     SELECT n.id, n.name, n.norm_label, n.file_path, n.label,
-           nodes_fts.rank
+           n.start_line, n.end_line, nodes_fts.rank
     FROM nodes_fts
     JOIN nodes n ON n.rowid = nodes_fts.rowid
     WHERE nodes_fts MATCH ?
@@ -55,7 +59,7 @@ export function ftsSearch(
     const likePattern = `%${escapedQuery}%`;
     let likeSql = `
       SELECT n.id, n.name, n.norm_label, n.file_path, n.label,
-             0 AS rank
+             n.start_line, n.end_line, 0 AS rank
       FROM nodes n
       WHERE (n.name LIKE ? OR n.norm_label LIKE ? OR n.file_path LIKE ?)
     `;
@@ -89,6 +93,8 @@ export function ftsSearch(
     filePath: (r.file_path as string | null) ?? null,
     label: r.label as string,
     rank: r.rank as number,
+    startLine: (r.start_line as number | null) ?? null,
+    endLine: (r.end_line as number | null) ?? null,
   }));
 }
 
@@ -183,7 +189,8 @@ export function hybridSearch(
     const escapedSafeQuery = safeQuery.replace(/%/g, '\\%').replace(/_/g, '\\_');
     const likePattern = `%${escapedSafeQuery}%`;
     let likeSql = `
-      SELECT n.id, n.name, n.norm_label, n.file_path, n.label
+      SELECT n.id, n.name, n.norm_label, n.file_path, n.label,
+             n.start_line, n.end_line
       FROM nodes n
       WHERE (n.name LIKE ? OR n.norm_label LIKE ?)
     `;
@@ -211,6 +218,8 @@ export function hybridSearch(
         filePath: (r.file_path as string | null) ?? null,
         label: lbl,
         rank: 0,
+        startLine: (r.start_line as number | null) ?? null,
+        endLine: (r.end_line as number | null) ?? null,
         combinedScore: combined,
         matchStrategy: 'like',
       });

package/src/storage/node-store.ts

@@ -23,15 +23,53 @@ export function insertNode(db: Database.Database, node: MonographNode): void {
   );
 }
 
+const INSERT_SQL = `
+    INSERT OR REPLACE INTO nodes
+      (id, label, name, norm_label, file_path, start_line, end_line,
+       community_id, is_exported, language, properties)
+    VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+  `;
+
 export function insertNodes(db: Database.Database, nodes: MonographNode[]): void {
+  if (nodes.length === 0) return;
+  // Prepare once and reuse across all rows — avoids N redundant prepare calls
+  const stmt = db.prepare(INSERT_SQL);
   const insertMany = db.transaction((rows: MonographNode[]) => {
     for (const n of rows) {
-      insertNode(db, n);
+      stmt.run(
+        n.id,
+        n.label,
+        n.name,
+        n.normLabel ?? toNormLabel(n.name),
+        n.filePath ?? null,
+        n.startLine ?? null,
+        n.endLine ?? null,
+        n.communityId ?? null,
+        n.isExported ? 1 : 0,
+        n.language ?? null,
+        n.properties ? JSON.stringify(n.properties) : null,
+      );
     }
   });
   insertMany(nodes);
 }
 
+/** Batch-fetch multiple nodes by ID using a single SQL IN query. Batches at 50 IDs. */
+export function getNodesByIds(db: Database.Database, ids: string[]): MonographNode[] {
+  if (ids.length === 0) return [];
+  const BATCH = 50;
+  const results: MonographNode[] = [];
+  for (let i = 0; i < ids.length; i += BATCH) {
+    const chunk = ids.slice(i, i + BATCH);
+    const placeholders = chunk.map(() => '?').join(',');
+    const rows = db
+      .prepare(`SELECT * FROM nodes WHERE id IN (${placeholders})`)
+      .all(...chunk) as Record<string, unknown>[];
+    for (const row of rows) results.push(rowToNode(row));
+  }
+  return results;
+}
+
 export function getNode(db: Database.Database, id: string): MonographNode | undefined {
   const row = db
     .prepare('SELECT * FROM nodes WHERE id = ?')

package/src/coverage/runtime.ts

@@ -1,249 +0,0 @@
-import type { MonographDb } from '../storage/db.js';
-
-export type RuntimeClassification =
-  | 'SafeToDelete'          // graph-dead AND not covered at runtime
-  | 'ReviewRequired'        // graph-dead BUT has runtime coverage
-  | 'LowTraffic'            // covered but <5% call rate
-  | 'Active'                // actively covered
-  | 'CoverageUnavailable';  // in graph but no coverage data for this file
-
-export interface FunctionCoverageEntry {
-  nodeId: string;
-  name: string;
-  filePath: string | null;
-  startLine: number | null;
-  covered: boolean;
-  callCount: number;
-  classification: RuntimeClassification;
-}
-
-export interface RuntimeCoverageReport {
-  entries: FunctionCoverageEntry[];
-  safeToDelete: number;
-  reviewRequired: number;
-  active: number;
-  coverageUnavailable: number;
-  blastRadius: string[];   // active entry-point file paths (covered + reachable)
-}
-
-// V8 coverage format (subset of what Node/Chrome produces)
-export interface V8CoverageFunction {
-  functionName: string;
-  url: string;          // file URL like 'file:///path/to/file.js'
-  ranges: Array<{ startOffset: number; endOffset: number; count: number }>;
-}
-
-export interface V8Coverage {
-  result: Array<{
-    url: string;
-    functions: V8CoverageFunction[];
-  }>;
-}
-
-interface CoverageMapEntry {
-  covered: boolean;
-  callCount: number;
-}
-
-interface SymbolNodeRow {
-  id: string;
-  name: string;
-  file_path: string | null;
-  start_line: number | null;
-  properties: string | null;
-}
-
-export function analyzeRuntimeCoverage(
-  db: MonographDb,
-  coverage: V8Coverage,
-  repoRoot?: string
-): RuntimeCoverageReport {
-  // Build a map: filePath -> Map<functionName, CoverageMapEntry>
-  const fileCoverageMap = new Map<string, Map<string, CoverageMapEntry>>();
-
-  for (const scriptCov of coverage.result) {
-    let filePath = scriptCov.url;
-
-    // Strip file:// prefix
-    if (filePath.startsWith('file://')) {
-      filePath = filePath.slice('file://'.length);
-    }
-
-    // Resolve relative to repoRoot if provided and path is relative
-    if (repoRoot && !filePath.startsWith('/')) {
-      filePath = repoRoot.replace(/\/$/, '') + '/' + filePath;
-    }
-
-    const fnMap = fileCoverageMap.get(filePath) ?? new Map<string, CoverageMapEntry>();
-
-    for (const fn of scriptCov.functions) {
-      const covered = fn.ranges.some(r => r.count > 0);
-      const callCount = fn.ranges.reduce((max, r) => Math.max(max, r.count), 0);
-      const existing = fnMap.get(fn.functionName);
-      if (!existing || callCount > existing.callCount) {
-        fnMap.set(fn.functionName, { covered, callCount });
-      }
-    }
-
-    fileCoverageMap.set(filePath, fnMap);
-  }
-
-  // Helper: normalize a file path for lookup
-  function normalizeForLookup(fp: string): string {
-    return fp.replace(/\\/g, '/');
-  }
-
-  // Build alternate lookup: basename -> filePath list
-  const filePathIndex = new Map<string, string[]>();
-  for (const fp of fileCoverageMap.keys()) {
-    const norm = normalizeForLookup(fp);
-    filePathIndex.set(norm, (filePathIndex.get(norm) ?? []).concat(fp));
-    // Also store by just the filename for relative matching
-    const parts = norm.split('/');
-    const base = parts[parts.length - 1];
-    if (base && base !== norm) {
-      filePathIndex.set(base, (filePathIndex.get(base) ?? []).concat(fp));
-    }
-  }
-
-  // Compute total call count across all functions for LowTraffic threshold
-  let totalCallCount = 0;
-  for (const fnMap of fileCoverageMap.values()) {
-    for (const entry of fnMap.values()) {
-      totalCallCount += entry.callCount;
-    }
-  }
-  const lowTrafficThreshold = totalCallCount * 0.05;
-
-  // Query all Symbol nodes that are Functions/Methods
-  const rows = db.prepare(`
-    SELECT id, name, file_path, start_line, properties
-    FROM nodes
-    WHERE label IN ('Function', 'Method')
-  `).all() as SymbolNodeRow[];
-
-  const entries: FunctionCoverageEntry[] = [];
-
-  for (const row of rows) {
-    const props = row.properties ? JSON.parse(row.properties) : {};
-    const reachabilityRole: string = props.reachabilityRole ?? '';
-
-    let fnEntry: CoverageMapEntry | null = null;
-
-    if (row.file_path) {
-      const normFilePath = normalizeForLookup(row.file_path);
-
-      // Try exact match first
-      const exactFnMap = fileCoverageMap.get(normFilePath) ?? fileCoverageMap.get(row.file_path);
-      if (exactFnMap) {
-        const match = exactFnMap.get(row.name);
-        if (match) fnEntry = match;
-        // If no exact function name match, aggregate all functions for this file
-        if (!fnEntry) {
-          // Best-effort: file is covered if any function is covered
-          let fileCovered = false;
-          let fileMaxCount = 0;
-          for (const e of exactFnMap.values()) {
-            if (e.covered) fileCovered = true;
-            fileMaxCount = Math.max(fileMaxCount, e.callCount);
-          }
-          if (exactFnMap.size > 0) {
-            fnEntry = { covered: fileCovered, callCount: fileMaxCount };
-          }
-        }
-      } else {
-        // Try relative path matching
-        for (const [covPath, fnMap] of fileCoverageMap.entries()) {
-          if (covPath.endsWith(normFilePath) || normFilePath.endsWith(covPath.replace(/.*\//, ''))) {
-            const match = fnMap.get(row.name);
-            if (match) { fnEntry = match; break; }
-            // Aggregate file-level coverage
-            let fileCovered = false;
-            let fileMaxCount = 0;
-            for (const e of fnMap.values()) {
-              if (e.covered) fileCovered = true;
-              fileMaxCount = Math.max(fileMaxCount, e.callCount);
-            }
-            if (fnMap.size > 0) {
-              fnEntry = { covered: fileCovered, callCount: fileMaxCount };
-              break;
-            }
-          }
-        }
-      }
-    }
-
-    let classification: RuntimeClassification;
-    let covered = false;
-    let callCount = 0;
-
-    if (!fnEntry) {
-      classification = 'CoverageUnavailable';
-    } else {
-      covered = fnEntry.covered;
-      callCount = fnEntry.callCount;
-
-      if (!covered && reachabilityRole === 'unreachable') {
-        classification = 'SafeToDelete';
-      } else if (covered && reachabilityRole === 'unreachable') {
-        classification = 'ReviewRequired';
-      } else if (covered && callCount < lowTrafficThreshold) {
-        classification = 'LowTraffic';
-      } else if (covered) {
-        classification = 'Active';
-      } else {
-        // not covered, not unreachable — treat as unavailable
-        classification = 'CoverageUnavailable';
-      }
-    }
-
-    entries.push({
-      nodeId: row.id,
-      name: row.name,
-      filePath: row.file_path,
-      startLine: row.start_line,
-      covered,
-      callCount,
-      classification,
-    });
-  }
-
-  // Aggregate counts
-  let safeToDelete = 0;
-  let reviewRequired = 0;
-  let active = 0;
-  let coverageUnavailable = 0;
-
-  const blastRadiusSet = new Set<string>();
-
-  for (const entry of entries) {
-    switch (entry.classification) {
-      case 'SafeToDelete': safeToDelete++; break;
-      case 'ReviewRequired': reviewRequired++; break;
-      case 'Active': active++; break;
-      case 'CoverageUnavailable': coverageUnavailable++; break;
-    }
-
-    // BlastRadius: Active nodes with reachabilityRole === 'runtime'
-    if (entry.classification === 'Active' && entry.filePath) {
-      const nodeProps = entries.find(e => e.nodeId === entry.nodeId);
-      // Re-query to get reachabilityRole for blast radius check
-      const nodeRow = db.prepare(`SELECT properties FROM nodes WHERE id = ?`).get(entry.nodeId) as { properties: string | null } | undefined;
-      if (nodeRow) {
-        const p = nodeRow.properties ? JSON.parse(nodeRow.properties) : {};
-        if (p.reachabilityRole === 'runtime') {
-          blastRadiusSet.add(entry.filePath);
-        }
-      }
-    }
-  }
-
-  return {
-    entries,
-    safeToDelete,
-    reviewRequired,
-    active,
-    coverageUnavailable,
-    blastRadius: Array.from(blastRadiusSet),
-  };
-}