feat(ingestion): add control-flow-graph layer for TS/JS (#2081)

[magyargergo]

Summary

Closes the M1 milestone of Epic #2087 (issue #2081). Populates the M0 BasicBlock/CFG graph substrate (#2080, PR #2092) with real per-function control-flow graphs for TypeScript & JavaScript, strictly behind an opt-in --pdg flag.

Default analyze runs are byte-identical to before — verified by the golden-graph parity test (AC4) with the flag off, and independently corroborated by an adversarial review pass.

What it does (opt-in --pdg)

• The parse worker builds a per-function CFG from the tree-sitter AST (where the AST lives — avoids the gitnexus analyze linux kernel source JavaScript heap out of memory OOM. #1983 main-thread re-parse OOM) and serializes it onto a new ParsedFile.cfgSideChannel as plain data.
• Scope-resolution emits BasicBlock nodes + CFG edges from that side-channel while the disk-backed ParsedFile store is still live — the architecture the doc-review corrected to (a standalone post-mro phase would read an empty store; see KTD1).
• The opt-in is folded into the parse-cache key so a pdg-off warm cache is never reused on a --pdg run (the perf(ingestion): Linux-kernel-scale analysis — worker-pool parse + finalize O(n²) + scope-resolution memory wall (#1983) #2038-class trap), with SCHEMA_BUMP 4→5.

Control-flow coverage

if/else/else-if, while/do-while/for/for-in/for-of (header + back-edge + exit), switch (case dispatch + fallthrough vs break), try/catch/finally (normal and exceptional flow both route through finally), labeled break/continue, early return/throw, expression-bodied arrows, async/generator/method bodies.

Implementation units

• U1 language-agnostic CFG core (builder, control-flow-context, traversal-result, types)
• U2 TS/JS tree-sitter CfgVisitor (one hazard per test)
• U3 worker build + cfgSideChannel + cache coherence (SCHEMA_BUMP + pdg-folded chunk key) + LanguageProvider.cfgVisitor hook
• U4 BasicBlock + CFG emit within scope-resolution (per-function edge cap, no silent truncation)
• U5 --pdg opt-in plumbing (CLI + .gitnexusrc → both the worker build gate and the emit gate)
• U7 acceptance fixtures, golden parity, end-to-end pipeline test, docs

Acceptance criteria

• ✅ AC1 10-function fixture CFG matches a committed snapshot
• ✅ AC2 every BasicBlock reachable from its function ENTRY
• ✅ AC3 try/throw/finally + labeled break/continue fixtures
• ✅ AC4 golden-graph parity unchanged with --pdg off (byte-identical)
• ✅ end-to-end runPipelineFromRepo({ pdg: true }) emits a queryable CFG; default run emits zero

Review (tri-method, applied in-PR)

A 10-reviewer pass (correctness/adversarial/performance/api-contract/reliability/testing/maintainability/project-standards/agent-native/learnings) confirmed the OFF-path byte-identity and found defects all within the --pdg path, all fixed in this PR:

• P1 same-line-function BasicBlock id collision → start-column disambiguator (BasicBlock:<file>:<line>:<col>:<idx>)
• P1 worker crash-cascade → per-file try/catch isolating the CFG build
• P2 edge-cap warning silently suppressed → unconditional logging
• P2 unguarded cfgSideChannel cast → Array.isArray guard
• P2 maxFunctionLines no default → DEFAULT_PDG_MAX_FUNCTION_LINES=2000 + caps forwarded through the server path
• P3 README duplicate paragraph, 0-vs-default docstrings, language-named CLI flag, stale JSDoc

Refuted: an HTTP-500 getNodeQuery finding — M0 already shipped the BasicBlock query branch + name-floor (R12/web-safety handled).

Known limitations (scoped to M1, documented in code)

• A non-local jump (break/continue/return) out of a try-with-finally edges directly to its target rather than routing through finally first (conservative under-approximation; sound for a CFG). The general fix duplicates finally per exit path — deferred to when the downstream taint analysis (M2+) needs the precision. Normal completion and throw do route through finally.
• Stacked labels (outer: inner: for) and break-to-block-label are unmodeled (the jump becomes a CFG sink — a missing edge, never a mis-route). Single-labeled loops/switches resolve correctly.
• pdgMaxFunctionLines / pdgMaxEdgesPerFunction have no CLI flag (plan-scoped to programmatic/server use for M1); reachable via PipelineOptions + runFullAnalysis.

Tests

56 CFG tests (unit + integration) + analyze-config; full suite green locally; golden parity byte-identical.

🤖 Generated with Claude Code

[vercel]

@magyargergo is attempting to deploy a commit to the NexusCore Team on Vercel.

A member of the Team first needs to authorize it.

[github-actions]

CI Report

✅ All checks passed

Pipeline Status

Stage	Status	Details
✅ Typecheck	success	tsc --noEmit
✅ Tests	success	unit tests, 3 platforms
✅ E2E	success	gitnexus-web changes only

Test Results

Tests	Passed	Failed	Skipped	Duration
11162	11146	0	16	480s

✅ All 11146 tests passed

16 test(s) skipped — expand for details

• COBOL pipeline benchmark > scales with file count
• C++ ADL emit benchmark > emit phase scales sub-quadratically with co-scaled files and sites
• C++ pipeline benchmark > scales with file count
• C# pipeline benchmark > scales with file count — namespaces spread across the solution
• C# pipeline benchmark > scales with file count — all types in one (global) namespace bucket
• C# pipeline benchmark > scales with file count — all types in one (named) namespace bucket
• Go pipeline benchmark > scales with file count (workers enabled)
• Go pipeline benchmark — worker pool (issue Worker idle timeout kills long Go scope extraction and surfaces as Napi::Error during analyze #1848) > does not quarantine the large generated Go file on sub-batch idle timeout
• Go structural interface detection benchmark > scales linearly with interface × struct count
• Go structural interface detection split-phase benchmark > separates index-build and detection time
• PHP pipeline benchmark > scales with file count (workers enabled)
• Ruby pipeline benchmark > scales with file count (workers enabled)
• Rust pipeline benchmark > scales with file count (workers enabled)
• Vue pipeline benchmark > scales with component count
• run.cjs direct-exec entrypoint (fix(cli): steer docs, skills, and hooks through a CLI-neutral project-local runner (#1939) #1945) > resolves a .cmd shim via the Windows shell branch, passing args and exit code
• buildTypeEnv > known limitations (documented skip tests) > Ruby block parameter: users.each { |user| } — closure param inference, different feature

Code Coverage

Tests

Metric	Coverage	Covered	Base	Delta	Status
Statements	75.53%	36652/48521	N/A%	—	🟢 ███████████████░░░░░
Branches	63.41%	22734/35850	N/A%	—	🟢 ████████████░░░░░░░░
Functions	81.17%	3951/4867	N/A%	—	🟢 ████████████████░░░░
Lines	79.27%	33125/41785	N/A%	—	🟢 ███████████████░░░░░

---

_{📋 View full run · Generated by CI}

[magyargergo]

Tri-review + CFG-domain-expert lane — M1 CFG layer (#2081)

Methods: GitNexus swarm + Compound-Engineering personas + Codex (the one genuinely independent engine — live) + a CFG / program-analysis domain-expert lane (added for completeness). 9 lanes; 2 gitnexus-* lanes (risk, test-ci) ended mid-investigation and were cross-covered by the adversarial/Codex/CFG-expert lanes. Engine breakdown: 7 Claude lanes + Codex — agreement between Codex and a Claude lane is the strong signal; Claude-only agreement is "consistent," not independent. Reproduction was partial (the review worktree can't build the worker, so pipeline-pdg's end-to-end worker path was unexercised locally).

What's solid (validated across lanes): the OFF-path byte-identity holds (every CFG path gated; pdg-off chunk keys unchanged; SCHEMA_BUMP is a one-time cold-miss with an identical graph); basic-block formation is sound (every jump target is a leader); loops are reducible; switch is sound (incl. default-in-middle + no-default fall-past); return/throw preserve single-exit; the extendBlock O(n²)→O(n) fix is byte-identical (fingerprint + snapshot unchanged); the BasicBlock id scheme (with the same-line start-column disambiguator) is sound; the cache pdg-fold is coherent. 58 CFG-logic tests pass.

Headline findings

1. [P1 for the M2 taint consumer · Codex + CFG-expert + correctness] Exceptional throw edge only from the try-body ENTRY block. visitTry wires bodyRes.entry → handler; when the try body's first statement is itself control flow (if, nested try, block after a branch), the interior blocks get no handler edge. Trigger: try { if (x) { const t = taintedA(); use(t); } } catch (e) { h(e); } — the use(t) block can't reach catch. The M1 graph stays reachability-sound, but it's a taint false-negative into catch for M2. The inline comment ("any statement in the protected region may raise") overstates the code. Fix: wire every protected-region block to the handler (the per-function cap already bounds the edge count).

2. [P1 · Codex, independent engine] pdgMaxFunctionLines/pdgMaxEdgesPerFunction not folded into the chunk hash. computeChunkHash folds only the pdg boolean. A programmatic caller that varies the cap across runs on a warm cache gets a stale CFG served (built with the old cap) — the exact #2038-class trap this PR otherwise guards. Latent today (the caps have no CLI surface) but reachable via the run-analyze programmatic path. Fix: fold the cap values into the key alongside pdg.

3. [P2 · Codex + CFG-expert] Stacked/block labels strand a block. outer: inner: for (…) { break outer } and blk: { … break blk } produce a block with no out-edge → it can't reach EXIT. Beyond the documented "missing edge": it breaks the single-exit invariant M2's post-dominator (PDG control-dependence) computation requires. Cheap fix: when breakTarget/continueTarget is undefined, wire the jump to EXIT (a sound "escapes to function exit").

4. [P2 · Codex + CFG-expert + 3 lanes · DOCUMENTED] break/continue/return out of a try-with-finally bypass finally. Documented M1 limitation. The CFG-expert sharpens it: it's a soundness gap (false-negative for taint flowing through a finally mutation), not merely "deferred precision." Action: re-label the source doc as a soundness/false-negative limitation + track as an M2 blocker; the real fix (finally-duplication per exit path) stays deferred.

5. [P2 · performance, measured] visitTry allocates namedChildren twice. Two sequential stmt.namedChildren.find(...) calls each allocate a fresh array (tree-sitter doesn't cache the getter); ~37% slower on try-heavy code in a microbenchmark; same pattern in bodyBlockOf/labelOf. Fix: one namedChild(i) loop.

Benchmark self-review (the new perf gate, under scrutiny)

6. [P3 · adversarial, reproduced] The straight-line scenario may not catch the very O(n²) it's named for. It coalesces to 4 blocks at any N, so disk/heap ratios measure output size (always linear) — only the time budget (2.0) guards the concat path, and a cons-string quadratic stays under 2.0 at N=2000 (reproduced ratio ~1.88). Fix: raise the straight-line LARGE N so a real quadratic separates (or tighten the budget).

7. [P3 · adversarial + performance + Codex] Heap gate silently no-ops without --expose-gc (--check still exits 0). Live in CI (the flag is passed) but a copy/edit dropping it downgrades the gate to a green no-op. Fix: when --check and global.gc is unavailable, FAIL loudly.

8. [P3 · Codex] Ratio-only gates miss absolute (constant-factor) regressions — a 10× linear blowup keeps ratios ~1.0. Enhancement: add deterministic absolute byte/heap-per-function ceilings.

Refuted / disagreement / lower-priority

• Refuted: Codex flagged the for(;;)/while(true) cond-false → loopExit edge as spurious (P2); the CFG-expert endorsed it as the conservative choice that keeps EXIT reachable for post-dominators. Keeping the edge is correct — not a defect.
• Maintainability (P2–P3): TS_FUNCTION_TYPES duplicates the TS/JS subset of FUNCTION_NODE_TYPES (divergence risk); collect.ts uses tree-sitter APIs directly so the CfgVisitor<TNode> generic is misleading; the bench median/check-loop duplicates scope-capture/measure.mjs.
• Test gaps: do-while / for-of back-edge endpoints not pinned; pipeline-pdg uses >0 (a partial-emit regression would pass); no end-to-end warm-cache flag-flip test; the snapshot omits block text/kind; no generator / empty-try tests.

CI: green except Vercel (deploy-auth, non-blocking).

Automated multi-tool digest (3 methods + a domain-expert lane). The author will address the corroborated findings in-PR. Verify before acting.

[magyargergo]

Multi-lane review digest — PR #2099 (CFG layer for TS/JS, #2081 M1)

Methods & engine breakdown: 6 Claude reviewer lanes (GitNexus swarm + Compound-Engineering personas: correctness, adversarial, performance, maintainability, testing, risk) + direct coordinator verification. Codex was unavailable (quota exhausted) — this is an all-Claude review; cross-lane agreement means "consistent across personas," not independent-engine confirmation. The two headline findings were verified directly by the coordinator (one reproduced against a real tree-sitter parse, one code-read through the full persistence chain). Digest was vetted by an independent synthesis-critic pass before posting.

What's solid (validated, not just absence of findings)

• The --pdg-off default path is genuinely zero-overhead and byte-identical: gated at worker init (PDG_ENABLED, parse-worker.ts), at emit (input.pdg === true, run.ts), and at the cache key (pdg-off keys verbatim pre-#2081) — pinned by the pre-existing pipeline-graph-golden edgeDigest plus pipeline-pdg.test.ts's flag-off zero-count. Confirmed by 3 lanes + coordinator.
• Both P1s from the earlier review round are fixed: functionStartColumn disambiguates same-line-function BasicBlock ids, and the worker CFG build has a per-file try/catch so one bad file can't drop its language group.
• The pdg cache namespace is honored end-to-end (worker shards keyed by the main-thread hash; run-scoped store cleared per run; warm byte-copy keyed identically): a --pdg run cannot hit a non-pdg chunk or vice versa.
• New CFG edges are inert in impact's whitelist traversal; BasicBlock read paths were already handled in M0 (api.ts). The merge commit (58f13ad) preserves both parents' changes (verified against each parent). CI builds dist before vitest, and the new bench gate hard-fails on real thresholds (fingerprint + time/disk/heap ratios).

Headline findings (inline comments)

1. P1 run-analyze.ts:666 — --pdg on an already-indexed repo silently persists ~zero CFG (incremental writeback is pdg-mode-blind). [code-read, full chain verified]
2. P2 cfg/visitors/typescript.ts:464 — empty catch {} treated as no catch; swallowed-exception flow bypasses the catch and exits the function. [reproduced]
3. P2 pipeline-phases/parse-impl.ts:750 — emit-time-only maxEdgesPerFunction folded into the parse-cache key → spurious full re-parse on cap change. [code-read; 2 lanes]
4. P3 scope-resolution/pipeline/run.ts:711 — outer-array-only guard; a malformed cfgSideChannel element still throws mid-graph-build, the exact failure the adjacent comment claims to prevent. [code-read; 2 lanes]
5. P3 cfg/visitors/typescript.ts:351 — for with a body but no increment: phantom header→header loop-back self-edge while the real back-edge is labeled seq. [agent-reproduced + code-read]
6. P3 storage/parse-cache.ts:162 — misleading comment: pdg-off keys are unchanged, but SCHEMA_BUMP 4→5 still cold-invalidates every cache once on upgrade. [code-read]

Lower-priority notes (no inline anchor)

• Alternating pdg/non-pdg runs mutually evict each other's cache + durable store on every flip (end-of-run pruning keeps only this run's keys + sibling-branch keys) — consider unioning the same branch's prior keys. (single lane, not coordinator-verified)
• Empty try body with a catch routes normal flow through the dead catch block (agent-reproduced; rare pattern).
• Degraded re-extract paths (missing durable shards) silently produce per-file CFG holes on --pdg runs — the existing warnings don't mention CFG loss; consider an emitted-with-CFG counter in the run summary.
• Implicit exceptions inside a catch body are not routed to finally (only explicit throws; asymmetric vs the try body's blanket handler edges).
• with_statement is absent from CONTROL_FLOW_TYPES (a return inside with is flattened to fallthrough; sloppy-mode-only exposure).
• emit.ts:28 doc says cap 0 ⇒ "use this default" but the code makes 0 ⇒ unlimited (run.ts's doc is the correct one).
• CfgEmitResult.cappedFunctions and CollectedCfgs.skipped are computed but never surfaced in production logs.
• --pdg ships CFG-only in M1 — worth a one-line scope note in the help text (or a --cfg alias) so config authors know the flag will expand.
• Perf: blanket try-body throw edges and ~1KB/function cfgSideChannel are real but bounded and bench-gated; a try-heavy bench scenario would close the one ungated pattern.

Test gaps (consistent across 3 lanes)

1. No --pdg-through-incremental-writeback integration test — would have caught the P1 (index → re-analyze --pdg → assert BasicBlock count > 0).
2. No warm-cache cross-flag test (pdg-off warm store → pdg-on run on the same storagePath).
3. Visitor shapes untested: return-in-try-with-finally, throw-in-catch-with-finally, nested try, switch default-in-middle, empty shared cases, for(;;).
4. No malformed-cfgSideChannel-element test through run.ts.

Refuted suspicions (probed, no divergence)

Cache poisoning across pdg namespaces; workerData plumbing with absent store paths; JSON-serialization hazards (−0/Infinity/reviver collisions); DB injection via BasicBlock text (CSV + escapeValue paths verified); quadratic collect.ts tree walk; toothless bench gate.

CI

Green at review time except Vercel (deploy-auth, known infra) and the windows/coverage jobs still pending.

Coverage: full 38-file diff read; visitor/builder/emit/cache/worker paths deep-read; persistence chain code-read; no end-to-end --pdg analyze run was executed (worktree build constraint).

Automated multi-lane review digest (all-Claude, Codex unavailable) — verify findings before acting on them.

[magyargergo]

P1 — --pdg silently persists no CFG on an already-indexed repo [code-read, full chain verified]

Trigger: repo already indexed (meta.fileHashes populated) → user runs gitnexus analyze --pdg with no file changes — the natural first use of this flag.

• isIncremental (this file, ~line 694) has no pdg term, and RepoMeta records no pdg mode (zero pdg refs in storage/repo-manager.ts), so the mode flip is invisible.
• Workers then pay the full CFG cost (cache misses everywhere — pdg-namespaced keys) and scope-resolution emits BasicBlocks into the in-memory graph…
• …but extractChangedSubgraph (core/incremental/subgraph-extract.ts:70-85) keeps only nodes whose filePath is in the changed set (+Community/Process). With changed=0, every BasicBlock node is dropped from the written subgraph. The run logs Incremental: changed=0 and succeeds with zero BasicBlock rows.
• Converse flip (plain analyze after a --pdg index — e.g. the standard re-index hook): deleteNodesForFile removes changed files' BasicBlocks, the pdg-off run rewrites none → a zombie mixed-coverage CFG layer only --force can clean.

Fix: record the pdg mode (and caps) in RepoMeta and force full writeback (or expand the write set to all CFG-bearing files) on mode flip; at minimum, loudly suggest --force when --pdg hits an incremental-eligible non-pdg index. A small integration test (index → re-analyze --pdg → assert BasicBlock count > 0) would pin this.

[magyargergo]

P3 — guard validates only the outer array; the comment overpromises [code-read; 2 lanes]

The comment above says a stale/wrong-shape value "must skip emission, not throw a TypeError mid-graph-build" — but the check is Array.isArray(cfgs) plus a cast. A malformed element (e.g. [{}]) reaches emitFileCfgs, which destructures and iterates cfg.blocks → TypeError on the main thread, with no per-file catch here (unlike the worker side), aborting the language's scope-resolution pass — exactly the failure the comment claims is defended against. Precondition (a shard that passes the version gate with mismatched element shape) is low-probability today, but M2 will add fields to FunctionCfg and this is the seam where a missed SCHEMA_BUMP turns into a crash.

Fix: per-element shape check (Array.isArray(cfg?.blocks) && Array.isArray(cfg?.edges) && typeof cfg?.filePath === 'string') with a warn-and-skip, or wrap the per-file emitFileCfgs call in try/catch mirroring the worker-side isolation.