@optave/codegraph 3.4.1 → 3.6.0

package/src/types.ts

@@ -22,10 +22,11 @@ export type CoreSymbolKind =
   | 'enum'
   | 'trait'
   | 'record'
-  | 'module';
+  | 'module'
+  | 'namespace';
 
 /** Sub-declaration kinds (Phase 1). Includes 'method' for class child nodes. */
-export type ExtendedSymbolKind = 'parameter' | 'property' | 'constant' | 'method';
+export type ExtendedSymbolKind = 'parameter' | 'property' | 'constant' | 'variable' | 'method';
 
 /** All queryable symbol kinds. */
 export type SymbolKind = CoreSymbolKind | ExtendedSymbolKind;
@@ -83,7 +84,13 @@ export type LanguageId =
   | 'csharp'
   | 'ruby'
   | 'php'
-  | 'hcl';
+  | 'hcl'
+  | 'c'
+  | 'cpp'
+  | 'kotlin'
+  | 'swift'
+  | 'scala'
+  | 'bash';
 
 /** Engine mode selector. */
 export type EngineMode = 'native' | 'wasm' | 'auto';
@@ -433,6 +440,11 @@ export interface Import {
   csharpUsing?: boolean;
   rubyRequire?: boolean;
   phpUse?: boolean;
+  cInclude?: boolean;
+  kotlinImport?: boolean;
+  swiftImport?: boolean;
+  scalaImport?: boolean;
+  bashSource?: boolean;
 }
 
 /** A class/struct/trait relationship (extends or implements). */
@@ -881,6 +893,15 @@ export interface EngineOpts {
   engine: EngineMode;
   dataflow: boolean;
   ast: boolean;
+  /** Persistent NativeDatabase connection for build writes (Phase 6.15). */
+  nativeDb?: NativeDatabase;
+  /**
+   * Suspend the JS (better-sqlite3) connection before a native write to avoid
+   * dual-connection WAL corruption. Call `resumeJsDb()` after the write completes.
+   * Only set during pipeline builds where both connections coexist.
+   */
+  suspendJsDb?: () => void;
+  resumeJsDb?: () => void;
 }
 
 /** A file change detected during incremental builds. */
@@ -1804,6 +1825,10 @@ export interface NativeAddon {
   buildCallEdges(files: unknown[], nodes: unknown[], builtinReceivers: string[]): unknown[];
   engineVersion(): string;
   ParseTreeCache: new () => NativeParseTreeCache;
+  NativeDatabase: {
+    openReadWrite(dbPath: string): NativeDatabase;
+    openReadonly(dbPath: string): NativeDatabase;
+  };
 }
 
 /** Native parse-tree cache instance. */
@@ -1814,6 +1839,436 @@ export interface NativeParseTreeCache {
   clear(): void;
 }
 
