parity

/parity — Engine Correctness Parity Audit & Fix

Codegraph has two engines that MUST produce identical results (see CLAUDE.md):

• wasm — JS pipeline + JS extractors + JS edge resolution
• native — full Rust orchestrator (crates/codegraph-core/src/domain/graph/builder/pipeline.rs)
• hybrid — JS pipeline + napi buildCallEdges (the fallback when the orchestrator is skipped: forced full rebuilds, older addons)

This skill runs scripts/parity-compare.mjs, which builds every resolution-benchmark fixture with each engine and compares the full node and edge multisets (kind, name, file, line, confidence, dynamic flag). Any difference is a bug in the less-accurate engine — never an acceptable gap, and never something to document as expected. The skill finds the root cause, fixes it, and re-verifies until the audit is clean.

Arguments

• $ARGUMENTS may contain:
  • --langs a,b,c — restrict to specific fixture names (e.g. javascript,pts-javascript)
  • --hybrid — also audit the hybrid path (recommended; slower)
  • --audit-only — report divergences without fixing them
  • No arguments — full audit across all fixtures, then fix divergences

Phase 0 — Pre-flight

All steps run from the repo root.

1. Confirm scripts/parity-compare.mjs exists. If not, this repo doesn't have the parity tooling — stop and report.
2. Build the TypeScript dist (the script imports dist/index.js, and extractor changes in src/ are invisible until rebuilt):

   npm run build
   

3. Ensure the native addon reflects the local Rust source:

   cd crates/codegraph-core && npx napi build --platform --release && cd ../..
   

   On macOS, locally built binaries must be re-signed or Node kills the process (exit 137):

   codesign --sign - --force crates/codegraph-core/*.node
   

4. Verify the loader picks up the locally built binary, not the published package. First check which path is actually resolved:

   node -e "
     const { createRequire } = require('node:module');
     const r = createRequire(require.resolve('./dist/index.js'));
     try { console.log(r.resolve('codegraph-core')); } catch { console.log('not found via require'); }
   "
   

   If the resolved path points to node_modules/@optave/codegraph-<platform>-<arch>/codegraph-core.node (the installed package), copy your freshly built binary over it:

   cp crates/codegraph-core/*.node node_modules/@optave/codegraph-<platform>-<arch>/codegraph-core.node
   

   Then confirm the loader picks it up:

   node -e "import('./dist/infrastructure/native.js').then(m => console.log(m.isNativeAvailable()))"
   

   If false, stop and report — auditing parity without the native engine is meaningless.