@optave/codegraph 3.4.0 → 3.5.0

package/src/presentation/queries-cli/path.ts

@@ -1,4 +1,4 @@
-import { kindIcon, pathData } from '../../domain/queries.js';
+import { filePathData, kindIcon, pathData } from '../../domain/queries.js';
 import { outputResult } from '../../infrastructure/result-formatter.js';
 
 interface PathCandidate {
@@ -80,6 +80,11 @@ export function symbolPath(
   customDbPath: string,
   opts: PathOpts = {},
 ): void {
+  if (opts.file) {
+    filePath(from, to, customDbPath, opts);
+    return;
+  }
+
   const data = pathData(from, to, customDbPath, opts) as PathDataResult;
   if (outputResult(data as unknown as Record<string, unknown>, null, opts)) return;
 
@@ -107,3 +112,68 @@ export function symbolPath(
   printPathSteps(data);
   console.log();
 }
+
+// ── File-level path ──────────────────────────────────────────────────────
+
+interface FilePathDataResult {
+  error?: string;
+  found?: boolean;
+  hops?: number | null;
+  reverse?: boolean;
+  maxDepth?: number;
+  path: string[];
+  fromCandidates: string[];
+  toCandidates: string[];
+  alternateCount: number;
+}
+
+function filePath(from: string, to: string, customDbPath: string, opts: PathOpts = {}): void {
+  const data = filePathData(from, to, customDbPath, opts) as FilePathDataResult;
+  if (outputResult(data as unknown as Record<string, unknown>, null, opts)) return;
+
+  if (data.error) {
+    console.log(data.error);
+    return;
+  }
+
+  if (!data.found) {
+    const dir = data.reverse ? 'reverse ' : '';
+    console.log(`No ${dir}file path from "${from}" to "${to}" within ${data.maxDepth} hops.`);
+    if (data.fromCandidates.length > 1) {
+      console.log(
+        `\n  "${from}" matched ${data.fromCandidates.length} files — using: ${data.fromCandidates[0]}`,
+      );
+    }
+    if (data.toCandidates.length > 1) {
+      console.log(
+        `  "${to}" matched ${data.toCandidates.length} files — using: ${data.toCandidates[0]}`,
+      );
+    }
+    return;
+  }
+
+  if (data.hops === 0) {
+    console.log(`\n"${from}" and "${to}" resolve to the same file (0 hops):`);
+    console.log(`  ${data.path[0]}\n`);
+    return;
+  }
+
+  const dir = data.reverse ? ' (reverse)' : '';
+  console.log(
+    `\nFile path from ${from} to ${to} (${data.hops} ${data.hops === 1 ? 'hop' : 'hops'})${dir}:\n`,
+  );
+  for (let i = 0; i < data.path.length; i++) {
+    const indent = '  '.repeat(i + 1);
+    if (i === 0) {
+      console.log(`${indent}${data.path[i]}`);
+    } else {
+      console.log(`${indent}→ ${data.path[i]}`);
+    }
+  }
+  if (data.alternateCount > 0) {
+    console.log(
+      `\n  (${data.alternateCount} alternate shortest ${data.alternateCount === 1 ? 'path' : 'paths'} at same depth)`,
+    );
+  }
+  console.log();
+}

package/src/presentation/result-formatter.ts

@@ -115,7 +115,6 @@ export interface OutputOpts {
 }
 
 export function outputResult(
-  // biome-ignore lint/suspicious/noExplicitAny: accepts any data shape from features
   data: Record<string, any>,
   field: string | null,
   opts: OutputOpts,

package/src/presentation/sequence.ts

@@ -16,7 +16,6 @@ interface SequenceOpts {
 }
 
 export function sequence(name: string, dbPath: string | undefined, opts: SequenceOpts = {}): void {
-  // biome-ignore lint/suspicious/noExplicitAny: dynamic shape from sequenceData
   const data = sequenceData(name, dbPath, opts) as any;
 
   if (outputResult(data, 'messages', opts)) return;

package/src/presentation/structure.ts

@@ -49,22 +49,10 @@ export function formatStructure(data: StructureResult): string {
   return lines.join('\n');
 }
 
-interface HotspotEntry {
-  name: string;
-  kind: string;
-  fileCount?: number;
-  cohesion?: number | null;
-  lineCount?: number;
-  symbolCount?: number;
-  fanIn?: number;
-  fanOut?: number;
-}
-
 interface HotspotsResult {
   metric: string;
   level: string;
   limit: number;
-  // biome-ignore lint/suspicious/noExplicitAny: hotspots shape varies by level
   hotspots: any[];
 }
 

package/src/presentation/triage.ts

@@ -37,7 +37,6 @@ interface TriageSummary {
 }
 
 export function triage(customDbPath: string | undefined, opts: TriageOpts = {}): void {
-  // biome-ignore lint/suspicious/noExplicitAny: dynamic shape from triageData
   const data = triageData(customDbPath, opts as any) as {
     items: TriageItem[];
     summary: TriageSummary;

package/src/shared/constants.ts

@@ -1,26 +1,40 @@
 import path from 'node:path';
 import { SUPPORTED_EXTENSIONS } from '../domain/parser.js';
 
-export const IGNORE_DIRS: Set<string> = new Set([
-  'node_modules',
-  '.git',
-  'dist',
-  'build',
-  '.next',
-  '.nuxt',
-  '.svelte-kit',
-  'coverage',
-  '.codegraph',
-  '__pycache__',
-  '.tox',
-  'vendor',
-  '.venv',
-  'venv',
-  'env',
-  '.env',
-]);
+/**
+ * Set with a `.toArray()` convenience method for consumers migrating from
+ * the pre-3.4 Array-based API (where `.includes()` / `.indexOf()` worked).
+ */
+export interface ArrayCompatSet<T> extends Set<T> {
+  toArray(): T[];
+}
+
+function withArrayCompat<T>(s: Set<T>): ArrayCompatSet<T> {
+  return Object.assign(s, { toArray: () => [...s] });
+}
+
+export const IGNORE_DIRS: ArrayCompatSet<string> = withArrayCompat(
+  new Set([
+    'node_modules',
+    '.git',
+    'dist',
+    'build',
+    '.next',
+    '.nuxt',
+    '.svelte-kit',
+    'coverage',
+    '.codegraph',
+    '__pycache__',
+    '.tox',
+    'vendor',
+    '.venv',
+    'venv',
+    'env',
+    '.env',
+  ]),
+);
 
-export { SUPPORTED_EXTENSIONS as EXTENSIONS };
+export const EXTENSIONS: ArrayCompatSet<string> = withArrayCompat(new Set(SUPPORTED_EXTENSIONS));
 
 export function shouldIgnore(dirName: string): boolean {
   return IGNORE_DIRS.has(dirName) || dirName.startsWith('.');

package/src/shared/errors.ts

@@ -72,3 +72,8 @@ export class BoundaryError extends CodegraphError {
     this.name = 'BoundaryError';
   }
 }
+
+/** Safely extract a string message from an unknown thrown value. */
+export function toErrorMessage(e: unknown): string {
+  return e instanceof Error ? e.message : String(e);
+}

package/src/shared/version.ts

@@ -0,0 +1,10 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+const __sharedDir = path.dirname(new URL(import.meta.url).pathname.replace(/^\/([A-Z]:)/i, '$1'));
+
+export const CODEGRAPH_VERSION: string = (
+  JSON.parse(fs.readFileSync(path.join(__sharedDir, '..', '..', 'package.json'), 'utf-8')) as {
+    version: string;
+  }
+).version;

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. */
@@ -1774,8 +1776,9 @@ export interface BetterSqlite3Database {
   exec(sql: string): this;
   close(): void;
   pragma(sql: string): unknown;
-  // biome-ignore lint/suspicious/noExplicitAny: must be compatible with better-sqlite3's generic Transaction<F> return type
-  transaction<F extends (...args: any[]) => any>(fn: F): F;
+  transaction<F extends (...args: any[]) => any>(
+    fn: F,
+  ): (...args: F extends (...a: infer A) => unknown ? A : never) => ReturnType<F>;
   readonly open: boolean;
   readonly name: string;
 }
@@ -1803,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. */
@@ -1813,20 +1820,283 @@ 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
 // ════════════════════════════════════════════════════════════════════════
 
 /** Shared context passed to every CLI command's execute/validate functions. */
 export interface CommandContext {
-  // biome-ignore lint/suspicious/noExplicitAny: config is a deeply nested dynamic object
   config: Record<string, any>;
-  // biome-ignore lint/suspicious/noExplicitAny: Commander options are dynamically typed
   resolveNoTests: (opts: any) => boolean;
-  // biome-ignore lint/suspicious/noExplicitAny: Commander options are dynamically typed
   resolveQueryOpts: (opts: any) => any;
   formatSize: (bytes: number) => string;
-  // biome-ignore lint/suspicious/noExplicitAny: data shapes vary per command
   outputResult: (data: any, key: string, opts: any) => boolean;
   program: import('commander').Command;
 }
@@ -1839,12 +2109,9 @@ export interface CommandDefinition {
   options?: Array<
     | [string, string]
     | [string, string, string | boolean | number]
-    // biome-ignore lint/suspicious/noExplicitAny: Commander parse functions accept arbitrary return types
     | [string, string, (val: string) => any, string | boolean | number]
   >;
-  // biome-ignore lint/suspicious/noExplicitAny: Commander options are dynamically typed
-  validate?: (args: any[], opts: any, ctx: CommandContext) => string | undefined | void;
-  // biome-ignore lint/suspicious/noExplicitAny: Commander options are dynamically typed
+  validate?: (args: any[], opts: any, ctx: CommandContext) => string | undefined;
   execute?: (args: any[], opts: any, ctx: CommandContext) => void | Promise<void>;
   subcommands?: CommandDefinition[];
 }

package/src/vendor.d.ts

@@ -1,39 +0,0 @@
-/**
- * Ambient type declarations for third-party modules without bundled types.
- * Used by the TS migration — keeps @types/* out of devDeps to avoid
- * declaration-emit conflicts with allowJs.
- */
-
-declare module 'better-sqlite3' {
-  namespace BetterSqlite3 {
-    interface Database {
-      prepare<TRow = unknown>(sql: string): Statement<TRow>;
-      exec(sql: string): Database;
-      // biome-ignore lint/suspicious/noExplicitAny: must match better-sqlite3's generic Transaction<F>
-      transaction<F extends (...args: any[]) => any>(fn: F): F;
-      close(): void;
-      pragma(pragma: string, options?: { simple?: boolean }): unknown;
-      readonly open: boolean;
-      readonly name: string;
-    }
-
-    interface Statement<TRow = unknown> {
-      run(...params: unknown[]): RunResult;
-      get(...params: unknown[]): TRow | undefined;
-      all(...params: unknown[]): TRow[];
-      iterate(...params: unknown[]): IterableIterator<TRow>;
-      raw(toggle?: boolean): this;
-    }
-
-    interface RunResult {
-      changes: number;
-      lastInsertRowid: number | bigint;
-    }
-  }
-
-  function BetterSqlite3(
-    filename: string,
-    options?: Record<string, unknown>,
-  ): BetterSqlite3.Database;
-  export = BetterSqlite3;
-}