@optave/codegraph 3.3.0 → 3.4.0

package/src/features/{branch-compare.js → branch-compare.ts}

@@ -1,11 +1,3 @@
-/**
- * Branch structural diff – compare code structure between two git refs.
- *
- * Builds separate codegraph databases for each ref using git worktrees,
- * then diffs at the symbol level to show added/removed/changed symbols
- * and transitive caller impact.
- */
-
 import { execFileSync } from 'node:child_process';
 import fs from 'node:fs';
 import os from 'node:os';
@@ -14,10 +6,17 @@ import Database from 'better-sqlite3';
 import { buildGraph } from '../domain/graph/builder.js';
 import { kindIcon } from '../domain/queries.js';
 import { isTestFile } from '../infrastructure/test-filter.js';
+import type { BetterSqlite3Database, EngineMode } from '../types.js';
+
+type DatabaseConstructor = new (
+  path: string,
+  opts?: Record<string, unknown>,
+) => BetterSqlite3Database;
+const Db = Database as unknown as DatabaseConstructor;
 
 // ─── Git Helpers ────────────────────────────────────────────────────────
 
-function validateGitRef(repoRoot, ref) {
+function validateGitRef(repoRoot: string, ref: string): string | null {
   try {
     const sha = execFileSync('git', ['rev-parse', '--verify', ref], {
       cwd: repoRoot,
@@ -30,7 +29,7 @@ function validateGitRef(repoRoot, ref) {
   }
 }
 
-function getChangedFilesBetweenRefs(repoRoot, base, target) {
+function getChangedFilesBetweenRefs(repoRoot: string, base: string, target: string): string[] {
   const output = execFileSync('git', ['diff', '--name-only', `${base}..${target}`], {
     cwd: repoRoot,
     encoding: 'utf-8',
@@ -40,7 +39,7 @@ function getChangedFilesBetweenRefs(repoRoot, base, target) {
   return output.split('\n').filter(Boolean);
 }
 
-function createWorktree(repoRoot, ref, dir) {
+function createWorktree(repoRoot: string, ref: string, dir: string): void {
   execFileSync('git', ['worktree', 'add', '--detach', dir, ref], {
     cwd: repoRoot,
     encoding: 'utf-8',
@@ -48,7 +47,7 @@ function createWorktree(repoRoot, ref, dir) {
   });
 }
 
-function removeWorktree(repoRoot, dir) {
+function removeWorktree(repoRoot: string, dir: string): void {
   try {
     execFileSync('git', ['worktree', 'remove', '--force', dir], {
       cwd: repoRoot,
@@ -56,7 +55,6 @@ function removeWorktree(repoRoot, dir) {
       stdio: ['pipe', 'pipe', 'pipe'],
     });
   } catch {
-    // Fallback: remove directory and prune
     try {
       fs.rmSync(dir, { recursive: true, force: true });
     } catch {
@@ -76,20 +74,51 @@ function removeWorktree(repoRoot, dir) {
 
 // ─── Symbol Loading ─────────────────────────────────────────────────────
 
-function makeSymbolKey(kind, file, name) {
+interface SymbolInfo {
+  id: number;
+  name: string;
+  kind: string;
+  file: string;
+  line: number;
+  lineCount: number;
+  fanIn: number;
+  fanOut: number;
+}
+
+interface CallerInfo {
+  name: string;
+  kind: string;
+  file: string;
+  line: number;
+}
+
+interface ChangedSymbol {
+  name: string;
+  kind: string;
+  file: string;
+  base: { line: number; lineCount: number; fanIn: number; fanOut: number };
+  target: { line: number; lineCount: number; fanIn: number; fanOut: number };
+  changes: { lineCount: number; fanIn: number; fanOut: number };
+  impact?: CallerInfo[];
+}
+
+function makeSymbolKey(kind: string, file: string, name: string): string {
   return `${kind}::${file}::${name}`;
 }
 
-function loadSymbolsFromDb(dbPath, changedFiles, noTests) {
-  const db = new Database(dbPath, { readonly: true });
+function loadSymbolsFromDb(
+  dbPath: string,
+  changedFiles: string[],
+  noTests: boolean,
+): Map<string, SymbolInfo> {
+  const db = new Db(dbPath, { readonly: true });
   try {
-    const symbols = new Map();
+    const symbols = new Map<string, SymbolInfo>();
 
     if (changedFiles.length === 0) {
       return symbols;
     }
 
-    // Query nodes in changed files
     const placeholders = changedFiles.map(() => '?').join(', ');
     const rows = db
       .prepare(
@@ -99,9 +128,15 @@ function loadSymbolsFromDb(dbPath, changedFiles, noTests) {
            AND n.kind NOT IN ('file', 'directory')
          ORDER BY n.file, n.line`,
       )
-      .all(...changedFiles);
+      .all(...changedFiles) as Array<{
+      id: number;
+      name: string;
+      kind: string;
+      file: string;
+      line: number;
+      end_line: number | null;
+    }>;
 
-    // Compute fan_in and fan_out for each node
     const fanInStmt = db.prepare(
       `SELECT COUNT(*) AS cnt FROM edges WHERE target_id = ? AND kind = 'calls'`,
     );
@@ -113,8 +148,8 @@ function loadSymbolsFromDb(dbPath, changedFiles, noTests) {
       if (noTests && isTestFile(row.file)) continue;
 
       const lineCount = row.end_line ? row.end_line - row.line + 1 : 0;
-      const fanIn = fanInStmt.get(row.id).cnt;
-      const fanOut = fanOutStmt.get(row.id).cnt;
+      const fanIn = (fanInStmt.get(row.id) as { cnt: number }).cnt;
+      const fanOut = (fanOutStmt.get(row.id) as { cnt: number }).cnt;
       const key = makeSymbolKey(row.kind, row.file, row.name);
 
       symbols.set(key, {
@@ -137,19 +172,24 @@ function loadSymbolsFromDb(dbPath, changedFiles, noTests) {
 
 // ─── Caller BFS ─────────────────────────────────────────────────────────
 
-function loadCallersFromDb(dbPath, nodeIds, maxDepth, noTests) {
+function loadCallersFromDb(
+  dbPath: string,
+  nodeIds: number[],
+  maxDepth: number,
+  noTests: boolean,
+): CallerInfo[] {
   if (nodeIds.length === 0) return [];
 
-  const db = new Database(dbPath, { readonly: true });
+  const db = new Db(dbPath, { readonly: true });
   try {
-    const allCallers = new Set();
+    const allCallers = new Set<string>();
 
     for (const startId of nodeIds) {
-      const visited = new Set([startId]);
+      const visited = new Set<number>([startId]);
       let frontier = [startId];
 
       for (let d = 1; d <= maxDepth; d++) {
-        const nextFrontier = [];
+        const nextFrontier: number[] = [];
         for (const fid of frontier) {
           const callers = db
             .prepare(
@@ -157,7 +197,13 @@ function loadCallersFromDb(dbPath, nodeIds, maxDepth, noTests) {
                FROM edges e JOIN nodes n ON e.source_id = n.id
                WHERE e.target_id = ? AND e.kind = 'calls'`,
             )
-            .all(fid);
+            .all(fid) as Array<{
+            id: number;
+            name: string;
+            kind: string;
+            file: string;
+            line: number;
+          }>;
 
           for (const c of callers) {
             if (!visited.has(c.id) && (!noTests || !isTestFile(c.file))) {
@@ -174,7 +220,7 @@ function loadCallersFromDb(dbPath, nodeIds, maxDepth, noTests) {
       }
     }
 
-    return [...allCallers].map((s) => JSON.parse(s));
+    return [...allCallers].map((s) => JSON.parse(s) as CallerInfo);
   } finally {
     db.close();
   }
@@ -182,26 +228,26 @@ function loadCallersFromDb(dbPath, nodeIds, maxDepth, noTests) {
 
 // ─── Symbol Comparison ──────────────────────────────────────────────────
 
-function compareSymbols(baseSymbols, targetSymbols) {
-  const added = [];
-  const removed = [];
-  const changed = [];
+function compareSymbols(
+  baseSymbols: Map<string, SymbolInfo>,
+  targetSymbols: Map<string, SymbolInfo>,
+): { added: SymbolInfo[]; removed: SymbolInfo[]; changed: ChangedSymbol[] } {
+  const added: SymbolInfo[] = [];
+  const removed: SymbolInfo[] = [];
+  const changed: ChangedSymbol[] = [];
 
-  // Added: in target but not base
   for (const [key, sym] of targetSymbols) {
     if (!baseSymbols.has(key)) {
       added.push(sym);
     }
   }
 
-  // Removed: in base but not target
   for (const [key, sym] of baseSymbols) {
     if (!targetSymbols.has(key)) {
       removed.push(sym);
     }
   }
 
-  // Changed: in both but with different metrics
   for (const [key, baseSym] of baseSymbols) {
     const targetSym = targetSymbols.get(key);
     if (!targetSym) continue;
@@ -241,13 +287,46 @@ function compareSymbols(baseSymbols, targetSymbols) {
 
 // ─── Main Data Function ─────────────────────────────────────────────────
 
-export async function branchCompareData(baseRef, targetRef, opts = {}) {
+interface BranchCompareOpts {
+  repoRoot?: string;
+  depth?: number;
+  noTests?: boolean;
+  engine?: string;
+}
+
+interface BranchCompareSummary {
+  added: number;
+  removed: number;
+  changed: number;
+  totalImpacted: number;
+  filesAffected: number;
+}
+
+type SymbolWithoutId = Omit<SymbolInfo, 'id'> & { impact?: CallerInfo[] };
+
+interface BranchCompareResult {
+  error?: string;
+  baseRef?: string;
+  targetRef?: string;
+  baseSha?: string;
+  targetSha?: string;
+  changedFiles?: string[];
+  added?: SymbolWithoutId[];
+  removed?: SymbolWithoutId[];
+  changed?: ChangedSymbol[];
+  summary?: BranchCompareSummary;
+}
+
+export async function branchCompareData(
+  baseRef: string,
+  targetRef: string,
+  opts: BranchCompareOpts = {},
+): Promise<BranchCompareResult> {
   const repoRoot = opts.repoRoot || process.cwd();
   const maxDepth = opts.depth || 3;
   const noTests = opts.noTests || false;
-  const engine = opts.engine || 'wasm';
+  const engine = (opts.engine || 'wasm') as EngineMode;
 
-  // Check if this is a git repo
   try {
     execFileSync('git', ['rev-parse', '--git-dir'], {
       cwd: repoRoot,
@@ -258,14 +337,12 @@ export async function branchCompareData(baseRef, targetRef, opts = {}) {
     return { error: 'Not a git repository' };
   }
 
-  // Validate refs
   const baseSha = validateGitRef(repoRoot, baseRef);
   if (!baseSha) return { error: `Invalid git ref: "${baseRef}"` };
 
   const targetSha = validateGitRef(repoRoot, targetRef);
   if (!targetSha) return { error: `Invalid git ref: "${targetRef}"` };
 
-  // Get changed files
   const changedFiles = getChangedFilesBetweenRefs(repoRoot, baseSha, targetSha);
 
   if (changedFiles.length === 0) {
@@ -288,49 +365,41 @@ export async function branchCompareData(baseRef, targetRef, opts = {}) {
     };
   }
 
-  // Create temp dir for worktrees
   const tmpBase = fs.mkdtempSync(path.join(os.tmpdir(), 'codegraph-bc-'));
   const baseDir = path.join(tmpBase, 'base');
   const targetDir = path.join(tmpBase, 'target');
 
   try {
-    // Create worktrees
     createWorktree(repoRoot, baseSha, baseDir);
     createWorktree(repoRoot, targetSha, targetDir);
 
-    // Build graphs
     await buildGraph(baseDir, { engine, skipRegistry: true });
     await buildGraph(targetDir, { engine, skipRegistry: true });
 
     const baseDbPath = path.join(baseDir, '.codegraph', 'graph.db');
     const targetDbPath = path.join(targetDir, '.codegraph', 'graph.db');
 
-    // Normalize file paths for comparison (relative to worktree root)
     const normalizedFiles = changedFiles.map((f) => f.replace(/\\/g, '/'));
 
-    // Load symbols from both DBs
     const baseSymbols = loadSymbolsFromDb(baseDbPath, normalizedFiles, noTests);
     const targetSymbols = loadSymbolsFromDb(targetDbPath, normalizedFiles, noTests);
 
-    // Compare
     const { added, removed, changed } = compareSymbols(baseSymbols, targetSymbols);
 
-    // BFS for transitive callers of removed/changed symbols in base graph
     const removedIds = removed.map((s) => s.id).filter(Boolean);
     const changedIds = changed
       .map((s) => {
         const baseSym = baseSymbols.get(makeSymbolKey(s.kind, s.file, s.name));
         return baseSym?.id;
       })
-      .filter(Boolean);
+      .filter((id): id is number => Boolean(id));
 
     const removedImpact = loadCallersFromDb(baseDbPath, removedIds, maxDepth, noTests);
     const changedImpact = loadCallersFromDb(baseDbPath, changedIds, maxDepth, noTests);
 
-    // Attach impact to removed/changed
     for (const sym of removed) {
       const symCallers = loadCallersFromDb(baseDbPath, sym.id ? [sym.id] : [], maxDepth, noTests);
-      sym.impact = symCallers;
+      (sym as SymbolInfo & { impact?: CallerInfo[] }).impact = symCallers;
     }
     for (const sym of changed) {
       const baseSym = baseSymbols.get(makeSymbolKey(sym.kind, sym.file, sym.name));
@@ -343,17 +412,21 @@ export async function branchCompareData(baseRef, targetRef, opts = {}) {
       sym.impact = symCallers;
     }
 
-    // Summary
-    const allImpacted = new Set();
+    const allImpacted = new Set<string>();
     for (const c of removedImpact) allImpacted.add(`${c.file}:${c.name}`);
     for (const c of changedImpact) allImpacted.add(`${c.file}:${c.name}`);
 
-    const impactedFiles = new Set();
-    for (const key of allImpacted) impactedFiles.add(key.split(':')[0]);
+    const impactedFiles = new Set<string>();
+    for (const key of allImpacted) impactedFiles.add(key.split(':')[0]!);
 
-    // Remove id fields from output (internal only)
-    const cleanAdded = added.map(({ id, ...rest }) => rest);
-    const cleanRemoved = removed.map(({ id, ...rest }) => rest);
+    const cleanAdded = added.map(({ id: _id, ...rest }) => rest as SymbolWithoutId);
+    const cleanRemoved = removed.map(({ id: _id, ...rest }) => {
+      const result = rest as SymbolWithoutId;
+      if ((rest as SymbolInfo & { impact?: CallerInfo[] }).impact) {
+        result.impact = (rest as SymbolInfo & { impact?: CallerInfo[] }).impact;
+      }
+      return result;
+    });
 
     return {
       baseRef,
@@ -373,9 +446,8 @@ export async function branchCompareData(baseRef, targetRef, opts = {}) {
       },
     };
   } catch (err) {
-    return { error: err.message };
+    return { error: (err as Error).message };
   } finally {
-    // Clean up worktrees
     removeWorktree(repoRoot, baseDir);
     removeWorktree(repoRoot, targetDir);
     try {
@@ -388,62 +460,63 @@ export async function branchCompareData(baseRef, targetRef, opts = {}) {
 
 // ─── Mermaid Output ─────────────────────────────────────────────────────
 
-export function branchCompareMermaid(data) {
+export function branchCompareMermaid(data: BranchCompareResult): string {
   if (data.error) return data.error;
-  if (data.added.length === 0 && data.removed.length === 0 && data.changed.length === 0) {
+  if (
+    (data.added?.length ?? 0) === 0 &&
+    (data.removed?.length ?? 0) === 0 &&
+    (data.changed?.length ?? 0) === 0
+  ) {
     return 'flowchart TB\n    none["No structural differences detected"]';
   }
 
   const lines = ['flowchart TB'];
   let nodeCounter = 0;
-  const nodeIdMap = new Map();
+  const nodeIdMap = new Map<string, string>();
 
-  function nodeId(key) {
+  function nodeId(key: string): string {
     if (!nodeIdMap.has(key)) {
       nodeIdMap.set(key, `n${nodeCounter++}`);
     }
-    return nodeIdMap.get(key);
+    return nodeIdMap.get(key)!;
   }
 
-  // Added subgraph (green)
-  if (data.added.length > 0) {
+  if (data.added && data.added.length > 0) {
     lines.push('    subgraph sg_added["Added"]');
     for (const sym of data.added) {
       const key = `added::${sym.kind}::${sym.file}::${sym.name}`;
-      const nid = nodeId(key, sym.name);
+      const nid = nodeId(key);
       lines.push(`        ${nid}["[${kindIcon(sym.kind)}] ${sym.name}"]`);
     }
     lines.push('    end');
     lines.push('    style sg_added fill:#e8f5e9,stroke:#4caf50');
   }
 
-  // Removed subgraph (red)
-  if (data.removed.length > 0) {
+  if (data.removed && data.removed.length > 0) {
     lines.push('    subgraph sg_removed["Removed"]');
     for (const sym of data.removed) {
       const key = `removed::${sym.kind}::${sym.file}::${sym.name}`;
-      const nid = nodeId(key, sym.name);
+      const nid = nodeId(key);
       lines.push(`        ${nid}["[${kindIcon(sym.kind)}] ${sym.name}"]`);
     }
     lines.push('    end');
     lines.push('    style sg_removed fill:#ffebee,stroke:#f44336');
   }
 
-  // Changed subgraph (orange)
-  if (data.changed.length > 0) {
+  if (data.changed && data.changed.length > 0) {
     lines.push('    subgraph sg_changed["Changed"]');
     for (const sym of data.changed) {
       const key = `changed::${sym.kind}::${sym.file}::${sym.name}`;
-      const nid = nodeId(key, sym.name);
+      const nid = nodeId(key);
       lines.push(`        ${nid}["[${kindIcon(sym.kind)}] ${sym.name}"]`);
     }
     lines.push('    end');
     lines.push('    style sg_changed fill:#fff3e0,stroke:#ff9800');
   }
 
-  // Impacted callers subgraph (purple)
-  const allImpacted = new Map();
-  for (const sym of [...data.removed, ...data.changed]) {
+  const allImpacted = new Map<string, CallerInfo>();
+  const impactSources = [...(data.removed || []), ...(data.changed || [])];
+  for (const sym of impactSources) {
     if (!sym.impact) continue;
     for (const c of sym.impact) {
       const key = `impact::${c.kind}::${c.file}::${c.name}`;
@@ -454,17 +527,16 @@ export function branchCompareMermaid(data) {
   if (allImpacted.size > 0) {
     lines.push('    subgraph sg_impact["Impacted Callers"]');
     for (const [key, c] of allImpacted) {
-      const nid = nodeId(key, c.name);
+      const nid = nodeId(key);
       lines.push(`        ${nid}["[${kindIcon(c.kind)}] ${c.name}"]`);
     }
     lines.push('    end');
     lines.push('    style sg_impact fill:#f3e5f5,stroke:#9c27b0');
   }
 
-  // Edges: removed/changed -> impacted callers
-  for (const sym of [...data.removed, ...data.changed]) {
+  for (const sym of impactSources) {
     if (!sym.impact) continue;
-    const prefix = data.removed.includes(sym) ? 'removed' : 'changed';
+    const prefix = (data.removed || []).includes(sym as SymbolWithoutId) ? 'removed' : 'changed';
     const symKey = `${prefix}::${sym.kind}::${sym.file}::${sym.name}`;
     for (const c of sym.impact) {
       const callerKey = `impact::${c.kind}::${c.file}::${c.name}`;