@optave/codegraph 3.4.1 → 3.5.0

package/src/types.ts

@@ -881,6 +881,8 @@ export interface EngineOpts {
   engine: EngineMode;
   dataflow: boolean;
   ast: boolean;
+  /** Persistent NativeDatabase connection for build writes (Phase 6.15). */
+  nativeDb?: NativeDatabase;
 }
 
 /** A file change detected during incremental builds. */
@@ -1804,6 +1806,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 +1820,273 @@ 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 | null;
+        visibility?: string | null;
+        children: Array<{
+          name: string;
+          kind: string;
+          line: number;
+          endLine?: number | null;
+          visibility?: string | null;
+        }>;
+      }>;
+      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;
+  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;
+
+  // ── 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
 // ════════════════════════════════════════════════════════════════════════