types.ts

/**
 * Core type definitions for codegraph.
 *
 * These interfaces serve as the migration contract — each module is migrated
 * to satisfy its interface. They capture every abstraction in the codebase:
 * symbol/edge kinds, database shapes, repository contracts, extractors,
 * parsers, builders, visitors, features, config, and the graph model.
 */

// ════════════════════════════════════════════════════════════════════════
// §1  Symbol & Edge Kind Enumerations
// ════════════════════════════════════════════════════════════════════════

/** The original 10 symbol kinds — default query scope. */
export type CoreSymbolKind =
  | 'function'
  | 'method'
  | 'class'
  | 'interface'
  | 'type'
  | 'struct'
  | 'enum'
  | 'trait'
  | 'record'
  | 'module'
  | 'namespace';

/** Sub-declaration kinds (Phase 1). Includes 'method' for class child nodes. */
export type ExtendedSymbolKind = 'parameter' | 'property' | 'constant' | 'variable' | 'method';

/** All queryable symbol kinds. */
export type SymbolKind = CoreSymbolKind | ExtendedSymbolKind;

/** Special kind used for file-level nodes in the graph. */
export type FileNodeKind = 'file';

/** Union of every kind that can appear in a node row. */
export type AnyNodeKind = SymbolKind | FileNodeKind;

/** Coupling and dependency edge kinds. */
export type CoreEdgeKind =
  | 'imports'
  | 'imports-type'
  | 'dynamic-imports'
  | 'reexports'
  | 'calls'
  | 'extends'
  | 'implements'
  | 'contains';

/** Parent/child and type relationship edges. */
export type StructuralEdgeKind = 'parameter_of' | 'receiver';

/** Dataflow-specific edge kinds. */
export type DataflowEdgeKind =
  | 'flows_to'
  | 'returns'
  | 'mutates'
  | 'def_use'
  | 'arg_in'
  | 'return_out';

/** All edge kinds that can appear in the graph. */
export type EdgeKind = CoreEdgeKind | StructuralEdgeKind;

/** Extended edge kinds including dataflow. */
export type AnyEdgeKind = EdgeKind | DataflowEdgeKind;

/** AST node kinds extracted during analysis. */
export type ASTNodeKind = 'new' | 'string' | 'regex' | 'throw' | 'await';

/** Coarse role classifications for symbols based on connectivity. */
export type CoreRole = 'entry' | 'core' | 'utility' | 'adapter' | 'dead' | 'test-only' | 'leaf';

/** Dead sub-roles — refine the coarse "dead" bucket. */
export type DeadSubRole = 'dead-leaf' | 'dead-entry' | 'dead-ffi' | 'dead-unresolved';

/** Every valid role. */
export type Role = CoreRole | DeadSubRole;

/** Supported language identifiers (from LANGUAGE_REGISTRY). */
export type LanguageId =
  | 'javascript'
  | 'typescript'
  | 'tsx'
  | 'python'
  | 'go'
  | 'rust'
  | 'java'
  | 'csharp'
  | 'ruby'
  | 'php'
  | 'hcl'
  | 'c'
  | 'cpp'
  | 'kotlin'
  | 'swift'
  | 'scala'
  | 'bash'
  | 'elixir'
  | 'lua'
  | 'dart'
  | 'zig'
  | 'haskell'
  | 'ocaml'
  | 'ocaml-interface'
  | 'fsharp'
  | 'fsharp-signature'
  | 'gleam'
  | 'clojure'
  | 'julia'
  | 'r'
  | 'erlang'
  | 'solidity'
  | 'objc'
  | 'cuda'
  | 'groovy'
  | 'verilog';

/** Engine mode selector. */
export type EngineMode = 'native' | 'wasm' | 'auto';

/** Graph export formats. */
export type ExportFormat = 'dot' | 'mermaid' | 'json' | 'graphml' | 'graphson' | 'neo4j-csv';

// ════════════════════════════════════════════════════════════════════════
// §2  Database Row Shapes
// ════════════════════════════════════════════════════════════════════════

/** A node row as stored in (and returned from) SQLite. */
export interface NodeRow {
  id: number;
  name: string;
  kind: AnyNodeKind;
  file: string;
  line: number;
  end_line: number | null;
  parent_id: number | null;
  exported: 0 | 1 | null;
  qualified_name: string | null;
  scope: string | null;
  visibility: 'public' | 'private' | 'protected' | null;
  role: Role | null;
}

/** A node row augmented with fan-in count (from findNodesWithFanIn). */
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;
  name: string;
  kind: string;
  line: number;
}

/** A child node row (from findNodeChildren). */
export interface ChildNodeRow {
  name: string;
  kind: SymbolKind;
  line: number;
  end_line: number | null;
  qualified_name: string | null;
  scope: string | null;
  visibility: 'public' | 'private' | 'protected' | null;
  file?: string;
}

/** An edge row as stored in SQLite. */
export interface EdgeRow {
  id: number;
  source_id: number;
  target_id: number;
  kind: EdgeKind;
  confidence: number | null;
  dynamic: 0 | 1;
  dynamic_kind?: string | null;
}

/** Callee/caller node shape (from findCallees / findCallers). */
export interface RelatedNodeRow {
  id: number;
  name: string;
  kind: string;
  file: string;
  line: number;
  end_line?: number | null;
}

/** An incoming/outgoing edge with the related node info. */
export interface AdjacentEdgeRow {
  name: string;
  kind: string;
  file: string;
  line: number;
  edge_kind: EdgeKind;
}

/** Import target/source row. */
export interface ImportEdgeRow {
  file: string;
  edge_kind: EdgeKind;
}

/** Intra-file call edge (from findIntraFileCallEdges). */
export interface IntraFileCallEdge {
  caller_name: string;
  callee_name: string;
}

/** Callable node row (for graph-read queries). */
export interface CallableNodeRow {
  id: number;
  name: string;
  kind: string;
  file: string;
}

/** Call edge row (for graph-read queries). */
export interface CallEdgeRow {
  source_id: number;
  target_id: number;
  confidence: number | null;
}

/** File node row (for graph-read queries). */
export interface FileNodeRow {
  id: number;
  name: string;
  file: string;
}

/** Import edge row (for graph-read queries). */
export interface ImportGraphEdgeRow {
  source_id: number;
  target_id: number;
}

/** Complexity metrics (from getComplexityForNode). */
export interface ComplexityMetrics {
  cognitive: number;
  cyclomatic: number;
  max_nesting: number;
  maintainability_index: number | null;
  halstead_volume: number | null;
}

// ════════════════════════════════════════════════════════════════════════
// §3  Repository Interface
// ════════════════════════════════════════════════════════════════════════

/** Query options common across many repository methods. */
export interface QueryOpts {
  kind?: SymbolKind;
  kinds?: SymbolKind[];
  /** Partial-match file filter. Repeatable on the CLI (`-f/--file`), so a single value arrives as a one-element array. */
  file?: string | string[];
  noTests?: boolean;
}

/** Options for listFunctionNodes / iterateFunctionNodes. */
export interface ListFunctionOpts {
  file?: string;
  pattern?: string;
  noTests?: boolean;
}

/** Options for findNodesForTriage. */
export interface TriageQueryOpts {
  kind?: string;
  role?: Role;
  noTests?: boolean;
  file?: string;
}

/**
 * Abstract Repository contract — defines all graph data access methods.
 * Concrete implementations: SqliteRepository, InMemoryRepository.
 */
export interface Repository {
  // ── Node lookups ──────────────────────────────────────────────────
  findNodeById(id: number): NodeRow | undefined;
  findNodesByFile(file: string): NodeRow[];
  findFileNodes(fileLike: string): NodeRow[];
  findNodesWithFanIn(namePattern: string, opts?: QueryOpts): NodeRowWithFanIn[];
  countNodes(): number;
  countEdges(): number;
  countFiles(): number;
  getNodeId(name: string, kind: string, file: string, line: number): number | undefined;
  getFunctionNodeId(name: string, file: string, line: number): number | undefined;
  bulkNodeIdsByFile(file: string): NodeIdRow[];
  findNodeChildren(parentId: number): ChildNodeRow[];
  findNodesByScope(scopeName: string, opts?: QueryOpts): NodeRow[];
  findNodeByQualifiedName(qualifiedName: string, opts?: { file?: string }): NodeRow[];
  listFunctionNodes(opts?: ListFunctionOpts): NodeRow[];
  iterateFunctionNodes(opts?: ListFunctionOpts): IterableIterator<NodeRow>;
  findNodesForTriage(opts?: TriageQueryOpts): TriageNodeRow[];

