fix(native): resolve dataflow null paramIndex and import edge key mismatch (#788)

* fix(native): resolve dataflow null paramIndex and import edge key mismatch

Two native engine bugs found during v3.8.0 dogfooding:

1. Dataflow edge insertion fails with null paramIndex (#753):
   napi-rs Option<u32> expects `undefined`, not `null`. Changed
   paramIndex from null to undefined for returns/mutates edges.

2. Native import edge builder produces 0 edges on Windows (#750):
   buildImportEdgesNative built resolve keys with backslash rootDir
   but Rust normalizes to forward slashes, causing every lookup to
   miss. Fixed by normalizing rootDir in JS keys. Added defensive
   fallback: if native returns 0 edges when imports exist, retry
   with the JS implementation.

Closes #750, closes #753

* fix: tighten paramIndex type and document fallback false-positive (#788)

- Remove `null` from bulkInsertDataflow paramIndex type to match napi-rs
  Option<u32> contract, preventing future null regressions
- Document known false-positive in import-edge fallback for codebases
  with only external imports

Author: carlos-alm

src/domain/graph/builder/stages/build-edges.ts

@@ -198,10 +198,12 @@ function buildImportEdgesNative(
   const fileNodeRowCache = new Map<string, { id: number }>();
 
   // 2. Pre-resolve all imports and build resolved imports array.
-  // Keys use rootDir + "/" + relPath to match the Rust lookup format
-  // (format!("{}/{}", root_dir, file)) — avoids separator mismatches on Windows
-  // where path.join uses backslashes but Rust joins with forward slash.
+  // Keys use forward-slash-normalized rootDir + "/" + relPath to match the Rust
+  // lookup format (format!("{}/{}", root_dir.replace('\\', "/"), file)).
+  // On Windows, rootDir has backslashes but Rust normalizes them — the JS side
+  // must do the same or every resolve key lookup misses (#750).
   const resolvedImports: Array<{ key: string; resolvedPath: string }> = [];
+  const fwdRootDir = rootDir.replace(/\\/g, '/');
 
   for (const [relPath, symbols] of fileSymbols) {
     const fileNodeRow = addFileNodeId(relPath);
@@ -221,8 +223,8 @@ function buildImportEdgesNative(
       const resolvedPath = getResolved(ctx, path.join(rootDir, relPath), imp.source);
       addFileNodeId(resolvedPath);
 
-      // Key matches Rust's format!("{}/{}", root_dir, file_input.file)
-      resolvedImports.push({ key: `${rootDir}/${relPath}|${imp.source}`, resolvedPath });
+      // Key matches Rust's format!("{}/{}", root_dir.replace('\\', "/"), file_input.file)
+      resolvedImports.push({ key: `${fwdRootDir}/${relPath}|${imp.source}`, resolvedPath });
 
       importInfos.push({
         source: imp.source,
@@ -737,7 +739,20 @@ export async function buildEdges(ctx: PipelineContext): Promise<void> {
     const useNativeImportEdges =
       native?.buildImportEdges && (ctx.isFullBuild || ctx.fileSymbols.size > 3);
     if (useNativeImportEdges) {
+      const beforeLen = allEdgeRows.length;
       buildImportEdgesNative(ctx, getNodeIdStmt, allEdgeRows, native!);
+      // Fallback: if native produced 0 import edges but there are imports to
+      // process, the native binary may have a key-format mismatch (e.g. Windows
+      // path separators — #750).  Retry with the JS implementation.
+      // NOTE: This also fires for codebases where every import targets an
+      // external package (npm deps) that the resolver intentionally skips.
+      // In that case the JS path resolves zero edges too, so the only cost
+      // is the redundant JS traversal — no correctness impact.
+      const hasImports = [...ctx.fileSymbols.values()].some((s) => s.imports.length > 0);
+      if (allEdgeRows.length === beforeLen && hasImports) {
+        debug('Native buildImportEdges produced 0 edges — falling back to JS');
+        buildImportEdges(ctx, getNodeIdStmt, allEdgeRows);
+      }
     } else {
       buildImportEdges(ctx, getNodeIdStmt, allEdgeRows);
     }

src/features/dataflow.ts

@@ -294,7 +294,7 @@ function collectNativeEdges(
         sourceId: producerNode.id,
         targetId: consumerNode.id,
         kind: 'returns',
-        paramIndex: null,
+        paramIndex: undefined,
         expression: assignment.expression,
         line: assignment.line,
         confidence: 1.0,
@@ -308,7 +308,7 @@ function collectNativeEdges(
         sourceId: mutatorNode.id,
         targetId: mutatorNode.id,
         kind: 'mutates',
-        paramIndex: null,
+        paramIndex: undefined,
         expression: mut.mutatingExpr,
         line: mut.line,
         confidence: 1.0,

src/types.ts

@@ -2220,7 +2220,7 @@ export interface NativeDatabase {
       sourceId: number;
       targetId: number;
       kind: string;
-      paramIndex?: number | null;
+      paramIndex?: number;
       expression?: string | null;
       line?: number | null;
       confidence: number;