@optave/codegraph 3.3.1 → 3.4.0

package/src/features/{export.js → export.ts}

@@ -1,4 +1,5 @@
 import path from 'node:path';
+import type BetterSqlite3 from 'better-sqlite3';
 import { isTestFile } from '../infrastructure/test-filter.js';
 import {
   renderFileLevelDOT,
@@ -11,27 +12,80 @@ import {
   renderFunctionLevelNeo4jCSV,
 } from '../presentation/export.js';
 import { paginateResult } from '../shared/paginate.js';
+import type { ExportNeo4jCSVResult, ExportOpts } from '../types.js';
 
 const DEFAULT_MIN_CONFIDENCE = 0.5;
 
+// ─── Internal interfaces ────────────────────────────────────────────
+
+interface FileLevelEdge {
+  source: string;
+  target: string;
+  edge_kind?: string;
+  confidence?: number;
+}
+
+interface FunctionLevelEdge {
+  source_id: number;
+  source_name: string;
+  source_kind: string;
+  source_file: string;
+  source_line: number;
+  source_role: string | null;
+  target_id: number;
+  target_name: string;
+  target_kind: string;
+  target_file: string;
+  target_line: number;
+  target_role: string | null;
+  edge_kind: string;
+  confidence: number;
+}
+
+interface DirectoryGroup {
+  name: string;
+  files: Array<{ path: string; basename: string }>;
+  cohesion: number | null;
+}
+
+interface MermaidDirectoryGroup {
+  name: string;
+  files: string[];
+}
+
+interface FileLevelLoadOpts {
+  noTests: boolean;
+  minConfidence?: number;
+  limit?: number;
+  includeKind?: boolean;
+  includeConfidence?: boolean;
+}
+
+interface FunctionLevelLoadOpts {
+  noTests: boolean;
+  minConfidence?: number;
+  limit?: number;
+}
+
 // ─── Shared data loaders ─────────────────────────────────────────────
 
 /**
  * Load file-level edges from DB with filtering.
- * @param {object} db
- * @param {object} opts
- * @param {boolean} [opts.includeKind] - Include edge_kind in SELECT DISTINCT
- * @param {boolean} [opts.includeConfidence] - Include confidence (adds a column to DISTINCT — use only when needed)
- * @returns {{ edges: Array, totalEdges: number }}
  */
 function loadFileLevelEdges(
-  db,
-  { noTests, minConfidence, limit, includeKind = false, includeConfidence = false },
-) {
+  db: BetterSqlite3.Database,
+  {
+    noTests,
+    minConfidence,
+    limit,
+    includeKind = false,
+    includeConfidence = false,
+  }: FileLevelLoadOpts,
+): { edges: FileLevelEdge[]; totalEdges: number } {
   const minConf = minConfidence ?? DEFAULT_MIN_CONFIDENCE;
   const kindClause = includeKind ? ', e.kind AS edge_kind' : '';
   const confidenceClause = includeConfidence ? ', e.confidence' : '';
-  let edges = db
+  let edges: FileLevelEdge[] = db
     .prepare(
       `
       SELECT DISTINCT n1.file AS source, n2.file AS target${kindClause}${confidenceClause}
@@ -42,7 +96,7 @@ function loadFileLevelEdges(
         AND e.confidence >= ?
     `,
     )
-    .all(minConf);
+    .all(minConf) as FileLevelEdge[];
   if (noTests) edges = edges.filter((e) => !isTestFile(e.source) && !isTestFile(e.target));
   const totalEdges = edges.length;
   if (limit && edges.length > limit) edges = edges.slice(0, limit);
@@ -52,11 +106,13 @@ function loadFileLevelEdges(
 /**
  * Load function-level edges from DB with filtering.
  * Returns the maximal field set needed by any serializer.
- * @returns {{ edges: Array, totalEdges: number }}
  */
-function loadFunctionLevelEdges(db, { noTests, minConfidence, limit }) {
+function loadFunctionLevelEdges(
+  db: BetterSqlite3.Database,
+  { noTests, minConfidence, limit }: FunctionLevelLoadOpts,
+): { edges: FunctionLevelEdge[]; totalEdges: number } {
   const minConf = minConfidence ?? DEFAULT_MIN_CONFIDENCE;
-  let edges = db
+  let edges: FunctionLevelEdge[] = db
     .prepare(
       `
       SELECT n1.id AS source_id, n1.name AS source_name, n1.kind AS source_kind,
@@ -73,7 +129,7 @@ function loadFunctionLevelEdges(db, { noTests, minConfidence, limit }) {
         AND e.confidence >= ?
     `,
     )
-    .all(minConf);
+    .all(minConf) as FunctionLevelEdge[];
   if (noTests)
     edges = edges.filter((e) => !isTestFile(e.source_file) && !isTestFile(e.target_file));
   const totalEdges = edges.length;
@@ -84,13 +140,13 @@ function loadFunctionLevelEdges(db, { noTests, minConfidence, limit }) {
 /**
  * Load directory groupings for file-level graphs.
  * Uses DB directory nodes if available, falls back to path.dirname().
- * @returns {Array<{ name: string, files: Array<{ path: string, basename: string }>, cohesion: number|null }>}
  */
-function loadDirectoryGroups(db, allFiles) {
+function loadDirectoryGroups(db: BetterSqlite3.Database, allFiles: Set<string>): DirectoryGroup[] {
   const hasDirectoryNodes =
-    db.prepare("SELECT COUNT(*) as c FROM nodes WHERE kind = 'directory'").get().c > 0;
+    (db.prepare("SELECT COUNT(*) as c FROM nodes WHERE kind = 'directory'").get() as { c: number })
+      .c > 0;
 
-  const dirs = new Map();
+  const dirs = new Map<string, { files: string[]; cohesion: number | null }>();
 
   if (hasDirectoryNodes) {
     const dbDirs = db
@@ -100,16 +156,18 @@ function loadDirectoryGroups(db, allFiles) {
         LEFT JOIN node_metrics nm ON n.id = nm.node_id
         WHERE n.kind = 'directory'
       `)
-      .all();
+      .all() as Array<{ id: number; name: string; cohesion: number | null }>;
 
     for (const d of dbDirs) {
-      const containedFiles = db
-        .prepare(`
+      const containedFiles = (
+        db
+          .prepare(`
           SELECT n.name FROM edges e
           JOIN nodes n ON e.target_id = n.id
           WHERE e.source_id = ? AND e.kind = 'contains' AND n.kind = 'file'
         `)
-        .all(d.id)
+          .all(d.id) as Array<{ name: string }>
+      )
         .map((r) => r.name)
         .filter((f) => allFiles.has(f));
 
@@ -121,7 +179,7 @@ function loadDirectoryGroups(db, allFiles) {
     for (const file of allFiles) {
       const dir = path.dirname(file) || '.';
       if (!dirs.has(dir)) dirs.set(dir, { files: [], cohesion: null });
-      dirs.get(dir).files.push(file);
+      dirs.get(dir)?.files.push(file);
     }
   }
 
@@ -137,22 +195,30 @@ function loadDirectoryGroups(db, allFiles) {
 /**
  * Load directory groupings for Mermaid file-level graphs (simplified — no cohesion, string arrays).
  */
-function loadMermaidDirectoryGroups(db, allFiles) {
+function loadMermaidDirectoryGroups(
+  db: BetterSqlite3.Database,
+  allFiles: Set<string>,
+): MermaidDirectoryGroup[] {
   const hasDirectoryNodes =
-    db.prepare("SELECT COUNT(*) as c FROM nodes WHERE kind = 'directory'").get().c > 0;
+    (db.prepare("SELECT COUNT(*) as c FROM nodes WHERE kind = 'directory'").get() as { c: number })
+      .c > 0;
 
-  const dirs = new Map();
+  const dirs = new Map<string, string[]>();
 
   if (hasDirectoryNodes) {
-    const dbDirs = db.prepare("SELECT id, name FROM nodes WHERE kind = 'directory'").all();
+    const dbDirs = db
+      .prepare("SELECT id, name FROM nodes WHERE kind = 'directory'")
+      .all() as Array<{ id: number; name: string }>;
     for (const d of dbDirs) {
-      const containedFiles = db
-        .prepare(`
+      const containedFiles = (
+        db
+          .prepare(`
           SELECT n.name FROM edges e
           JOIN nodes n ON e.target_id = n.id
           WHERE e.source_id = ? AND e.kind = 'contains' AND n.kind = 'file'
         `)
-        .all(d.id)
+          .all(d.id) as Array<{ name: string }>
+      )
         .map((r) => r.name)
         .filter((f) => allFiles.has(f));
       if (containedFiles.length > 0) dirs.set(d.name, containedFiles);
@@ -161,7 +227,7 @@ function loadMermaidDirectoryGroups(db, allFiles) {
     for (const file of allFiles) {
       const dir = path.dirname(file) || '.';
       if (!dirs.has(dir)) dirs.set(dir, []);
-      dirs.get(dir).push(file);
+      dirs.get(dir)?.push(file);
     }
   }
 
@@ -172,11 +238,13 @@ function loadMermaidDirectoryGroups(db, allFiles) {
 
 /**
  * Load node roles for Mermaid function-level styling.
- * @returns {Map<string, string>} "file::name" → role
  */
-function loadNodeRoles(db, edges) {
-  const roles = new Map();
-  const seen = new Set();
+function loadNodeRoles(
+  db: BetterSqlite3.Database,
+  edges: FunctionLevelEdge[],
+): Map<string, string> {
+  const roles = new Map<string, string>();
+  const seen = new Set<string>();
   for (const e of edges) {
     for (const [file, name] of [
       [e.source_file, e.source_name],
@@ -187,7 +255,7 @@ function loadNodeRoles(db, edges) {
       seen.add(key);
       const row = db
         .prepare('SELECT role FROM nodes WHERE file = ? AND name = ? AND role IS NOT NULL LIMIT 1')
-        .get(file, name);
+        .get(file, name) as { role: string } | undefined;
       if (row?.role) roles.set(key, row.role);
     }
   }
@@ -199,7 +267,7 @@ function loadNodeRoles(db, edges) {
 /**
  * Export the dependency graph in DOT (Graphviz) format.
  */
-export function exportDOT(db, opts = {}) {
+export function exportDOT(db: BetterSqlite3.Database, opts: ExportOpts = {}): string {
   const fileLevel = opts.fileLevel !== false;
   const noTests = opts.noTests || false;
   const minConfidence = opts.minConfidence;
@@ -207,7 +275,7 @@ export function exportDOT(db, opts = {}) {
 
   if (fileLevel) {
     const { edges, totalEdges } = loadFileLevelEdges(db, { noTests, minConfidence, limit });
-    const allFiles = new Set();
+    const allFiles = new Set<string>();
     for (const { source, target } of edges) {
       allFiles.add(source);
       allFiles.add(target);
@@ -223,7 +291,10 @@ export function exportDOT(db, opts = {}) {
 /**
  * Export the dependency graph in Mermaid format.
  */
-export function exportMermaid(db, opts = {}) {
+export function exportMermaid(
+  db: BetterSqlite3.Database,
+  opts: ExportOpts & { direction?: string } = {},
+): string {
   const fileLevel = opts.fileLevel !== false;
   const noTests = opts.noTests || false;
   const minConfidence = opts.minConfidence;
@@ -237,13 +308,19 @@ export function exportMermaid(db, opts = {}) {
       limit,
       includeKind: true,
     });
-    const allFiles = new Set();
+    const allFiles = new Set<string>();
     for (const { source, target } of edges) {
       allFiles.add(source);
       allFiles.add(target);
     }
     const dirs = loadMermaidDirectoryGroups(db, allFiles);
-    return renderFileLevelMermaid({ direction, dirs, edges, totalEdges, limit });
+    return renderFileLevelMermaid({
+      direction,
+      dirs,
+      edges: edges as Array<{ source: string; target: string; edge_kind: string }>,
+      totalEdges,
+      limit,
+    });
   }
 
   const { edges, totalEdges } = loadFunctionLevelEdges(db, { noTests, minConfidence, limit });
@@ -254,7 +331,10 @@ export function exportMermaid(db, opts = {}) {
 /**
  * Export as JSON adjacency list.
  */
-export function exportJSON(db, opts = {}) {
+export function exportJSON(
+  db: BetterSqlite3.Database,
+  opts: ExportOpts = {},
+): { nodes: unknown[]; edges: unknown[] } {
   const noTests = opts.noTests || false;
   const minConf = opts.minConfidence ?? DEFAULT_MIN_CONFIDENCE;
 
@@ -262,7 +342,7 @@ export function exportJSON(db, opts = {}) {
     .prepare(`
     SELECT id, name, kind, file, line FROM nodes WHERE kind = 'file'
   `)
-    .all();
+    .all() as Array<{ id: number; name: string; kind: string; file: string; line: number }>;
   if (noTests) nodes = nodes.filter((n) => !isTestFile(n.file));
 
   let edges = db
@@ -273,17 +353,20 @@ export function exportJSON(db, opts = {}) {
     JOIN nodes n2 ON e.target_id = n2.id
     WHERE n1.file != n2.file AND e.confidence >= ?
   `)
-    .all(minConf);
+    .all(minConf) as Array<{ source: string; target: string; kind: string; confidence: number }>;
   if (noTests) edges = edges.filter((e) => !isTestFile(e.source) && !isTestFile(e.target));
 
   const base = { nodes, edges };
-  return paginateResult(base, 'edges', { limit: opts.limit, offset: opts.offset });
+  return paginateResult(base, 'edges', { limit: opts.limit, offset: opts.offset }) as {
+    nodes: unknown[];
+    edges: unknown[];
+  };
 }
 
 /**
  * Export the dependency graph in GraphML (XML) format.
  */
-export function exportGraphML(db, opts = {}) {
+export function exportGraphML(db: BetterSqlite3.Database, opts: ExportOpts = {}): string {
   const fileLevel = opts.fileLevel !== false;
   const noTests = opts.noTests || false;
   const minConfidence = opts.minConfidence;
@@ -301,7 +384,10 @@ export function exportGraphML(db, opts = {}) {
 /**
  * Export the dependency graph in TinkerPop GraphSON v3 format.
  */
-export function exportGraphSON(db, opts = {}) {
+export function exportGraphSON(
+  db: BetterSqlite3.Database,
+  opts: ExportOpts = {},
+): { vertices: unknown[]; edges: unknown[] } {
   const noTests = opts.noTests || false;
   const minConf = opts.minConfidence ?? DEFAULT_MIN_CONFIDENCE;
 
@@ -310,7 +396,14 @@ export function exportGraphSON(db, opts = {}) {
     SELECT id, name, kind, file, line, role FROM nodes
     WHERE kind IN ('function', 'method', 'class', 'interface', 'type', 'struct', 'enum', 'trait', 'record', 'module', 'constant', 'file')
   `)
-    .all();
+    .all() as Array<{
+    id: number;
+    name: string;
+    kind: string;
+    file: string;
+    line: number | null;
+    role: string | null;
+  }>;
   if (noTests) nodes = nodes.filter((n) => !isTestFile(n.file));
 
   let edges = db
@@ -321,7 +414,13 @@ export function exportGraphSON(db, opts = {}) {
     JOIN nodes n2 ON e.target_id = n2.id
     WHERE e.confidence >= ?
   `)
-    .all(minConf);
+    .all(minConf) as Array<{
+    id: number;
+    outV: number;
+    inV: number;
+    kind: string;
+    confidence: number;
+  }>;
   if (noTests) {
     const nodeIds = new Set(nodes.map((n) => n.id));
     edges = edges.filter((e) => nodeIds.has(e.outV) && nodeIds.has(e.inV));
@@ -349,14 +448,20 @@ export function exportGraphSON(db, opts = {}) {
   }));
 
   const base = { vertices, edges: gEdges };
-  return paginateResult(base, 'edges', { limit: opts.limit, offset: opts.offset });
+  return paginateResult(base, 'edges', { limit: opts.limit, offset: opts.offset }) as {
+    vertices: unknown[];
+    edges: unknown[];
+  };
 }
 
 /**
  * Export the dependency graph as Neo4j bulk-import CSV files.
  * Returns { nodes: string, relationships: string }.
  */
-export function exportNeo4jCSV(db, opts = {}) {
+export function exportNeo4jCSV(
+  db: BetterSqlite3.Database,
+  opts: ExportOpts = {},
+): ExportNeo4jCSVResult {
   const fileLevel = opts.fileLevel !== false;
   const noTests = opts.noTests || false;
   const minConfidence = opts.minConfidence;
@@ -370,7 +475,14 @@ export function exportNeo4jCSV(db, opts = {}) {
       includeKind: true,
       includeConfidence: true,
     });
-    return renderFileLevelNeo4jCSV({ edges });
+    return renderFileLevelNeo4jCSV({
+      edges: edges as Array<{
+        source: string;
+        target: string;
+        edge_kind: string;
+        confidence: number;
+      }>,
+    });
   }
 
   const { edges } = loadFunctionLevelEdges(db, { noTests, minConfidence, limit });

package/src/features/{flow.js → flow.ts}

@@ -9,32 +9,30 @@ import { openReadonlyOrFail } from '../db/index.js';
 import { CORE_SYMBOL_KINDS, findMatchingNodes } from '../domain/queries.js';
 import { isTestFile } from '../infrastructure/test-filter.js';
 import { paginateResult } from '../shared/paginate.js';
+import type { BetterSqlite3Database } from '../types.js';
 import { FRAMEWORK_ENTRY_PREFIXES } from './structure.js';
 
-/**
- * Determine the entry point type from a node name based on framework prefixes.
- * @param {string} name
- * @returns {'route'|'event'|'command'|'exported'|null}
- */
-export function entryPointType(name) {
+export function entryPointType(name: string): 'route' | 'event' | 'command' | 'exported' | null {
   for (const prefix of FRAMEWORK_ENTRY_PREFIXES) {
     if (name.startsWith(prefix)) {
-      return prefix.slice(0, -1); // 'route:', 'event:', 'command:' → 'route', 'event', 'command'
+      return prefix.slice(0, -1) as 'route' | 'event' | 'command'; // 'route:', 'event:', 'command:' → 'route', 'event', 'command'
     }
   }
   return null;
 }
 
-/**
- * Query all entry points from the graph, grouped by type.
- * Entry points are nodes with framework prefixes or role = 'entry'.
- *
- * @param {string} [dbPath]
- * @param {object} [opts]
- * @param {boolean} [opts.noTests]
- * @returns {{ entries: object[], byType: object, count: number }}
- */
-export function listEntryPointsData(dbPath, opts = {}) {
+interface EntryPointRow {
+  name: string;
+  kind: string;
+  file: string;
+  line: number;
+  role: string | null;
+}
+
+export function listEntryPointsData(
+  dbPath?: string,
+  opts: { noTests?: boolean; limit?: number; offset?: number } = {},
+): Record<string, unknown> {
   const db = openReadonlyOrFail(dbPath);
   try {
     const noTests = opts.noTests || false;
@@ -44,7 +42,7 @@ export function listEntryPointsData(dbPath, opts = {}) {
     const prefixParams = FRAMEWORK_ENTRY_PREFIXES.map((p) => `${p}%`);
 
     let rows = db
-      .prepare(
+      .prepare<EntryPointRow>(
         `SELECT n.name, n.kind, n.file, n.line, n.role
          FROM nodes n
          WHERE (
@@ -67,7 +65,7 @@ export function listEntryPointsData(dbPath, opts = {}) {
       type: entryPointType(r.name) || (r.role === 'entry' ? 'exported' : null),
     }));
 
-    const byType = {};
+    const byType: Record<string, typeof entries> = {};
     for (const e of entries) {
       const t = e.type || 'other';
       if (!byType[t]) byType[t] = [];
@@ -81,24 +79,44 @@ export function listEntryPointsData(dbPath, opts = {}) {
   }
 }
 
-/**
- * Forward BFS from a matched node through callees to leaves.
- *
- * @param {string} name - Node name to trace from (supports partial/prefix-stripped matching)
- * @param {string} [dbPath]
- * @param {object} [opts]
- * @param {number} [opts.depth=10]
- * @param {boolean} [opts.noTests]
- * @param {string} [opts.file]
- * @param {string} [opts.kind]
- * @returns {{ entry: object|null, depth: number, steps: object[], leaves: object[], cycles: object[], totalReached: number, truncated: boolean }}
- */
-export function flowData(name, dbPath, opts = {}) {
+interface CalleeRow {
+  id: number;
+  name: string;
+  kind: string;
+  file: string;
+  line: number;
+  role: string | null;
+}
+
+interface NodeInfo {
+  name: string;
+  kind: string;
+  file: string;
+  line: number;
+  role?: string | null;
+  type?: string;
+}
+
+export function flowData(
+  name: string,
+  dbPath?: string,
+  opts: {
+    depth?: number;
+    noTests?: boolean;
+    file?: string;
+    kind?: string;
+    limit?: number;
+    offset?: number;
+  } = {},
+): Record<string, unknown> {
   const db = openReadonlyOrFail(dbPath);
   try {
     const maxDepth = opts.depth || 10;
     const noTests = opts.noTests || false;
-    const flowOpts = { ...opts, kinds: opts.kind ? [opts.kind] : CORE_SYMBOL_KINDS };
+    const flowOpts = {
+      ...opts,
+      kinds: opts.kind ? [opts.kind] : (CORE_SYMBOL_KINDS as unknown as string[]),
+    };
 
     // Phase 1: Direct LIKE match on full name (use all 10 core symbol kinds,
     // not just FUNCTION_KINDS, so flow can trace from interfaces/types/structs/etc.)
@@ -125,7 +143,7 @@ export function flowData(name, dbPath, opts = {}) {
     }
 
     const epType = entryPointType(matchNode.name);
-    const entry = {
+    const entry: NodeInfo = {
       name: matchNode.name,
       kind: matchNode.kind,
       file: matchNode.file,
@@ -135,24 +153,24 @@ export function flowData(name, dbPath, opts = {}) {
     };
 
     // Forward BFS through callees
-    const visited = new Set([matchNode.id]);
+    const visited = new Set<number>([matchNode.id]);
     let frontier = [matchNode.id];
-    const steps = [];
-    const cycles = [];
+    const steps: Array<{ depth: number; nodes: NodeInfo[] }> = [];
+    const cycles: Array<{ from: string; to: string; depth: number }> = [];
     let truncated = false;
 
     // Track which nodes are at each depth and their depth for leaf detection
-    const nodeDepths = new Map();
-    const idToNode = new Map();
+    const nodeDepths = new Map<number, number>();
+    const idToNode = new Map<number, NodeInfo>();
     idToNode.set(matchNode.id, entry);
 
     for (let d = 1; d <= maxDepth; d++) {
-      const nextFrontier = [];
-      const levelNodes = [];
+      const nextFrontier: number[] = [];
+      const levelNodes: NodeInfo[] = [];
 
       for (const fid of frontier) {
         const callees = db
-          .prepare(
+          .prepare<CalleeRow>(
             `SELECT DISTINCT n.id, n.name, n.kind, n.file, n.line, n.role
              FROM edges e JOIN nodes n ON e.target_id = n.id
              WHERE e.source_id = ? AND e.kind = 'calls'`,
@@ -173,7 +191,7 @@ export function flowData(name, dbPath, opts = {}) {
 
           visited.add(c.id);
           nextFrontier.push(c.id);
-          const nodeInfo = { name: c.name, kind: c.kind, file: c.file, line: c.line };
+          const nodeInfo: NodeInfo = { name: c.name, kind: c.kind, file: c.file, line: c.line };
           levelNodes.push(nodeInfo);
           nodeDepths.set(c.id, d);
           idToNode.set(c.id, nodeInfo);
@@ -194,10 +212,10 @@ export function flowData(name, dbPath, opts = {}) {
 
     // Identify leaves: visited nodes that have no outgoing 'calls' edges to other visited nodes
     // (or no outgoing calls at all)
-    const leaves = [];
+    const leaves: Array<NodeInfo & { depth: number }> = [];
     for (const [id, depth] of nodeDepths) {
       const outgoing = db
-        .prepare(
+        .prepare<{ id: number }>(
           `SELECT DISTINCT n.id
            FROM edges e JOIN nodes n ON e.target_id = n.id
            WHERE e.source_id = ? AND e.kind = 'calls'`,