  // ── Edge queries ──────────────────────────────────────────────────
  findCallees(nodeId: number): RelatedNodeRow[];
  findCallers(nodeId: number): RelatedNodeRow[];
  findCallersBatch(nodeIds: number[]): Map<number, RelatedNodeRow[]>;
  findDistinctCallers(nodeId: number): RelatedNodeRow[];
  findAllOutgoingEdges(nodeId: number): AdjacentEdgeRow[];
  findAllIncomingEdges(nodeId: number): AdjacentEdgeRow[];
  findCalleeNames(nodeId: number): string[];
  findCallerNames(nodeId: number): string[];
  findImportTargets(nodeId: number): ImportEdgeRow[];
  findImportSources(nodeId: number): ImportEdgeRow[];
  findImportDependents(nodeId: number): NodeRow[];
  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 ────────────────────────────────────────────
  getCallableNodes(): CallableNodeRow[];
  getCallEdges(): CallEdgeRow[];
  getFileNodesAll(): FileNodeRow[];
  getImportEdges(): ImportGraphEdgeRow[];

  // ── Optional table checks ─────────────────────────────────────────
  hasCfgTables(): boolean;
  hasEmbeddings(): boolean;
  hasDataflowTable(): boolean;
  getComplexityForNode(nodeId: number): ComplexityMetrics | undefined;

  // ── Convenience queries ──────────────────────────────────────────
  getFileHash(file: string): string | null;
  hasImplementsEdges(): boolean;
  hasCoChangesTable(): boolean;

  // ── Composite queries ──────────────────────────────────────────────
  fnDeps(
    name: string,
    opts?: { depth?: number; noTests?: boolean; file?: string | string[]; kind?: string },
  ): {
    name: string;
    results: Array<{
      name: string;
      kind: string;
      file: string;
      line: number | null;
      endLine: number | null;
      role: string | null;
      fileHash: string | null;
      callees: Array<{ name: string; kind: string; file: string; line: number | null }>;
      callers: Array<{
        name: string;
        kind: string;
        file: string;
        line: number | null;
        viaHierarchy?: string;
      }>;
      transitiveCallers: Record<
        number,
        Array<{ name: string; kind: string; file: string; line: number | null }>
      >;
    }>;
  } | null;
}

/**
 * In-memory repository — mutable, used for testing and incremental builds.
 * Extends Repository with mutation methods.
 */
export interface MutableRepository extends Repository {
  addNode(attrs: {
    name: string;
    kind: AnyNodeKind;
    file: string;
    line: number;
    end_line?: number;
    parent_id?: number;
    exported?: 0 | 1;
    qualified_name?: string;
    scope?: string;
    visibility?: 'public' | 'private' | 'protected';
    role?: Role;
  }): number;

  addEdge(attrs: {
    source_id: number;
    target_id: number;
    kind: AnyEdgeKind;
    confidence?: number;
    dynamic?: 0 | 1;
  }): number;

  addComplexity(
    nodeId: number,
    metrics: {
      cognitive: number;
      cyclomatic: number;
      max_nesting: number;
      maintainability_index?: number;
      halstead_volume?: number;
    },
  ): void;
}

// ════════════════════════════════════════════════════════════════════════
// §4  Extractor Types
// ════════════════════════════════════════════════════════════════════════

/** A symbol definition produced by any extractor. */
export interface Definition {
  name: string;
  kind: SymbolKind;
  line: number;
  endLine?: number;
  children?: SubDeclaration[];
  visibility?: 'public' | 'private' | 'protected';
  decorators?: string[];
  /** Populated post-analysis by the complexity visitor. */
  complexity?: DefinitionComplexity;
  /** Populated post-analysis by the CFG visitor. */
  cfg?: { blocks: CfgBlock[]; edges: CfgEdge[] } | null;
}

/** Sub-declaration (child) within a definition. */
export interface SubDeclaration {
  name: string;
  kind: 'parameter' | 'property' | 'constant' | 'method';
  line: number;
  endLine?: number;
  visibility?: 'public' | 'private' | 'protected';
  decorators?: string[];
}

/** Complexity metrics attached to a definition post-analysis. */
export interface DefinitionComplexity {
  cognitive: number;
  cyclomatic: number;
  maxNesting: number;
  halstead?: HalsteadDerivedMetrics | HalsteadMetrics;
  loc?: LOCMetrics;
  maintainabilityIndex?: number;
}

/** Halstead software science metrics. */
export interface HalsteadMetrics {
  volume: number;
  difficulty: number;
  effort: number;
  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;
  sloc: number;
  commentLines: number;
}

/**
 * Taxonomy for dynamic/computed call sites — distinguishes resolvable kinds
 * (computed-literal, reflection) from flag-only kinds (eval, computed-key,
 * unresolved-dynamic) that cannot be resolved statically.
 */
export type DynamicKind =
  | 'computed-literal' // obj["foo"]()    — resolvable; already emitted as normal edge
  | 'computed-key' // obj[k]()        — potentially resolvable via pts; else flagged
  | 'reflection' // .call/.apply/.bind / Reflect.* / callable-ref — resolved when target is in codebase; sink edge emitted if unresolved
  | 'eval' // eval() / new Function() — undecidable; always flagged
  | 'unresolved-dynamic' // any other detected dynamic pattern; flagged
  | 'value-ref'; // bare identifier used as a value reference rather than a call site — object-literal property value (dispatch-table pattern, e.g. `{ resolve: someFn }`, #1771) or assignment to a Lua global/builtin identifier (e.g. `require = tracedRequire`, #1776) — resolved only against function/method-kind targets; unresolved (e.g. plain data references) are dropped silently, NOT flagged

/** A function/method call detected by an extractor. */
export interface Call {
  name: string;
  line: number;
  receiver?: string;
  dynamic?: boolean;
  dynamicKind?: DynamicKind;
  /** Raw key/arg text — used for diagnostics and future RES-1 const-string resolution. */
  keyExpr?: string;
}

/** An import statement detected by an extractor. */
export interface Import {
  source: string;
  names: string[];
  line: number;
  // Standard flags
  typeOnly?: boolean;
  reexport?: boolean;
  wildcardReexport?: boolean;
  dynamicImport?: boolean;
  /**
   * For `import { X as Y }` specifiers: the local binding name (Y) mapped to
   * the original name exported by the source module (X). `names` always
   * carries the local (post-rename) binding — this field lets call-edge
   * resolution recover the *original* symbol name to look up in the imported
   * file when a call site uses the local alias (#1730). Only populated for
   * specifiers that actually rename a binding; entries where local === source
   * name are omitted. Not populated for `export { X as Y } from …` reexports
   * — barrel/reexport tracing is a distinct mechanism (see resolveBarrelExport).
   */
  renamedImports?: Array<{ local: string; imported: string }>;
  // Language-specific flags (mutually exclusive at runtime)
  pythonImport?: boolean;
  goImport?: boolean;
  rustUse?: boolean;
  javaImport?: boolean;
  csharpUsing?: boolean;
  rubyRequire?: boolean;
  phpUse?: boolean;
  cInclude?: boolean;
  kotlinImport?: boolean;
  swiftImport?: boolean;
  scalaImport?: boolean;
  bashSource?: boolean;
}

/** A class/struct/trait relationship (extends or implements). */
export interface ClassRelation {
  name: string;
  extends?: string;
  implements?: string;
  line: number;
}

/** A named export from a module. */
export interface Export {
  name: string;
  kind: SymbolKind;
  line: number;
}

/** A type-map entry for call resolution confidence scoring. */
export interface TypeMapEntry {
  type: string;
  confidence: number;
}

/**
 * A variable assignment from a call expression, recorded during extraction for
 * cross-file return-type propagation (Phase 8.2).
 */
export interface CallAssignment {
  /** Variable being assigned to. */
  varName: string;
  /** Name of the function or method being called. */
  calleeName: string;
  /** Resolved receiver type, if the call is a method call (e.g. service.getRepo()). */
  receiverTypeName?: string;
}

