@optave/codegraph 3.3.0 → 3.4.0

package/src/graph/builders/{dependency.js → dependency.ts}

@@ -11,17 +11,29 @@ import {
   Repository,
 } from '../../db/index.js';
 import { isTestFile } from '../../infrastructure/test-filter.js';
+import type {
+  BetterSqlite3Database,
+  CallableNodeRow,
+  CallEdgeRow,
+  FileNodeRow,
+  ImportGraphEdgeRow,
+} from '../../types.js';
 import { CodeGraph } from '../model.js';
 
+export interface DependencyGraphOptions {
+  fileLevel?: boolean;
+  noTests?: boolean;
+  minConfidence?: number;
+}
+
 /**
- * @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}
+ * Build a dependency graph from an open database or Repository instance.
+ * Supports both file-level (import edges) and function-level (call edges) graphs.
  */
-export function buildDependencyGraph(dbOrRepo, opts = {}) {
+export function buildDependencyGraph(
+  dbOrRepo: BetterSqlite3Database | Repository,
+  opts: DependencyGraphOptions = {},
+): CodeGraph {
   const fileLevel = opts.fileLevel !== false;
   const noTests = opts.noTests || false;
 
@@ -31,20 +43,23 @@ export function buildDependencyGraph(dbOrRepo, opts = {}) {
   return buildFunctionLevelGraph(dbOrRepo, noTests, opts.minConfidence);
 }
 
-function buildFileLevelGraph(dbOrRepo, noTests) {
+function buildFileLevelGraph(
+  dbOrRepo: BetterSqlite3Database | Repository,
+  noTests: boolean,
+): CodeGraph {
   const graph = new CodeGraph();
   const isRepo = dbOrRepo instanceof Repository;
 
-  let nodes = isRepo ? dbOrRepo.getFileNodesAll() : getFileNodesAll(dbOrRepo);
+  let nodes: FileNodeRow[] = isRepo ? dbOrRepo.getFileNodesAll() : getFileNodesAll(dbOrRepo);
   if (noTests) nodes = nodes.filter((n) => !isTestFile(n.file));
 
-  const nodeIds = new Set();
+  const nodeIds = new Set<number>();
   for (const n of nodes) {
     graph.addNode(String(n.id), { label: n.file, file: n.file, dbId: n.id });
     nodeIds.add(n.id);
   }
 
-  const edges = isRepo ? dbOrRepo.getImportEdges() : getImportEdges(dbOrRepo);
+  const edges: ImportGraphEdgeRow[] = 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);
@@ -58,14 +73,23 @@ function buildFileLevelGraph(dbOrRepo, noTests) {
   return graph;
 }
 
-function buildFunctionLevelGraph(dbOrRepo, noTests, minConfidence) {
+interface MinConfidenceEdgeRow {
+  source_id: number;
+  target_id: number;
+}
+
+function buildFunctionLevelGraph(
+  dbOrRepo: BetterSqlite3Database | Repository,
+  noTests: boolean,
+  minConfidence?: number,
+): CodeGraph {
   const graph = new CodeGraph();
   const isRepo = dbOrRepo instanceof Repository;
 
-  let nodes = isRepo ? dbOrRepo.getCallableNodes() : getCallableNodes(dbOrRepo);
+  let nodes: CallableNodeRow[] = isRepo ? dbOrRepo.getCallableNodes() : getCallableNodes(dbOrRepo);
   if (noTests) nodes = nodes.filter((n) => !isTestFile(n.file));
 
-  const nodeIds = new Set();
+  const nodeIds = new Set<number>();
   for (const n of nodes) {
     graph.addNode(String(n.id), {
       label: n.name,
@@ -76,7 +100,7 @@ function buildFunctionLevelGraph(dbOrRepo, noTests, minConfidence) {
     nodeIds.add(n.id);
   }
 
-  let edges;
+  let edges: CallEdgeRow[] | MinConfidenceEdgeRow[];
   if (minConfidence != null) {
     if (isRepo) {
       // Trade-off: Repository.getCallEdges() returns all call edges, so we
@@ -88,8 +112,10 @@ function buildFunctionLevelGraph(dbOrRepo, noTests, minConfidence) {
         .getCallEdges()
         .filter((e) => e.confidence != null && e.confidence >= minConfidence);
     } else {
-      edges = dbOrRepo
-        .prepare("SELECT source_id, target_id FROM edges WHERE kind = 'calls' AND confidence >= ?")
+      edges = (dbOrRepo as BetterSqlite3Database)
+        .prepare<MinConfidenceEdgeRow>(
+          "SELECT source_id, target_id FROM edges WHERE kind = 'calls' AND confidence >= ?",
+        )
         .all(minConfidence);
     }
   } else {

package/src/graph/builders/structure.ts

@@ -0,0 +1,58 @@
+/**
+ * Build a containment graph (directory -> file) from the SQLite database.
+ */
+
+import type { BetterSqlite3Database } from '../../types.js';
+import { CodeGraph } from '../model.js';
+
+interface DirRow {
+  id: number;
+  name: string;
+}
+
+interface FileRow {
+  id: number;
+  name: string;
+  file: string;
+}
+
+interface ContainsEdgeRow {
+  source_id: number;
+  target_id: number;
+}
+
+/**
+ * Build a directed graph with directory->file containment edges.
+ */
+export function buildStructureGraph(db: BetterSqlite3Database): CodeGraph {
+  const graph = new CodeGraph();
+
+  const dirs = db.prepare<DirRow>("SELECT id, name FROM nodes WHERE kind = 'directory'").all();
+
+  for (const d of dirs) {
+    graph.addNode(String(d.id), { label: d.name, kind: 'directory' });
+  }
+
+  const files = db.prepare<FileRow>("SELECT id, name, file FROM nodes WHERE kind = 'file'").all();
+
+  for (const f of files) {
+    graph.addNode(String(f.id), { label: f.name, kind: 'file', file: f.file });
+  }
+
+  const containsEdges = db
+    .prepare<ContainsEdgeRow>(`
+      SELECT e.source_id, e.target_id
+      FROM edges e
+      JOIN nodes n ON e.source_id = n.id
+      WHERE e.kind = 'contains' AND n.kind = 'directory'
+    `)
+    .all();
+
+  for (const e of containsEdges) {
+    graph.addEdge(String(e.source_id), String(e.target_id), {
+      kind: 'contains',
+    });
+  }
+
+  return graph;
+}

package/src/graph/builders/temporal.ts

@@ -0,0 +1,51 @@
+/**
+ * Build a co-change (temporal) graph weighted by Jaccard similarity.
+ */
+
+import type { BetterSqlite3Database } from '../../types.js';
+import { CodeGraph } from '../model.js';
+
+export interface TemporalGraphOptions {
+  minJaccard?: number;
+}
+
+interface TableCheckRow {
+  name: string;
+}
+
+interface CoChangeRow {
+  file_a: string;
+  file_b: string;
+  jaccard: number;
+}
+
+/**
+ * Build an undirected graph weighted by Jaccard similarity from the co_changes table.
+ */
+export function buildTemporalGraph(
+  db: BetterSqlite3Database,
+  opts: TemporalGraphOptions = {},
+): CodeGraph {
+  const minJaccard = opts.minJaccard ?? 0.0;
+  const graph = new CodeGraph({ directed: false });
+
+  // Check if co_changes table exists
+  const tableCheck = db
+    .prepare<TableCheckRow>(
+      "SELECT name FROM sqlite_master WHERE type='table' AND name='co_changes'",
+    )
+    .get();
+  if (!tableCheck) return graph;
+
+  const rows = db
+    .prepare<CoChangeRow>('SELECT file_a, file_b, jaccard FROM co_changes WHERE jaccard >= ?')
+    .all(minJaccard);
+
+  for (const r of rows) {
+    if (!graph.hasNode(r.file_a)) graph.addNode(r.file_a, { label: r.file_a });
+    if (!graph.hasNode(r.file_b)) graph.addNode(r.file_b, { label: r.file_b });
+    graph.addEdge(r.file_a, r.file_b, { jaccard: r.jaccard });
+  }
+
+  return graph;
+}

package/src/graph/classifiers/{risk.js → risk.ts}

@@ -2,11 +2,21 @@
  * Risk scoring — pure logic, no DB.
  */
 
+import type { Role } from '../../types.js';
+
+export interface RiskWeights {
+  fanIn: number;
+  complexity: number;
+  churn: number;
+  role: number;
+  mi: number;
+}
+
 // Weights sum to 1.0. Complexity gets the highest weight because cognitive load
 // is the strongest predictor of defect density. Fan-in and churn are next as
 // they reflect coupling and volatility. Role adds architectural context, and MI
 // (maintainability index) is a weaker composite signal, so it gets the least.
-export const DEFAULT_WEIGHTS = {
+export const DEFAULT_WEIGHTS: RiskWeights = {
   fanIn: 0.25,
   complexity: 0.3,
   churn: 0.2,
@@ -18,7 +28,7 @@ export const DEFAULT_WEIGHTS = {
 // dependency graph, utilities are widely imported, entry points are API
 // surfaces. Adapters bridge subsystems but are replaceable. Leaves, dead
 // code, and test-only symbols have minimal downstream impact.
-export const ROLE_WEIGHTS = {
+export const ROLE_WEIGHTS: Record<string, number> = {
   core: 1.0,
   utility: 0.9,
   entry: 0.8,
@@ -35,7 +45,7 @@ export const ROLE_WEIGHTS = {
 const DEFAULT_ROLE_WEIGHT = 0.5;
 
 /** Min-max normalize an array of numbers. All-equal → all zeros. */
-export function minMaxNormalize(values) {
+export function minMaxNormalize(values: number[]): number[] {
   const min = Math.min(...values);
   const max = Math.max(...values);
   if (max === min) return values.map(() => 0);
@@ -43,21 +53,41 @@ export function minMaxNormalize(values) {
   return values.map((v) => (v - min) / range);
 }
 
-function round4(n) {
+function round4(n: number): number {
   return Math.round(n * 10000) / 10000;
 }
 
+export interface RiskItem {
+  fan_in: number;
+  cognitive: number;
+  churn: number;
+  mi: number;
+  role: Role | string | null;
+}
+
+export interface RiskResult {
+  normFanIn: number;
+  normComplexity: number;
+  normChurn: number;
+  normMI: number;
+  roleWeight: number;
+  riskScore: number;
+}
+
+export interface ScoreRiskOpts {
+  roleWeights?: Record<string, number>;
+  defaultRoleWeight?: number;
+}
+
 /**
  * Score risk for a list of items.
- *
- * @param {{ fan_in: number, cognitive: number, churn: number, mi: number, role: string|null }[]} items
- * @param {object} [weights] - Override DEFAULT_WEIGHTS
- * @param {{ roleWeights?: object, defaultRoleWeight?: number }} [opts] - Optional role weight overrides
- * @returns {{ normFanIn: number, normComplexity: number, normChurn: number, normMI: number, roleWeight: number, riskScore: number }[]}
- *   Parallel array with risk metrics for each input item.
  */
-export function scoreRisk(items, weights = {}, opts = {}) {
-  const w = { ...DEFAULT_WEIGHTS, ...weights };
+export function scoreRisk(
+  items: RiskItem[],
+  weights: Partial<RiskWeights> = {},
+  opts: ScoreRiskOpts = {},
+): RiskResult[] {
+  const w: RiskWeights = { ...DEFAULT_WEIGHTS, ...weights };
   const rw = opts.roleWeights || ROLE_WEIGHTS;
   const drw = opts.defaultRoleWeight ?? DEFAULT_ROLE_WEIGHT;
 
@@ -73,19 +103,19 @@ export function scoreRisk(items, weights = {}, opts = {}) {
   const normMIs = normMIsRaw.map((v) => round4(1 - v));
 
   return items.map((r, i) => {
-    const roleWeight = rw[r.role] ?? drw;
+    const roleWeight = (r.role != null ? rw[r.role] : undefined) ?? drw;
+    const nfi = normFanIns[i] ?? 0;
+    const nci = normCognitives[i] ?? 0;
+    const nch = normChurns[i] ?? 0;
+    const nmi = normMIs[i] ?? 0;
     const riskScore =
-      w.fanIn * normFanIns[i] +
-      w.complexity * normCognitives[i] +
-      w.churn * normChurns[i] +
-      w.role * roleWeight +
-      w.mi * normMIs[i];
+      w.fanIn * nfi + w.complexity * nci + w.churn * nch + w.role * roleWeight + w.mi * nmi;
 
     return {
-      normFanIn: round4(normFanIns[i]),
-      normComplexity: round4(normCognitives[i]),
-      normChurn: round4(normChurns[i]),
-      normMI: round4(normMIs[i]),
+      normFanIn: round4(nfi),
+      normComplexity: round4(nci),
+      normChurn: round4(nch),
+      normMI: round4(nmi),
       roleWeight,
       riskScore: round4(riskScore),
     };

package/src/graph/classifiers/{roles.js → roles.ts}

@@ -10,7 +10,9 @@
  *   dead-unresolved — genuinely unreferenced callables (the real dead code)
  */
 
-export const FRAMEWORK_ENTRY_PREFIXES = ['route:', 'event:', 'command:'];
+import type { DeadSubRole, Role } from '../../types.js';
+
+export const FRAMEWORK_ENTRY_PREFIXES: readonly string[] = ['route:', 'event:', 'command:'];
 
 // ── Dead sub-classification helpers ────────────────────────────────
 
@@ -19,7 +21,7 @@ const LEAF_KINDS = new Set(['parameter', 'property', 'constant']);
 const FFI_EXTENSIONS = new Set(['.rs', '.c', '.cpp', '.h', '.go', '.java', '.cs']);
 
 /** Path patterns indicating framework-dispatched entry points. */
-const ENTRY_PATH_PATTERNS = [
+const ENTRY_PATH_PATTERNS: readonly RegExp[] = [
   /cli[/\\]commands[/\\]/,
   /mcp[/\\]/,
   /routes?[/\\]/,
@@ -27,13 +29,15 @@ const ENTRY_PATH_PATTERNS = [
   /middleware[/\\]/,
 ];
 
+export interface ClassifiableNode {
+  kind?: string;
+  file?: string;
+}
+
 /**
  * Refine a "dead" classification into a sub-category.
- *
- * @param {{ kind?: string, file?: string }} node
- * @returns {'dead-leaf'|'dead-entry'|'dead-ffi'|'dead-unresolved'}
  */
-function classifyDeadSubRole(node) {
+function classifyDeadSubRole(node: ClassifiableNode): DeadSubRole {
   // Leaf kinds are dead by definition — they can't have callers
   if (node.kind && LEAF_KINDS.has(node.kind)) return 'dead-leaf';
 
@@ -46,7 +50,7 @@ function classifyDeadSubRole(node) {
     if (dotIdx !== -1 && FFI_EXTENSIONS.has(node.file.slice(dotIdx))) return 'dead-ffi';
 
     // Framework-dispatched entry points (CLI commands, MCP tools, routes)
-    if (ENTRY_PATH_PATTERNS.some((p) => p.test(node.file))) return 'dead-entry';
+    if (ENTRY_PATH_PATTERNS.some((p) => p.test(node.file!))) return 'dead-entry';
   }
 
   return 'dead-unresolved';
@@ -54,19 +58,28 @@ function classifyDeadSubRole(node) {
 
 // ── Helpers ────────────────────────────────────────────────────────
 
-function median(sorted) {
+function median(sorted: number[]): number {
   if (sorted.length === 0) return 0;
   const mid = Math.floor(sorted.length / 2);
-  return sorted.length % 2 === 0 ? (sorted[mid - 1] + sorted[mid]) / 2 : sorted[mid];
+  return sorted.length % 2 === 0 ? (sorted[mid - 1]! + sorted[mid]!) / 2 : sorted[mid]!;
+}
+
+export interface RoleClassificationNode {
+  id: string;
+  name: string;
+  kind?: string;
+  file?: string;
+  fanIn: number;
+  fanOut: number;
+  isExported: boolean;
+  testOnlyFanIn?: number;
+  productionFanIn?: number;
 }
 
 /**
  * Classify nodes into architectural roles based on fan-in/fan-out metrics.
- *
- * @param {{ id: string, name: string, kind?: string, file?: string, fanIn: number, fanOut: number, isExported: boolean, testOnlyFanIn?: number }[]} nodes
- * @returns {Map<string, string>} nodeId → role
  */
-export function classifyRoles(nodes) {
+export function classifyRoles(nodes: RoleClassificationNode[]): Map<string, Role> {
   if (nodes.length === 0) return new Map();
 
   const nonZeroFanIn = nodes
@@ -81,19 +94,22 @@ export function classifyRoles(nodes) {
   const medFanIn = median(nonZeroFanIn);
   const medFanOut = median(nonZeroFanOut);
 
-  const result = new Map();
+  const result = new Map<string, Role>();
 
   for (const node of nodes) {
     const highIn = node.fanIn >= medFanIn && node.fanIn > 0;
     const highOut = node.fanOut >= medFanOut && node.fanOut > 0;
     const hasProdFanIn = typeof node.productionFanIn === 'number';
 
-    let role;
+    let role: Role;
     const isFrameworkEntry = FRAMEWORK_ENTRY_PREFIXES.some((p) => node.name.startsWith(p));
     if (isFrameworkEntry) {
       role = 'entry';
     } else if (node.fanIn === 0 && !node.isExported) {
-      role = node.testOnlyFanIn > 0 ? 'test-only' : classifyDeadSubRole(node);
+      role =
+        node.testOnlyFanIn != null && node.testOnlyFanIn > 0
+          ? 'test-only'
+          : classifyDeadSubRole(node);
     } else if (node.fanIn === 0 && node.isExported) {
       role = 'entry';
     } else if (hasProdFanIn && node.fanIn > 0 && node.productionFanIn === 0) {