@optave/codegraph 3.7.0 → 3.8.0

package/src/extractors/verilog.ts

@@ -0,0 +1,315 @@
+import type { ExtractorOutput, SubDeclaration, TreeSitterNode, TreeSitterTree } from '../types.js';
+import { findChild, nodeEndLine } from './helpers.js';
+
+/**
+ * Extract symbols from Verilog/SystemVerilog files.
+ *
+ * The tree-sitter-verilog grammar covers modules, interfaces, packages,
+ * tasks, functions, classes, always blocks, and instantiations.
+ */
+export function extractVerilogSymbols(tree: TreeSitterTree, _filePath: string): ExtractorOutput {
+  const ctx: ExtractorOutput = {
+    definitions: [],
+    calls: [],
+    imports: [],
+    classes: [],
+    exports: [],
+    typeMap: new Map(),
+  };
+
+  walkVerilogNode(tree.rootNode, ctx);
+  return ctx;
+}
+
+function walkVerilogNode(node: TreeSitterNode, ctx: ExtractorOutput): void {
+  switch (node.type) {
+    case 'module_declaration':
+      handleModuleDecl(node, ctx);
+      break;
+    case 'interface_declaration':
+      handleInterfaceDecl(node, ctx);
+      break;
+    case 'package_declaration':
+      handlePackageDecl(node, ctx);
+      break;
+    case 'class_declaration':
+      handleClassDecl(node, ctx);
+      break;
+    case 'function_declaration':
+      handleFunctionDecl(node, ctx);
+      break;
+    case 'task_declaration':
+      handleTaskDecl(node, ctx);
+      break;
+    case 'module_instantiation':
+      handleModuleInstantiation(node, ctx);
+      break;
+    case 'package_import_declaration':
+      handlePackageImport(node, ctx);
+      break;
+    case 'include_compiler_directive':
+      handleIncludeDirective(node, ctx);
+      break;
+  }
+
+  for (let i = 0; i < node.childCount; i++) {
+    const child = node.child(i);
+    if (child) walkVerilogNode(child, ctx);
+  }
+}
+
+// ── Handlers ───────────────────────────────────────────────────────────────
+
+function handleModuleDecl(node: TreeSitterNode, ctx: ExtractorOutput): void {
+  const nameNode = findModuleName(node);
+  if (!nameNode) return;
+
+  const ports = extractPorts(node);
+  ctx.definitions.push({
+    name: nameNode.text,
+    kind: 'module',
+    line: node.startPosition.row + 1,
+    endLine: nodeEndLine(node),
+    children: ports.length > 0 ? ports : undefined,
+  });
+}
+
+function handleInterfaceDecl(node: TreeSitterNode, ctx: ExtractorOutput): void {
+  const nameNode = findDeclName(node);
+  if (!nameNode) return;
+
+  ctx.definitions.push({
+    name: nameNode.text,
+    kind: 'interface',
+    line: node.startPosition.row + 1,
+    endLine: nodeEndLine(node),
+  });
+}
+
+function handlePackageDecl(node: TreeSitterNode, ctx: ExtractorOutput): void {
+  const nameNode = findDeclName(node);
+  if (!nameNode) return;
+
+  ctx.definitions.push({
+    name: nameNode.text,
+    kind: 'module',
+    line: node.startPosition.row + 1,
+    endLine: nodeEndLine(node),
+  });
+}
+
+function handleClassDecl(node: TreeSitterNode, ctx: ExtractorOutput): void {
+  const nameNode = node.childForFieldName('name');
+  if (!nameNode) return;
+
+  ctx.definitions.push({
+    name: nameNode.text,
+    kind: 'class',
+    line: node.startPosition.row + 1,
+    endLine: nodeEndLine(node),
+  });
+
+  // Superclass via extends
+  const superclass = node.childForFieldName('superclass');
+  if (superclass) {
+    ctx.classes.push({
+      name: nameNode.text,
+      extends: superclass.text,
+      line: node.startPosition.row + 1,
+    });
+  }
+}
+
+function handleFunctionDecl(node: TreeSitterNode, ctx: ExtractorOutput): void {
+  const nameNode = findFunctionOrTaskName(node, 'function_identifier');
+  if (!nameNode) return;
+
+  const parentModule = findVerilogParent(node);
+  const fullName = parentModule ? `${parentModule}.${nameNode.text}` : nameNode.text;
+
+  ctx.definitions.push({
+    name: fullName,
+    kind: 'function',
+    line: node.startPosition.row + 1,
+    endLine: nodeEndLine(node),
+  });
+}
+
+function handleTaskDecl(node: TreeSitterNode, ctx: ExtractorOutput): void {
+  const nameNode = findFunctionOrTaskName(node, 'task_identifier');
+  if (!nameNode) return;
+
+  const parentModule = findVerilogParent(node);
+  const fullName = parentModule ? `${parentModule}.${nameNode.text}` : nameNode.text;
+
+  ctx.definitions.push({
+    name: fullName,
+    kind: 'function',
+    line: node.startPosition.row + 1,
+    endLine: nodeEndLine(node),
+  });
+}
+
+function handleModuleInstantiation(node: TreeSitterNode, ctx: ExtractorOutput): void {
+  // Module instantiations are like function calls: `ModuleName instance_name(...);`
+  const moduleType = node.childForFieldName('type') || node.child(0);
+  if (!moduleType) return;
+
+  ctx.calls.push({
+    name: moduleType.text,
+    line: node.startPosition.row + 1,
+  });
+}
+
+function handlePackageImport(node: TreeSitterNode, ctx: ExtractorOutput): void {
+  // import pkg::item; or import pkg::*;
+  for (let i = 0; i < node.childCount; i++) {
+    const child = node.child(i);
+    if (!child) continue;
+    if (child.type === 'package_import_item') {
+      const text = child.text;
+      const parts = text.split('::');
+      const pkg = parts[0] ?? text;
+      const item = parts[1] ?? '*';
+      ctx.imports.push({
+        source: pkg,
+        names: [item],
+        line: node.startPosition.row + 1,
+      });
+    }
+  }
+}
+
+function handleIncludeDirective(node: TreeSitterNode, ctx: ExtractorOutput): void {
+  // `include "file.vh"
+  for (let i = 0; i < node.childCount; i++) {
+    const child = node.child(i);
+    if (child && (child.type === 'string_literal' || child.type === 'quoted_string')) {
+      const source = child.text.replace(/^["']|["']$/g, '');
+      ctx.imports.push({
+        source,
+        names: [source.split('/').pop() ?? source],
+        line: node.startPosition.row + 1,
+        cInclude: true,
+      });
+      return;
+    }
+  }
+}
+
+// ── Helpers ────────────────────────────────────────────────────────────────
+
+function findModuleName(node: TreeSitterNode): TreeSitterNode | null {
+  // Try field name first, then look for module_header > identifier
+  const nameNode = node.childForFieldName('name');
+  if (nameNode) return nameNode;
+
+  const header = findChild(node, 'module_header');
+  if (header) {
+    const id = findChild(header, 'simple_identifier') || findChild(header, 'identifier');
+    if (id) return id;
+  }
+
+  // Direct child identifier after `module` keyword
+  for (let i = 0; i < node.childCount; i++) {
+    const child = node.child(i);
+    if (child && (child.type === 'simple_identifier' || child.type === 'identifier')) return child;
+  }
+  return null;
+}
+
+function findDeclName(node: TreeSitterNode): TreeSitterNode | null {
+  const nameNode = node.childForFieldName('name');
+  if (nameNode) return nameNode;
+
+  for (let i = 0; i < node.childCount; i++) {
+    const child = node.child(i);
+    if (child && (child.type === 'simple_identifier' || child.type === 'identifier')) return child;
+  }
+  return null;
+}
+
+/**
+ * Find a function or task name by searching for the dedicated identifier node
+ * type (e.g. `function_identifier`, `task_identifier`) recursively through
+ * body declarations.  Falls back to `findDeclName` for grammars that use
+ * plain identifiers.
+ */
+function findFunctionOrTaskName(
+  node: TreeSitterNode,
+  identifierType: string,
+): TreeSitterNode | null {
+  // Try the standard approach first
+  const simple = findDeclName(node);
+  if (simple) return simple;
+
+  // Search children (including body declarations) for the dedicated identifier node
+  for (let i = 0; i < node.childCount; i++) {
+    const child = node.child(i);
+    if (!child) continue;
+    if (child.type === identifierType) return child;
+    // Look one level deeper into body declarations
+    for (let j = 0; j < child.childCount; j++) {
+      const grandchild = child.child(j);
+      if (grandchild && grandchild.type === identifierType) return grandchild;
+    }
+  }
+  return null;
+}
+
+function findVerilogParent(node: TreeSitterNode): string | null {
+  let current = node.parent;
+  while (current) {
+    if (
+      current.type === 'module_declaration' ||
+      current.type === 'interface_declaration' ||
+      current.type === 'package_declaration' ||
+      current.type === 'class_declaration'
+    ) {
+      const name = findDeclName(current) || findModuleName(current);
+      return name ? name.text : null;
+    }
+    current = current.parent;
+  }
+  return null;
+}
+
+function extractPorts(moduleNode: TreeSitterNode): SubDeclaration[] {
+  const ports: SubDeclaration[] = [];
+
+  // Look for port declarations in the module header or body
+  const collectFromNode = (node: TreeSitterNode): void => {
+    for (let i = 0; i < node.childCount; i++) {
+      const child = node.child(i);
+      if (!child) continue;
+
+      if (
+        child.type === 'ansi_port_declaration' ||
+        child.type === 'port_declaration' ||
+        child.type === 'input_declaration' ||
+        child.type === 'output_declaration' ||
+        child.type === 'inout_declaration'
+      ) {
+        const nameNode =
+          child.childForFieldName('name') ||
+          findChild(child, 'simple_identifier') ||
+          findChild(child, 'identifier');
+        if (nameNode) {
+          ports.push({ name: nameNode.text, kind: 'property', line: child.startPosition.row + 1 });
+        }
+      }
+
+      // Recurse into port list containers
+      if (
+        child.type === 'list_of_port_declarations' ||
+        child.type === 'module_header' ||
+        child.type === 'port_declaration_list'
+      ) {
+        collectFromNode(child);
+      }
+    }
+  };
+
+  collectFromNode(moduleNode);
+  return ports;
+}

package/src/features/ast.ts

@@ -12,10 +12,9 @@ import type { ASTNodeKind, BetterSqlite3Database, Definition, TreeSitterNode } f
 
 // ─── Constants ────────────────────────────────────────────────────────
 
-export const AST_NODE_KINDS: ASTNodeKind[] = ['call', 'new', 'string', 'regex', 'throw', 'await'];
+export const AST_NODE_KINDS: ASTNodeKind[] = ['new', 'string', 'regex', 'throw', 'await'];
 
 const KIND_ICONS: Record<string, string> = {
-  call: '\u0192', // ƒ
   new: '\u2295', // ⊕
   string: '"',
   regex: '/',

package/src/graph/algorithms/bfs.ts

@@ -1,3 +1,4 @@
+import { loadNative } from '../../infrastructure/native.js';
 import type { CodeGraph } from '../model.js';
 
 export interface BfsOpts {
@@ -8,6 +9,8 @@ export interface BfsOpts {
 /**
  * Breadth-first traversal on a CodeGraph.
  *
+ * Tries the native Rust implementation first, falls back to JS.
+ *
  * @returns nodeId → depth from nearest start node
  */
 export function bfs(
@@ -19,6 +22,37 @@ export function bfs(
   const direction = opts.direction ?? 'forward';
   const starts = Array.isArray(startIds) ? startIds : [startIds];
 
+  const native = loadNative();
+  if (native?.bfsTraversal) {
+    const edges = graph.toEdgeArray();
+    const nativeMaxDepth = maxDepth === Infinity ? null : maxDepth;
+    // Undirected graphs deduplicate edges to one canonical direction in toEdgeArray(),
+    // so the Rust side must traverse both directions to preserve symmetry.
+    const nativeDirection = !graph.directed ? 'both' : direction;
+    const result = native.bfsTraversal(edges, starts, nativeMaxDepth, nativeDirection);
+    const depths = new Map<string, number>();
+    for (const entry of result) {
+      depths.set(entry.node, entry.depth);
+    }
+    // The Rust side only knows nodes referenced by edges; restore any isolated start nodes.
+    for (const startId of starts) {
+      if (graph.hasNode(startId) && !depths.has(startId)) {
+        depths.set(startId, 0);
+      }
+    }
+    return depths;
+  }
+
+  return bfsJS(graph, starts, maxDepth, direction);
+}
+
+/** Pure JS fallback for BFS (used when native addon is unavailable). */
+function bfsJS(
+  graph: CodeGraph,
+  starts: string[],
+  maxDepth: number,
+  direction: string,
+): Map<string, number> {
   const depths = new Map<string, number>();
   const queue: string[] = [];
 

package/src/graph/algorithms/centrality.ts

@@ -1,3 +1,4 @@
+import { loadNative } from '../../infrastructure/native.js';
 import type { CodeGraph } from '../model.js';
 
 export interface FanInOut {
@@ -7,8 +8,37 @@ export interface FanInOut {
 
 /**
  * Fan-in / fan-out centrality for all nodes in a CodeGraph.
+ *
+ * Tries the native Rust implementation first, falls back to JS.
  */
 export function fanInOut(graph: CodeGraph): Map<string, FanInOut> {
+  const native = loadNative();
+  if (native?.fanInOut) {
+    let edges = graph.toEdgeArray();
+    if (!graph.directed) {
+      // Undirected: toEdgeArray() deduplicates to one canonical direction;
+      // mirror each edge so the Rust side counts symmetric in/out degrees.
+      edges = [...edges, ...edges.map((e) => ({ source: e.target, target: e.source }))];
+    }
+    const nativeResult = native.fanInOut(edges);
+    const result = new Map<string, FanInOut>();
+    for (const entry of nativeResult) {
+      result.set(entry.node, { fanIn: entry.fanIn, fanOut: entry.fanOut });
+    }
+    // Ensure isolated nodes (no edges) are included
+    for (const id of graph.nodeIds()) {
+      if (!result.has(id)) {
+        result.set(id, { fanIn: 0, fanOut: 0 });
+      }
+    }
+    return result;
+  }
+
+  return fanInOutJS(graph);
+}
+
+/** Pure JS fallback for fan-in/out. */
+function fanInOutJS(graph: CodeGraph): Map<string, FanInOut> {
   const result = new Map<string, FanInOut>();
   for (const id of graph.nodeIds()) {
     result.set(id, {

package/src/graph/algorithms/louvain.ts

@@ -1,11 +1,13 @@
 /**
- * Community detection via vendored Leiden algorithm.
+ * Community detection via native Rust Louvain or vendored Leiden algorithm.
  * Maintains backward-compatible API: { assignments: Map<string, number>, modularity: number }
  *
- * Note: Always runs in undirected mode (`directed: false`) regardless of
- * the input graph's directedness. For direction-aware community detection,
- * use `detectClusters` from `./leiden/index.js` directly.
+ * Native path: classic Louvain (Rust, undirected modularity optimization).
+ * JS fallback: Leiden algorithm via `detectClusters` (always undirected, `directed: false`).
  */
+
+import { warn } from '../../infrastructure/logger.js';
+import { loadNative } from '../../infrastructure/native.js';
 import type { CodeGraph } from '../model.js';
 import type { DetectClustersResult } from './leiden/index.js';
 import { detectClusters } from './leiden/index.js';
@@ -28,6 +30,31 @@ export function louvainCommunities(graph: CodeGraph, opts: LouvainOptions = {}):
   }
 
   const resolution: number = opts.resolution ?? 1.0;
+
+  const native = loadNative();
+  if (native?.louvainCommunities) {
+    // maxLevels, maxLocalPasses, and refinementTheta are Leiden-specific tuning knobs
+    // not supported by the Rust Louvain implementation. Warn callers who set them.
+    if (opts.maxLevels != null || opts.maxLocalPasses != null || opts.refinementTheta != null) {
+      warn(
+        'louvainCommunities: maxLevels/maxLocalPasses/refinementTheta are ignored by the native Rust path',
+      );
+    }
+    const edges = graph.toEdgeArray();
+    const nodeIds = graph.nodeIds();
+    const result = native.louvainCommunities(edges, nodeIds, resolution, 42);
+    const assignments = new Map<string, number>();
+    for (const entry of result.assignments) {
+      assignments.set(entry.node, entry.community);
+    }
+    return { assignments, modularity: result.modularity };
+  }
+
+  return louvainJS(graph, opts, resolution);
+}
+
+/** JS fallback using the vendored Leiden algorithm. */
+function louvainJS(graph: CodeGraph, opts: LouvainOptions, resolution: number): LouvainResult {
   const result: DetectClustersResult = detectClusters(graph, {
     resolution,
     randomSeed: 42,

package/src/graph/algorithms/shortest-path.ts

@@ -1,8 +1,11 @@
+import { loadNative } from '../../infrastructure/native.js';
 import type { CodeGraph } from '../model.js';
 
 /**
  * BFS-based shortest path on a CodeGraph.
  *
+ * Tries the native Rust implementation first, falls back to JS.
+ *
  * @returns Path from fromId to toId (inclusive), or null if unreachable
  */
 export function shortestPath(graph: CodeGraph, fromId: string, toId: string): string[] | null {
@@ -12,6 +15,23 @@ export function shortestPath(graph: CodeGraph, fromId: string, toId: string): st
   if (!graph.hasNode(from) || !graph.hasNode(to)) return null;
   if (from === to) return [from];
 
+  const native = loadNative();
+  if (native?.shortestPath) {
+    let edges = graph.toEdgeArray();
+    if (!graph.directed) {
+      // Undirected: toEdgeArray() deduplicates to one canonical direction;
+      // mirror each edge so the Rust BFS can traverse in both directions.
+      edges = [...edges, ...edges.map((e) => ({ source: e.target, target: e.source }))];
+    }
+    const result = native.shortestPath(edges, from, to);
+    return result.length > 0 ? result : null;
+  }
+
+  return shortestPathJS(graph, from, to);
+}
+
+/** Pure JS fallback for shortest path. */
+function shortestPathJS(graph: CodeGraph, from: string, to: string): string[] | null {
   const parent = new Map<string, string | null>();
   parent.set(from, null);
   const queue = [from];
@@ -23,7 +43,6 @@ export function shortestPath(graph: CodeGraph, fromId: string, toId: string): st
       if (parent.has(neighbor)) continue;
       parent.set(neighbor, current);
       if (neighbor === to) {
-        // Reconstruct path
         const path: string[] = [];
         let node: string | null = to;
         while (node !== null) {

package/src/types.ts

@@ -61,7 +61,7 @@ export type EdgeKind = CoreEdgeKind | StructuralEdgeKind;
 export type AnyEdgeKind = EdgeKind | DataflowEdgeKind;
 
 /** AST node kinds extracted during analysis. */
-export type ASTNodeKind = 'call' | 'new' | 'string' | 'regex' | 'throw' | 'await';
+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';
@@ -96,7 +96,19 @@ export type LanguageId =
   | 'dart'
   | 'zig'
   | 'haskell'
-  | 'ocaml';
+  | 'ocaml'
+  | 'ocaml-interface'
+  | 'fsharp'
+  | 'gleam'
+  | 'clojure'
+  | 'julia'
+  | 'r'
+  | 'erlang'
+  | 'solidity'
+  | 'objc'
+  | 'cuda'
+  | 'groovy'
+  | 'verilog';
 
 /** Engine mode selector. */
 export type EngineMode = 'native' | 'wasm' | 'auto';
@@ -383,6 +395,7 @@ export interface SubDeclaration {
   line: number;
   endLine?: number;
   visibility?: 'public' | 'private' | 'protected';
+  decorators?: string[];
 }
 
 /** Complexity metrics attached to a definition post-analysis. */
@@ -1828,8 +1841,42 @@ export interface NativeAddon {
   ): 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[]): unknown[];
+  buildImportEdges?(
+    files: unknown[],
+    resolvedImports: unknown[],
+    fileReexports: unknown[],
+    fileNodeIds: unknown[],
+    barrelFiles: string[],
+    rootDir: string,
+  ): unknown[];
   engineVersion(): string;
+  analyzeComplexity(source: string, filePath: string): NativeFunctionComplexityResult[];
+  buildCfgAnalysis(source: string, filePath: string): NativeFunctionCfgResult[];
+  extractDataflowAnalysis(source: string, filePath: string): DataflowResult | null;
   ParseTreeCache: new () => NativeParseTreeCache;
   NativeDatabase: {
     openReadWrite(dbPath: string): NativeDatabase;
@@ -1837,6 +1884,40 @@ export interface NativeAddon {
   };
 }
 
+/** 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;
@@ -2266,6 +2347,32 @@ export interface NativeDatabase {
     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>[];
@@ -2273,6 +2380,14 @@ export interface NativeDatabase {
   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;
 }
 
 // ════════════════════════════════════════════════════════════════════════