/**
 * A function-reference binding recorded during extraction for points-to analysis (Phase 8.3).
 * Captures `const fn = handler` or `const fn = obj.method` patterns where the right-hand
 * side is a named function reference (not a call expression or literal).
 */
export interface FnRefBinding {
  /** Variable being assigned (the left-hand side identifier). */
  lhs: string;
  /** Named function/property on the right-hand side. */
  rhs: string;
  /** If rhs is a member expression (obj.method), the receiver object name. */
  rhsReceiver?: string;
}

/**
 * An argument-to-parameter binding at a call site, recorded for parameter-flow
 * points-to analysis (Phase 8.3c). Captures `f(x)` where `x` is an identifier
 * that may carry a function reference into `f`'s parameter.
 */
export interface ParamBinding {
  /** The function being called at the call site. */
  callee: string;
  /** Zero-based index of the argument. */
  argIndex: number;
  /** Identifier name of the argument being passed. */
  argName: string;
}

/**
 * A this-context binding recorded when `fn.call(namedCtx, ...)` or
 * `fn.apply(namedCtx, ...)` is seen. Seeds `fn::this → namedCtx` in the
 * points-to map so that `this()` calls inside `fn` resolve to `namedCtx`.
 */
export interface ThisCallBinding {
  /** The function being invoked via .call() or .apply(). */
  callee: string;
  /** The identifier passed as the `this` context (first argument). */
  thisArg: string;
}

/**
 * An array-element binding: `const arr = [fn1, fn2]` records each named function
 * stored at a specific index. Phase 8.3e: array-element pts tracking.
 */
export interface ArrayElemBinding {
  arrayName: string;
  index: number;
  elemName: string;
}

/**
 * A spread-argument binding: `f(...arr)` records that `arr` is spread into `f`'s
 * parameter list starting at `startIndex`. Phase 8.3e.
 */
export interface SpreadArgBinding {
  callee: string;
  arrayName: string;
  startIndex: number;
}

/**
 * A for-of iteration binding: `for (const x of arr)` records that `x` receives
 * each element of `arr` within `enclosingFunc`. Phase 8.3e.
 */
export interface ForOfBinding {
  varName: string;
  sourceName: string;
  enclosingFunc: string;
}

/**
 * An array-callback binding: `Array.from(arr, cb)` records that `cb`'s first
 * parameter receives each element of `arr`. Phase 8.3e.
 */
export interface ArrayCallbackBinding {
  sourceName: string;
  calleeName: string;
}

/**
 * An object-rest parameter binding: `function f({ a, ...rest })` records that
 * `rest` is the rest of the object passed as argument `argIndex` to `f`.
 * Phase 8.3f: object destructuring rest dispatch.
 */
export interface ObjectRestParamBinding {
  /** Function that owns this rest parameter, e.g. "f3" */
  callee: string;
  /** Name of the rest binding, e.g. "eerest" */
  restName: string;
  /** Zero-based index of the argument whose rest is bound, e.g. 0 */
  argIndex: number;
}

/**
 * An object-property binding: `const obj = { e4 }` or `const obj = { e4: fn }` records
 * that `obj.e4` points to the named function `fn`. Phase 8.3f.
 */
export interface ObjectPropBinding {
  /** Variable holding the object, e.g. "obj" */
  objectName: string;
  /** Property name, e.g. "e4" */
  propName: string;
  /** Named function value, e.g. "e4" or "fn" */
  valueName: string;
}

