@optave/codegraph 3.3.1 → 3.4.0

package/src/types.ts

@@ -116,6 +116,16 @@ export interface NodeRowWithFanIn extends NodeRow {
   fan_in: number;
 }
 
+/** A node row augmented with triage signals (from findNodesForTriage). */
+export interface TriageNodeRow extends NodeRow {
+  fan_in: number;
+  cognitive: number;
+  mi: number;
+  cyclomatic: number;
+  max_nesting: number;
+  churn: number;
+}
+
 /** Compact node ID row (from bulkNodeIdsByFile). */
 export interface NodeIdRow {
   id: number;
@@ -133,6 +143,7 @@ export interface ChildNodeRow {
   qualified_name: string | null;
   scope: string | null;
   visibility: 'public' | 'private' | 'protected' | null;
+  file?: string;
 }
 
 /** An edge row as stored in SQLite. */
@@ -261,7 +272,7 @@ export interface Repository {
   findNodeByQualifiedName(qualifiedName: string, opts?: { file?: string }): NodeRow[];
   listFunctionNodes(opts?: ListFunctionOpts): NodeRow[];
   iterateFunctionNodes(opts?: ListFunctionOpts): IterableIterator<NodeRow>;
-  findNodesForTriage(opts?: TriageQueryOpts): NodeRow[];
+  findNodesForTriage(opts?: TriageQueryOpts): TriageNodeRow[];
 
   // ── Edge queries ──────────────────────────────────────────────────
   findCallees(nodeId: number): RelatedNodeRow[];
@@ -277,6 +288,8 @@ export interface Repository {
   findCrossFileCallTargets(file: string): Set<number>;
   countCrossFileCallers(nodeId: number, file: string): number;
   getClassHierarchy(classNodeId: number): Set<number>;
+  findImplementors(nodeId: number): RelatedNodeRow[];
+  findInterfaces(nodeId: number): RelatedNodeRow[];
   findIntraFileCallEdges(file: string): IntraFileCallEdge[];
 
   // ── Graph-read queries ────────────────────────────────────────────
@@ -377,6 +390,16 @@ export interface HalsteadMetrics {
   bugs: number;
 }
 
+/** Halstead derived metrics including raw counts. */
+export interface HalsteadDerivedMetrics extends HalsteadMetrics {
+  n1: number;
+  n2: number;
+  bigN1: number;
+  bigN2: number;
+  vocabulary: number;
+  length: number;
+}
+
 /** Lines-of-code metrics. */
 export interface LOCMetrics {
   loc: number;
@@ -451,6 +474,8 @@ export interface ExtractorOutput {
   dataflow?: DataflowResult;
   /** AST node rows, populated post-analysis. */
   astNodes?: ASTNodeRow[];
+  /** Set when typeMap was backfilled from WASM for a native parse result. */
+  _typeMapBackfilled?: boolean;
 }
 
 /** Extractor function signature. */
@@ -475,6 +500,7 @@ export interface LanguageRegistryEntry {
 
 /** tree-sitter opaque types (thin wrappers — real impl is WASM). */
 export interface TreeSitterNode {
+  id: number;
   type: string;
   text: string;
   startPosition: { row: number; column: number };
@@ -485,6 +511,8 @@ export interface TreeSitterNode {
   namedChild(index: number): TreeSitterNode | null;
   childForFieldName(name: string): TreeSitterNode | null;
   parent: TreeSitterNode | null;
+  previousSibling: TreeSitterNode | null;
+  nextSibling: TreeSitterNode | null;
   children: TreeSitterNode[];
   namedChildren: TreeSitterNode[];
 }
@@ -618,30 +646,111 @@ export type ASTTypeMap = Map<string, ASTNodeKind>;
 /** Complexity rules for a language. */
 export interface ComplexityRules {
   branchNodes: Set<string>;
+  caseNodes: Set<string>;
+  logicalOperators: Set<string>;
+  logicalNodeType: string | null;
+  optionalChainType: string | null;
   nestingNodes: Set<string>;
   functionNodes: Set<string>;
+  ifNodeType: string | null;
+  elseNodeType: string | null;
+  elifNodeType: string | null;
+  elseViaAlternative: boolean;
+  switchLikeNodes: Set<string>;
 }
 
 /** Halstead rules for a language. */
 export interface HalsteadRules {
-  operators: Set<string>;
-  operands: Set<string>;
-}
-
-/** CFG rules for a language. */
-export interface CfgRules {
-  controlFlowNodes: Set<string>;
+  operatorLeafTypes: Set<string>;
+  operandLeafTypes: Set<string>;
+  compoundOperators: Set<string>;
+  skipTypes: Set<string>;
+}
+
+/** CFG rules for a language (merged result of CFG_DEFAULTS + overrides). */
+export interface CfgRulesConfig {
+  ifNode: string | null;
+  ifNodes: Set<string> | null;
+  elifNode: string | null;
+  elseClause: string | null;
+  elseViaAlternative: boolean;
+  ifConsequentField: string | null;
+  forNodes: Set<string>;
+  whileNode: string | null;
+  whileNodes: Set<string> | null;
+  doNode: string | null;
+  infiniteLoopNode: string | null;
+  unlessNode: string | null;
+  untilNode: string | null;
+  switchNode: string | null;
+  switchNodes: Set<string> | null;
+  caseNode: string | null;
+  caseNodes: Set<string> | null;
+  defaultNode: string | null;
+  tryNode: string | null;
+  catchNode: string | null;
+  finallyNode: string | null;
+  returnNode: string | null;
+  throwNode: string | null;
+  breakNode: string | null;
+  continueNode: string | null;
+  blockNode: string | null;
+  blockNodes: Set<string> | null;
+  labeledNode: string | null;
   functionNodes: Set<string>;
 }
 
-/** Dataflow rules for a language. */
-export interface DataflowRules {
-  variableDeclarators: Set<string>;
-  parameterNodes: Set<string>;
-  callNodes: Set<string>;
-  memberNodes: Set<string>;
-  returnNodes: Set<string>;
-  awaitNodes: Set<string>;
+/** Dataflow rules for a language (merged result of DATAFLOW_DEFAULTS + overrides). */
+export interface DataflowRulesConfig {
+  functionNodes: Set<string>;
+  nameField: string;
+  varAssignedFnParent: string | null;
+  assignmentFnParent: string | null;
+  pairFnParent: string | null;
+  paramListField: string;
+  paramIdentifier: string;
+  paramWrapperTypes: Set<string>;
+  defaultParamType: string | null;
+  restParamType: string | null;
+  objectDestructType: string | null;
+  arrayDestructType: string | null;
+  shorthandPropPattern: string | null;
+  pairPatternType: string | null;
+  extractParamName: ((node: TreeSitterNode) => string[] | null) | null;
+  returnNode: string | null;
+  varDeclaratorNode: string | null;
+  varDeclaratorNodes: Set<string> | null;
+  varNameField: string;
+  varValueField: string;
+  assignmentNode: string | null;
+  assignLeftField: string;
+  assignRightField: string;
+  callNode: string | null;
+  callNodes: Set<string> | null;
+  callFunctionField: string;
+  callArgsField: string;
+  spreadType: string | null;
+  memberNode: string | null;
+  memberObjectField: string;
+  memberPropertyField: string;
+  optionalChainNode: string | null;
+  awaitNode: string | null;
+  mutatingMethods: Set<string>;
+  expressionStmtNode: string;
+  callObjectField: string | null;
+  expressionListType: string | null;
+  equalsClauseType: string | null;
+  argumentWrapperType: string | null;
+  extraIdentifierTypes: Set<string> | null;
+}
+
+/** Language rule module: exports from each language rule file. */
+export interface LanguageRuleModule {
+  complexity: ComplexityRules;
+  halstead: HalsteadRules;
+  cfg: CfgRulesConfig;
+  dataflow: DataflowRulesConfig;
+  astTypes: Record<string, string> | null;
 }
 
 /** A basic block in a control flow graph. */
@@ -853,6 +962,10 @@ export interface BuildGraphOpts {
   engine?: EngineMode;
   dataflow?: boolean;
   ast?: boolean;
+  complexity?: boolean;
+  cfg?: boolean;
+  scope?: string[];
+  skipRegistry?: boolean;
 }
 
 /** Build timing result from buildGraph. */
@@ -956,7 +1069,12 @@ export interface CodegraphConfig {
     briefMediumRiskCallers: number;
   };
 
-  community: { resolution: number };
+  community: {
+    resolution: number;
+    maxLevels: number;
+    maxLocalPasses: number;
+    refinementTheta: number;
+  };
   structure: { cohesionThreshold: number };
 
   risk: {
@@ -1007,6 +1125,7 @@ export interface RiskWeights {
 }
 
 export interface McpDefaults {
+  [key: string]: number;
   list_functions: number;
   query: number;
   where: number;
@@ -1029,6 +1148,8 @@ export interface McpDefaults {
   structure: number;
   triage: number;
   ast_query: number;
+  implementations: number;
+  interfaces: number;
 }
 
 // ════════════════════════════════════════════════════════════════════════
@@ -1491,6 +1612,32 @@ export interface RolesResult {
   symbols: NodeRow[];
 }
 
+// ── Implementations / Interfaces ─────────────────────────────────
+
+export interface ImplementationsResult {
+  name: string;
+  results: Array<{
+    name: string;
+    kind: string;
+    file: string;
+    line: number;
+    implementors: Array<{ name: string; kind: string; file: string; line: number }>;
+  }>;
+  _pagination?: PaginationMeta;
+}
+
+export interface InterfacesResult {
+  name: string;
+  results: Array<{
+    name: string;
+    kind: string;
+    file: string;
+    line: number;
+    interfaces: Array<{ name: string; kind: string; file: string; line: number }>;
+  }>;
+  _pagination?: PaginationMeta;
+}
+
 // ════════════════════════════════════════════════════════════════════════
 // §15  Registry (Multi-repo)
 // ════════════════════════════════════════════════════════════════════════
@@ -1607,3 +1754,97 @@ export interface ExportNeo4jCSVResult {
   nodes: string;
   relationships: string;
 }
+
+// ════════════════════════════════════════════════════════════════════════
+// §21  SQLite Database (better-sqlite3 surface)
+// ════════════════════════════════════════════════════════════════════════
+
+/** Minimal prepared-statement interface matching better-sqlite3. */
+export interface SqliteStatement<TRow = unknown> {
+  get(...params: unknown[]): TRow | undefined;
+  all(...params: unknown[]): TRow[];
+  run(...params: unknown[]): { changes: number; lastInsertRowid: number | bigint };
+  iterate(...params: unknown[]): IterableIterator<TRow>;
+  raw(toggle?: boolean): this;
+}
+
+/** Minimal database interface matching the better-sqlite3 surface we use. */
+export interface BetterSqlite3Database {
+  prepare<TRow = unknown>(sql: string): SqliteStatement<TRow>;
+  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;
+  readonly open: boolean;
+  readonly name: string;
+}
+
+/** WeakMap-based statement cache: one prepared statement per db instance. */
+export type StmtCache<TRow = unknown> = WeakMap<BetterSqlite3Database, SqliteStatement<TRow>>;
+
+// ════════════════════════════════════════════════════════════════════════
+// §22  Native Addon (napi-rs FFI boundary)
+// ════════════════════════════════════════════════════════════════════════
+
+/** The native napi-rs addon interface (crates/codegraph-core). */
+export interface NativeAddon {
+  parseFile(filePath: string, source: string, dataflow: boolean, ast: boolean): unknown;
+  parseFiles(files: string[], rootDir: string, dataflow: boolean, ast: boolean): unknown[];
+  resolveImport(fromFile: string, importSource: string, rootDir: string, aliases: unknown): string;
+  resolveImports(
+    items: Array<{ fromFile: string; importSource: string }>,
+    rootDir: string,
+    aliases: unknown,
+    knownFiles: string[] | null,
+  ): Array<{ fromFile: string; importSource: string; resolvedPath: string }>;
+  computeConfidence(callerFile: string, targetFile: string, importedFrom: string | null): number;
+  detectCycles(edges: Array<{ source: string; target: string }>): string[][];
+  buildCallEdges(files: unknown[], nodes: unknown[], builtinReceivers: string[]): unknown[];
+  engineVersion(): string;
+  ParseTreeCache: new () => NativeParseTreeCache;
+}
+
+/** Native parse-tree cache instance. */
+export interface NativeParseTreeCache {
+  get(filePath: string): unknown;
+  set(filePath: string, tree: unknown): void;
+  delete(filePath: string): void;
+  clear(): void;
+}
+
+// ════════════════════════════════════════════════════════════════════════
+// §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;
+}
+
+/** Shape of a CLI command definition used by the registerCommand framework. */
+export interface CommandDefinition {
+  name: string;
+  description: string;
+  queryOpts?: boolean;
+  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
+  execute?: (args: any[], opts: any, ctx: CommandContext) => void | Promise<void>;
+  subcommands?: CommandDefinition[];
+}

package/src/vendor.d.ts

@@ -0,0 +1,39 @@
+/**
+ * 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;
+}

package/dist/index.cjs.map

@@ -1 +0,0 @@
-{"version":3,"file":"index.cjs","sourceRoot":"","sources":["../src/index.cjs"],"names":[],"mappings":";AAAA;;;;;;;;;;;GAWG;AACH,sFAAsF;AACtF,wFAAwF;AACxF,4CAA4C;AAC5C,MAAM,CAAC,OAAO,GAAG,MAAM,CAAC,YAAY,CAAC,CAAC"}

package/dist/index.d.cts

@@ -1,3 +0,0 @@
-declare const _exports: Promise<typeof import("./index.js", { with: { "resolution-mode": "import" } })>;
-export = _exports;
-//# sourceMappingURL=index.d.cts.map

package/dist/index.d.cts.map

@@ -1 +0,0 @@
-{"version":3,"file":"index.d.cts","sourceRoot":"","sources":["../src/index.cjs"],"names":[],"mappings":""}

package/src/cli/commands/models.js

@@ -1,19 +0,0 @@
-import { DEFAULT_MODEL, MODELS } from '../../domain/search/index.js';
-
-export const command = {
-  name: 'models',
-  description: 'List available embedding models',
-  execute(_args, _opts, ctx) {
-    const defaultModel = ctx.config.embeddings?.model || DEFAULT_MODEL;
-    console.log('\nAvailable embedding models:\n');
-    for (const [key, cfg] of Object.entries(MODELS)) {
-      const def = key === defaultModel ? ' (default)' : '';
-      const ctxWindow = cfg.contextWindow ? `${cfg.contextWindow} ctx` : '';
-      console.log(
-        `  ${key.padEnd(12)} ${String(cfg.dim).padStart(4)}d  ${ctxWindow.padEnd(9)} ${cfg.desc}${def}`,
-      );
-    }
-    console.log('\nUsage: codegraph embed --model <name> --strategy <structured|source>');
-    console.log('       codegraph search "query" --model <name>\n');
-  },
-};

package/src/db/repository/base.js

@@ -1,201 +0,0 @@
-/**
- * Abstract Repository base class.
- *
- * Defines the contract for all graph data access. Every method throws
- * "not implemented" by default — concrete subclasses override what they support.
- */
-export class Repository {
-  // ── Node lookups ────────────────────────────────────────────────────
-  /** @param {number} id @returns {object|undefined} */
-  findNodeById(_id) {
-    throw new Error('not implemented');
-  }
-
-  /** @param {string} file @returns {object[]} */
-  findNodesByFile(_file) {
-    throw new Error('not implemented');
-  }
-
-  /** @param {string} fileLike @returns {object[]} */
-  findFileNodes(_fileLike) {
-    throw new Error('not implemented');
-  }
-
-  /** @param {string} namePattern @param {object} [opts] @returns {object[]} */
-  findNodesWithFanIn(_namePattern, _opts) {
-    throw new Error('not implemented');
-  }
-
-  /** @returns {number} */
-  countNodes() {
-    throw new Error('not implemented');
-  }
-
-  /** @returns {number} */
-  countEdges() {
-    throw new Error('not implemented');
-  }
-
-  /** @returns {number} */
-  countFiles() {
-    throw new Error('not implemented');
-  }
-
-  /** @param {string} name @param {string} kind @param {string} file @param {number} line @returns {number|undefined} */
-  getNodeId(_name, _kind, _file, _line) {
-    throw new Error('not implemented');
-  }
-
-  /** @param {string} name @param {string} file @param {number} line @returns {number|undefined} */
-  getFunctionNodeId(_name, _file, _line) {
-    throw new Error('not implemented');
-  }
-
-  /** @param {string} file @returns {{ id: number, name: string, kind: string, line: number }[]} */
-  bulkNodeIdsByFile(_file) {
-    throw new Error('not implemented');
-  }
-
-  /** @param {number} parentId @returns {object[]} */
-  findNodeChildren(_parentId) {
-    throw new Error('not implemented');
-  }
-
-  /** @param {string} scopeName @param {object} [opts] @returns {object[]} */
-  findNodesByScope(_scopeName, _opts) {
-    throw new Error('not implemented');
-  }
-
-  /** @param {string} qualifiedName @param {object} [opts] @returns {object[]} */
-  findNodeByQualifiedName(_qualifiedName, _opts) {
-    throw new Error('not implemented');
-  }
-
-  /** @param {object} [opts] @returns {object[]} */
-  listFunctionNodes(_opts) {
-    throw new Error('not implemented');
-  }
-
-  /** @param {object} [opts] @returns {IterableIterator} */
-  iterateFunctionNodes(_opts) {
-    throw new Error('not implemented');
-  }
-
-  /** @param {object} [opts] @returns {object[]} */
-  findNodesForTriage(_opts) {
-    throw new Error('not implemented');
-  }
-
-  // ── Edge queries ────────────────────────────────────────────────────
-  /** @param {number} nodeId @returns {object[]} */
-  findCallees(_nodeId) {
-    throw new Error('not implemented');
-  }
-
-  /** @param {number} nodeId @returns {object[]} */
-  findCallers(_nodeId) {
-    throw new Error('not implemented');
-  }
-
-  /** @param {number} nodeId @returns {object[]} */
-  findDistinctCallers(_nodeId) {
-    throw new Error('not implemented');
-  }
-
-  /** @param {number} nodeId @returns {object[]} */
-  findAllOutgoingEdges(_nodeId) {
-    throw new Error('not implemented');
-  }
-
-  /** @param {number} nodeId @returns {object[]} */
-  findAllIncomingEdges(_nodeId) {
-    throw new Error('not implemented');
-  }
-
-  /** @param {number} nodeId @returns {string[]} */
-  findCalleeNames(_nodeId) {
-    throw new Error('not implemented');
-  }
-
-  /** @param {number} nodeId @returns {string[]} */
-  findCallerNames(_nodeId) {
-    throw new Error('not implemented');
-  }
-
-  /** @param {number} nodeId @returns {{ file: string, edge_kind: string }[]} */
-  findImportTargets(_nodeId) {
-    throw new Error('not implemented');
-  }
-
-  /** @param {number} nodeId @returns {{ file: string, edge_kind: string }[]} */
-  findImportSources(_nodeId) {
-    throw new Error('not implemented');
-  }
-
-  /** @param {number} nodeId @returns {object[]} */
-  findImportDependents(_nodeId) {
-    throw new Error('not implemented');
-  }
-
-  /** @param {string} file @returns {Set<number>} */
-  findCrossFileCallTargets(_file) {
-    throw new Error('not implemented');
-  }
-
-  /** @param {number} nodeId @param {string} file @returns {number} */
-  countCrossFileCallers(_nodeId, _file) {
-    throw new Error('not implemented');
-  }
-
-  /** @param {number} classNodeId @returns {Set<number>} */
-  getClassHierarchy(_classNodeId) {
-    throw new Error('not implemented');
-  }
-
-  /** @param {string} file @returns {{ caller_name: string, callee_name: string }[]} */
-  findIntraFileCallEdges(_file) {
-    throw new Error('not implemented');
-  }
-
-  // ── Graph-read queries ──────────────────────────────────────────────
-  /** @returns {{ id: number, name: string, kind: string, file: string }[]} */
-  getCallableNodes() {
-    throw new Error('not implemented');
-  }
-
-  /** @returns {{ source_id: number, target_id: number, confidence: number|null }[]} */
-  getCallEdges() {
-    throw new Error('not implemented');
-  }
-
-  /** @returns {{ id: number, name: string, file: string }[]} */
-  getFileNodesAll() {
-    throw new Error('not implemented');
-  }
-
-  /** @returns {{ source_id: number, target_id: number }[]} */
-  getImportEdges() {
-    throw new Error('not implemented');
-  }
-
-  // ── Optional table checks (default: false/undefined) ────────────────
-  /** @returns {boolean} */
-  hasCfgTables() {
-    throw new Error('not implemented');
-  }
-
-  /** @returns {boolean} */
-  hasEmbeddings() {
-    throw new Error('not implemented');
-  }
-
-  /** @returns {boolean} */
-  hasDataflowTable() {
-    throw new Error('not implemented');
-  }
-
-  /** @param {number} nodeId @returns {object|undefined} */
-  getComplexityForNode(_nodeId) {
-    throw new Error('not implemented');
-  }
-}

package/src/db/repository/dataflow.js

@@ -1,17 +0,0 @@
-import { cachedStmt } from './cached-stmt.js';
-
-// ─── Statement caches (one prepared statement per db instance) ────────────
-const _hasDataflowTableStmt = new WeakMap();
-
-/**
- * Check whether the dataflow table exists and has data.
- * @param {object} db
- * @returns {boolean}
- */
-export function hasDataflowTable(db) {
-  try {
-    return cachedStmt(_hasDataflowTableStmt, db, 'SELECT COUNT(*) AS c FROM dataflow').get().c > 0;
-  } catch {
-    return false;
-  }
-}