@optave/codegraph 3.3.1 → 3.4.0

package/src/db/repository/{nodes.js → nodes.ts}

@@ -1,5 +1,17 @@
 import { ConfigError } from '../../shared/errors.js';
 import { EVERY_SYMBOL_KIND, VALID_ROLES } from '../../shared/kinds.js';
+import type {
+  BetterSqlite3Database,
+  ChildNodeRow,
+  ListFunctionOpts,
+  NodeIdRow,
+  NodeRow,
+  NodeRowWithFanIn,
+  QueryOpts,
+  StmtCache,
+  TriageNodeRow,
+  TriageQueryOpts,
+} from '../../types.js';
 import { buildFileConditionSQL, NodeQuery } from '../query-builder.js';
 import { cachedStmt } from './cached-stmt.js';
 
@@ -7,14 +19,12 @@ import { cachedStmt } from './cached-stmt.js';
 
 /**
  * Find nodes matching a name pattern, with fan-in count.
- * @param {object} db
- * @param {string} namePattern - LIKE pattern (already wrapped with %)
- * @param {object} [opts]
- * @param {string[]} [opts.kinds]
- * @param {string} [opts.file]
- * @returns {object[]}
  */
-export function findNodesWithFanIn(db, namePattern, opts = {}) {
+export function findNodesWithFanIn(
+  db: BetterSqlite3Database,
+  namePattern: string,
+  opts: QueryOpts = {},
+): NodeRowWithFanIn[] {
   const q = new NodeQuery()
     .select('n.*, COALESCE(fi.cnt, 0) AS fan_in')
     .withFanIn()
@@ -32,12 +42,12 @@ export function findNodesWithFanIn(db, namePattern, opts = {}) {
 
 /**
  * Fetch nodes for triage scoring: fan-in + complexity + churn.
- * @param {object} db
- * @param {object} [opts]
- * @returns {object[]}
  */
-export function findNodesForTriage(db, opts = {}) {
-  if (opts.kind && !EVERY_SYMBOL_KIND.includes(opts.kind)) {
+export function findNodesForTriage(
+  db: BetterSqlite3Database,
+  opts: TriageQueryOpts = {},
+): TriageNodeRow[] {
+  if (opts.kind && !(EVERY_SYMBOL_KIND as readonly string[]).includes(opts.kind)) {
     throw new ConfigError(
       `Invalid kind: ${opts.kind} (expected one of ${EVERY_SYMBOL_KIND.join(', ')})`,
     );
@@ -49,7 +59,8 @@ export function findNodesForTriage(db, opts = {}) {
   const kindsToUse = opts.kind ? [opts.kind] : ['function', 'method', 'class'];
   const q = new NodeQuery()
     .select(
-      `n.id, n.name, n.kind, n.file, n.line, n.end_line, n.role,
+      `n.id, n.name, n.kind, n.file, n.line, n.end_line,
+              n.parent_id, n.exported, n.qualified_name, n.scope, n.visibility, n.role,
               COALESCE(fi.cnt, 0) AS fan_in,
               COALESCE(fc.cognitive, 0) AS cognitive,
               COALESCE(fc.maintainability_index, 0) AS mi,
@@ -71,10 +82,8 @@ export function findNodesForTriage(db, opts = {}) {
 
 /**
  * Shared query builder for function/method/class node listing.
- * @param {object} [opts]
- * @returns {NodeQuery}
  */
-function _functionNodeQuery(opts = {}) {
+function _functionNodeQuery(opts: ListFunctionOpts = {}): InstanceType<typeof NodeQuery> {
   return new NodeQuery()
     .select('name, kind, file, line, end_line, role')
     .kinds(['function', 'method', 'class'])
@@ -86,84 +95,74 @@ function _functionNodeQuery(opts = {}) {
 
 /**
  * List function/method/class nodes with basic info.
- * @param {object} db
- * @param {object} [opts]
- * @returns {object[]}
  */
-export function listFunctionNodes(db, opts = {}) {
+export function listFunctionNodes(
+  db: BetterSqlite3Database,
+  opts: ListFunctionOpts = {},
+): NodeRow[] {
   return _functionNodeQuery(opts).all(db);
 }
 
 /**
  * Iterator version of listFunctionNodes for memory efficiency.
- * @param {object} db
- * @param {object} [opts]
- * @returns {IterableIterator}
  */
-export function iterateFunctionNodes(db, opts = {}) {
+export function iterateFunctionNodes(
+  db: BetterSqlite3Database,
+  opts: ListFunctionOpts = {},
+): IterableIterator<NodeRow> {
   return _functionNodeQuery(opts).iterate(db);
 }
 
 // ─── Statement caches (one prepared statement per db instance) ────────────
 // WeakMap keys on the db object so statements are GC'd when the db closes.
-const _countNodesStmt = new WeakMap();
-const _countEdgesStmt = new WeakMap();
-const _countFilesStmt = new WeakMap();
-const _findNodeByIdStmt = new WeakMap();
-const _findNodesByFileStmt = new WeakMap();
-const _findFileNodesStmt = new WeakMap();
-const _getNodeIdStmt = new WeakMap();
-const _getFunctionNodeIdStmt = new WeakMap();
-const _bulkNodeIdsByFileStmt = new WeakMap();
-const _findNodeChildrenStmt = new WeakMap();
-const _findNodeByQualifiedNameStmt = new WeakMap();
+const _countNodesStmt: StmtCache<{ cnt: number }> = new WeakMap();
+const _countEdgesStmt: StmtCache<{ cnt: number }> = new WeakMap();
+const _countFilesStmt: StmtCache<{ cnt: number }> = new WeakMap();
+const _findNodeByIdStmt: StmtCache<NodeRow> = new WeakMap();
+const _findNodesByFileStmt: StmtCache<NodeRow> = new WeakMap();
+const _findFileNodesStmt: StmtCache<NodeRow> = new WeakMap();
+const _getNodeIdStmt: StmtCache<{ id: number }> = new WeakMap();
+const _getFunctionNodeIdStmt: StmtCache<{ id: number }> = new WeakMap();
+const _bulkNodeIdsByFileStmt: StmtCache<NodeIdRow> = new WeakMap();
+const _findNodeChildrenStmt: StmtCache<ChildNodeRow> = new WeakMap();
+const _findNodeByQualifiedNameStmt: StmtCache<NodeRow> = new WeakMap();
 
 /**
  * Count total nodes.
- * @param {object} db
- * @returns {number}
  */
-export function countNodes(db) {
-  return cachedStmt(_countNodesStmt, db, 'SELECT COUNT(*) AS cnt FROM nodes').get().cnt;
+export function countNodes(db: BetterSqlite3Database): number {
+  return cachedStmt(_countNodesStmt, db, 'SELECT COUNT(*) AS cnt FROM nodes').get()?.cnt ?? 0;
 }
 
 /**
  * Count total edges.
- * @param {object} db
- * @returns {number}
  */
-export function countEdges(db) {
-  return cachedStmt(_countEdgesStmt, db, 'SELECT COUNT(*) AS cnt FROM edges').get().cnt;
+export function countEdges(db: BetterSqlite3Database): number {
+  return cachedStmt(_countEdgesStmt, db, 'SELECT COUNT(*) AS cnt FROM edges').get()?.cnt ?? 0;
 }
 
 /**
  * Count distinct files.
- * @param {object} db
- * @returns {number}
  */
-export function countFiles(db) {
-  return cachedStmt(_countFilesStmt, db, 'SELECT COUNT(DISTINCT file) AS cnt FROM nodes').get().cnt;
+export function countFiles(db: BetterSqlite3Database): number {
+  return (
+    cachedStmt(_countFilesStmt, db, 'SELECT COUNT(DISTINCT file) AS cnt FROM nodes').get()?.cnt ?? 0
+  );
 }
 
 // ─── Shared node lookups ───────────────────────────────────────────────
 
 /**
  * Find a single node by ID.
- * @param {object} db
- * @param {number} id
- * @returns {object|undefined}
  */
-export function findNodeById(db, id) {
+export function findNodeById(db: BetterSqlite3Database, id: number): NodeRow | undefined {
   return cachedStmt(_findNodeByIdStmt, db, 'SELECT * FROM nodes WHERE id = ?').get(id);
 }
 
 /**
  * Find non-file nodes for a given file path (exact match), ordered by line.
- * @param {object} db
- * @param {string} file - Exact file path
- * @returns {object[]}
  */
-export function findNodesByFile(db, file) {
+export function findNodesByFile(db: BetterSqlite3Database, file: string): NodeRow[] {
   return cachedStmt(
     _findNodesByFileStmt,
     db,
@@ -173,11 +172,8 @@ export function findNodesByFile(db, file) {
 
 /**
  * Find file-kind nodes matching a LIKE pattern.
- * @param {object} db
- * @param {string} fileLike - LIKE pattern (caller wraps with %)
- * @returns {object[]}
  */
-export function findFileNodes(db, fileLike) {
+export function findFileNodes(db: BetterSqlite3Database, fileLike: string): NodeRow[] {
   return cachedStmt(
     _findFileNodesStmt,
     db,
@@ -187,15 +183,14 @@ export function findFileNodes(db, fileLike) {
 
 /**
  * Look up a node's ID by its unique (name, kind, file, line) tuple.
- * Shared by builder, watcher, structure, complexity, cfg, engine.
- * @param {object} db
- * @param {string} name
- * @param {string} kind
- * @param {string} file
- * @param {number} line
- * @returns {number|undefined}
  */
-export function getNodeId(db, name, kind, file, line) {
+export function getNodeId(
+  db: BetterSqlite3Database,
+  name: string,
+  kind: string,
+  file: string,
+  line: number,
+): number | undefined {
   return cachedStmt(
     _getNodeIdStmt,
     db,
@@ -205,14 +200,13 @@ export function getNodeId(db, name, kind, file, line) {
 
 /**
  * Look up a function/method node's ID (kind-restricted variant of getNodeId).
- * Used by complexity.js, cfg.js where only function/method kinds are expected.
- * @param {object} db
- * @param {string} name
- * @param {string} file
- * @param {number} line
- * @returns {number|undefined}
  */
-export function getFunctionNodeId(db, name, file, line) {
+export function getFunctionNodeId(
+  db: BetterSqlite3Database,
+  name: string,
+  file: string,
+  line: number,
+): number | undefined {
   return cachedStmt(
     _getFunctionNodeIdStmt,
     db,
@@ -222,13 +216,8 @@ export function getFunctionNodeId(db, name, file, line) {
 
 /**
  * Bulk-fetch all node IDs for a file in one query.
- * Returns rows suitable for building a `name|kind|line -> id` lookup map.
- * Shared by builder, ast.js, ast-analysis/engine.js.
- * @param {object} db
- * @param {string} file
- * @returns {{ id: number, name: string, kind: string, line: number }[]}
  */
-export function bulkNodeIdsByFile(db, file) {
+export function bulkNodeIdsByFile(db: BetterSqlite3Database, file: string): NodeIdRow[] {
   return cachedStmt(
     _bulkNodeIdsByFileStmt,
     db,
@@ -238,11 +227,8 @@ export function bulkNodeIdsByFile(db, file) {
 
 /**
  * Find child nodes (parameters, properties, constants) of a parent.
- * @param {object} db
- * @param {number} parentId
- * @returns {{ name: string, kind: string, line: number, end_line: number|null, qualified_name: string|null, scope: string|null, visibility: string|null }[]}
  */
-export function findNodeChildren(db, parentId) {
+export function findNodeChildren(db: BetterSqlite3Database, parentId: number): ChildNodeRow[] {
   return cachedStmt(
     _findNodeChildrenStmt,
     db,
@@ -252,43 +238,37 @@ export function findNodeChildren(db, parentId) {
 
 /**
  * Find all nodes that belong to a given scope (by scope column).
- * Enables "all methods of class X" without traversing edges.
- * @param {object} db
- * @param {string} scopeName - The scope to search for (e.g., class name)
- * @param {object} [opts]
- * @param {string} [opts.kind] - Filter by node kind
- * @param {string} [opts.file] - Filter by file path (LIKE match)
- * @returns {object[]}
  */
-export function findNodesByScope(db, scopeName, opts = {}) {
+export function findNodesByScope(
+  db: BetterSqlite3Database,
+  scopeName: string,
+  opts: QueryOpts = {},
+): NodeRow[] {
   let sql = 'SELECT * FROM nodes WHERE scope = ?';
-  const params = [scopeName];
+  const params: unknown[] = [scopeName];
   if (opts.kind) {
     sql += ' AND kind = ?';
     params.push(opts.kind);
   }
-  const fc = buildFileConditionSQL(opts.file, 'file');
+  const fc = buildFileConditionSQL(opts.file ?? '', 'file');
   sql += fc.sql;
   params.push(...fc.params);
   sql += ' ORDER BY file, line';
-  return db.prepare(sql).all(...params);
+  return db.prepare<NodeRow>(sql).all(...params);
 }
 
 /**
- * Find nodes by qualified name. Returns all matches since the same
- * qualified_name can exist in different files (e.g., two classes named
- * `DateHelper.format` in separate modules). Pass `opts.file` to narrow.
- * @param {object} db
- * @param {string} qualifiedName - e.g., 'DateHelper.format'
- * @param {object} [opts]
- * @param {string} [opts.file] - Filter by file path (LIKE match)
- * @returns {object[]}
+ * Find nodes by qualified name.
  */
-export function findNodeByQualifiedName(db, qualifiedName, opts = {}) {
-  const fc = buildFileConditionSQL(opts.file, 'file');
+export function findNodeByQualifiedName(
+  db: BetterSqlite3Database,
+  qualifiedName: string,
+  opts: { file?: string } = {},
+): NodeRow[] {
+  const fc = buildFileConditionSQL(opts.file ?? '', 'file');
   if (fc.sql) {
     return db
-      .prepare(`SELECT * FROM nodes WHERE qualified_name = ?${fc.sql} ORDER BY file, line`)
+      .prepare<NodeRow>(`SELECT * FROM nodes WHERE qualified_name = ?${fc.sql} ORDER BY file, line`)
       .all(qualifiedName, ...fc.params);
   }
   return cachedStmt(
@@ -297,3 +277,37 @@ export function findNodeByQualifiedName(db, qualifiedName, opts = {}) {
     'SELECT * FROM nodes WHERE qualified_name = ? ORDER BY file, line',
   ).all(qualifiedName);
 }
+
+// ─── Metric helpers ──────────────────────────────────────────────────────
+
+const _getLineCountForNodeStmt: StmtCache<{ line_count: number }> = new WeakMap();
+
+/**
+ * Get line_count from node_metrics for a given node.
+ * @param {object} db
+ * @param {number} nodeId
+ * @returns {{ line_count: number } | undefined}
+ */
+export function getLineCountForNode(db: BetterSqlite3Database, nodeId: number) {
+  return cachedStmt(
+    _getLineCountForNodeStmt,
+    db,
+    'SELECT line_count FROM node_metrics WHERE node_id = ?',
+  ).get(nodeId);
+}
+
+const _getMaxEndLineForFileStmt: StmtCache<{ max_end: number | null }> = new WeakMap();
+
+/**
+ * Get the maximum end_line across all nodes in a file.
+ * @param {object} db
+ * @param {string} file
+ * @returns {{ max_end: number | null } | undefined}
+ */
+export function getMaxEndLineForFile(db: BetterSqlite3Database, file: string) {
+  return cachedStmt(
+    _getMaxEndLineForFileStmt,
+    db,
+    'SELECT MAX(end_line) as max_end FROM nodes WHERE file = ?',
+  ).get(file);
+}

package/src/db/repository/{sqlite-repository.js → sqlite-repository.ts}

@@ -1,3 +1,23 @@
+import type {
+  AdjacentEdgeRow,
+  BetterSqlite3Database,
+  CallableNodeRow,
+  CallEdgeRow,
+  ChildNodeRow,
+  ComplexityMetrics,
+  FileNodeRow,
+  ImportEdgeRow,
+  ImportGraphEdgeRow,
+  IntraFileCallEdge,
+  ListFunctionOpts,
+  NodeIdRow,
+  NodeRow,
+  NodeRowWithFanIn,
+  QueryOpts,
+  RelatedNodeRow,
+  TriageNodeRow,
+  TriageQueryOpts,
+} from '../../types.js';
 import { Repository } from './base.js';
 import { hasCfgTables } from './cfg.js';
 import { getComplexityForNode } from './complexity.js';
@@ -12,9 +32,11 @@ import {
   findCallers,
   findCrossFileCallTargets,
   findDistinctCallers,
+  findImplementors,
   findImportDependents,
   findImportSources,
   findImportTargets,
+  findInterfaces,
   findIntraFileCallEdges,
   getClassHierarchy,
 } from './edges.js';
@@ -44,176 +66,183 @@ import {
  * behind the Repository interface so callers can use `repo.method(...)`.
  */
 export class SqliteRepository extends Repository {
-  #db;
+  #db: BetterSqlite3Database;
 
-  /** @param {object} db - better-sqlite3 Database instance */
-  constructor(db) {
+  constructor(db: BetterSqlite3Database) {
     super();
     this.#db = db;
   }
 
   /** Expose the underlying db for code that still needs raw access. */
-  get db() {
+  get db(): BetterSqlite3Database {
     return this.#db;
   }
 
   // ── Node lookups ──────────────────────────────────────────────────
 
-  findNodeById(id) {
+  findNodeById(id: number): NodeRow | undefined {
     return findNodeById(this.#db, id);
   }
 
-  findNodesByFile(file) {
+  findNodesByFile(file: string): NodeRow[] {
     return findNodesByFile(this.#db, file);
   }
 
-  findFileNodes(fileLike) {
+  findFileNodes(fileLike: string): NodeRow[] {
     return findFileNodes(this.#db, fileLike);
   }
 
-  findNodesWithFanIn(namePattern, opts) {
+  findNodesWithFanIn(namePattern: string, opts?: QueryOpts): NodeRowWithFanIn[] {
     return findNodesWithFanIn(this.#db, namePattern, opts);
   }
 
-  countNodes() {
+  countNodes(): number {
     return countNodes(this.#db);
   }
 
-  countEdges() {
+  countEdges(): number {
     return countEdges(this.#db);
   }
 
-  countFiles() {
+  countFiles(): number {
     return countFiles(this.#db);
   }
 
-  getNodeId(name, kind, file, line) {
+  getNodeId(name: string, kind: string, file: string, line: number): number | undefined {
     return getNodeId(this.#db, name, kind, file, line);
   }
 
-  getFunctionNodeId(name, file, line) {
+  getFunctionNodeId(name: string, file: string, line: number): number | undefined {
     return getFunctionNodeId(this.#db, name, file, line);
   }
 
-  bulkNodeIdsByFile(file) {
+  bulkNodeIdsByFile(file: string): NodeIdRow[] {
     return bulkNodeIdsByFile(this.#db, file);
   }
 
-  findNodeChildren(parentId) {
+  findNodeChildren(parentId: number): ChildNodeRow[] {
     return findNodeChildren(this.#db, parentId);
   }
 
-  findNodesByScope(scopeName, opts) {
+  findNodesByScope(scopeName: string, opts?: QueryOpts): NodeRow[] {
     return findNodesByScope(this.#db, scopeName, opts);
   }
 
-  findNodeByQualifiedName(qualifiedName, opts) {
+  findNodeByQualifiedName(qualifiedName: string, opts?: { file?: string }): NodeRow[] {
     return findNodeByQualifiedName(this.#db, qualifiedName, opts);
   }
 
-  listFunctionNodes(opts) {
+  listFunctionNodes(opts?: ListFunctionOpts): NodeRow[] {
     return listFunctionNodes(this.#db, opts);
   }
 
-  iterateFunctionNodes(opts) {
+  iterateFunctionNodes(opts?: ListFunctionOpts): IterableIterator<NodeRow> {
     return iterateFunctionNodes(this.#db, opts);
   }
 
-  findNodesForTriage(opts) {
+  findNodesForTriage(opts?: TriageQueryOpts): TriageNodeRow[] {
     return findNodesForTriage(this.#db, opts);
   }
 
   // ── Edge queries ──────────────────────────────────────────────────
 
-  findCallees(nodeId) {
+  findCallees(nodeId: number): RelatedNodeRow[] {
     return findCallees(this.#db, nodeId);
   }
 
-  findCallers(nodeId) {
+  findCallers(nodeId: number): RelatedNodeRow[] {
     return findCallers(this.#db, nodeId);
   }
 
-  findDistinctCallers(nodeId) {
+  findDistinctCallers(nodeId: number): RelatedNodeRow[] {
     return findDistinctCallers(this.#db, nodeId);
   }
 
-  findAllOutgoingEdges(nodeId) {
+  findAllOutgoingEdges(nodeId: number): AdjacentEdgeRow[] {
     return findAllOutgoingEdges(this.#db, nodeId);
   }
 
-  findAllIncomingEdges(nodeId) {
+  findAllIncomingEdges(nodeId: number): AdjacentEdgeRow[] {
     return findAllIncomingEdges(this.#db, nodeId);
   }
 
-  findCalleeNames(nodeId) {
+  findCalleeNames(nodeId: number): string[] {
     return findCalleeNames(this.#db, nodeId);
   }
 
-  findCallerNames(nodeId) {
+  findCallerNames(nodeId: number): string[] {
     return findCallerNames(this.#db, nodeId);
   }
 
-  findImportTargets(nodeId) {
+  findImportTargets(nodeId: number): ImportEdgeRow[] {
     return findImportTargets(this.#db, nodeId);
   }
 
-  findImportSources(nodeId) {
+  findImportSources(nodeId: number): ImportEdgeRow[] {
     return findImportSources(this.#db, nodeId);
   }
 
-  findImportDependents(nodeId) {
+  findImportDependents(nodeId: number): NodeRow[] {
     return findImportDependents(this.#db, nodeId);
   }
 
-  findCrossFileCallTargets(file) {
+  findCrossFileCallTargets(file: string): Set<number> {
     return findCrossFileCallTargets(this.#db, file);
   }
 
-  countCrossFileCallers(nodeId, file) {
+  countCrossFileCallers(nodeId: number, file: string): number {
     return countCrossFileCallers(this.#db, nodeId, file);
   }
 
-  getClassHierarchy(classNodeId) {
+  getClassHierarchy(classNodeId: number): Set<number> {
     return getClassHierarchy(this.#db, classNodeId);
   }
 
-  findIntraFileCallEdges(file) {
+  findImplementors(nodeId: number): RelatedNodeRow[] {
+    return findImplementors(this.#db, nodeId);
+  }
+
+  findInterfaces(nodeId: number): RelatedNodeRow[] {
+    return findInterfaces(this.#db, nodeId);
+  }
+
+  findIntraFileCallEdges(file: string): IntraFileCallEdge[] {
     return findIntraFileCallEdges(this.#db, file);
   }
 
   // ── Graph-read queries ────────────────────────────────────────────
 
-  getCallableNodes() {
+  getCallableNodes(): CallableNodeRow[] {
     return getCallableNodes(this.#db);
   }
 
-  getCallEdges() {
+  getCallEdges(): CallEdgeRow[] {
     return getCallEdges(this.#db);
   }
 
-  getFileNodesAll() {
+  getFileNodesAll(): FileNodeRow[] {
     return getFileNodesAll(this.#db);
   }
 
-  getImportEdges() {
+  getImportEdges(): ImportGraphEdgeRow[] {
     return getImportEdges(this.#db);
   }
 
   // ── Optional table checks ─────────────────────────────────────────
 
-  hasCfgTables() {
+  hasCfgTables(): boolean {
     return hasCfgTables(this.#db);
   }
 
-  hasEmbeddings() {
+  hasEmbeddings(): boolean {
     return hasEmbeddings(this.#db);
   }
 
-  hasDataflowTable() {
+  hasDataflowTable(): boolean {
     return hasDataflowTable(this.#db);
   }
 
-  getComplexityForNode(nodeId) {
+  getComplexityForNode(nodeId: number): ComplexityMetrics | undefined {
     return getComplexityForNode(this.#db, nodeId);
   }
 }