/** The normalized output shape returned by every language extractor. */
export interface ExtractorOutput {
  definitions: Definition[];
  calls: Call[];
  imports: Import[];
  classes: ClassRelation[];
  exports: Export[];
  typeMap: Map<string, TypeMapEntry>;
  /**
   * Maps function/method names to their declared or inferred return types.
   * Keys: plain name (e.g. "createUser") or qualified name (e.g. "UserService.getUser").
   * Populated by JS/TS extractor; used for inter-procedural type propagation (Phase 8.2).
   */
  returnTypeMap?: Map<string, TypeMapEntry>;
  /**
   * Variable assignments from call expressions that could not be resolved from the
   * per-file returnTypeMap. Consumed by build-edges.ts to propagate cross-file return types.
   */
  callAssignments?: CallAssignment[];
  /**
   * Function-reference bindings for points-to analysis (Phase 8.3).
   * Records `const fn = handler` and `const fn = obj.method` patterns so the
   * edge builder can follow aliases when a call target has no direct definition.
   */
  fnRefBindings?: FnRefBinding[];
  /**
   * Argument-to-parameter bindings for parameter-flow points-to analysis (Phase 8.3c).
   * Records `f(x)` call sites where `x` is an identifier, enabling the pts solver
   * to propagate function references through function parameters.
   */
  paramBindings?: ParamBinding[];
  /** Phase 8.3e: array-element bindings from `const arr = [fn1, fn2]` patterns. */
  arrayElemBindings?: ArrayElemBinding[];
  /** Phase 8.3e: spread-argument bindings from `f(...arr)` call sites. */
  spreadArgBindings?: SpreadArgBinding[];
  /** Phase 8.3e: for-of iteration variable bindings. */
  forOfBindings?: ForOfBinding[];
  /** Phase 8.3e: array callback bindings from Array.from/forEach/etc. */
  arrayCallbackBindings?: ArrayCallbackBinding[];
  /** Phase 8.3f: object-rest parameter bindings from `function f({ ...rest })` patterns. */
  objectRestParamBindings?: ObjectRestParamBinding[];
  /** Phase 8.3f: object-property bindings from `const obj = { fn }` patterns. */
  objectPropBindings?: ObjectPropBinding[];
  /**
   * This-context bindings from `fn.call(namedCtx, ...)` / `fn.apply(namedCtx, ...)`.
   * Seeds `fn::this → namedCtx` in the points-to map so that `this()` calls inside
   * `fn` resolve to `namedCtx` when `fn` is invoked via `.call()`/`.apply()`.
   */
  thisCallBindings?: ThisCallBinding[];
  /**
   * Phase 8.5 (RTA): constructor names from all `new X()` expressions in the file,
   * including unassigned ones (e.g. `doSomething(new Foo())`). Used to build the
   * project-wide instantiated-types set for Rapid Type Analysis filtering.
   */
  newExpressions?: readonly string[];
  /**
   * Object.defineProperty receiver bindings: maps function name → target object name.
   * Records `Object.defineProperty(obj, "bar", { get: getter })` so the edge builder
   * can resolve `this.X()` calls inside `getter` as `obj.X()` (this === obj when the
   * accessor is invoked through the property).
   *
   * Example: `Object.defineProperty(obj, "bar", { get: getter })` emits
   * `definePropertyReceivers.set("getter", "obj")`.
   */
  definePropertyReceivers?: Map<string, string>;
  /**
   * CJS require bindings from `const { X, Y } = require('./path')` patterns.
   * Used by buildImportedNamesMap to classify X and Y as import artifacts so
   * receiver-edge resolution falls back to the global class lookup rather than
   * treating the destructured-binding function node as a local definition (#1661).
   * Does NOT cause DB import edges — use `imports` for that.
   */
  cjsRequireBindings?: Array<{ names: string[]; source: string }>;
  /** WASM tree retained for downstream analysis (complexity, CFG, dataflow). */
  _tree?: TreeSitterTree;
  /** Language identifier. */
  _langId?: LanguageId;
  /** Line count for metrics. */
  _lineCount?: number;
  /** Dataflow results, populated post-analysis. */
  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. */
export type ExtractorFn = (
  tree: TreeSitterTree,
  filePath: string,
  query?: TreeSitterQuery,
) => ExtractorOutput;

// ════════════════════════════════════════════════════════════════════════
// §5  Parser & Language Registry
// ════════════════════════════════════════════════════════════════════════

/** A single entry in the LANGUAGE_REGISTRY. */
export interface LanguageRegistryEntry {
  id: LanguageId;
  extensions: string[];
  grammarFile: string;
  extractor: ExtractorFn;
  required: boolean;
}

/** tree-sitter opaque types (thin wrappers — real impl is WASM). */
export interface TreeSitterNode {
  id: number;
  type: string;
  text: string;
  /**
   * Whether this node is a named grammar production vs. an anonymous token
   * (keyword/punctuation). Tree-sitter grammars can define an anonymous
   * token whose text matches a *named* node's type string — e.g.
   * tree-sitter-typescript's `predefined_type` wraps an anonymous `string`
   * keyword token that collides with the named `string` literal node type
   * (#1729). Consumers matching by `type` alone must also check `isNamed`
   * to avoid misclassifying keyword tokens as literal/expression nodes.
   */
  isNamed: boolean;
  startPosition: { row: number; column: number };
  endPosition: { row: number; column: number };
  childCount: number;
  namedChildCount: number;
  child(index: number): TreeSitterNode | null;
  namedChild(index: number): TreeSitterNode | null;
  childForFieldName(name: string): TreeSitterNode | null;
  fieldNameForChild(index: number): string | null;
  parent: TreeSitterNode | null;
  previousSibling: TreeSitterNode | null;
  nextSibling: TreeSitterNode | null;
  children: TreeSitterNode[];
  namedChildren: TreeSitterNode[];
}

export interface TreeSitterTree {
  rootNode: TreeSitterNode;
}

export interface TreeSitterQuery {
  matches(node: TreeSitterNode): TreeSitterQueryMatch[];
  captures(node: TreeSitterNode): TreeSitterQueryCapture[];
}

export interface TreeSitterQueryMatch {
  pattern: number;
  captures: TreeSitterQueryCapture[];
}

export interface TreeSitterQueryCapture {
  name: string;
  node: TreeSitterNode;
}

// ════════════════════════════════════════════════════════════════════════
// §6  Import Resolution
// ════════════════════════════════════════════════════════════════════════

/** A single import to resolve. */
export interface ImportBatchItem {
  fromFile: string;
  importSource: string;
}

/** Batch of imports to resolve. */
export type ImportBatch = ImportBatchItem[];

/** Result of resolveImportsBatch: Map<"fromFile|importSource", resolvedPath>. */
export type BatchResolvedMap = Map<string, string>;

/** Path aliases from tsconfig/jsconfig. */
export interface PathAliases {
  baseUrl: string | null;
  paths: Record<string, string[]>;
}

/** Parsed bare specifier. */
export interface BareSpecifier {
  packageName: string;
  subpath: string;
}

// ════════════════════════════════════════════════════════════════════════
// §7  AST Visitor System
// ════════════════════════════════════════════════════════════════════════

/** Shared context mutated during the DFS walk. */
export interface VisitorContext {
  nestingLevel: number;
  currentFunction: TreeSitterNode | null;
  langId: string;
  scopeStack: ScopeEntry[];
}

/** An entry on the scope stack. */
export interface ScopeEntry {
  funcName: string | null;
  funcNode: TreeSitterNode;
  params: Map<string, unknown>;
  locals: Map<string, unknown>;
}

/** Return value from enterNode — request skip of descendants. */
export interface EnterNodeResult {
  skipChildren?: boolean;
}

/** A pluggable analysis visitor for the unified DFS walker. */
export interface Visitor {
  name: string;
  init?(langId: string): void;
  enterNode?(node: TreeSitterNode, context: VisitorContext): EnterNodeResult | undefined;
  exitNode?(node: TreeSitterNode, context: VisitorContext): void;
  enterFunction?(funcNode: TreeSitterNode, funcName: string | null, context: VisitorContext): void;
  exitFunction?(funcNode: TreeSitterNode, funcName: string | null, context: VisitorContext): void;
  finish?(): unknown;
  functionNodeTypes?: Set<string>;
}

/** Options for walkWithVisitors. */
export interface WalkOptions {
  functionNodeTypes?: Set<string>;
  nestingNodeTypes?: Set<string>;
  getFunctionName?: (node: TreeSitterNode) => string | null;
}

/** Result of walkWithVisitors: Map of visitor.name → finish() result. */
export type WalkResults = Record<string, unknown>;

// ════════════════════════════════════════════════════════════════════════
// §8  AST Analysis Engine
// ════════════════════════════════════════════════════════════════════════

/** Toggles for runAnalyses. */
export interface AnalysisOpts {
  ast?: boolean;
  complexity?: boolean;
  cfg?: boolean;
  dataflow?: boolean;
}

/** Timing output from runAnalyses. */
export interface AnalysisTiming {
  astMs: number;
  complexityMs: number;
  cfgMs: number;
  dataflowMs: number;
  /**
   * Diagnostic: total wall-clock time for the unified walk loop (includes
   * setupVisitors overhead). Walk time is already distributed equally into
   * the per-phase timers above, so this overlaps — it is not an additive
   * bucket. Useful for cross-checking that Σ phase timers ≈ this value.
   */
  _unifiedWalkMs?: number;
}

/** An AST node row stored in the database. */
export interface ASTNodeRow {
  node_id: number;
  kind: ASTNodeKind;
  line: number;
  text: string;
}

/** AST type mapping: tree-sitter node type → analysis kind. */
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 {
  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 (merged result of DATAFLOW_DEFAULTS + overrides). */
export interface DataflowRulesConfig {
  functionNodes: Set<string>;
  nameField: string;
  /** Override for languages with nested function name structures (e.g. C/C++). */
  nameExtractor: ((node: TreeSitterNode) => string | null) | null;
  varAssignedFnParent: string | null;
  assignmentFnParent: string | null;
  pairFnParent: string | null;
  paramListField: string;
  /** Override for languages where the param list is nested (e.g. C: function_definition → declarator → parameters). */
  getParamListNode: ((funcNode: TreeSitterNode) => TreeSitterNode | null) | null;
  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. */
export interface CfgBlock {
  id: number;
  label: string;
  startLine: number;
  endLine: number;
}

/** An edge in a control flow graph. */
export interface CfgEdge {
  from: number;
  to: number;
  label?: string;
}

/**
 * A dataflow vertex: an addressable data location within a function.
 * Populated during extraction (P1+); persisted to `dataflow_vertices`.
 */
export interface DataflowVertex {
  /** Name of the enclosing function (used to resolve func_id at insert time). */
  funcName: string;
  /** Vertex kind: 'param' | 'local' | 'return' | 'receiver'. */
  kind: 'param' | 'local' | 'return' | 'receiver';
  name?: string;
  paramIndex?: number;
  line?: number;
}

/** Dataflow extraction result. */
export interface DataflowResult {
  parameters: DataflowParam[];
  returns: DataflowReturn[];
  assignments: DataflowAssignment[];
  argFlows: DataflowArgFlow[];
  mutations: DataflowMutation[];
}

export interface DataflowParam {
  name: string;
  funcName: string;
  line: number;
  typeHint?: string;
}

export interface DataflowReturn {
  funcName: string;
  line: number;
  expression: string;
}

export interface DataflowAssignment {
  name: string;
  line: number;
  expression: string;
}

export interface DataflowArgFlow {
  callerFunc: string;
  callee: string;
  argIndex: number;
  binding: { name: string; type: 'param' | 'local' | 'unknown' };
  line: number;
}

export interface DataflowMutation {
  binding: { name: string; type: 'param' | 'local' | 'unknown' };
  mutatingExpr: string;
  line: number;
}

// ════════════════════════════════════════════════════════════════════════
// §10  Build Pipeline
// ════════════════════════════════════════════════════════════════════════

/** Engine options for the build pipeline. */
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. */
export interface ParseChange {
  file: string;
  relPath?: string;
  content?: string;
  hash?: string;
  stat?: { mtime: number; size: number };
  _reverseDepOnly?: boolean;
}

/** Metadata-only self-heal update. */
export interface MetadataUpdate {
  relPath: string;
  hash: string;
  stat: { mtime: number; size: number };
}

/** A file queued for parsing. */
export interface FileToParse {
  file: string;
  relPath?: string;
}

/** Shared mutable state threaded through all build stages. */
export interface PipelineContext {
  // Inputs (set during setup)
  rootDir: string;
  db: unknown; // better-sqlite3.Database
  dbPath: string;
  config: CodegraphConfig;
  opts: BuildGraphOpts;
  engineOpts: EngineOpts;
  engineName: 'native' | 'wasm';
  engineVersion: string | null;
  aliases: PathAliases;
  incremental: boolean;
  forceFullRebuild: boolean;
  schemaVersion: number;

  // File collection
  allFiles: string[];
  discoveredDirs: Set<string>;

  // Change detection
  isFullBuild: boolean;
  parseChanges: ParseChange[];
  metadataUpdates: MetadataUpdate[];
  removed: string[];
  earlyExit: boolean;

  // Parsing
  allSymbols: Map<string, ExtractorOutput>;
  fileSymbols: Map<string, ExtractorOutput>;
  filesToParse: FileToParse[];

  // Import resolution
  batchResolved: BatchResolvedMap | null;
  reexportMap: Map<string, unknown[]>;
  barrelOnlyFiles: Set<string>;

  // Node lookup
  nodesByName: Map<string, NodeRow[]>;
  nodesByNameAndFile: Map<string, NodeRow[]>;

  // Misc state
  hasEmbeddings: boolean;
  lineCountMap: Map<string, number>;

  // Phase timing
  timing: {
    setupMs?: number;
    collectMs?: number;
    detectMs?: number;
    parseMs?: number;
    insertMs?: number;
    resolveMs?: number;
    edgesMs?: number;
    structureMs?: number;
    rolesMs?: number;
    astMs?: number;
    complexityMs?: number;
    cfgMs?: number;
    dataflowMs?: number;
    finalizeMs?: number;
    [key: string]: number | undefined;
  };
  buildStart: number;
}

/** Options for buildGraph. */
export interface BuildGraphOpts {
  incremental?: boolean;
  engine?: EngineMode;
  dataflow?: boolean;
  ast?: boolean;
  complexity?: boolean;
  cfg?: boolean;
  scope?: string[];
  /**
   * Glob patterns merged on top of `config.exclude` for this build only.
   * Lets callers extend exclusion programmatically without writing a config
   * file — used by the benchmark scripts to skip resolution-benchmark
   * fixtures that aren't representative of real code.
   */
  exclude?: string[];
  skipRegistry?: boolean;
  /**
   * Override the graph.db location. Resolved absolute. When omitted, the
   * pipeline writes to `<rootDir>/.codegraph/graph.db` — same default as
   * `findDbPath` for every other DB-scoped command.
   */
  dbPath?: string;
  /**
   * User-config override for this build (from --user-config / --no-user-config).
   * - false          → --no-user-config: skip global layer for this run
   * - string         → --user-config <path>: apply the given file
   * - true           → --user-config (bare): apply the default global file
   * - undefined      → honour per-repo consent from the registry (normal)
   */
  userConfig?: string | boolean;
  /**
   * When true, an interactive consent prompt may fire on first build for
   * repos whose global-config consent is undecided. Only set by the CLI
   * build command when stdin/stdout are TTYs and CI is not set.
   */
  promptForConsent?: boolean;
}

/** Build timing result from buildGraph. */
export interface BuildResult {
  phases: {
    setupMs: number;
    collectMs: number;
    detectMs: number;
    parseMs: number;
    insertMs: number;
    resolveMs: number;
    edgesMs: number;
    structureMs: number;
    rolesMs: number;
    /** Wall-clock time for the CHA expansion post-pass (native path only). */
    chaMs?: number;
    /** Wall-clock time for the this/super dispatch WASM post-pass (native path only). */
    thisDispatchMs?: number;
    /** Wall-clock time for the dropped-language gap detection + backfill (native path only). */
    gapDetectMs?: number;
    /** Wall-clock time for role re-classification after JS edge-writing post-passes (native path only). */
    reclassifyMs?: number;
    /** Wall-clock time for the technique-column backfill on native-written edges (native path only). */
    techniqueBackfillMs?: number;
    astMs: number;
    complexityMs: number;
    cfgMs: number;
    dataflowMs: number;
    finalizeMs: number;
  };
}

/** A pipeline stage function. */
export type PipelineStage = (ctx: PipelineContext) => Promise<void>;

// ════════════════════════════════════════════════════════════════════════
// §11  Configuration
// ════════════════════════════════════════════════════════════════════════

export interface CodegraphConfig {
  include: string[];
  exclude: string[];
  ignoreDirs: string[];
  /** Additional directory names to ignore on top of the built-in IGNORE_DIRS set. */
  ignoreAdditionalDirs: string[];
  extensions: string[];
  aliases: Record<string, unknown>;

  build: {
    incremental: boolean;
    dbPath: string;
    driftThreshold: number;
    smallFilesThreshold: number;
    /**
     * Minimum existing file-node count for a repo to be treated as a "large
     * codebase" when deciding whether to scope node loading to changed files.
     * Used by loadNodes() in `src/domain/graph/builder/stages/build-edges.ts`.
     */
    largeCodebaseFileThreshold: number;
    /**
     * Use the TypeScript compiler API to enrich typeMap for .ts/.tsx files.
     * Improves method-call edge accuracy for patterns like `const svc = container.get<MyService>()`.
     * Disabled by default because `ts.createProgram` adds ~1s overhead per build;
     * enable in `.codegraphrc.json` when you need accurate type-resolved call edges.
     * Default: false.
     */
    typescriptResolver: boolean;
    /**
     * Engine selection override. Values: `'auto'` (default), `'native'`, `'wasm'`.
     *
     * **Current wiring (partial):** This field is populated by `applyEnvOverrides`
     * from `CODEGRAPH_ENGINE` env var — env var → `config.build.engine`. The
     * `--engine` CLI flag is also forwarded. However, `connection.ts` and
     * `pipeline.ts` still read `process.env.CODEGRAPH_ENGINE` / `ctx.opts.engine`
     * directly, so a value set only in `.codegraphrc.json` (not via env var or CLI)
     * is silently ignored by the pipeline.
     *
     * Full config-file wiring is tracked in issue #1596.
     */
    engine: 'auto' | 'native' | 'wasm';
    /**
     * Enable diagnostic logging for the native fast-skip pre-flight check.
     * Equivalent to `CODEGRAPH_FAST_SKIP_DIAG=1`. When true, logs why the
     * fast-skip gate was skipped (e.g. forceFullRebuild, engineName mismatch).
     * Default: false.
     */
    fastSkipDiag: boolean;
    /**
     * Max stdout buffer size (bytes) for the `git check-ignore` subprocess spawned via
     * `execFileSync` in the native-orchestrator build stage (used to filter gitignored
     * files out of the dropped-language-gap detection). Default: 104857600 (100 MB).
     */
    execMaxBufferBytes: number;
  };

  db: {
    /**
     * SQLite `busy_timeout` pragma (ms) applied to every opened connection.
     * See `busyTimeoutMs` in `src/infrastructure/config.ts` for wiring status.
     */
    busyTimeoutMs: number;
  };

  query: {
    defaultDepth: number;
    defaultLimit: number;
    excludeTests: boolean;
  };

  embeddings: {
    model: string | null;
    llmProvider: string | null;
    /**
     * Embedding backend for `codegraph embed`. `null` (default) uses the
     * local bundled model via `@huggingface/transformers`. `"openai"` calls
     * a remote OpenAI-compatible `/embeddings` endpoint configured via
     * `llm.baseUrl` — this covers self-hosted servers (text-embeddings-inference,
     * Ollama, LM Studio, vLLM, etc.) that implement the same request/response
     * shape, not just OpenAI itself. When set, `embeddings.model` must be the
     * model identifier the endpoint expects.
     */
    provider: string | null;
  };

  llm: {
    provider: string | null;
    model: string | null;
    baseUrl: string | null;
    apiKey: string | null;
    /**
     * Command that prints the API key to stdout. Must be a single string —
     * it is split on whitespace and executed via `execFileSync` with no shell,
     * so shell features like `$(...)`, pipes, globs, or variable expansion are
     * not supported. Example: `"op read op://vault/openai/api-key"`. Non-string
     * values are rejected with a `ConfigError` at load time.
     */
    apiKeyCommand: string | null;
    /**
     * Per-request timeout (ms) for remote HTTP calls made against `llm.baseUrl`
     * (currently the remote embedding provider). Prevents an unresponsive
     * self-hosted server from hanging the process indefinitely. Default: 120000.
     */
    requestTimeoutMs: number;
    /**
     * Timeout (ms) for the `apiKeyCommand` subprocess spawned via `execFileSync`.
     * Prevents a hung secret-manager CLI from blocking config loading indefinitely.
     * Default: 10000.
     */
    apiKeyCommandTimeoutMs: number;
    /**
     * Max stdout buffer size (bytes) for the `apiKeyCommand` subprocess spawned via
     * `execFileSync`. Default: 65536 (64 KB).
     */
    apiKeyCommandMaxBufferBytes: number;
  };

  search: {
    defaultMinScore: number;
    rrfK: number;
    topK: number;
    similarityWarnThreshold: number;
  };

  ci: {
    failOnCycles: boolean;
    impactThreshold: number | null;
  };

  manifesto: {
    rules: ManifestoRules;
    boundaries: unknown | null;
  };

  check: {
    cycles: boolean;
    blastRadius: number | null;
    signatures: boolean;
    boundaries: boolean;
    depth: number;
    /**
     * Max stdout buffer size (bytes) for the `git diff` subprocess spawned via
     * `execFileSync` when computing changed-line ranges for `codegraph check`
     * and `codegraph diff-impact`. Default: 10485760 (10 MB).
     */
    execMaxBufferBytes: number;
  };

  coChange: {
    since: string;
    minSupport: number;
    minJaccard: number;
    maxFilesPerCommit: number;
    /**
     * Max stdout buffer size (bytes) for the `git log` subprocess spawned via
     * `execFileSync` when scanning commit history for co-change analysis.
     * Default: 52428800 (50 MB).
     */
    execMaxBufferBytes: number;
  };

  analysis: {
    impactDepth: number;
    fnImpactDepth: number;
    auditDepth: number;
    sequenceDepth: number;
    falsePositiveCallers: number;
    briefCallerDepth: number;
    briefImporterDepth: number;
    briefHighRiskCallers: number;
    briefMediumRiskCallers: number;
    /** Maximum chain depth for inter-procedural return-type propagation (Phase 8.2). */
    typePropagationDepth: number;
    /**
     * Maximum fixed-point iterations for the Phase 8.3 points-to solver.
     * Wired as the default `maxIterations` parameter of `buildPointsToMap()`
     * in `src/domain/graph/resolver/points-to.ts`. The build pipeline (which
     * already holds a resolved config) passes this value through explicitly
     * to both the WASM solver and, via `native.buildCallEdges()` / the
     * `BuildConfig` JSON payload, the native Rust solver in `stages/build_edges.rs`.
     */
    pointsToMaxIterations: number;
    /**
     * Confidence score for a return type inferred from `return new Constructor()`
     * with no explicit TypeScript annotation.
     * Mirrors `INFERRED_RETURN_TYPE_CONFIDENCE` in `src/extractors/javascript.ts`.
     * @reserved — not yet wired; see TODO in `src/infrastructure/config.ts`.
     */
    typeInferenceConfidence: number;
  };

  community: {
    resolution: number;
    maxLevels: number;
    maxLocalPasses: number;
    refinementTheta: number;
    /**
     * Growth multiplier applied when a Leiden partition's per-community
     * typed arrays need to be resized to fit a larger community count.
     * See `capacityGrowthFactor` in `src/infrastructure/config.ts` for wiring status.
     */
    capacityGrowthFactor: number;
  };
  structure: { cohesionThreshold: number };

  risk: {
    weights: RiskWeights;
    roleWeights: Record<Role, number>;
    defaultRoleWeight: number;
  };

  display: {
    maxColWidth: number;
    excerptLines: number;
    summaryMaxChars: number;
    jsdocEndScanLines: number;
    jsdocOpenScanLines: number;
    signatureGatherLines: number;
  };

  mcp: {
    defaults: McpDefaults;
    disabledTools?: string[];
  };
}

export interface ManifestoRules {
  cognitive: ThresholdRule;
  cyclomatic: ThresholdRule;
  maxNesting: ThresholdRule;
  maintainabilityIndex: ThresholdRule;
  importCount: ThresholdRule;
  exportCount: ThresholdRule;
  lineCount: ThresholdRule;
  fanIn: ThresholdRule;
  fanOut: ThresholdRule;
  noCycles: ThresholdRule;
  boundaries: ThresholdRule;
}

export interface ThresholdRule {
  warn: number | null;
  fail?: number | null;
}

export interface RiskWeights {
  fanIn: number;
  complexity: number;
  churn: number;
  role: number;
  mi: number;
}

export interface McpDefaults {
  [key: string]: number;
  list_functions: number;
  query: number;
  where: number;
  node_roles: number;
  export_graph: number;
  fn_impact: number;
  context: number;
  explain: number;
  file_deps: number;
  file_exports: number;
  diff_impact: number;
  impact_analysis: number;
  semantic_search: number;
  execution_flow: number;
  hotspots: number;
  co_changes: number;
  complexity: number;
  manifesto: number;
  communities: number;
  structure: number;
  triage: number;
  ast_query: number;
  implementations: number;
  interfaces: number;
}

/** Per-repo consent decision for the user-level global config. */
export type ConsentDecision = 'enabled' | 'disabled';

/** Which layer contributed a resolved config value. */
export type ConfigSource = 'default' | 'user' | 'project' | 'env';

/** Maps config key paths (dot notation) to the layer that supplied the value. */
export type ConfigProvenance = Record<string, ConfigSource>;

/** Result of loadConfigWithProvenance. */
export interface ConfigWithProvenance {
  config: CodegraphConfig;
  provenance: ConfigProvenance;
  /** Absolute path of the applied global file, or null if none was applied. */
  appliedGlobalPath: string | null;
  /** This repo's recorded consent decision (may be undefined if undecided). */
  consentDecision: ConsentDecision | undefined;
}

// ════════════════════════════════════════════════════════════════════════
// §12  Pagination
// ════════════════════════════════════════════════════════════════════════

export interface PaginationOpts {
  limit?: number;
  offset?: number;
}

export interface PaginationMeta {
  total: number;
  offset: number;
  limit: number;
  hasMore: boolean;
  returned: number;
}

export interface PaginatedItems<T> {
  items: T[];
  pagination?: PaginationMeta;
}

/** A result object with optional _pagination metadata. */
export type Paginated<T> = T & { _pagination?: PaginationMeta };

// ════════════════════════════════════════════════════════════════════════
// §14  Feature Module Result Shapes
// ════════════════════════════════════════════════════════════════════════

// ── Audit ────────────────────────────────────────────────────────────

export interface AuditResult {
  target: string;
  kind: 'function' | 'file';
  functions: AuditFunctionEntry[];
}

/** A single manifesto threshold breach reported against an audited function. */
export interface ThresholdBreach {
  metric: string;
  value: number;
  threshold: number;
  level: 'warn' | 'fail';
}

/** Complexity/maintainability health metrics attached to an audited function. */
export interface AuditHealthMetrics {
  cognitive: number | null;
  cyclomatic: number | null;
  maxNesting: number | null;
  maintainabilityIndex: number | null;
  halstead: HalsteadMetrics;
  loc: number;
  sloc: number;
  commentLines: number;
  thresholdBreaches: ThresholdBreach[];
}

export interface AuditFunctionEntry {
  name: string;
  kind: SymbolKind;
  file: string;
  line: number;
  endLine: number | null;
  role: Role | null;
  lineCount: number | null;
  summary: string | null;
  signature: { params: string | null; returnType: string | null } | null;
  callees: Array<{ name: string; kind: string; file: string; line: number }>;
  callers: Array<{ name: string; kind: string; file: string; line: number }>;
  relatedTests: Array<{ file: string }>;
  impact: {
    totalDependents: number;
    levels: Record<number, ImpactLevelEntry[]>;
  };
  health: AuditHealthMetrics;
  riskScore: number | null;
  complexityNotes: string | null;
  sideEffects: string | null;
}

export interface ImpactLevelEntry {
  name: string;
  kind: string;
  file: string;
  line: number;
  viaImplements?: boolean;
}

// ── Complexity ───────────────────────────────────────────────────────

export interface ComplexityResult {
  functions: ComplexityEntry[];
  summary: {
    analyzed: number;
    avgCognitive: number;
    maxCognitive: number;
    avgCyclomatic: number;
    maxCyclomatic: number;
    avgMI: number;
    minMI: number;
    aboveWarn: number;
  };
  thresholds: ManifestoRules;
  hasGraph: boolean;
}

export interface ComplexityEntry {
  name: string;
  kind: SymbolKind;
  file: string;
  line: number;
  endLine: number | null;
  cognitive: number;
  cyclomatic: number;
  maxNesting: number;
  loc: number;
  sloc: number;
  maintainabilityIndex: number;
  halstead: HalsteadMetrics;
  exceeds?: Array<'cognitive' | 'cyclomatic' | 'maxNesting' | 'maintainabilityIndex'>;
}

// ── Diff Impact ──────────────────────────────────────────────────────

export interface DiffImpactResult {
  error?: string;
  changedFiles: number;
  newFiles: string[];
  affectedFunctions: AffectedFunction[];
  affectedFiles: string[];
  historicallyCoupled?: CoChangeEntry[];
  ownership?: Record<string, string>;
  boundaryViolations?: BoundaryViolation[];
  boundaryViolationCount: number;
  summary?: DiffImpactSummary;
}

export interface AffectedFunction {
  name: string;
  kind: string;
  file: string;
  line: number;
  totalDependents: number;
  levels: Record<number, ImpactLevelEntry[]>;
}

export interface CoChangeEntry {
  file: string;
  support: number;
  jaccard: number;
}

export interface BoundaryViolation {
  from: string;
  to: string;
  rule: string;
}

export interface DiffImpactSummary {
  changedFiles: number;
  newFiles: number;
  affectedFunctions: number;
  totalDependents: number;
  boundaryViolations: number;
}

// ── Triage ───────────────────────────────────────────────────────────

export interface TriageResult {
  items: TriageEntry[];
  summary: {
    total: number;
    analyzed: number;
    avgScore: number;
    maxScore: number;
    weights: RiskWeights;
    signalCoverage: {
      complexity: number;
      churn: number;
      fanIn: number;
      mi: number;
    };
  };
  _pagination?: PaginationMeta;
}

export interface TriageEntry {
  name: string;
  kind: SymbolKind;
  file: string;
  line: number;
  role: Role | null;
  fanIn: number;
  cognitive: number;
  churn: number;
  maintainabilityIndex: number;
  normFanIn: number;
  normComplexity: number;
  normChurn: number;
  normMI: number;
  roleWeight: number;
  riskScore: number;
}

// ── Communities ───────────────────────────────────────────────────────

export interface CommunitiesResult {
  communities: CommunityEntry[];
  modularity: number;
  drift: {
    splitCandidates: Array<{ directory: string; communityCount: number }>;
    mergeCandidates: Array<{
      communityId: number;
      size: number;
      directoryCount: number;
      directories: string[];
    }>;
  };
  summary: {
    communityCount: number;
    modularity: number;
    nodeCount: number;
    driftScore: number;
  };
  _pagination?: PaginationMeta;
}

export interface CommunityEntry {
  id: number;
  size: number;
  directories: Record<string, number>;
  members?: Array<{ name: string; file: string; kind?: string }>;
}

// ── Check ────────────────────────────────────────────────────────────

export interface CheckResult {
  predicates: CheckPredicate[];
  summary: {
    total: number;
    passed: number;
    failed: number;
    changedFiles: number;
    newFiles: number;
  };
  passed: boolean;
  error?: string;
}

export interface CheckPredicate {
  name: string;
  passed: boolean;
  violations: unknown[];
  maxFound?: number;
  threshold?: number;
  note?: string;
}

// ── Batch ────────────────────────────────────────────────────────────

export type BatchCommand =
  | 'fn-impact'
  | 'context'
  | 'explain'
  | 'where'
  | 'query'
  | 'impact'
  | 'deps'
  | 'exports'
  | 'flow'
  | 'dataflow'
  | 'complexity';

export interface BatchResult {
  command: BatchCommand;
  total: number;
  succeeded: number;
  failed: number;
  results: BatchResultEntry[];
}

export interface BatchResultEntry {
  target: string;
  ok: boolean;
  data?: unknown;
  error?: string;
}

export interface MultiBatchItem {
  command: BatchCommand;
  target: string;
  opts?: Record<string, unknown>;
}

export interface MultiBatchResult {
  mode: 'multi';
  total: number;
  succeeded: number;
  failed: number;
  results: BatchResultEntry[];
}

// ── Flow ─────────────────────────────────────────────────────────────

export interface FlowResult {
  entry: FlowEntry | null;
  depth: number;
  steps: Array<{
    depth: number;
    nodes: Array<{ name: string; kind: string; file: string; line: number }>;
  }>;
  leaves: Array<{ name: string; kind: string; file: string; line: number; depth: number }>;
  cycles: Array<{ from: string; to: string; depth: number }>;
  totalReached: number;
  truncated: boolean;
  _pagination?: PaginationMeta;
}

export interface FlowEntry {
  name: string;
  kind: string;
  file: string;
  line: number;
  type: string;
  role: Role | null;
}

// ── Manifesto ────────────────────────────────────────────────────────

export type ManifestoRuleLevel = 'function' | 'file' | 'graph';

export interface ManifestoRuleDef {
  name: string;
  level: ManifestoRuleLevel;
  metric: string;
  defaults: ThresholdRule;
  reportOnly?: boolean;
}

export interface ManifestoResult {
  rules: ManifestoRuleStatus[];
  violations: ManifestoViolation[];
  summary: { total: number; passed: number; warned: number; failed: number };
  _pagination?: PaginationMeta;
}

export interface ManifestoRuleStatus {
  name: string;
  level: ManifestoRuleLevel;
  status: 'pass' | 'warn' | 'fail';
  thresholds: ThresholdRule;
  violationCount: number;
}

export interface ManifestoViolation {
  rule: string;
  level: ManifestoRuleLevel;
  value: number;
  threshold: number;
  name?: string;
  kind?: string;
  file?: string;
  line?: number;
}

// ── Exports (file) ───────────────────────────────────────────────────

export interface FileExportsResult {
  file: string;
  results: FileExportEntry[];
  reexports: Array<{ file: string }>;
  totalExported: number;
  totalInternal: number;
  totalUnused: number;
}

export interface FileExportEntry {
  name: string;
  kind: SymbolKind;
  line: number;
  endLine: number | null;
  role: Role | null;
  signature: string | null;
  summary: string | null;
  consumers: Array<{ name: string; file: string; line: number }>;
  consumerCount: number;
}

// ── Path ─────────────────────────────────────────────────────────────

export interface PathResult {
  from: string;
  to: string;
  fromCandidates: NodeRow[];
  toCandidates: NodeRow[];
  found: boolean;
  hops: number | null;
  path: PathStep[];
  alternateCount: number;
  edgeKinds: string[];
  reverse: boolean;
  maxDepth: number;
}

export interface PathStep {
  name: string;
  kind: string;
  file: string;
  line: number;
  edgeKind: AnyEdgeKind | null;
}

// ── Stats ────────────────────────────────────────────────────────────

export interface StatsResult {
  nodes: { total: number; byKind: Record<string, number> };
  edges: { total: number; byKind: Record<string, number> };
  files: Record<string, unknown>;
  cycles: { fileLevel: number; functionLevel: number };
  hotspots: unknown[];
  embeddings?: unknown;
  quality?: unknown;
  roles: Record<Role, number>;
  complexity?: unknown;
}

// ── Module Map ───────────────────────────────────────────────────────

export interface ModuleMapResult {
  limit: number;
  topNodes: ModuleMapEntry[];
  stats: { totalFiles: number; totalNodes: number; totalEdges: number };
}

export interface ModuleMapEntry {
  file: string;
  dir: string;
  inEdges: number;
  outEdges: number;
  coupling: number;
}

// ── Roles ────────────────────────────────────────────────────────────

export interface RolesResult {
  count: number;
  summary: Record<Role, number>;
  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)
// ════════════════════════════════════════════════════════════════════════

export interface RegistryEntry {
  path: string;
  dbPath: string;
  addedAt: string;
  lastAccessedAt: string;
}

export interface Registry {
  repos: Record<string, RegistryEntry>;
}

export interface RegistryListItem {
  name: string;
  path: string;
  dbPath: string;
  addedAt: string;
  lastAccessedAt: string;
}

// ════════════════════════════════════════════════════════════════════════
// §16  MCP Server
// ════════════════════════════════════════════════════════════════════════

export interface MCPServerOptions {
  multiRepo?: boolean;
  allowedRepos?: string[];
}

// ════════════════════════════════════════════════════════════════════════
// §17  Command Interface (CLI)
// ════════════════════════════════════════════════════════════════════════

export interface OptionDef {
  flags: string;
  description: string;
  default?: unknown;
}

export interface Command {
  name: string;
  description: string;
  options: OptionDef[];
  validate?(args: unknown, opts: unknown): void;
  execute(args: unknown, opts: unknown): Promise<void>;
}

// ════════════════════════════════════════════════════════════════════════
// §18  Risk Scoring
// ════════════════════════════════════════════════════════════════════════

export interface RiskInput {
  fan_in: number;
  cognitive: number;
  churn: number;
  mi: number;
  role?: Role;
}

export interface RiskScored {
  normFanIn: number;
  normComplexity: number;
  normChurn: number;
  normMI: number;
  roleWeight: number;
  riskScore: number;
}

// ════════════════════════════════════════════════════════════════════════
// §19  Sequence Diagrams
// ════════════════════════════════════════════════════════════════════════

export interface SequenceStep {
  caller: string;
  callee: string;
  depth: number;
}

export interface SequenceResult {
  entry: string;
  steps: SequenceStep[];
  participants: string[];
}

// ════════════════════════════════════════════════════════════════════════
// §20  Graph Export
// ════════════════════════════════════════════════════════════════════════

export interface ExportOpts {
  fileLevel?: boolean;
  noTests?: boolean;
  minConfidence?: number;
  limit?: number;
  offset?: number;
  direction?: string;
}

export interface ExportJSONResult {
  nodes: NodeRow[];
  edges: EdgeRow[];
  _pagination?: PaginationMeta;
}

export interface ExportGraphSONResult {
  vertices: unknown[];
  edges: unknown[];
  _pagination?: PaginationMeta;
}

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;
  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;
}

/** 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[];
  parseFilesFull?(files: string[], rootDir: string): 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[][];
  bfsTraversal(
    edges: Array<{ source: string; target: string }>,
    startIds: string[],
    maxDepth?: number | null,
    direction?: string | null,
  ): Array<{ node: string; depth: number }>;
  shortestPath(
    edges: Array<{ source: string; target: string }>,
    fromId: string,
    toId: string,
  ): string[];
  fanInOut(
    edges: Array<{ source: string; target: string }>,
  ): Array<{ node: string; fanIn: number; fanOut: number }>;
  louvainCommunities(
    edges: Array<{ source: string; target: string }>,
    nodeIds: string[],
    resolution?: number | null,
    randomSeed?: number | null,
  ): {
    assignments: Array<{ node: string; community: number }>;
    modularity: number;
  };
  buildCallEdges(
    files: unknown[],
    nodes: unknown[],
    builtinReceivers: string[],
    maxIterations: number,
  ): unknown[];
  buildImportEdges?(
    files: unknown[],
    resolvedImports: unknown[],
    fileReexports: unknown[],
    fileNodeIds: unknown[],
    barrelFiles: string[],
    rootDir: string,
    symbolNodes?: Array<{ name: string; file: string; nodeId: number }>,
  ): unknown[];
  engineVersion(): string;
  analyzeComplexity(
    source: string,
    filePath: string,
    langId?: string | null,
  ): NativeFunctionComplexityResult[];
  buildCfgAnalysis(
    source: string,
    filePath: string,
    langId?: string | null,
  ): NativeFunctionCfgResult[];
  extractDataflowAnalysis(
    source: string,
    filePath: string,
    langId?: string | null,
  ): DataflowResult | null;
  /**
   * Batch counterpart to {@link extractDataflowAnalysis}: read and analyse many
   * files in parallel (rayon) in a single NAPI call. Results are positional —
   * `null` where the file could not be read or has no dataflow rules. Optional:
   * older published addons predate this export, so callers must feature-detect
   * and fall back to per-file `extractDataflowAnalysis`.
   */
  extractDataflowAnalysisBatch?(filePaths: string[]): (DataflowResult | null)[];
  ParseTreeCache: new () => NativeParseTreeCache;
  NativeDatabase: {
    openReadWrite(dbPath: string): NativeDatabase;
    openReadonly(dbPath: string): NativeDatabase;
  };
}

/** Per-function complexity result from native standalone analysis (napi output shape). */
export interface NativeFunctionComplexityResult {
  name: string;
  line: number;
  endLine: number | null;
  complexity: {
    cognitive: number;
    cyclomatic: number;
    maxNesting: number;
    halstead?: {
      n1: number;
      n2: number;
      bigN1: number;
      bigN2: number;
      vocabulary: number;
      length: number;
      volume: number;
      difficulty: number;
      effort: number;
      bugs: number;
    };
    loc?: { loc: number; sloc: number; commentLines: number };
    maintainabilityIndex?: number | null;
  };
}

/** Per-function CFG result from native standalone analysis. */
export interface NativeFunctionCfgResult {
  name: string;
  line: number;
  endLine: number | null;
  cfg: { blocks: CfgBlock[]; edges: CfgEdge[] };
}

/** Native parse-tree cache instance. */
export interface NativeParseTreeCache {
  get(filePath: string): unknown;
  set(filePath: string, tree: unknown): void;
  delete(filePath: string): void;
  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 composite query types (fnDeps) ──────────────────────────────

export interface NativeFnDepsNode {
  name: string;
  kind: string;
  file: string;
  line: number | null;
}

export interface NativeFnDepsCallerNode {
  name: string;
  kind: string;
  file: string;
  line: number | null;
  viaHierarchy: string | null;
}

export interface NativeFnDepsTransitiveGroup {
  depth: number;
  callers: NativeFnDepsNode[];
}

export interface NativeFnDepsEntry {
  name: string;
  kind: string;
  file: string;
  line: number | null;
  endLine: number | null;
  role: string | null;
  fileHash: string | null;
  callees: NativeFnDepsNode[];
  callers: NativeFnDepsCallerNode[];
  transitiveCallers: NativeFnDepsTransitiveGroup[];
}

export interface NativeFnDepsResult {
  name: string;
  results: NativeFnDepsEntry[];
}

/** 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;
  hasImplementsEdges(): boolean;
  hasCoChangesTable(): boolean;
  getComplexityForNode(nodeId: number): NativeComplexityMetrics | null;
  getFileHash(file: string): string | null;

  // ── Composite queries ──────────────────────────────────────────────
  fnDeps(
    name: string,
    depth: number | null | undefined,
    noTests: boolean | null | undefined,
    file: string[] | null | undefined,
    kind: string | null | undefined,
  ): NativeFnDepsResult;

  // ── 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;
      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;
  }>;

  // ── Batched build-glue queries (6.18) ────────────────────────────────
  /** All file_hashes rows + table existence + max mtime in one call. */
  getFileHashData?(): {
    exists: boolean;
    rows: Array<{ file: string; hash: string; mtime: number; size: number }>;
    maxMtime: number;
  };
  /** CFG and dataflow table counts (-1 = table missing). */
  checkPendingAnalysis?(): { cfgCount: number; dataflowCount: number };
  /** Batch upsert file_hashes for metadata healing. */
  healFileMetadata?(
    entries: Array<{ file: string; hash: string; mtime: number; size: number }>,
  ): number;
  /** Find files with edges pointing to changed files. */
  findReverseDependencies?(changedFiles: string[]): string[];
  /** Node + edge counts in one call. */
  getFinalizeCounts?(): { nodeCount: number; edgeCount: number };
  /** Orphaned embeddings, stale embeddings, unused exports in one call. */
  runAdvisoryChecks?(hasEmbeddings: boolean): {
    orphanedEmbeddings: number;
    embedBuiltAt: string | null;
    unusedExports: number;
  };
  /** File_hashes count + all file paths in one call. */
  getCollectFilesData?(): { count: number; files: string[] };

  // ── 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;

  // ── Full Rust build orchestration (#695) ─────────────────────────────
  /**
   * Run the entire build pipeline in Rust with zero napi boundary crossings.
   * Returns a JSON string with timing and build result data.
   * When unavailable, the JS pipeline (runPipelineStages) is used as fallback.
   */
  buildGraph?(rootDir: string, configJson: string, aliasesJson: string, optsJson: string): string;
}

// ════════════════════════════════════════════════════════════════════════
// §14  CLI Command Framework
// ════════════════════════════════════════════════════════════════════════

/** Shared context passed to every CLI command's execute/validate functions. */
export interface CommandContext {
  config: Record<string, any>;
  resolveNoTests: (opts: any) => boolean;
  resolveQueryOpts: (opts: any) => any;
  formatSize: (bytes: number) => string;
  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]
    | [string, string, (val: string) => any, string | boolean | number]
  >;
  validate?: (args: any[], opts: any, ctx: CommandContext) => string | undefined;
  execute?: (args: any[], opts: any, ctx: CommandContext) => void | Promise<void>;
  subcommands?: CommandDefinition[];
}