+/** Row types returned by NativeDatabase query methods (auto-generated by napi-rs). */
+export interface NativeNodeRow {
+  id: number;
+  name: string;
+  kind: string;
+  file: string;
+  line: number | null;
+  endLine: number | null;
+  parentId: number | null;
+  exported: number | null;
+  qualifiedName: string | null;
+  scope: string | null;
+  visibility: string | null;
+  role: string | null;
+}
+
+export interface NativeNodeRowWithFanIn extends NativeNodeRow {
+  fanIn: number;
+}
+
+export interface NativeTriageNodeRow extends NativeNodeRow {
+  fanIn: number;
+  cognitive: number;
+  mi: number;
+  cyclomatic: number;
+  maxNesting: number;
+  churn: number;
+}
+
+export interface NativeNodeIdRow {
+  id: number;
+  name: string;
+  kind: string;
+  line: number | null;
+}
+
+export interface NativeChildNodeRow {
+  name: string;
+  kind: string;
+  line: number | null;
+  endLine: number | null;
+  qualifiedName: string | null;
+  scope: string | null;
+  visibility: string | null;
+}
+
+export interface NativeRelatedNodeRow {
+  id: number;
+  name: string;
+  kind: string;
+  file: string;
+  line: number | null;
+  endLine: number | null;
+}
+
+export interface NativeAdjacentEdgeRow {
+  name: string;
+  kind: string;
+  file: string;
+  line: number | null;
+  edgeKind: string;
+}
+
+export interface NativeImportEdgeRow {
+  file: string;
+  edgeKind: string;
+}
+
+export interface NativeIntraFileCallEdge {
+  callerName: string;
+  calleeName: string;
+}
+
+export interface NativeCallableNodeRow {
+  id: number;
+  name: string;
+  kind: string;
+  file: string;
+}
+
+export interface NativeCallEdgeRow {
+  sourceId: number;
+  targetId: number;
+  confidence: number | null;
+}
+
+export interface NativeFileNodeRow {
+  id: number;
+  name: string;
+  file: string;
+}
+
+export interface NativeImportGraphEdgeRow {
+  sourceId: number;
+  targetId: number;
+}
+
+export interface NativeComplexityMetrics {
+  cognitive: number;
+  cyclomatic: number;
+  maxNesting: number;
+  maintainabilityIndex: number | null;
+  halsteadVolume: number | null;
+}
+
+/** Native rusqlite database wrapper instance (Phase 6.13 + 6.14 + 6.15). */
+export interface NativeDatabase {
+  // ── Lifecycle (6.13) ────────────────────────────────────────────────
+  initSchema(): void;
+  getBuildMeta(key: string): string | null;
+  setBuildMeta(entries: Array<{ key: string; value: string }>): void;
+  exec(sql: string): void;
+  pragma(sql: string): string | null;
+  close(): void;
+  readonly dbPath: string;
+  readonly isOpen: boolean;
+
+  // ── Node lookups (6.14) ──────────────────────────────────────────────
+  countNodes(): number;
+  countEdges(): number;
+  countFiles(): number;
+  findNodeById(id: number): NativeNodeRow | null;
+  getNodeId(name: string, kind: string, file: string, line: number): number | null;
+  getFunctionNodeId(name: string, file: string, line: number): number | null;
+  bulkNodeIdsByFile(file: string): NativeNodeIdRow[];
+  findNodeChildren(parentId: number): NativeChildNodeRow[];
+  findNodesByFile(file: string): NativeNodeRow[];
+  findFileNodes(fileLike: string): NativeNodeRow[];
+  findNodesByScope(
+    scopeName: string,
+    kind: string | null | undefined,
+    file: string | null | undefined,
+  ): NativeNodeRow[];
+  findNodeByQualifiedName(qualifiedName: string, file: string | null | undefined): NativeNodeRow[];
+  findNodesWithFanIn(
+    namePattern: string,
+    kinds: string[] | null | undefined,
+    file: string | null | undefined,
+  ): NativeNodeRowWithFanIn[];
+  findNodesForTriage(
+    kind: string | null | undefined,
+    role: string | null | undefined,
+    file: string | null | undefined,
+    noTests: boolean | null | undefined,
+  ): NativeTriageNodeRow[];
+  listFunctionNodes(
+    file: string | null | undefined,
+    pattern: string | null | undefined,
+    noTests: boolean | null | undefined,
+  ): NativeNodeRow[];
+  iterateFunctionNodes(
+    file: string | null | undefined,
+    pattern: string | null | undefined,
+    noTests: boolean | null | undefined,
+  ): NativeNodeRow[];
+
+  // ── Edge queries (6.14) ──────────────────────────────────────────────
+  findCallees(nodeId: number): NativeRelatedNodeRow[];
+  findCallers(nodeId: number): NativeRelatedNodeRow[];
+  findDistinctCallers(nodeId: number): NativeRelatedNodeRow[];
+  findAllOutgoingEdges(nodeId: number): NativeAdjacentEdgeRow[];
+  findAllIncomingEdges(nodeId: number): NativeAdjacentEdgeRow[];
+  findCalleeNames(nodeId: number): string[];
+  findCallerNames(nodeId: number): string[];
+  findImportTargets(nodeId: number): NativeImportEdgeRow[];
+  findImportSources(nodeId: number): NativeImportEdgeRow[];
+  findImportDependents(nodeId: number): NativeNodeRow[];
+  findCrossFileCallTargets(file: string): number[];
+  countCrossFileCallers(nodeId: number, file: string): number;
+  getClassHierarchy(classNodeId: number): number[];
+  findImplementors(nodeId: number): NativeRelatedNodeRow[];
+  findInterfaces(nodeId: number): NativeRelatedNodeRow[];
+  findIntraFileCallEdges(file: string): NativeIntraFileCallEdge[];
+
+  // ── Graph-read queries (6.14) ────────────────────────────────────────
+  getCallableNodes(): NativeCallableNodeRow[];
+  getCallEdges(): NativeCallEdgeRow[];
+  getFileNodesAll(): NativeFileNodeRow[];
+  getImportEdges(): NativeImportGraphEdgeRow[];
+
+  // ── Table checks (6.14) ──────────────────────────────────────────────
+  hasCfgTables(): boolean;
+  hasEmbeddings(): boolean;
+  hasDataflowTable(): boolean;
+  getComplexityForNode(nodeId: number): NativeComplexityMetrics | null;
+
+  // ── Build pipeline writes (6.15) ───────────────────────────────────
+  bulkInsertNodes(
+    batches: Array<{
+      file: string;
+      definitions: Array<{
+        name: string;
+        kind: string;
+        line: number;
+        endLine?: number;
+        visibility?: string;
+        children: Array<{
+          name: string;
+          kind: string;
+          line: number;
+          endLine?: number;
+          visibility?: string;
+        }>;
+      }>;
+      exports: Array<{ name: string; kind: string; line: number }>;
+    }>,
+    fileHashes: Array<{ file: string; hash: string; mtime: number; size: number }>,
+    removedFiles: string[],
+  ): boolean;
+  bulkInsertEdges(
+    edges: Array<{
+      sourceId: number;
+      targetId: number;
+      kind: string;
+      confidence: number;
+      dynamic: number;
+    }>,
+  ): boolean;
+  bulkInsertAstNodes(
+    batches: Array<{
+      file: string;
+      nodes: Array<{
+        line: number;
+        kind: string;
+        name: string;
+        text?: string | null;
+        receiver?: string | null;
+      }>;
+    }>,
+  ): number;
+  bulkInsertComplexity?(
+    rows: Array<{
+      nodeId: number;
+      cognitive: number;
+      cyclomatic: number;
+      maxNesting: number;
+      loc: number;
+      sloc: number;
+      commentLines: number;
+      halsteadN1: number;
+      halsteadN2: number;
+      halsteadBigN1: number;
+      halsteadBigN2: number;
+      halsteadVocabulary: number;
+      halsteadLength: number;
+      halsteadVolume: number;
+      halsteadDifficulty: number;
+      halsteadEffort: number;
+      halsteadBugs: number;
+      maintainabilityIndex: number;
+    }>,
+  ): number;
+  bulkInsertCfg?(
+    entries: Array<{
+      nodeId: number;
+      blocks: Array<{
+        index: number;
+        blockType: string;
+        startLine?: number | null;
+        endLine?: number | null;
+        label?: string | null;
+      }>;
+      edges: Array<{
+        sourceIndex: number;
+        targetIndex: number;
+        kind: string;
+      }>;
+    }>,
+  ): number;
+  bulkInsertDataflow?(
+    edges: Array<{
+      sourceId: number;
+      targetId: number;
+      kind: string;
+      paramIndex?: number | null;
+      expression?: string | null;
+      line?: number | null;
+      confidence: number;
+    }>,
+  ): number;
+  classifyRolesFull(): {
+    entry: number;
+    core: number;
+    utility: number;
+    adapter: number;
+    dead: number;
+    deadLeaf: number;
+    deadEntry: number;
+    deadFfi: number;
+    deadUnresolved: number;
+    testOnly: number;
+    leaf: number;
+  } | null;
+  classifyRolesIncremental(changedFiles: string[]): {
+    entry: number;
+    core: number;
+    utility: number;
+    adapter: number;
+    dead: number;
+    deadLeaf: number;
+    deadEntry: number;
+    deadFfi: number;
+    deadUnresolved: number;
+    testOnly: number;
+    leaf: number;
+  } | null;
+  purgeFilesData(files: string[], purgeHashes?: boolean, reverseDepFiles?: string[]): void;
+
+  // ── Batched query methods ────────────────────────────────────────────
+  /** All graph statistics in a single napi call (replaces ~11 queries in module-map). */
+  getGraphStats?(noTests: boolean): {
+    totalNodes: number;
+    totalEdges: number;
+    nodesByKind: Array<{ kind: string; count: number }>;
+    edgesByKind: Array<{ kind: string; count: number }>;
+    roleCounts: Array<{ role: string; count: number }>;
+    quality: {
+      callableTotal: number;
+      callableWithCallers: number;
+      callEdges: number;
+      highConfCallEdges: number;
+    };
+    hotspots: Array<{ file: string; fanIn: number; fanOut: number }>;
+    complexity: {
+      analyzed: number;
+      avgCognitive: number;
+      avgCyclomatic: number;
+      maxCognitive: number;
+      maxCyclomatic: number;
+      avgMi: number;
+      minMi: number;
+    } | null;
+    embeddings: {
+      count: number;
+      model: string | null;
+      dim: number | null;
+      builtAt: string | null;
+    } | null;
+  };
+  /** All 6 directional dataflow edge sets for a node in one call. */
+  getDataflowEdges?(nodeId: number): {
+    flowsToOut: Array<{
+      name: string;
+      kind: string;
+      file: string;
+      line: number | null;
+      paramIndex: number | null;
+      expression: string | null;
+      confidence: number | null;
+    }>;
+    flowsToIn: Array<{
+      name: string;
+      kind: string;
+      file: string;
+      line: number | null;
+      paramIndex: number | null;
+      expression: string | null;
+      confidence: number | null;
+    }>;
+    returnsOut: Array<{
+      name: string;
+      kind: string;
+      file: string;
+      line: number | null;
+      paramIndex: number | null;
+      expression: string | null;
+      confidence: number | null;
+    }>;
+    returnsIn: Array<{
+      name: string;
+      kind: string;
+      file: string;
+      line: number | null;
+      paramIndex: number | null;
+      expression: string | null;
+      confidence: number | null;
+    }>;
+    mutatesOut: Array<{
+      name: string;
+      kind: string;
+      file: string;
+      line: number | null;
+      paramIndex: number | null;
+      expression: string | null;
+      confidence: number | null;
+    }>;
+    mutatesIn: Array<{
+      name: string;
+      kind: string;
+      file: string;
+      line: number | null;
+      paramIndex: number | null;
+      expression: string | null;
+      confidence: number | null;
+    }>;
+  };
+  /** Hotspot rows for a metric/kind/limit in one call. */
+  getHotspots?(
+    kind: string,
+    metric: string,
+    noTests: boolean,
+    limit: number,
+  ): Array<{
+    name: string;
+    kind: string;
+    lineCount: number | null;
+    symbolCount: number | null;
+    importCount: number | null;
+    exportCount: number | null;
+    fanIn: number | null;
+    fanOut: number | null;
+    cohesion: number | null;
+    fileCount: number | null;
+  }>;
+  /** Batch fan-in/fan-out for multiple node IDs in one call. */
+  batchFanMetrics?(nodeIds: number[]): Array<{
+    nodeId: number;
+    fanIn: number;
+    fanOut: number;
+  }>;
+
+  // ── Generic query execution & version validation (6.16) ─────────────
+  /** Execute a parameterized SELECT and return all rows as objects. */
+  queryAll(sql: string, params: Array<string | number | null>): Record<string, unknown>[];
+  /** Execute a parameterized SELECT and return the first row, or null. */
+  queryGet(sql: string, params: Array<string | number | null>): Record<string, unknown> | null;
+  /** Validate DB codegraph_version matches expected. Warns on mismatch. */
+  validateSchemaVersion(expectedVersion: string): boolean;
+}
+
 // ════════════════════════════════════════════════════════════════════════
 // §14  CLI Command Framework
 // ════════════════════════════════════════════════════════════════════════