mirror of https://github.com/abhigyanpatwari/GitNexus.git synced 2026-11-01 07:02:35 +00:00

Mirror of https://github.com/abhigyanpatwari/GitNexus.git

Find a file

DuduPhudu 258ca06122 fix: close the nine follow-up review findings from #2856 (routes, receiver typing, truncation honesty) (#2899 ) * fix(typescript): a type parameter shadows a declared type of the same name (W2-8) First item of wave 2, promised to the reviewer on #2856. `export function unwrap<Result>(value: Result): Result` names the PARAMETER, not the `interface Result` beside it — tsc resolves both annotations to the parameter. The type-reference capture that makes a contract answerable ("what breaks if I remove this field?") had no notion of a parameter binding, so every annotation mentioning `Result` inside `unwrap` minted a `USES` edge into the interface, at the same confidence as a real consumer and indistinguishable from one. Measured on the new fixture: `unwrap` produced TWO false edges while the genuine consumer produced one. Blast radius is every generic whose parameter name collides with a declared type, and the colliding names are ordinary choices for both: `Result`, `Key`, `Value`, `Item`, `Node`, `Options`, `Config`, `Props`, `State`, `Response`. TWO HALVES, and the first is why upstream's fix could not reach this. #2833 introduced `bindsTypeParameter` for the CALL-receiver path, where a workspace `class T` was answering for `<T>`. Reusing it here changed nothing at first, and the reason is its own documented contract: `@declaration.type-parameters` was captured for class/interface declarations ONLY, so a generic FUNCTION recorded no parameter list and the predicate correctly returned false — absence is not evidence. The data was missing, not the logic. So: - TYPESCRIPT_SCOPE_QUERY now captures type parameters on `function_declaration`, `generator_function_declaration` and `type_alias_declaration`; - the graph bridge consults `bindsTypeParameter` before emitting `USES`. Both are load-bearing — removing either one fails the fixture. The fixture carries two controls, because the obvious wrong fix is to stop emitting: a genuine consumer of the interface must still link, and a generic whose parameter does NOT collide must still link its real reference. Both are asserted, and the "genuine consumer" case is asserted FIRST so the absences below it cannot pass vacuously. SCHEMA_BUMP 53 -> 54: parse-time capture change. A warm cache replays defs with no parameter list, so the guard reads nothing and the feature is inert while looking implemented. Capture fingerprint re-baselined with justification. NO NEW CAPTURE NAME — diffing the capture-name sets against the wave-1 branch returns empty; the tag existed and now fires on more declarations. capture_groups_fp 2338 -> 2371, fixture_count 151 -> 152, scaling 1.06 < 1.5, and JavaScript's fingerprint does not move at all, which is the check that this is the TS declaration rules rather than something broader. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> * fix(analyze): close the four false-success paths in the graph-write-collapse guard (W2-6) Second wave-2 item, promised on #2856. All four were reported; all four reproduced by reading the code they name. (a) A SAME-COMMIT RE-RUN REPORTED SUCCESS FOREVER. Every other meta-driven trigger — schema fingerprint, PDG mode, runner identity, CJK segmentation, embedding dims — has a block that forces a rebuild before the `alreadyUpToDate` fast path. `graphWriteCollapsed` had none; `grep -rn` found writes and no reads. So the one state meaning "most of your edges are gone" was the one state that repaired itself only if the user happened to pass `--force`. Now forces a full rebuild, and forcing is right rather than merely re-running: the persisted graph disagrees with what the pipeline produced, so an incremental pass over unchanged files would write nothing and re-stamp the same broken index as fresh. (b) AN INCREMENTAL RE-RUN ERASED THE STAMP. `saveMeta` is a full atomic overwrite, and the field was spread in only when the CURRENT run had a verdict. `undefined` meant two different things at that site — "full run, no collapse" (a positive all-clear) and "incremental write, not comparable" (no opinion) — so the second case silently dropped `graph-write-collapsed` from meta.json while the edges were still missing. Now three-way: stamp on detection, CLEAR on a healthy full run, CARRY FORWARD when there is no verdict. That is the shape `branch: branchLabel ?? existingMeta?.branch` two lines away had all along. (c) THE SERVER PATH NEVER CONSUMED IT. `analyze-worker-ipc.ts` projects the field "so a server-side caller sees the same degraded outcome the CLI does" — but nothing read it, so the comment described an intention and every collapsed run reported `complete` to the UI and to every API consumer. Now reports `failed` with the counts and the remedy, matching the CLI, which prints `Repository indexed INCOMPLETELY` and exits non-zero. A consumer that reads "complete" will query the index and get confident wrong answers. (d) --pdg ROWS MASKED TOTAL STRUCTURAL LOSS. `expected` counts the in-memory graph plus the streamed STRUCTURAL manifest; the streamed PDG layers never enter `graph.relationshipCount`. But `persisted` was `stats.edges`, a count of EVERY `CodeRelation` row, and PDG writes into that same table. With 1,000 structural edges expected and 4,000 PDG rows persisted, losing every structural edge still read `persisted = 4000`, cleared the ratio, and stayed silent — on exactly the large repos `--pdg` is used for. Worth recording that the OBVIOUS fix does not work. Padding `expected` with the PDG rows makes the two universes match but leaves the ratio judging a minority population: 4,000 of 5,000 still clears 0.5. I wrote that first, and the test I wrote to prove it failed. Only comparing structural against structural asks the question the check exists to ask, so `getLbugStats` gains a `structuralEdges` count excluding `PDG_EDGE_TYPES`. `TAINT_PATH` is deliberately NOT in that set — it is a whole-program Function→Function edge persisted by the normal emit, so it is structural and stays counted on both sides. `index-freshness-graph-collapse.test.ts` had pinned the masking as correct (`detectGraphWriteCollapse(1000, 4000)` → undefined, "PDG layers write into the same table, so persisted > expected is normal"). True about the table, and it licensed the hole. Replaced with the case that matters and a note on why the fix is at the caller. The new `structuralEdges` assertion in `lbug-core-adapter` is there because the failure mode is silent: the query sits in a try/catch that yields `undefined`, and `undefined` makes the collapse check decline to compare — so a typo in the Cypher would throw nothing, fail nothing, and switch the guard off. Verified against a real LadybugDB and mutation-checked by breaking the query. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> * fix(processes): make process selection insertion-order invariant (W2-5) Third wave-2 item. Reproduced before fixing: two equal three-step flows with `maxProcesses: 1` select `handleAlpha`; inserting the identical nodes and CALLS edges in reverse select `handleBeta`. Same repository, same commit, a different persisted graph — so a filesystem that enumerates differently, or an incremental run that reorders assembly, silently changes what the tool reports. Four sorts ranked by score or length alone and returned 0 on a tie. `Array.prototype.sort` is stable, so a 0 preserves INPUT order, which traces back to `graph.iterNodes()`. Under `maxProcesses` capping that decided which `Process` and `STEP_IN_PROCESS` nodes were persisted at all. Each now falls through to a totally-ordered, content-derived key — node id for entry points, the joined path for traces. WHAT IS ACTUALLY VERIFIED, stated precisely because "four fixes" would overclaim: - the ENTRY-POINT sort is individually mutation-verified; - the two DEDUP sorts are collectively mutation-verified; - the TRACE-RANK tiebreak is NOT individually observable, and the source says so. The dedup sorts already impose a total order on the list that reaches it, so removing it alone fails nothing. Kept as defence in depth: it cannot misbehave — it only makes an already-deterministic order explicit — and it is what stops a change to dedup ordering from silently re-opening this. Finding that out took two fixtures. The first (three chains, three entry points) is separated by the entry-point sort before trace ranking is reached, so it never exercises the trace comparator at all; the second gives ONE entry point two equal-length branches to different terminals, which is the only shape where the trace comparator decides. Both are kept — they gate different sites. The invariance tests assert the INVARIANT rather than any single sort, so they cover all four sites and any future one without needing to know where they are. Three assertions: same selection under a cap, identical set uncapped, and identical ORDER — the last because order is what the cap consumes, so a set-only assertion would pass while the defect persisted. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> * fix(impact): UNKNOWN dominates a mixed candidate set, instead of reporting the known floor (W2-4) Fourth wave-2 item. The all-UNKNOWN branch here was reasoned about carefully and is correct — its comment even names the two ways a set can be all-UNKNOWN. The MIXED case fell straight through it. `RISK_ORDER` is `['LOW','MEDIUM','HIGH','CRITICAL']` and has no `UNKNOWN` entry, so `indexOf('UNKNOWN')` is -1 and an UNKNOWN candidate can never win the reduce. An ambiguous name with one caller-less candidate (UNKNOWN, per the round-1 fix) beside one single-caller candidate (LOW) reported `maxRisk: 'LOW'` — a confident floor over a set containing an interpretation nobody measured. That is the same false-safe the all-UNKNOWN branch exists to prevent, one case over, and it surfaced in the UI as "Max blast radius N (LOW risk)". `maxRisk` answers "how bad could this be?", and an unresolved candidate could be CRITICAL — so any UNKNOWN in the set makes the aggregate UNKNOWN. Narrowing it that way would normally cost information, so the measured part travels alongside as `knownMaxRisk`, present only when the two differ: absent on a fully-resolved set, where it would duplicate `maxRisk`, and absent on a fully-unknown one, where there is no measured part. A reader gets "at least LOW among what resolved, and one interpretation could not be walked at all", which is strictly more than either value alone. The human-readable message says the same thing. The seed gained a mixed pair because the existing one could not reach this: both its twins are caller-less, so it only ever exercises the all-UNKNOWN branch — which is precisely why the gap survived a round of review. Three assertions, both halves mutation-verified. `eval-server.ts` needs no change: it renders `result.maxRisk ?? 'UNKNOWN'`, so it now shows UNKNOWN where it previously showed the floor. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> * fix(routes): track ternary polarity in dispatch guards, so a selected verb cannot be inverted (W2-9) `if ((req.method === 'GET' ? false : true) && pathname === '/api/i')` emitted `GET /api/i` — the one method that branch guarantees the request does NOT have. A ternary SELECTS between its arms, so a verb inside one is not reached merely because the whole condition is truthy, but `findVerbInSubtree` descended into both arms and returned the first verb it saw. Same inversion `!` produced before `d4dcba8c`, one level up. Handled by folding the ternary where an arm is a boolean literal, which is what collapses the selection into a conjunction: c ? A : false == c && A both hold, so search both c ? false : B == !c && B c must NOT hold, so search it at flipped parity c ? true : B == c \|\| B a disjunction guarantees neither operand c ? A : true == !c \|\| A likewise Two non-literal arms leave the verb chosen by an unknown condition, so the ternary guarantees nothing. Refusing every ternary would also have fixed the reported bug, but three of the four shapes measured were ALREADY correct and would have silently lost their verb; they are pinned now. A second defect in the same walk, found while reproducing: the `!` rule was keyed on PRESENCE, returning null at the first negation it saw, while `isNegatedContext` two functions above states the rule is PARITY and says so outright — `!!x` is `x`. So `!!(req.method === 'GET')` dropped a verb the source states plainly. The existing double-negation test covered the PATH position, where the parity walk already ran, and so never saw it. The verb walk now tracks parity too, and the two agree. Verb-less, not route-less: the path comparison is untouched evidence that the branch serves that path, so an inverted verb becomes a missing verb rather than a missing route. SCHEMA_BUMP 54 -> 55. Routes are emitted at parse time and replayed verbatim from a warm cache, so without the bump an already-indexed repo keeps serving the inverted verb and the fix looks inert. Free against origin/main (48). Every rule mutation-checked: removing the ternary dispatch, either literal-arm rule, the negated-ternary guard, or the parity walk each fails exactly the tests that claim it. One assertion I wrote survived all five mutations and was removed rather than kept. Not a recall win on crypto-trading-bot, which contains neither shape — this is precision insurance for dispatchers that do. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> * feat(routes): report every method a dispatch guard serves, not just the first (R3-8 part 1) `if ((req.method === 'GET' \|\| req.method === 'POST') && bundlesMatch)` is two routes. The verb walk returned the FIRST verb it found, so `route_map` presented a two-method route as GET-only and `impact` on the POST path found nothing. Taken verbatim from the reporting repo's researchRunRoutes.js. `governingVerb` -> `governingVerbs`, returning a list; `findVerbInSubtree` and `verbFromTernary` likewise. A guard with several verbs emits one route per verb via the new `pushPerVerb` — they share a path and a handler but not a method, and `(method, url)` is the key every downstream consumer dedups and looks up on. A disjunction yields ALL its verbs or NONE, which also fixes an over-attribution the first-match rule had: req.method === 'GET' \|\| req.method === 'POST' -> GET, POST req.method === 'GET' \|\| isAdmin -> no verb The second is reached for ANY method when `isAdmin` holds. Reporting `GET` — as first-match did — describes a route open to everything as single-method, which is the direction this module treats as more expensive than saying nothing. Negated, `!(A \|\| B)` is `!A && !B`, so it excludes verbs rather than offering them and yields none. Generic descent deliberately stays FIRST-match rather than unioning across children: an arbitrary node says nothing about how its children combine, and two verbs found under one are far more likely unrelated than alternatives. `\|\|` is the one construct that genuinely means "either of these". Pinned against regression: the pre-existing rule that distributes ONE verb across an OR of PATHS must not start multiplying methods, and switch arms inherit the full method set. SCHEMA_BUMP 55 -> 56. Routes are parse-time output replayed verbatim from a warm cache. Free against origin/main (48). Four mutations, each failing exactly the tests that claim it: removing the disjunction dispatch, dropping the all-operands rule, allowing a disjunction at odd parity, and emitting only the first verb. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> * feat(routes): read `.match()` dispatch, and the capturing wildcard it needs (R3-8 part 2) `RE.test(pathname)` and `pathname.match(RE)` are the same test with the operands swapped. Only `.test` was read, which is why 28 of the reporting repo's 75 routes still named the shared route table as their handler rather than the module that serves them: those modules dispatch with `.match`. THE CAPTURING WILDCARD, which is the part that made the rest inert. `regexToRoutePath` accepted `[^/]+` and refused `([^/]+)` — `(` fell through to the metacharacter bail. So the non-capturing form translated and the capturing form produced nothing, and every existing test passed because every existing test used the non-capturing form. The tests were written against the implementation rather than against the corpus, and the reporting repo contains no non-capturing path wildcard at all: a dispatcher captures the segment because it needs the id. This alone also repairs the already-shipped `.test` rule. A capture around anything that is NOT one segment still bails — `(.+)` spans slashes — and the alternation is balanced, so `([^/]+` unclosed is not a match. `.match` differs from `.test` in one way that matters: its result is USED, so it is almost always BOUND, and the verb then lives in a later `if`: const runMatch = pathname.match(/^\/api\/research-runs\/([^/]+)$/) if (req.method === 'GET' && runMatch) { … } Reading the verb off the CALL would report every one of those verb-less. So a bound match records `name -> path` and the route is emitted where the binding is TESTED, once per test site — one binding tested for GET and for PUT is two routes. A reference counts only in a truthiness position (`&&`/`\|\|` operand, or a whole `if` condition), which is what separates `if (m && …)` from `m[1]`: a read of the captured segment says nothing about dispatch and would otherwise mint a duplicate route per use of the id. A binding never tested still emits one verb-less route — the code did compute an anchored match against the path. Regexes named by a same-file const resolve too (`pathname.match(POSITION_REPLAY_RE)`), with the same ambiguity refusal the string-constant map uses: bound twice to different patterns means dropped, because a half-right regex is a wrong route. SCHEMA_BUMP 56 -> 57. Free against origin/main (48). Nine mutations, each failing exactly the tests that claim it. TWO of my own tests initially survived their mutation and were rewritten, not kept: - the non-path-receiver case had no path token anywhere in the fixture, so PATH_TOKEN_HINT skipped the file and the assertion was satisfied by a file that was never examined; - the negation case used `!m`, which never reaches the negation check at all — a `unary_expression` parent is not a truthiness position to begin with. The shape that exercises it is `!(req.method === 'GET' && m)`. A declaration-site skip written alongside them proved unreachable for the same reason and was removed rather than left to imply a hazard. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> * feat(processes): report what the detection ceilings dropped, instead of logging it at debug (W2-3) `processProcesses` has five ceilings - the entry-point trace quota, the per-entry trace budget, `maxTraceDepth`, `maxBranching` and `maxProcesses` - and every one of them fired silently. The result came back looking whole and no consumer could tell it was a sample. The code's own comment already said so: // A silently truncating cap reads as "this is everything", which is the // same class of confident-empty answer this work is about. and then only called `logger.debug`. A log nobody has enabled is not a disclosure. `stats.truncation` is additive, so every existing consumer of `totalProcesses` / `crossCommunityCount` / `avgStepCount` / `entryPointsFound` is unchanged. It carries one boolean to branch on plus a counter per ceiling, kept SEPARATE rather than summed because they mean different things: unexplored entry points mean whole flows are missing, while a depth-capped trace means a flow is present but shorter than it really is. `processesDropped` counts against the DEDUPED population, not the raw trace list - the gap between those two is deduplication doing its job, and counting it as truncation would report a permanent non-zero on every healthy repo. `truncated` is DERIVED from the counters rather than set at each site, so a ceiling added later only has to increment its own counter to be reported. Surfaced at `warn` and NOT gated on `isDev`: "823 flows" printed without it reads as the complete set, which is the confident-empty failure wearing its other face - a confident-COMPLETE one. The debug line stays for the per-entry detail it carries. Seven mutations, each failing exactly the tests that claim it, including BOTH directions of the flag: hardcoding `truncated` false fails the four positive cases, and hardcoding it true fails the nothing-was-truncated case, which is asserted first precisely so the positives cannot pass vacuously. The `walksCutByBudget` fixture gives every node exactly `maxBranching` callees so it asserts its own counter and not a neighbour's. Also fixes a defect this work exposed: 10b0c7a1 (W2-5) embedded a RAW NUL BYTE in `trace.join(...)` instead of the backslash-u escape the rest of the repo uses. It behaves identically at runtime, but `file` reports the source as `data`, and grep, git diff and code search treat it as binary - several greps against this file silently returned nothing while I was reading it. main was clean here; two other files carry the same raw byte from before this branch and are left alone. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> * feat(scope-resolution): resolve members through a MEMBER-CALL producer's return shape (W2-1) const svc = new SignalService() const r = svc.make() return r.secretFlag // <- no edge `return-shape-members` types `r` to the producer that made it, but a member call binds the spelling `svc.make`, and slicing that to its last segment leaves `make` — a METHOD, never a callable binding in scope. The producer lookup failed and the pass declined. The limit shipped documented as needing inter-procedural receiver typing. It does not. Measured on a fixture, the pipeline had already done the hard part: - `readMake -> Method:...SignalService.make#0` already resolves as an ordinary CALLS edge, so the receiver is already typed; and - `Property:...SignalService.make.secretFlag@N:C` already exists, because R3-4 anchors a returned literal's keys to the METHOD that returns them, not only to free functions. Both halves were present and unjoined — the same shape as R3-5 itself. ADDITIVE, not a reroute. The new branch sits inside `if (producerFile === undefined)`, so it can only fire where the callable lookup already declined; every reference that resolved before resolves identically, by construction rather than by test. Nothing new is inferred. The receiver is typed by the SAME predicate that typed `r`, and it must itself resolve to a class — a receiver that cannot be typed still declines, so `make.<member>` is never matched by name across the graph. That fabrication is what the existing guards exist to stop and they all carry over unchanged: the owner must resolve, its file must match the candidate's, and `ownFilePaths` keeps the polyglot class registry from walking a JS read into a Java field. The owner segment is TWO parts for a method (`SignalService.make`) and one for a free function (`makeSignal`), which is exactly how R3-4 qualifies each. That is what separates two methods of one class returning the same key name from each other AND from a free function of that name — the fixture gives `secretFlag` three owners so a wrong resolution is detectable rather than a coin flip that happens to look right. Four mutations, each failing exactly the two tests that claim it: removing the fallback, using the method alone as the owner segment, taking the producer file from the reading file instead of the owner class, and dropping the receiver-type requirement. 3,408 resolver tests pass, including `polyglot-property-isolation`, which is the one this could plausibly break. No SCHEMA_BUMP: this is a resolution pass over ParsedFiles, not parse-time output, so a warm cache replays the same input and produces the new edges. Measured on crypto-trading-bot: ZERO new edges, byte-identical at 62,158. Its 170 `const x = new Y()` bindings are overwhelmingly built-ins (Map, Set, Promise, S3Client) rather than workspace classes whose methods return object literals — it is a module-style JS codebase. Correctness fix for class-shaped code, not a recall win on this corpus, and it should not be presented as one. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> * feat(scope-resolution): type a bare parameter from what its callers pass (W2-2) function readSpike(spike) { return spike.wickRatio } had nothing to type `spike` from, so the read fell through to the 0.5 name tier. That is the standing limit of R3-5 and, measured, by far the largest: 11,012 of 13,672 property edges on the reporting repo (81%) rest on that name guess. The two facts needed were already extracted, for a different consumer. For JS and TS among others, `callable-flow-captures` synthesizes: formal owner=readSpike binding=spike parameter-index=0 argument source=s parameter-index=0 direct-callee-name=readSpike Joining them on (callee, parameterIndex) says which cell reaches which parameter, and the argument's own binding is typed by the same `findReceiverTypeBinding` a directly-bound receiver already uses. So the parameter inherits the producer and `spike.wickRatio` resolves as evidence rather than inference. No new capture, no parse-time change, NO SCHEMA_BUMP. And deliberately not a change to the callable-value-flow solver that owns these sites: that pass is guarded by a fingerprint CORRECTNESS gate plus a timing budget, so this reads the same facts and computes its own map. AMBIGUITY DECLINES. A parameter whose callers pass different producers resolves to nothing. Picking one would fabricate at the 0.9 PRECISE tier, which no `minConfidence` floor can filter out — the same reason `buildConstantMap` drops an ambiguous constant instead of taking the first. Keyed by the formal's (scope, name), not by a definition id. The first attempt used a def and measured `paramDef=NONE`: a parameter is not reachable through `findValueBindingInScope` (its predicate is `isOwnableValueLabel`, which lists Const/Variable/Property/Static because it exists for OWNERSHIP registration, and a parameter is owned by nothing) and it is not a `local` binding either. The formal site already states the scope its parameter binds in, which is enough. Formals carry their DECLARING FILE in the key, so two same-named functions in different files cannot answer for each other — dropping it makes both go ambiguous and both readers silently lose their edge. COVERAGE, counted rather than assumed. The synthesis skips an argument that is itself a call result (an explicit `continue` in `callable-flow-captures`), so `f(makeSignal())` emits no argument site and only the bound spelling `const s = makeSignal(); f(s)` is served. That looked fatal until measured: in the reporting repo, bare-identifier arguments outnumber call-result arguments 2,563 to 50 — 51:1. Extending the shared, benched capture synthesis for the 2% case is not worth its risk. Four mutations, each failing exactly the tests that claim it: keeping the first producer instead of declining on conflict, dropping the read-site lookup, matching a formal at index 0 regardless of the argument's index, and dropping the declaring file from the formal key. Two of those could not be caught by the first fixture at all — it had a single parameter and a single consumer file — so the fixture gained a two-parameter callee and a same-named twin in a second file before they were meaningful. The test helper also had to start filtering by source FILE, or two different `readSpike` symbols merged into one count. Measured on crypto-trading-bot: 36 reads left the 0.5 name-guess tier. 26 became precise 0.9 edges (return-shape reads 1,130 -> 1,156, which is the whole delta), and 10 became honest absences — the receiver was typed, the producer's shape was known, and the member is NOT on it, so the site is claimed as disproved rather than left for the name fallback to invent an answer for. That is ~0.3% of the 11,012, and it should be reported as such. The 81% figure is the size of the PROBLEM, not of this fix: the shape requires a bound argument, a producer that returns an object literal, and a parameter read as a receiver, and that intersection is narrow. The remaining name-tier reads are mostly receivers no workspace producer types at all. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> * fix(processes,ci): anchor trace subsumption, cover the sink wiring, stop one bench guard hiding the rest (#2894, #2896, #2895) Three follow-ups reported against #2856 after it merged. Each was reproduced before it was fixed. #2894 — trace subsumption matched mid-identifier. `deduplicateTraces` decided whether one trace is a sub-path of another with an UNANCHORED `String.includes`, so a match could begin in the middle of a node id: 'X->AA->B'.includes('A->B') -> true and `A -> B` was discarded as redundant against a chain `A` is not a step of at all. Reproduced directly against the function before fixing. Padding both keys with the separator makes `includes` match whole steps only. Reported as measured-inert and that holds — the collision needs one node id to be a strict suffix of another at a `->` boundary, which real ids (`Function:<path>:<name>`) do not produce. Fixed anyway because the predicate did not mean what the surrounding code says it means, in a function whose entire job is deciding what to delete, and nothing pinned it. `deduplicateTraces` is exported for the test, matching how `traceFromEntryPoint` and `buildSinkFunctionSet` are already reached. The tests use bare ids because the shape cannot be built from realistic ones — which is exactly why nothing caught it. Alongside the regression case, two tests pin that GENUINE subsumption still happens, prefix and suffix, so the fix cannot degenerate into "subsume nothing" and pass the first test trivially. Mutation-checked: reverting the padding fails the mid-identifier test and only that one. The encoding assumes `->` never appears IN a node id; a C++ `operator->` would defeat the join regardless of padding. Out of scope, but the assumption is now written down where the join happens. #2896 — the sink wiring was only ever exercised through its fail-open catch. `processesPhase` reads `allFetchCalls` / `allORMQueries` off the parse output inside a try/catch that falls open to "no sinks", and every phase-level test omitted `parse` — so all of them took the CATCH branch and the success path had no coverage. `getPhaseOutput` is a raw `as T` cast, so a field rename would make the phase detect zero sinks while every test still passed, because zero sinks is what they already assert. The new test asserts the one thing only the success path can produce: a flow ENDING at the sink while a longer chain continues past it. Its control is the same graph with no `parse` dep, which must NOT produce that terminal — without the control the assertion could pass for an unrelated reason. Also asserts `processesPhase.deps` contains `parse`, so the read and the declaration cannot diverge, and that a parse output missing those fields still fails open rather than losing every process. Mutation-checked, including the exact drift scenario reported: renaming `allFetchCalls` at the read site, dropping `parse` from `deps`, and passing no sinks to `processProcesses` each fail exactly the test that claims them. #2895 — a failing bench guard aborted the job and masked every later guard. Every step in the benchmarks job was fail-fast, so the first failing `--check` aborted it and the rest reported `skipped`, which reads identically to "nothing to do". Audited over 13 runs on #2856: the job succeeded zero times and the last two guards executed zero times for the life of the PR, while two reviews read the checks summary and saw nothing wrong. Both guards did in fact pass — that was luck, not verification. `if: ${{ !cancelled() }}` on all ten steps after the first, so one stale baseline reports one red step instead of hiding nine. `!cancelled()` rather than `always()` so an explicit cancel still stops the job instead of running seven minutes of benchmarks nobody is waiting for. The two steps easiest to miss are covered: `Receiver-resolution drop guards`, whose `run:` sits twenty lines below its `name:` behind a long comment, and the final `Cross-language pipeline benchmarks` step, which is not a `--check` and so falls outside any grep for one — and is one of the two that never ran. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> * fix(parse): capture a fetch call site even when its URL is not a literal (#2897) The `fetch` rule required the argument to be a string or template literal: arguments: (arguments [(string (string_fragment) @route.url) (template_string) @route.template_url]) so `fetch(url)` with a variable matched nothing at all. Measured across this repository's own TypeScript sources: 44 of 47 fetch calls pass a variable, so 94% produced no site. That is what makes R3-6 look inert. The sink set is built entirely from `allFetchCalls` / `allORMQueries`, so a function performing an outward call through a computed URL was never a sink, no flow could terminate there, and the sink-first ranking rule never changed an ordering. The feature was fine; the signal underneath it was almost always empty. The URL alternation is now OPTIONAL, so one match covers both shapes. The R3-6 sink set needs only WHERE the program reaches outward, not where to. Route linking is untouched, by construction rather than by hope: `processNextjsFetchRoutes` normalizes the URL first and skips anything that yields nothing, so a URL-less entry cannot mint a FETCHES edge. Verified on this repo — FETCHES went 8 -> 9 across the change, i.e. the widening added sink sites without inventing route edges, which was the one real risk here. Tested in BOTH JavaScript and TypeScript, since the rule is duplicated in each query block and fixing one would have left the other blind: - a variable argument is captured, with no URL <- the regression case - a computed argument (`fetch(buildUrl(), {...})`) likewise - a literal URL is still captured WITH its URL <- route linking depends on it - a template URL likewise - exactly ONE site per call — an optional alternation must not make a literal match twice, which would double-count the site and could mint two edges - `prefetch('/x')` is still not a fetch Mutation-checked: restoring the mandatory alternation fails six of the twelve, three in each language. SCHEMA_BUMP 57 -> 58. Parse-time capture output is replayed verbatim from a warm cache, so without the bump an already-indexed repo keeps its empty sink set and the fix looks inert — which is the failure this constant exists to prevent, and would have reproduced the very symptom being fixed. Not addressed here, and worth stating: this widens `fetch` only. The reporter's broader point stands — anything keyed on FETCHES / QUERIES is only as good as the extraction underneath it, and the ORM side has not been measured. A guard that fails when a corpus known to contain outward calls yields zero sites is the right follow-up; this change makes such a guard meaningful rather than tautological. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> * test(bench): re-baseline receiver-resolution for the two fixtures this PR adds `receiver-resolution --check` failed on: countArm.totalDropsAllKinds: 140 -> 148 countArm.bySiteKind.write: 11 -> 19 Investigated before touching the baseline, because a guard that exists to catch unexplained movement should not be silenced by an unverified story. WHAT IT IS: the count arm runs the real pipeline over a corpus that includes `test/fixtures/lang-resolution/`, and this PR adds two fixtures there — `member-call-producer` (W2-1) and `parameter-producer` (W2-2). Each returns an object literal with two keys, and a producer writing its own returned key is a write site the receiver recorder logs. Four each, eight total. Attributed by dumping the individual drops rather than reading the aggregate: member-call-producer/src/producer.js secretFlag, wickRatio (2 lines) = 4 parameter-producer/src/producer.js source, wickRatio (2 lines) = 4 The eleven drops already in the baseline are all `javascript-object-properties` fixtures of exactly the same shape, so the new ones are not a new KIND of drop — they are more of one the baseline already records. This is the first case the guard's own failure message names: "a fixture was added". WHAT IT IS NOT: `callDrops` — THE gate number, and `call`-only by deliberate design because reads and writes "would inflate it" — is unchanged at 102. `read` drops unchanged at 27. The SHAPE ARM shows no drift at all: no receiver spelling moved between RESOLVES / VISIBLE-GAP / INVISIBLE-GAP, so no resolution regressed. HOW IT WAS ISOLATED, since the first attempt was misleading and the record is worth having: reverting `return-shape-members.ts` alone did NOT reproduce it and pointed away from W2-1/W2-2. Only a commit-level bisect was trustworthy — `origin/main` OK, W2-8 OK, W2-3 OK, then W2-1 +4 and W2-2 +4, which matches the fixture count exactly. A file-level revert leaves the fixtures in the tree, and the fixtures are the cause. The update is two numbers. Nothing else in the baseline moves. Worth noting where this failure became visible at all: under the fail-fast benchmarks job it would have aborted the run and shown the five guards after it as `skipped`. It is legible here because #2895 — fixed in this same PR — now lets every later guard run. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> * fix(analyze): stop `--pdg` runs reporting a healthy index as INCOMPLETE Every `gitnexus analyze --pdg` reported a graph-write collapse and exited 1 on an index where every row had persisted. Reported by a user hitting it on a real repo; introduced by this PR's own W2-6(d). Repository indexed INCOMPLETELY the pipeline produced 200,501 relationships but only 64,764 are readable The index was complete: 200,190 rows present, 109,905 PDG and the rest structural, all queryable. WHAT WENT WRONG. W2-6(d) made the persisted side count STRUCTURAL rows only — correct, and the reason is in its own comment: PDG writes into the same table, so counting everything let PDG surplus mask real structural loss. But the expected side kept using `graphEmitManifest.totalRows`, and that is a BUFFER-POOL SIZE HINT which counts every streamed row. PDG streams through that same sink, so the check compared a structural-plus-PDG expectation against a structural measurement. On any repo with a PDG layer that is a guaranteed false collapse. It compounds rather than merely misreporting: the run stamps `graph-write-collapsed`, and W2-6(a)'s rebuild trigger — added alongside it — forces a full re-analyze next run, which collapses again. A permanent rebuild loop, on an index that was never damaged, at ~100s a cycle. MEASURED RATHER THAN ASSUMED, because the first attempt was wrong. I first subtracted PDG edges RESIDENT in `graph.relationshipCount`, rebuilt, re-ran the failing command and got byte-identical numbers. Instrumenting the three terms showed why: relationshipCount=20,825 graphManifestTotalRows=179,676 pdgEmitManifest=absent residentPdgInGraph=0 PDG is not resident in the graph AND has no separate manifest — it streams through the ordinary `GraphEmitSink`. The reverted attempt is not in this diff. THE FIX. A pair key cannot separate them: it is `From\|To` NODE LABELS, and a CFG edge shares `Function\|Function` with CALLS. Only the write path sees `relationship.type`, so the sink now counts a `structuralRows` subtotal there and publishes it on the manifest. `totalRows` is unchanged — it still sizes the buffer pool, which is what it was for. WHY THIS SHIPPED UNCAUGHT, and what changed about that. The wiring test kept a LOCAL MIRROR of the expected-count expression "because the production expression is inline in a 3000-line function". A mirror cannot catch a term the original got wrong. That expression is now an exported `computeExpectedStructuralRelationships` which production calls and the test imports. It also takes the MANIFEST rather than a pre-selected number, deliberately: the defect was choosing the wrong FIELD, and a numeric parameter leaves that choice at a call site no unit test can reach. Verified — with the helper taking a number, reverting to `totalRows` failed nothing; taking the manifest, the same revert fails four tests. Verified end to end on the reported command: `analyze --force --embeddings 0 --pdg` now exits 0 with "indexed successfully", 86,963 nodes / 200,217 edges, and the run clears the stale collapse stamp. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> * fix(routes): scope match bindings, and intersect ternary conjunctions Two ways the dispatch-guard walk minted a route that does not exist — the one thing this module's header says is worse than missing one. MATCH BINDINGS WERE KEYED BY BARE NAME, FILE-WIDE. `collectFromMatchBindings` walked from `tree.rootNode` and resolved `matchBindings.get(node.text)` at every identifier in a truthiness position, so a same-named binding in ANOTHER function answered for it. The poison check only fired on a second REGEX match with a different URL; a non-match binding never entered `collectFromRegexDispatch`, so nothing refused it. Reproduced: function handleReplay(req, res) { const m = pathname.match(/^\/api\/live\/positions\/([^/]+)\/replay$/); if (req.method === 'GET' && m) { … } } function handleSettings(req, res) { const m = req.headers['x-mode']; // unrelated value, same name if (req.method === 'DELETE' && m) { … } } GET /api/live/positions/{param1}/replay handler=handleReplay correct DELETE /api/live/positions/{param1}/replay handler=handleSettings FABRICATED Wrong in method, handler and line. `m`, `match`, `result` are the ordinary names here. Two ways the truth was then lost: the fabricated route is VERBED, so `reconcileDispatchGuardRoutes` kept it and dropped the true verb-less one — the #2856 `/api/report` shape, through the channel this series added — and `tested` was name-keyed too, so the tail loop suppressed the real binding's own honest verb-less emit before reconciliation ever ran. `matchBindings` and `tested` are now keyed on (enclosing function, name). `enclosingFunction` is extracted from the walk `enclosingHandlerName` already did, so there is one function-boundary mechanism, not two. A second declarator for a key refuses it, and an assignment refuses the name in its own scope and every enclosing one. `buildRegexConstantMap` refuses a name rebound to anything that is not a regex literal, closing `let RE = /…/; RE = buildDynamic(req)` and the `new RegExp(prefix + '/x')` twin. A use resolves only within its own function. Resolving outward would need a complete declaration model — params, imports, catch bindings — and a miss there fabricates exactly the route this fixes. Declining costs the verb, not the path. THE TERNARY TOOK FIRST-MATCH WHERE THE ALGEBRA IS INTERSECTION. The docblock proves `c ? A : false ≡ c && A` and says "both hold, so search both", but `firstNonEmpty` returned one operand's set unintersected: (req.method === 'GET' \|\| req.method === 'POST') ? (req.method === 'POST' \|\| req.method === 'PUT') : false emitted GET and POST only POST is reachable req.method === 'GET' ? req.method === 'POST' : false emitted GET, unsatisfiable `intersectVerbs` replaces it for both conjunction shapes. An empty side still yields to the other — "names no method" is not "admits none", which is what the `isAdmin && POST` fallthrough is for — but two non-empty sides intersect, and an empty intersection is an unsatisfiable guard that yields no verb. Both changes strictly REMOVE routes, so SCHEMA_BUMP 58 -> 59: routes are parse-time output replayed verbatim from a warm cache, and without the bump an indexed repo keeps serving the fabricated verbed route while the fix looks implemented. 10 tests added, 9 of which fail without the change. All 86 existing assertions pass unchanged; none was weakened. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01LZu3G5USo5Rs9myaaxVWjK * fix(scope-resolution): bind a type parameter only inside the scope it opened W2-8 captured `@declaration.type-parameters` on EVERY `type_alias_declaration`, but an alias becomes a SCOPE only when its value is an `object_type` (`typescript/query.ts:149`). For a union, array, conditional, mapped, tuple or function alias there is no scope, so the def — now carrying `typeParameters` — attached to the innermost enclosing scope, which is the MODULE. And `typeParameterNamesInScope` folds each scope's set from its PARENT'S, so the name landed in every scope in the file. The `USES` guard then deleted every edge whose target had that simple name: export interface Result { ok: boolean } export type Maybe<Result> = Result \| null // one ordinary line export function readResult(r: Result) { … } // its USES edge is DELETED Silent data loss, in the edge class whose whole purpose is answering "what breaks if I remove this field?". Measured: adding two scope-less generic aliases emptied the fixture of USES edges entirely. The existing fixture could not see it — it wrote `type Box<Result> = { held: Result }`, the ONE alias form that opens a scope. `typeParameterNamesInScope` now reads a def's `typeParameters` only when that declaration OPENED the scope owning it: `scope.kind !== 'Module'` and the def-id position equals the scope range start, via the canonical `definitionIdPosition` rather than slicing the id. That is the same alignment test `pickCallerCallableDef` uses to tell a closure from a nested function, and it is language-neutral — it also covers `function f() { type W<Result> = Result[] }`, which a module-scope-only stopgap would miss. Every language populating the capture was audited (ts, java, csharp, kotlin, rust, cpp): all anchor it on a declaration that IS a scope node, including C++ where the capture rides `template_declaration` but the anchor is the inner `class_specifier`. Go uses a separate sidecar. The TypeScript non-object alias was the only mismatch in the codebase. `query.ts` is untouched. THE GUARD ALSO SAT AT THE WRONG LAYER, which forced three defects at once. It keyed on `edgeType === 'USES'` — and `mapReferenceKindToEdgeType` maps THREE kinds there, `type-reference`, `value-ref` (#2437) and `macro` (#1934) — and, because `Reference` carries no spelled name, substituted the resolved def's name via `simpleNameOfDefId`. So `import { Result as ApiResult }` inside `function unwrap<Result>()` deleted a REAL edge, while a namespace-qualified target (`Host.Result`) kept a FALSE one, and a positional `@row:col` suffix broke the last-colon parse outright. Moved to `lookupForSite`'s `case 'type-reference'` in `resolve-references.ts`, which has the spelled `site.name` and the reference kind in hand. One line closes all three, deletes `simpleNameOfDefId` — a byte-identical duplicate of `simpleNameOfGraphId` — and removes the only `graph-bridge/` -> `scope/` import in that directory. Honest scope: all three sub-defects are real in the code but none is observable end-to-end today (`value-ref` never reaches this path; TypeScript emits no cross-file USES for a type annotation at all — a separate pre-existing gap). Those arms are labelled forward guards in the test rather than claimed as repros. Fixture grows 1 file -> 4; 3 of 9 assertions fail without the change. The scope-capture TypeScript fingerprint moves for FIXTURE-CORPUS GROWTH ONLY, with per-file accounting that sums to the delta and JavaScript unchanged as the control — see the `_rebaselined_` key. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01LZu3G5USo5Rs9myaaxVWjK * fix(scope-resolution): refuse an ambiguous formal, stop the walk at the nearest binding Two ways W2-2 typed a parameter from the wrong caller, both at the PRECISE 0.9 tier — above every `minConfidence` floor, so nothing downstream can filter them. `formals` WAS LAST-WRITE-WINS. The key is (filePath, ownerName, parameterIndex), `ownerName` is a bare identifier, and `emitFormalFacts` emits one site per parameter of EVERY function collected, nested functions and class methods included. A plain `.set` let two same-named callables in one file collide — a free `parse` and a nested `parse`, a free `apply` and `Runner.apply` — so the last one visited won, fabricating an edge on the loser and leaving the genuine consumer untyped. The file's own comment covers only the cross-FILE axis. The correct shape was thirty lines below, in the `producers` map, which does `producers.delete(cell); conflicted.add(cell)`. `formals` now refuses the same way: a key claimed by two DIFFERENT parameters is deleted and recorded, so a third same-named formal cannot re-claim it. Re-stating the same cell is not a disagreement, so a benign duplicate capture cannot poison a real key. THE SCOPE WALK CLIMBED PAST A NEARER BINDING. The docblock claimed it stops at the first scope carrying the name, but it consulted only `parameterProducers` — a shadowing `const`, a catch binding or an arrow parameter is not in that map, so the walk went straight past it to the enclosing formal: function readSpike(spike) { … items.map((spike) => spike.wickRatio) … } typed the ARRAY ELEMENT from the outer parameter. `parameterProducerFor` now stops at the first scope that binds the name AT ALL — reading the scope's own tables, the same channels and the same reasoning as the sibling `isNamespaceNameShadowed` — and then stops at a Function boundary. That boundary is what covers the anonymous arrow: `collectFunctions` drops a callable it cannot name, so an anonymous arrow emits no formal site and its scope looks empty while in fact rebinding the name. The cost — a closure genuinely reading an enclosing parameter now declines — is documented as the deliberate trade. No cycle guard, deliberately and with the reason stated: both constructions of `indexes.scopeTree` validate through `buildScopeTree`, which enforces strict parent-contains-child ranges, so a cycle needs a scope strictly containing itself. A per-site Set on every read/write site in the repo would defend against a state the builder rejects. 5 fixtures, 5 assertions; 4 fail without the change and the control passes both ways. Still uncovered and not faked: a `for (const x of …)` binder shadow — the binder lives in the loop header, so JS emits no scope to stop at and no Function boundary intervenes. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01LZu3G5USo5Rs9myaaxVWjK * fix(analyze): measure one population in every config, split the stamp on the verdict `1b41c9df6` fixed the collapse check for the STREAMED configuration by giving the sink a `structuralRows` subtotal. It does not cover the other one. `resolveStreamGraphEmit` and `resolveStreamPdgEmit` both open with a `force === true` gate, so a run without `--force` streams nothing: there is no manifest, `structuralRows ?? 0` contributes 0, and `scope-resolution/pipeline/run.ts:1222` (`input.pdgEmitSink ?? graph`) writes PDG into the ordinary in-memory graph, where `relationshipCount` counts it. And `isIncremental` requires an existing meta, so a FIRST run is a full write and the check runs. A first-time `gitnexus analyze --pdg` on a fresh repo therefore compared structural+PDG against structural and exited non-zero with "Repository indexed INCOMPLETELY" on a healthy index. MEASURED, not assumed — `runScopeResolution({ pdg: true })` with no sink: pdgEmitSink = absent (non-force shape) relationshipCount = 1 residentPdgInGraph = 1 byType = [["CFG",1]] The prior `residentPdgInGraph=0` was taken on a `--force` run, where `input.graph` IS the sink; it never spoke to this case. `graph-collapse-wiring.test.ts` had pinned the gap, asserting a PDG-inclusive in-memory count was a valid structural expectation. `countStructuralRelationships(graph)` filters `PDG_EDGE_TYPES` over `forEachRelationshipFields` — the same predicate the sink uses for `structuralRows` and the adapter for `structuralEdges` — so all three terms measure one population in every configuration. Declining whenever `pdg && !streaming` was rejected: that is the DEFAULT PDG shape, so the guard would be off for every non-force run including the only full write most users ever do. An unscannable graph (mocked pipelines) yields NaN, the same fact the old `undefined + rows` produced and one `detectGraphWriteCollapse` already documents as expected input. THE THREE-WAY STAMP WAS A TWO-WAY. The comment enumerated collapse -> stamp, healthy -> clear, no verdict -> carry forward, but the code split on the WRITE MODE. `graphWriteCollapsed` is undefined for two different reasons, and one of them is "the structural query threw" — so on a full run where the count could not be READ, the code took "healthy, clear it" and erased a stamp recording real edge loss. Run 3 then printed "Already up to date" forever: the exact failure the comment says it fixed, reachable through the new code's own `catch {}`. `detectGraphWriteCollapse` now returns `'collapsed' \| 'healthy' \| 'unmeasurable'` with a reason, and `selectPersistedCollapseStamp` is a pure exported function production calls. Two boundaries worth naming: `expected === 0` is unmeasurable (its own docstring calls it "could not report a total"), but the small-repo exemption and a cleared ratio are HEALTHY — both counts were taken. Making the exemption a non-verdict would leave a stamp unclearable on any repo that shrank below 100 edges, relocating the wedge rather than fixing it. `getLbugStats` now reports `structuralEdgesError` and warns, and `run-analyze` falls back to `stats.edges` only when the run had no PDG layer, where the two are equal by construction. With `--pdg` on there is no substitute, so the absence becomes an explicit unmeasurable verdict — which preserves the stamp. 13 tests added; 8 fail without the change. The integration suite now seeds a CFG row and asserts `edges` moves while `structuralEdges` does not — the exclusion filter was previously unexercised, its own comment conceding "structural == total here". Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01LZu3G5USo5Rs9myaaxVWjK * fix(server): check the collapse before publishing the index W2-6 marked a collapsed run's job `failed`, but the check ran INSIDE `.then(() => backend.init())` — after the publish. `LocalBackend.init()` is the publish step: it refreshes the registry and atomically swaps the in-memory repo map every MCP tool and HTTP route resolves through, and its `validate` pass prunes only entries whose metadata is provably gone, so it can publish but never quarantine. The known-incomplete database was therefore live and queryable before the job was ever marked failed — the job status was a label on a published index, not a gate. The pre-existing comment two lines above says so outright: "the repo is actually queryable when the client receives the SSE complete event." `backend-client.ts` routes `failed` to `onError` and never calls `onComplete`, so the UI showed an error toast while every query against that repo answered from the incomplete graph — precisely the confident-wrong-answers failure this guard exists to prevent. The collapse branch now returns before publishing; the healthy path publishes via a nested `backend.init()` so the trailing `.catch` still converts init failures into the same message. `closeDbHandle()` runs on both paths — it is eviction, not publication, and the worker rewrote the DB files regardless of outcome, so skipping it would leave a stale pre-rewrite handle. Honest limit, stated in the error string rather than overclaimed: this keeps a FIRST-TIME analyze unpublished, which is the UI's main flow. On re-analysis of an already-published repo the existing map entry survives and points at the same storagePath. A real quarantine needs an un-register hook on `LocalBackend`, which does not exist today — follow-up. `'partial'` was considered and rejected on evidence: it is not a status. It is an embedding-specific detail object in the `updateJob` allowlist; the status union excludes it. Adding it would make `isTerminalJobStatus` false, so `sse-progress` never writes a terminal frame and never calls `res.end()` — the stream hangs open — while `backend-client` falls through to `onMessage` and `api.ts` spins the full hold-queue timeout. `failed` at least terminates. The failure branch also now sets `repoName`, which only the success path did. First tests this file has ever had: 4, of which 2 fail without the change. They assert the ORDERING, not just the final status, and build the worker message by calling the production `projectAnalyzeResultForIpc` so a field rename breaks the test instead of silently disabling the branch. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01LZu3G5USo5Rs9myaaxVWjK * fix(processes): count the entry-point cap, and make the disclosure proportionate W2-3 added a truncation disclosure and then missed the largest ceiling it was written to report. `findEntryPoints` ends `.slice(0, 200)` and `entryPointsUnexplored` counted against the POST-slice list, so candidates 201..N were invisible — while the derivation docblock claimed "a new ceiling added later cannot be forgotten here". An existing one was. On this repo's own corpus the new counter reads 780 of 980 candidates never ranked in. `entryPointCandidatesDropped` reports the pre-slice count, folded into `truncated`, with `ENTRY_POINT_CANDIDATE_LIMIT` extracted and `findEntryPoints` taking the same optional out-parameter `traceFromEntryPoint` already uses. Its return contract is unchanged. THE WARN FIRED ON EVERY RUN. At the shipped defaults — only `maxProcesses` is overridden — `calleesDropped` fires for any function with 5+ callees and `tracesDepthCapped` for any chain deeper than 10, so an ungated `logger.warn` was constant background noise, and a warning that always fires is one nobody reads. The split is the module's own, from the `ProcessTruncationStats` docblock: "unexplored entry points mean whole flows are missing, while a depth-capped trace means a flow is present but shorter than it really is." So `warn` iff whole flows are absent — candidates dropped, entry points never traced, or flows dropped at `maxProcesses` — and `debug` for a run truncated only in depth or breadth. `stats.truncation` still carries all six counters; the machine-readable channel is unchanged, only the log level moves. `entryPointCandidatesDropped` stays in the loud set deliberately: it is the only ceiling that GROWS with repo size, while the other two can only fire while `maxProcesses` is small enough to bind, so gating on those alone would go silent on exactly the large repos where 200-of-several-thousand is the thinnest sample. The message leads with the ratio so the line carries a fact, not an alarm. THREE COMPARATORS ALLOCATED PER COMPARISON, in the function whose own comment explains the hoist that removed this shape (`deep_chain` 1233 -> 102 ms). Measured here: +99 ms once per analyze at 80k functions — small, because `n` is capped at 200 entry points x a 12-trace budget = 2,400 traces regardless of repo size. Worth fixing anyway: 23,851 comparisons cost 70,524 joins. One shared `sortByDepthThenPath` (Schwartzian, key built once per trace) now serves all three sites, and `rankedByInterest` additionally hoists the `isSink` test that ran twice per comparison. It also settles a separator inconsistency: `deduplicateByEndpoints` joined on a SPACE while `traceOrderKey` used NUL, and node ids embed file paths, so two different traces could produce the same key and the tiebreak fell back to the insertion order it exists to remove — the same hazard this series' own `->`-padding fix addresses. Order identity is pinned by a seeded 200-trace corpus asserting the new sort equals the old one exactly. 11 tests added, 9 failing without the change, including two end-to-end insertion-order arms. The W2-5 determinism block is unregressed. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01LZu3G5USo5Rs9myaaxVWjK * fix(docs): restore the agent guidance, and put it in the generator that deleted it Commit `9e602aef0` — whose message is entirely about the fetch capture — also regenerated the machine-managed `<!-- gitnexus:start -->` block from a local non-`--pdg` index, deleting from both AGENTS.md and CLAUDE.md: - the whole `MUST treat risk: UNKNOWN as unresolved, not as low` bullet - the `pdg_query({mode:"controls"/"flows"})` bullet - the `mode: "pdg"` text on the impact bullet - `…never read UNKNOWN as an all-clear…` from Never Do and regressing the stats 248612/565510/918 -> 42853/135955/758. All four document SHIPPED features: `pdg_query` at `mcp/tools.ts:675`, dispatched at `local-backend.ts:2233`; `mode: "pdg"` at `tools.ts:448`; `riskNote` at eight sites. It matters more than a docs nit because the SAME series makes `UNKNOWN` dominate a mixed candidate set (`local-backend.ts:6058`) — correct, and it makes UNKNOWN far more common. The surviving rule only warns on HIGH/CRITICAL, so a set measuring CRITICAL now reports UNKNOWN and that rule no longer fires, while the rule that covered the gap was deleted in the same commit range, from all three files agents actually read. ROOT CAUSE, which is why restoring the files alone would not have held. `cli/ai-context.ts` is the template. The `pdg_query` and `mode: "pdg"` text IS in it, correctly `hasPdg`-gated — a non-PDG analyze SHOULD drop those. The `risk: UNKNOWN` rules were never in the template at all: they had been hand-added INSIDE the machine-managed region, so every `gitnexus analyze` on any repo silently deleted them. This was the second occurrence; #2856's `8f8261021` was the first. Both lines are now generated unconditionally — they describe impact's risk semantics, which are not PDG-dependent — so regeneration restores them instead of removing them. AGENTS.md and CLAUDE.md are byte-identical to origin/main again, and the fixed template reproduces that block exactly for `hasPdg: true` plus the real stats. `.claude/skills/gitnexus-guide/SKILL.md` regains the "Inline staleness signal" section for a live feature (`local-backend.ts:921`, `:1017-1024`, `:1995`); the npm mirror's lack of it is pre-existing drift and is left alone, so the new sync guard is scoped to the canonical and plugin copies. Guards added, both demonstrated failing against the unrestored files: the managed block must contain the UNKNOWN policy and its Always-Do/Never-Do bullet counts must not fall below a floor, and `generateGitNexusContent` must render both lines for `hasPdg` true AND false while keeping `pdg_query` gated. The existing fragment lists could never have caught this — they assert presence, and this was a deletion. One deliberate loosening, called out rather than buried: the restored text pushes `ai-context.test.ts`'s block-size ratio past 0.55, so it moves to 0.65. That test argues against exactly this nudge-the-number pattern. The defence is that the wording is origin/main's own and the 0.55 budget was calibrated against a block already missing it; trimming shipped guidance to fit a budget would be the wrong direction. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01LZu3G5USo5Rs9myaaxVWjK --------- Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com> Co-authored-by: Gergo Magyar <gergomagyar0@gmail.com> Co-authored-by: Gergő Magyar <gergomagyar@icloud.com>		2026-08-09 11:44:52 +01:00
.agents/plugins	feat: full Codex support — hooks, plugin marketplace, and setup (#2328 , supersedes #1131 ) (#2369 )	2026-07-04 13:32:17 +01:00
.claude	feat: close reported graph blind spots in reference resolution, analyze and storage (#2856 )	2026-08-08 09:58:14 +01:00
.claude-plugin	chore: release v1.6.9 (#2367 )	2026-07-04 07:53:06 +01:00
.cursor	fix(storage): rename index metadata to gitnexus.json with dual-write compatibility (#2363 )	2026-07-03 19:32:59 +01:00
.devcontainer	fix: large-repo analyze OOM and false worker-timeout cascade (#2649 ) (#2679 )	2026-07-25 09:16:17 +01:00
.gemini/commands	feat(review): add PR reviewer swarm agents (#1851 )	2026-05-29 18:24:16 +01:00
.github	fix: close the nine follow-up review findings from #2856 (routes, receiver typing, truncation honesty) (#2899 )	2026-08-09 11:44:52 +01:00
.history/gitnexus	fix(test): add --repo to CLI e2e tool tests for multi-repo environment	2026-03-18 08:12:25 +00:00
.husky	feat: configure prettier with pre-commit hook (#563 )	2026-03-28 14:58:04 +00:00
.sisyphus/drafts	fixed constructor to method relation not getting stored in kuzu issue	2026-01-26 22:58:15 +05:30
deploy/kubernetes	ci(docker): mirror signed images to Docker Hub alongside GHCR (#1029 )	2026-04-23 18:59:26 +01:00
docs/plans	fix(python): resolve calls through an unaliased dotted namespace import (#2826 ) (#2828 )	2026-08-05 11:35:27 +01:00
Documentation	Add Kilo Code + GitNexus MCP setup guide (#2259 )	2026-07-02 11:04:22 +01:00
eslint-rules	fix(windows): 32767-char tree-sitter crash + VECTOR extension SIGSEGV (#1433 )	2026-05-10 16:00:36 +01:00
eval	chore(deps): bump aiohttp in /eval in the uv group across 1 directory (#2825 )	2026-08-04 09:55:59 +00:00
gitnexus	fix: close the nine follow-up review findings from #2856 (routes, receiver typing, truncation honesty) (#2899 )	2026-08-09 11:44:52 +01:00
gitnexus-claude-plugin	feat: close reported graph blind spots in reference resolution, analyze and storage (#2856 )	2026-08-08 09:58:14 +01:00
gitnexus-cursor-integration	feat: close reported graph blind spots in reference resolution, analyze and storage (#2856 )	2026-08-08 09:58:14 +01:00
gitnexus-shared	fix(resolution): resolve calls through a generic-typed field receiver in every language (#2833 ) (#2855 )	2026-08-07 17:14:13 +01:00
gitnexus-test-setup	feat: merge gitnexus-mcp into gitnexus package - unified CLI+MCP	2026-02-04 01:12:41 +05:30
gitnexus-web	chore(deps)(deps): bump dompurify (#2893 )	2026-08-08 09:59:39 +01:00
pr-swarm-review	feat(skills): GitNexus Engineering Tool Kits (#2566 )	2026-07-19 15:07:24 +01:00
.cursorrules	docs: agent development framework, GitHub templates, eval refactor (#479 )	2026-03-25 06:48:41 +00:00
.dockerignore	fix(ci): Change docker base image from alpine to debian (#1014 )	2026-04-21 21:31:58 +01:00
.env.example	feat(analyze): private GitHub repos via PAT + Azure DevOps Server support (#2076 , #2210 ) (#2223 )	2026-06-16 05:49:02 +01:00
.git-blame-ignore-revs	feat: configure eslint with unused import removal (#564 )	2026-03-28 15:28:09 +00:00
.gitattributes	feat(devcontainer): add devcontainer for Claude/Codex/Cursor CLIs (#1875 )	2026-06-02 05:09:01 +01:00
.gitignore	chore: stop tracking docs/plans (planning output stays local)	2026-07-21 10:09:35 +00:00
.gitleaks.toml	feat(analyze): private GitHub repos via PAT + Azure DevOps Server support (#2076 , #2210 ) (#2223 )	2026-06-16 05:49:02 +01:00
.gitleaksignore	chore(security): suppress deleted auth placeholder	2026-07-16 10:08:59 +07:00
.mcp.json	fix: use cross-platform npx command in .mcp.json	2026-02-22 17:46:04 +00:00
.prettierignore	chore(quality): exclude test/fixtures from CodeQL, ESLint, and Prettier (#1313 )	2026-05-04 09:35:34 +01:00
.prettierrc	feat: configure prettier with pre-commit hook (#563 )	2026-03-28 14:58:04 +00:00
.windsurfrules	resources implemented and agents.md and skills updated to use it	2026-02-05 05:13:48 +05:30
AGENTS.md	feat: close reported graph blind spots in reference resolution, analyze and storage (#2856 )	2026-08-08 09:58:14 +01:00
ARCHITECTURE.md	feat: close reported graph blind spots in reference resolution, analyze and storage (#2856 )	2026-08-08 09:58:14 +01:00
CHANGELOG.md	perf(hooks): cmdline-first Linux db-lock scan, drop the lsof fallback (#2180 ) (#2183 )	2026-06-13 11:52:14 +01:00
CLAUDE.md	feat: close reported graph blind spots in reference resolution, analyze and storage (#2856 )	2026-08-08 09:58:14 +01:00
compound-engineering.local.md	feat: Phase 7 type resolution — return-aware loop inference & PHP class-property iterables (#341 )	2026-03-18 08:39:38 +00:00
CONTRIBUTING.md	feat(serve): validate and port-scope the origin/proxy configuration surface (#2820 )	2026-08-05 06:52:39 +01:00
docker-compose.yaml	feat(web): support GITNEXUS_BACKEND_URL env var for Docker deployments (#1286 )	2026-05-25 11:21:11 +01:00
docker-server.mjs	feat(render): add one-click deploy to render support (#2804 )	2026-08-06 00:19:44 +00:00
docker-server.test.mjs	feat(render): add one-click deploy to render support (#2804 )	2026-08-06 00:19:44 +00:00
Dockerfile.cli	feat(render): add one-click deploy to render support (#2804 )	2026-08-06 00:19:44 +00:00
Dockerfile.web	fix(security): Pin Docker Node base images, remove runtime package-manager CVE surface, verify Trivy on PRs, and harden Dependabot policy (#1455 )	2026-05-09 16:55:31 +01:00
DoD.md	feat(skills): GitNexus Engineering Tool Kits (#2566 )	2026-07-19 15:07:24 +01:00
eslint.config.mjs	fix(windows): 32767-char tree-sitter crash + VECTOR extension SIGSEGV (#1433 )	2026-05-10 16:00:36 +01:00
GUARDRAILS.md	feat: close reported graph blind spots in reference resolution, analyze and storage (#2856 )	2026-08-08 09:58:14 +01:00
LICENSE	docs: update license copyright holder	2026-02-03 22:54:01 +05:30
llms.txt	docs: agent development framework, GitHub templates, eval refactor (#479 )	2026-03-25 06:48:41 +00:00
MIGRATION.md	feat: close reported graph blind spots in reference resolution, analyze and storage (#2856 )	2026-08-08 09:58:14 +01:00
package-lock.json	chore(deps-dev): bump the npm_and_yarn group across 1 directory with 2 updates (#2621 )	2026-07-21 22:43:34 +01:00
package.json	feat(package): add gitnexus commands for analysis	2026-04-29 16:37:06 +03:00
README.md	feat(render): add one-click deploy to render support (#2804 )	2026-08-06 00:19:44 +00:00
render.yaml	feat(render): add one-click deploy to render support (#2804 )	2026-08-06 00:19:44 +00:00
RUNBOOK.md	feat: close reported graph blind spots in reference resolution, analyze and storage (#2856 )	2026-08-08 09:58:14 +01:00
SECURITY.md	feat(render): add one-click deploy to render support (#2804 )	2026-08-06 00:19:44 +00:00
skills.mdm	FEAT: Added support for optional skill generation based on KuzuDB after initial repo analysis (npx gitnexus analyze --skills) (#171 )	2026-03-13 08:29:13 +00:00
swift-ingestion-gaps.md	docs: add macro declarations to Swift ingestion gaps	2026-03-23 14:21:32 +01:00
TESTING.md	refactor(ingestion): delete legacy call-resolution DAG + heritage processor (RING4-1, #942 ) (#2023 )	2026-06-04 11:07:37 +01:00
type-resolution-roadmap.md	feat: implement cross-file binding propagation for multiple languages	2026-03-21 07:47:04 +00:00
type-resolution-system.md	feat(ingestion): TypeScript registry-primary scope resolution (Ring 3) (#1050 )	2026-04-26 08:23:08 +01:00

README.md

GitNexus

⚠️ Important Notice: GitNexus has NO official cryptocurrency, token, or coin. Any token/coin using the GitNexus name on Pump.fun or any other platform is not affiliated with, endorsed by, or created by this project or its maintainers. Do not purchase any cryptocurrency claiming association with GitNexus.

The nervous system for agent context.

Indexes any codebase into a knowledge graph — every dependency, call chain, cluster, and execution flow — then exposes it through smart MCP tools so AI agents never miss code.

💬 Discord · 🌐 Web UI · 🏢 Enterprise (SaaS & self-hosted)

https://github.com/user-attachments/assets/172685ba-8e54-4ea7-9ad1-e31a3398da72

Like DeepWiki, but deeper. DeepWiki helps you understand code. GitNexus lets you analyze it — a knowledge graph tracks every relationship, not just descriptions.

TL;DR: The CLI + MCP makes your AI agent reliable — it gives Cursor, Claude Code, Antigravity, Codex, and friends a deep architectural view of your codebase so they stop missing dependencies, breaking call chains, and shipping blind edits. Even smaller models get full architectural clarity. The Web UI is a quick way to chat with any repo in the browser.

Quick Start

# 1. Index your repo (run from repo root)
npx gitnexus analyze

# 2. Connect your editors (one-time, auto-detects Claude Code, Cursor, Codex, …)
npx gitnexus setup

That's it. analyze indexes the codebase, installs agent skills, registers Claude Code hooks, and creates AGENTS.md / CLAUDE.md context files — all in one command. setup writes the MCP config so your AI agent can use the graph.

Install problems? npm 11 crash · slow cold install · no C++ toolchain

On npm 11.x? npx can crash during install with Cannot destructure property 'package' of 'node.target' (an npm/arborist bug, before GitNexus runs). Use pnpm instead — it builds the native deps explicitly:
pnpm --allow-build=@ladybugdb/core --allow-build=gitnexus --allow-build=tree-sitter dlx gitnexus@latest analyze
Or install globally (npm install -g gitnexus@latest) and run gitnexus analyze. See #1939.

Fastest MCP startup: install globally (npm i -g gitnexus) before running gitnexus setup — this writes an absolute-path MCP config that bypasses npx entirely. On a cold cache, an npx-based MCP install can exceed Claude Code's MCP_TIMEOUT default (~30s).

No C++ toolchain? Set GITNEXUS_SKIP_OPTIONAL_GRAMMARS=1 before npm install -g gitnexus to skip the vendored grammar materialize/build for tree-sitter-dart, tree-sitter-proto, tree-sitter-swift, and tree-sitter-kotlin — those four languages won't be parsed, but install completes in seconds without python3/make/g++. Strict =1 only — any other value falls through to the rebuild.

Behind an HTTP proxy / regional firewall? onnxruntime-node's postinstall downloads optional CUDA binaries from api.nuget.org and ignores HTTP_PROXY/HTTPS_PROXY (#2370). The embedding stack is an optional dependency, so a failed download no longer breaks the install — and it self-heals: the first gitnexus analyze --embeddings (or gitnexus embeddings install) fetches the stack through your npm registry config (mirrors/proxies apply, no NuGet) into ~/.gitnexus/embedding-runtime (override with GITNEXUS_EMBEDDING_RUNTIME_DIR). The on-demand prefix needs Node with module.registerHooks (≥ 22.15 on 22.x, ≥ 23.5 on 23.x); on older Node, keep the stack in the install itself with ONNXRUNTIME_NODE_INSTALL=skip npm install -g gitnexus (works on every supported Node).

About tree-sitter-kotlin: like Dart/Proto/Swift, Kotlin is a vendored grammar (under gitnexus/vendor/tree-sitter-kotlin). Upstream ships source only (no prebuilt binaries), so GitNexus cross-builds the platform prebuilds itself (via the build-tree-sitter-prebuilds GitHub Actions workflow) and vendors them — the same uniform pipeline used for Dart, Proto, and Swift. node-gyp-build selects the right .node at require time, so no C/C++ toolchain is needed. If no prebuild matches your platform-arch, only Kotlin (.kt/.kts) parsing is unavailable; the rest of gitnexus is unaffected.

Deploy to Render

Deploy GitNexus in one click:

The Blueprint creates two services. gitnexus-server runs gitnexus serve as a private service: no public URL, reachable only over Render's private network, with a persistent disk for indexes and cloned repos. gitnexus-web is the public one. It serves the UI and reverse-proxies /api/* to the server, so the browser talks to a single origin.

At the Blueprint's defaults this runs about $35/month: $25 for the server's standard instance, $7 for the web service's starter instance, and $2.50 for the 10 GB disk. See Render's pricing for other plans.

The deploy generates an access token, and the UI asks for it on first use:

Open the gitnexus-web service in your Render dashboard.
Copy GITNEXUS_SERVE_AUTH_TOKEN from its Environment tab.
Load the site and paste the token into the prompt (or the settings panel).

Every /api/* request carries that token as a header, and the proxy answers 401 without it. The browser keeps it in sessionStorage, so a new tab asks again. To rotate it, edit the environment variable and redeploy.

The proxy strips Origin before forwarding, so the server's CSRF guard does nothing for proxied traffic; it passes Origin-less requests through by design. The token is the only control on this deploy, not a second layer behind the guard. Anyone holding it can read every indexed repo. See SECURITY.md.

Indexing is memory-bound. If gitnexus-server runs out of memory on a large repo, raise its plan, which sets available RAM: standard is 2 GB, pro is 4 GB. Raise sizeGB only if the disk fills with clones and indexes.

Two Ways to Use GitNexus

	CLI + MCP (recommended)	Web UI
What	Index repos locally, connect AI agents via MCP	Visual graph explorer + AI chat in browser
For	Daily development with Cursor, Claude Code, Antigravity, Codex, Windsurf, OpenCode	Quick exploration, demos, one-off analysis
Scale	Full repos, any size	Limited by browser memory (~5k files), or unlimited via backend mode
Install	`npm install -g gitnexus`	No install — gitnexus.vercel.app
Storage	LadybugDB native (fast, persistent)	LadybugDB WASM (in-memory, per session)
Parsing	Tree-sitter native bindings	Tree-sitter WASM
Privacy	Everything local, no network	Everything in-browser, no server

Bridge mode: gitnexus serve connects the two — the web UI auto-detects the local server and can browse all your CLI-indexed repos without re-uploading or re-indexing.

Why a Knowledge Graph?

Tools like Cursor, Claude Code, Codex, Cline, Roo Code, and Windsurf are powerful — but they don't truly know your codebase structure. So this happens:

AI edits UserService.validate()
Doesn't know 47 functions depend on its return type
Breaking changes ship

Traditional Graph RAG gives the LLM raw graph edges and hopes it explores enough. GitNexus precomputes structure at index time — clustering, tracing, scoring — so tools return complete context in one call:

flowchart TB
    subgraph Traditional["Traditional Graph RAG"]
        direction TB
        U1["User: What depends on UserService?"]
        U1 --> LLM1["LLM receives raw graph"]
        LLM1 --> Q1["Query 1: Find callers"]
        Q1 --> Q2["Query 2: What files?"]
        Q2 --> Q3["Query 3: Filter tests?"]
        Q3 --> Q4["Query 4: High-risk?"]
        Q4 --> OUT1["Answer after 4+ queries"]
    end

    subgraph GN["GitNexus Smart Tools"]
        direction TB
        U2["User: What depends on UserService?"]
        U2 --> TOOL["impact UserService upstream"]
        TOOL --> PRECOMP["Pre-structured response:
        8 callers, 3 clusters, all 90%+ confidence"]
        PRECOMP --> OUT2["Complete answer, 1 query"]
    end

Core innovation: Precomputed Relational Intelligence

Reliability — the LLM can't miss context; it's already in the tool response
Token efficiency — no 10-query chains to understand one function
Model democratization — smaller LLMs work because the tools do the heavy lifting

What Your AI Agent Gets

17 MCP tools (15 per-repo + 2 group)

Tool	What It Does
`list_repos`	Discover all indexed repositories (paginated — `limit`/`offset`)
`query`	Process-grouped hybrid search (BM25 + semantic + RRF)
`context`	360-degree symbol view — categorized refs, process participation
`impact`	Blast radius analysis with depth grouping and confidence
`trace`	Shortest directed path between two symbols (call + class-member edges)
`detect_changes`	Git-diff impact — maps changed lines to affected processes
`check`	Read-only structural checks against the indexed graph
`rename`	Multi-file coordinated rename with graph + text search
`cypher`	Raw Cypher graph queries
`route_map`	API route map — which components fetch which endpoints, and handlers
`tool_map`	MCP/RPC tool definitions — where they're defined and handled
`shape_check`	Validate API response shapes against consumers' property accesses
`api_impact`	Pre-change impact report for an API route handler
`explain`	Explain persisted taint findings (source→sink flows, `--pdg` indexes)
`pdg_query`	Query control/data dependence at statement level (`--pdg` indexes)
`group_list`	List configured repository groups
`group_sync`	Rebuild a group's Contract Registry and cross-repo links

Per-repo tools take an optional repo parameter (omit it when only one repo is indexed) and an optional branch for indexes pinned with gitnexus analyze --branch. Omitting branch queries the workspace index, which follows your checked-out working tree — switching branches and re-running gitnexus analyze updates it incrementally. explain and pdg_query need an index built with gitnexus analyze --pdg.

Resources for instant context

Resource	Purpose
`gitnexus://repos`	List all indexed repositories (read this first)
`gitnexus://setup`	Setup and usage guidance for agents
`gitnexus://repo/{name}/context`	Codebase stats, staleness check, and available tools
`gitnexus://repo/{name}/clusters`	All functional clusters with cohesion scores
`gitnexus://repo/{name}/cluster/{name}`	Cluster members and details
`gitnexus://repo/{name}/processes`	All execution flows
`gitnexus://repo/{name}/process/{name}`	Full process trace with steps
`gitnexus://repo/{name}/schema`	Graph schema for Cypher queries
`gitnexus://group/{name}/contracts`	A group's extracted contracts and cross-links
`gitnexus://group/{name}/status`	Staleness of repos in a group

2 MCP prompts for guided workflows

Prompt	What It Does
`detect_impact`	Pre-commit change analysis — scope, affected processes, risk level
`generate_map`	Architecture documentation from the knowledge graph with mermaid diagrams

Agent skills installed to `.claude/skills/` and `.agents/skills/` (if `.agents/` exists) automatically

Exploring — navigate unfamiliar code using the knowledge graph
Debugging — trace bugs through call chains
Impact Analysis — analyze blast radius before changes
Refactoring — plan safe refactors using dependency mapping
Guide — GitNexus tool/resource/schema reference for the agent
CLI — run analyze/status/clean/wiki commands on request
PDG Query — statement-level control/data dependence queries (--pdg index)
Taint Analysis — source→sink data-flow findings (--pdg index)
Plan (/gitnexus-plan) — implementation-ready engineering plans backed by the graph and PDG slices
Work (/gitnexus-work) — executes a plan as impact-checked, detect_changes-gated atomic commits
Review (/gitnexus-review) — graph-backed review of a PR, branch, range, or local diff, with taint pass and per-domain expert lenses
LFG (/gitnexus-lfg) — the full pipeline: plan → user gate → work → review

Repo-specific skills — run gitnexus analyze --skills and GitNexus detects the functional areas of your codebase (via Leiden community detection) and generates each one as a direct project skill under .claude/skills/gitnexus-area-<name>/. Each skill describes a module's key files, entry points, execution flows, and cross-area connections, and is regenerated on each --skills run to stay current.

When a repo contains an .agents/ directory, the standard and generated skills are also mirrored to .agents/skills/ (e.g. .agents/skills/gitnexus-cli/, .agents/skills/gitnexus-area-<name>/) so agents that read repo-local .agents/skills/ (like Codex) stay in sync.

Editor Setup

gitnexus setup auto-detects your editors and writes the correct global MCP config. Run it once. To configure only selected integrations, pass --coding-agent/-c with a comma-separated list, e.g. gitnexus setup -c cursor,codex.

Editor	MCP	Skills	Hooks (auto-augment)	Support
Claude Code	Yes	Yes	Yes (PreToolUse + PostToolUse)	Full
Cursor	Yes	Yes	Yes (postToolUse, manual install)	Full
Antigravity (Google)	Yes	Yes	Yes (AfterTool, Gemini CLI hooks schema)¹	Full
Codex	Yes	Yes	Yes (PreToolUse + PostToolUse, Codex hooks)	Full
OpenCode	Yes	Yes	—	MCP + Skills
CodeBuddy (Tencent)	Yes	Yes	—	MCP + Skills
Qoder (Alibaba)	Yes	Yes	—	MCP + Skills
Windsurf	Yes	—	—	MCP

Claude Code and Codex get the deepest integration: MCP tools + agent skills + PreToolUse hooks that enrich searches with graph context + PostToolUse hooks that detect a stale index after commits and prompt the agent to reindex.

¹ Antigravity hooks follow the Gemini CLI hooks reference (Antigravity 2.0 is the documented successor to Gemini CLI). Augmentation runs in AfterTool because BeforeTool has no context-injection channel in the Gemini contract — the agent sees graph context appended to the tool result via hookSpecificOutput.additionalContext. Stale-index hints land in the same channel after a successful git commit/merge/rebase/cherry-pick/pull. The schema may evolve if Antigravity-specific hook docs diverge from Gemini CLI's; the implementation will track those changes.

Manual MCP configuration (if you prefer not to run gitnexus setup)

Claude Code (full support — MCP + skills + hooks):

# macOS / Linux
claude mcp add gitnexus -- npx -y gitnexus@latest mcp

# Windows
claude mcp add gitnexus -- cmd /c npx -y gitnexus@latest mcp

Codex (full support — MCP + skills + hooks):

codex mcp add gitnexus -- npx -y gitnexus@latest mcp

Or via ~/.codex/config.toml (system scope) / .codex/config.toml (project scope):

[mcp_servers.gitnexus]
command = "npx"
args = ["-y", "gitnexus@latest", "mcp"]

Codex hooks (PreToolUse graph enrichment + PostToolUse stale-index detection in ~/.codex/hooks.json, same schema as Claude Code) need the bundled adapter script, so they are installed by gitnexus setup -c codex rather than manually.

Alternatively, install everything as a Codex plugin (MCP + skills + hooks in one step):

codex plugin marketplace add abhigyanpatwari/GitNexus
# then inside Codex: /plugins → install "GitNexus"

Codex notes: SessionStart is intentionally not registered — Codex reads AGENTS.md natively, which already carries the GitNexus context block. Newly installed hooks need a one-time approval in Codex via /hooks before they run. Pick one install route (gitnexus setup -c codex or the plugin): plugin hooks load alongside ~/.codex/hooks.json, so installing both can fire duplicate hooks per tool call.

Cursor (~/.cursor/mcp.json — global, works for all projects):

{
  "mcpServers": {
    "gitnexus": {
      "command": "npx",
      "args": ["-y", "gitnexus@latest", "mcp"]
    }
  }
}

Antigravity (Google) — ~/.gemini/antigravity/mcp_config.json:

{
  "mcpServers": {
    "gitnexus": {
      "command": "npx",
      "args": ["-y", "gitnexus@latest", "mcp"]
    }
  }
}

gitnexus setup also merges an AfterTool entry into ~/.gemini/settings.json (under the canonical Gemini CLI hooks schema) and installs skills to ~/.gemini/antigravity/skills/. Existing user hooks are preserved. The hook adapter's path is rewritten at install time, so run gitnexus setup rather than hand-editing.

OpenCode (~/.config/opencode/config.json):

{
  "mcp": {
    "gitnexus": {
      "type": "local",
      "command": ["gitnexus", "mcp"]
    }
  }
}

CodeBuddy (Tencent) — priority chain, edit the first non-empty file that exists: ~/.codebuddy/.mcp.json (recommended) → ~/.codebuddy/mcp.json (deprecated) → ~/.codebuddy.json (legacy). CodeBuddy reads only the first existing file, so adding servers to a higher-priority file than the one currently in use would hide the servers below it. Create ~/.codebuddy/.mcp.json only if none exist:

{
  "mcpServers": {
    "gitnexus": {
      "command": "npx",
      "args": ["-y", "gitnexus@latest", "mcp"]
    }
  }
}

Qoder (Alibaba) — ~/.qoder.json:

{
  "mcpServers": {
    "gitnexus": {
      "command": "npx",
      "args": ["-y", "gitnexus@latest", "mcp"]
    }
  }
}

MCP read-only mode

Set GITNEXUS_MCP_READ_ONLY=1 before starting the MCP server to expose only the proven single-repository read surface. Raw cypher, rename and group tools, group routing, and group resources are omitted from discovery and rejected before backend dispatch. Tool descriptions and generated setup/context resources are scrubbed so they do not recommend unavailable routes.

The default is unchanged when the variable is unset or 0. Any other value fails server startup rather than silently weakening the policy.

MCP repository policy

Set GITNEXUS_MCP_ALLOWED_REPOS to a comma-separated list of canonical registry names or absolute indexed paths. Entries are trimmed, resolved against the registry, and deduplicated at startup. When exactly one repository is allowed it becomes the implicit default; when several are allowed, callers must select one unless GITNEXUS_MCP_DEFAULT_REPO is also set.

The default repository must resolve to an allowed repository. Invalid, ambiguous, blank, or mismatched configuration fails startup before stdio or HTTP begins serving. The allowlist applies to tools, aliases, discovery, resources, templates, implicit resolution, and embedded HTTP; hidden repository details are not included in selection errors. Setting only GITNEXUS_MCP_DEFAULT_REPO chooses a default without restricting explicit repository selections. An allowed repository whose name is duplicated in the registry must be configured by path, and its context resource is only served for the unique name form.

MCP response budgets

The query, context, and impact tools accept an optional positive-integer maxTokens argument. It bounds the complete formatted MCP response, including hints and error text, using a deterministic four-UTF-8-bytes-per-token estimate. When truncation is required, the response ends with … and remains valid UTF-8.

Set GITNEXUS_MCP_DEFAULT_MAX_TOKENS to apply the same guardrail when callers do not send maxTokens. An explicit tool argument takes precedence. Leaving both unset preserves the existing response byte-for-byte; this is a transport guardrail, not semantic pagination or an exact model-specific tokenizer limit.

CLI Reference

Everyday commands:

gitnexus setup                   # Configure MCP for detected editors (one-time; -c to select)
gitnexus analyze [path]          # Index a repository (or update a stale index)
gitnexus mcp                     # Start MCP server (stdio) — serves all indexed repos
gitnexus serve                   # Start local HTTP server (multi-repo) for web UI connection
gitnexus eval-server             # Start lightweight evaluation HTTP tools (loopback by default)
gitnexus list                    # List all indexed repositories
gitnexus status                  # Show index status for current repo
gitnexus clean                   # Delete index for current repo
gitnexus wiki [path]             # Generate repository wiki from knowledge graph
gitnexus uninstall               # Preview removal of GitNexus MCP/skills/hooks (--force to apply)

You can also query the graph directly from the terminal — gitnexus query, context, impact, trace, cypher, detect-changes, and check mirror the MCP tools of the same names, and gitnexus doctor prints runtime platform capabilities.

Authenticated eval-server binding

gitnexus eval-server binds to 127.0.0.1 by default. Loopback bindings do not require authentication. Any non-loopback bind, including 0.0.0.0, a LAN address, or a hostname that resolves to a LAN IPv4 address, requires GITNEXUS_AUTH_TOKEN. Every endpoint then requires an exact Authorization: Bearer <token> header.

GITNEXUS_AUTH_TOKEN='replace-me' gitnexus eval-server --host 0.0.0.0

The token may be set in the shell, .env.local, or .env in the working directory. Precedence is shell > .env.local > .env. Only GITNEXUS_AUTH_TOKEN is read from those files; their other values are not added to the process environment. Keep token files uncommitted.

All analyze flags

gitnexus analyze --force         # Full rebuild: re-parse + graph rebuild + FTS rebuild
gitnexus analyze --repair-fts    # Fast path: rebuild/verify only FTS indexes on existing index data
gitnexus analyze --skills        # Generate repo-specific skill files from detected communities
gitnexus analyze --skip-embeddings  # Skip embedding generation (faster)
gitnexus analyze --embeddings [limit]  # Enable embedding generation (slower, better search)
gitnexus analyze --skip-agents-md   # Preserve custom AGENTS.md/CLAUDE.md gitnexus section edits
gitnexus analyze --skip-skills      # Skip installing standard skill files under .claude/skills/ and .agents/skills/
gitnexus analyze --skip-git         # Index folders that are not Git repositories
gitnexus analyze --default-branch develop  # Branch used in the generated regression-compare example (base_ref)
gitnexus analyze --verbose       # Log skipped files when parsers are unavailable
gitnexus analyze --worker-timeout 60  # Increase worker idle timeout for slow parses
gitnexus analyze --workers <n>   # Parse worker pool size (>=1; default: cores-1, capped at 16,
                                 # auto-sized to the repo). 0 is rejected — there is no sequential mode.
gitnexus analyze --wal-checkpoint-threshold 67108864  # LadybugDB WAL auto-checkpoint threshold in bytes
                                 # (default 67108864 = 64 MiB; -1 keeps Ladybug stock ~16 MiB)

If analyze reports a worker parse timeout on a large or unusual repository, it keeps running and falls back safely. To give slow worker jobs more time, use --worker-timeout 60 or set GITNEXUS_WORKER_SUB_BATCH_TIMEOUT_MS=60000. For very large files, GITNEXUS_WORKER_SUB_BATCH_MAX_BYTES controls the worker job byte budget.

Embeddings node limit — gitnexus analyze --embeddings generates semantic search vectors with a default 50,000-node safety cap to protect memory on large repositories:

gitnexus analyze --embeddings          # default 50,000 node safety cap
gitnexus analyze --embeddings 0        # disable the cap entirely
gitnexus analyze --embeddings 100000   # custom cap

If embeddings are skipped on a large repository, the indexed graph likely exceeds the default cap — re-run with --embeddings 0 or a higher limit.

Repository groups (multi-repo / monorepo service tracking)

gitnexus group create <name>                           # Create a repository group
gitnexus group add <group> <groupPath> <registryName>  # Add a repo. <groupPath> is a hierarchy path
                                                       # (e.g. hr/hiring/backend); <registryName> is the
                                                       # repo's name from the registry (see `gitnexus list`)
gitnexus group remove <group> <groupPath>              # Remove a repo by its hierarchy path
gitnexus group list [name]                             # List groups, or show one group's config
gitnexus group sync <name>                             # Extract contracts and match across repos/services
gitnexus group contracts <name>                        # Inspect extracted contracts and cross-links
gitnexus group query <name> <q>                        # Search execution flows across all repos in a group
gitnexus group status <name>                           # Check staleness of repos in a group
gitnexus group impact <name> --target <symbol> --repo <groupPath>  # Cross-repo blast radius

Project config (.gitnexusrc)

Commit a .gitnexusrc JSON file at the repo root to preconfigure recurring analyze options per project, instead of re-passing the same flags every run. It is read from the resolved repo root (not .gitnexus/, which is gitignored index storage). CLI flags always override .gitnexusrc.

{
  // Default branch used in the generated regression-compare example (base_ref).
  // Use this so a project on `develop`/`master` doesn't get "main" rewritten
  // over its fix on every analyze. (Alias: "branch".)
  "defaultBranch": "develop",
  "skipContextFiles": true, // alias of skipAgentsMd: keep your own AGENTS.md/CLAUDE.md
  "skipSkills": true, // don't install standard skill files under .claude/skills/ and .agents/skills/
  "embeddings": true, // generate embeddings by default
  "workerTimeout": 60,
}

A nested analyze block is also accepted (and overrides flat keys for the same option):

{ "analyze": { "defaultBranch": "develop", "skipSkills": true } }

Notes:

The default branch is resolved as: --default-branch > .gitnexusrc defaultBranch/branch > auto-detected origin/HEAD > main.
skipContextFiles / skipAiContext are aliases for skipAgentsMd — they skip the AGENTS.md / CLAUDE.md block only. They do not imply skipSkills. indexOnly is the stronger option that skips all file injection.
Supported keys: defaultBranch (branch), skipAgentsMd (skipContextFiles, skipAiContext), skipSkills, indexOnly, stats/noStats, embeddings, dropEmbeddings, name, allowDuplicateName, maxFileSize, workerTimeout, walCheckpointThreshold, workers, embeddingThreads, embeddingBatchSize, embeddingSubBatchSize, embeddingDevice.
The file is JSON only. Unknown keys and invalid values fail fast with an actionable error before analysis starts.

Environment variables

Most analyze knobs are also CLI flags (--workers, --worker-timeout, --max-file-size, --verbose). Use the env-var form when you'd otherwise repeat the same flag every run, or when invoking GitNexus from a long-running host (MCP server, eval-server, CI shell) that already manages its own environment. CLI flags take precedence over env vars; env vars take precedence over built-in defaults.

Variable	Default	Effect	Tune when…
`GITNEXUS_WORKER_POOL_SIZE`	`cores - 1`, capped at 16	Parse worker pool size (must be ≥ 1). Equivalent to `--workers <n>`. The worker pool is the sole parse path — there is no sequential parser, so `0` is rejected with an actionable error (the pool self-heals via quarantine + respawn).	Constrained containers (cgroup CPU limits) or CI runners with explicit quotas. To narrow down a worker crash set `1` for a single-worker pool — not `0`.
`GITNEXUS_PARSE_CHUNK_CONCURRENCY`	`2`	Number of chunks whose file contents may be read into memory in parallel while the pool dispatches the current chunk. Worker dispatch itself stays serial.	Repos large enough to chunk (multi-MB total source) where disk I/O is a measurable fraction of analyze wall-clock.
`GITNEXUS_VERBOSE`	unset	When `1`, enables verbose ingestion logs (skipped-file warnings, per-chunk throughput, parse-cache stats). Equivalent to `--verbose`.	Debugging an analyze that "completed" but seems to have missed files; tuning `--workers` / chunk concurrency against observable throughput.
`GITNEXUS_AUTH_TOKEN`	unset	Bearer token required when `eval-server` binds beyond loopback. May also be read from `.env.local` or `.env`; shell values take precedence.	Exposing the evaluation HTTP tools to a container, VM, or LAN.
`GITNEXUS_PROFILE_DEFERRED`	unset	When `1`, emits `[deferred-profile]` timing/progress logs for the post-chunk deferred resolution band (imports → heritage → buildHeritageMap → legacy call resolution). Implied by `GITNEXUS_VERBOSE`.	Diagnosing analyze stalls in "Resolving calls (all chunks)" on large Java/Kotlin repos (issue #1741) without the full verbose ingestion noise.
`GITNEXUS_PROFILE_DEFERRED_SLOW_MS`	`3000` (verbose) / `5000`	Per-file threshold in ms above which `processCallsFromExtracted` emits a `slow file …` log line. Parsed via `Number()`: accepts integers (`5000`), scientific notation (`2.5e3`), decimals (`.5`), and hex (`0x10`). Non-finite or non-positive values fall back to the default.	Hunting a few outlier files dominating the deferred call-resolution stage; lower to surface more, raise to focus only on the worst.
`PROF_LBUG_LOAD`	unset	When `1`, emits one `[lbug-load prof]` summary line per `loadGraphToLbug` call breaking the graph-DB persistence wall into stages (`csv-emit` / `copy-nodes` / `copy-rels` / `fallback` / `total`) plus node & edge counts. Zero-cost when unset.	Attributing large-repo analyze wall time across CSV generation vs. LadybugDB `COPY` (issue #2203) — the analyze "emit" timing is the scope-resolution bucket, not this DB-write path.
`GITNEXUS_MAX_FILE_SIZE`	`512` (KB)	Walker skip threshold in KB. Hard cap is `32768` (tree-sitter buffer ceiling). Equivalent to `--max-file-size <kb>`.	Indexing repos with intentionally-large source files (generated parsers, vendored bundles) that should still be parsed.
`GITNEXUS_WORKER_SUB_BATCH_TIMEOUT_MS`	`30000`	Worker idle timeout in milliseconds before retry/fallback. Equivalent to `--worker-timeout <seconds>` × 1000.	Slow-parsing files (large minified JS, deeply-nested TS types) that legitimately need more than 30s.
`GITNEXUS_WORKER_READY_TIMEOUT_MS`	`5000`	Startup budget in milliseconds for a parse worker to load its grammar bindings and report `{type:'ready'}`. Slots that miss it are treated as startup crashes.	Slow or heavily loaded hosts where a full pool cold-starting concurrently needs more than 5s, and analyze aborts with "did not report ready within 5000ms".
`GITNEXUS_FTS_STEMMER`	`porter`	Stemmer used when rebuilding BM25/FTS indexes. Use `none` for CJK-heavy repositories, or a language stemmer such as `german`, `french`, or `spanish` for matching repository comments. Re-run `gitnexus analyze --repair-fts` after changing it.	Keyword search quality is poor for non-English comments or identifiers under English stemming.
`GITNEXUS_WAL_CHECKPOINT_THRESHOLD`	`67108864` (64 MiB)	LadybugDB WAL auto-checkpoint threshold in bytes. Equivalent to `--wal-checkpoint-threshold <bytes>`. `-1` keeps LadybugDB's stock threshold (~16 MiB). Larger thresholds reduce checkpoint frequency but increase the WAL size at rotation time — choose a smaller value on disk-constrained environments.	You need a larger or smaller WAL auto-checkpoint threshold for your analyze workload.
`GITNEXUS_LBUG_BUFFER_POOL_SIZE`	min(2 GiB, 80% RAM)	LadybugDB buffer-pool ceiling in bytes for every GitNexus database (analyze, MCP server, serve, group bridges). `0` restores LadybugDB's native unbounded default of 80% of system RAM; invalid values warn and fall back to the default (#2557). During `analyze` the pool is right-sized to the graph, scaled on non-4 KiB-page hosts by the page-size granule ratio up to min(2 GiB × pageSize/4 KiB, 80% RAM) (#2631); this env var overrides all of that as an absolute value.	A long-lived `gitnexus mcp` or a big incremental `analyze` uses too much memory, or a huge repo's working set genuinely needs a pool larger than 2 GiB.
`GITNEXUS_LBUG_MAX_DB_SIZE`	`17179869184` (16 GiB)	Maximum size in bytes of a single LadybugDB database file — an mmap/disk-address-space ceiling, not a memory limit (it does not constrain the buffer pool). Invalid values silently fall back to the default.	Indexing a genuinely huge monorepo whose on-disk graph index approaches 16 GiB.
`GITNEXUS_WORKER_SUB_BATCH_MAX_BYTES`	`8388608` (8 MB)	Per-job byte budget the pool will send to a worker in one `postMessage`.	Very large individual files; mostly diagnostic — bumping past 8 MB risks structured-clone memory pressure.
`GITNEXUS_WORKER_MAX_RESPAWNS_PER_SLOT`	`3`	Max replacement spawns per worker slot before the slot is dropped from the active rotation. Bounds respawn loops on a chronically-crashing slot.	Hosts where a flaky worker should retry more (raise) or fail-fast (lower) before the slot is dropped.
`GITNEXUS_WORKER_MAX_CUMULATIVE_TIMEOUT_MS`	`5 × subBatchTimeoutMs`	Total retry wall-time budget per job before quarantining. Combined with `timeoutBackoffFactor`, prevents exponentially-growing retries from stalling for hours.	Slow files that legitimately need long total retry windows; lower to fail-fast on stalls.
`GITNEXUS_WORKER_CONSECUTIVE_FAILURE_THRESHOLD`	`max(3, poolSize)`	Per-slot consecutive deaths before the pool's circuit breaker trips. After tripping, every subsequent dispatch rejects until a fresh pool is created.	Hosts where a SIGSEGV-prone native grammar should trip the breaker sooner; CI runners that should fail loudly.
`GITNEXUS_WORKER_SHUTDOWN_DRAIN_MS`	`30000`	Max wait at pool shutdown for a retired worker still inside native code. The worker is terminated at its next JS-safe point instead of mid-native-call (which aborts the whole process with `Napi::Error`, #2432); on expiry it is left running, unref'd, and terminated when it surfaces.	Shutdown latency matters more than draining a wedged worker (lower), or a legitimately-slow native grammar needs longer to surface (raise).
`GITNEXUS_CPP_CAPTURE_BUDGET_MS`	`20000`	Per-file wall-clock budget for C++ capture extraction. On breach the file keeps the captures accumulated so far and logs a warning — the worker returns to JS instead of stalling in native-heavy loops (#2432). `0` expires immediately.	Pathological generated C++ that still exceeds the budget after the indexed lookups; raise for completeness, lower to fail-fast.
`GITNEXUS_CHUNK_BYTE_BUDGET`	`2097152` (2 MB)	Chunk boundary used for cache-key composition and dispatch. Smaller = finer-grained cache hits but more dispatch overhead.	Tuning incremental-analyze cache behavior on monorepos.
`GITNEXUS_NO_GITIGNORE`	unset	When set, skips `.gitignore` parsing. `.gitnexusignore` is still honored.	Indexing a repo whose `.gitignore` excludes files you actually want indexed (e.g., generated code committed for cross-repo lookup).
`GITNEXUS_SKIP_OPTIONAL_GRAMMARS`	unset	When `=1` strictly, skips the vendored grammar materialize for `tree-sitter-dart`, `tree-sitter-proto`, `tree-sitter-swift`, and `tree-sitter-kotlin` at install time (and the Dart/Proto source builds). Those four won't be parsed; the install still succeeds.	Installing on a host without a C++ toolchain or where the vendored prebuilds don't match; willing to skip Dart/Proto/Swift/Kotlin parsing.
`GITNEXUS_MCP_READ_ONLY`	unset	Set to `1` to expose only proven single-repository read tools and resources; `0` disables the policy and any other value fails startup.	The MCP server runs in an environment where graph mutation, raw Cypher, and cross-repository group routing must be unavailable.
`GITNEXUS_MCP_ALLOWED_REPOS`	unset	Comma-separated allowlist of canonical indexed repository names or absolute paths. Invalid, ambiguous, or blank entries fail startup.	One MCP process must expose only a bounded subset of the repositories in the global registry.
`GITNEXUS_MCP_DEFAULT_REPO`	unset	Canonical indexed repository name or absolute path used when a tool or resource omits its repository. Must belong to the allowlist when one is set.	Several repositories are available but unqualified MCP calls should resolve deterministically.
`GITNEXUS_MCP_DEFAULT_MAX_TOKENS`	unset	Default positive-integer response budget for MCP `query`, `context`, and `impact`, estimated at four UTF-8 bytes per token. Explicit `maxTokens` wins.	Long MCP responses consume too much model context and callers cannot reliably add a per-request budget.
`GITNEXUS_PUBLIC_ORIGIN`	unset	The single browser origin `serve` is reached through, added to the CORS allowlist and to the write-route origin guard. A wildcard bind (`0.0.0.0`) has no host identity, so without this the server's own UI is refused. Setting it currently refuses to start: `serve` has no authentication, requests carrying no `Origin` header already reach `POST /api/analyze` and `DELETE /api/repo`, and this is the setting that would admit browser writes on top of that. Matching rules for when the gate lifts: the hostname must match exactly, and so must the scheme. A value with no scheme (`app.example.com`) means `https`, since a bare host comes from platform service discovery and those terminate TLS; spell out `http://app.example.com` for plain HTTP. An explicit port must match; with no port, any port on that hostname is accepted. Anything that is not one reachable host (a list, `*`, a bare port number, a `:0` port, a trailing dot) warns at startup and allows nothing.	`gitnexus serve` runs behind a reverse proxy or on a wildcard bind, and the UI's index/delete requests return `origin_not_allowed`.
`GITNEXUS_TRUST_PROXY`	`loopback, linklocal, uniquelocal`	Express `trust proxy` value — which upstream hops may set `X-Forwarded-`, and so what the per-IP rate limiter reads as the client IP. Set it to the exact number of proxies you control. Every hop past that is one more entry of the chain the caller gets to write. `false`/`no`/`off` (and a `0` hop count) trust no hop; a proxy list Express can compile (`loopback`, `10.0.0.0/8, 127.0.0.1`) names them instead. `true`/`yes`/`on` is rejected*: it reads the client-controlled leftmost `X-Forwarded-For` entry, so a spoofed chain earns a fresh rate-limit key per request, and express-rate-limit rejects it too (`ERR_ERL_PERMISSIVE_TRUST_PROXY`). Counts above `16` are rejected as well, as a sanity ceiling rather than a safety boundary. Any invalid value warns and falls back to the default. Bind non-loopback with this unset and `serve` warns: a load balancer outside the private ranges is untrusted, so every request keys to the balancer and the per-IP limit becomes one shared limit.	`serve` sits behind a load balancer outside the private ranges (AWS ALB, Cloudflare, CGNAT), where every request otherwise collapses to the proxy hop and rate limiting goes global.

gitnexus uninstall

gitnexus uninstall reverses gitnexus setup — it removes the GitNexus MCP entries, hooks, and skill directories it added to each detected editor. Skill directories are identified by bundled gitnexus skill name (e.g. gitnexus-cli/), so if you customized files inside an installed skill directory, back them up first. It is a dry-run preview by default and prints the exact paths it would remove; pass --force to apply. Per-repo indexes (gitnexus clean --all) and the global npm package (npm uninstall -g gitnexus) are left for you to remove.

Publishing to understand-quickly (opt-in)

looptech-ai/understand-quickly is a public registry of code-knowledge graphs that lists gitnexus@1 as a first-class format. After registering your repo once (npx @understand-quickly/cli add or the wizard), gitnexus publish fires a single repository_dispatch event so the registry resyncs your entry on demand instead of waiting for the nightly job.

It is opt-in and a no-op without UNDERSTAND_QUICKLY_TOKEN — a fine-grained GitHub PAT with Repository dispatches: write on the registry repo. Nothing else happens; no graph file is uploaded. See the protocol spec for the full contract.

How It Works

GitNexus builds a complete knowledge graph of your codebase through a multi-phase indexing pipeline:

Structure — walks the file tree and maps folder/file relationships
Parsing — extracts functions, classes, methods, and interfaces using Tree-sitter ASTs
Resolution — resolves imports, function calls, heritage, constructor inference, and self/this receiver types across files with language-aware logic
Clustering — groups related symbols into functional communities
Processes — traces execution flows from entry points through call chains
Search — builds hybrid search indexes for fast retrieval

Supported Languages

Language	Imports	Named Bindings	Exports	Heritage	Type Annotations	Constructor Inference	Config	Frameworks	Entry Points
TypeScript	✓	✓	✓	✓	✓	✓	✓	✓	✓
JavaScript	✓	✓	✓	✓	—	✓	✓	✓	✓
Python	✓	✓	✓	✓	✓	✓	✓	✓	✓
Java	✓	✓	✓	✓	✓	✓	—	✓	✓
Kotlin	✓	✓	✓	✓	✓	✓	—	✓	✓
C#	✓	✓	✓	✓	✓	✓	✓	✓	✓
Go	✓	—	✓	✓	✓	✓	✓	✓	✓
Rust	✓	✓	✓	✓	✓	✓	—	✓	✓
PHP	✓	✓	✓	—	✓	✓	✓	✓	✓
Ruby	✓	—	✓	✓	—	✓	—	✓	✓
Swift	—	—	✓	✓	✓	✓	✓	✓	✓
C	—	—	✓	—	✓	✓	—	✓	✓
C++	—	—	✓	✓	✓	✓	—	✓	✓
Dart	✓	—	✓	✓	✓	✓	—	✓	✓

Imports — cross-file import resolution · Named Bindings — import { X as Y } / re-export tracking · Exports — public/exported symbol detection · Heritage — class inheritance, interfaces, mixins · Type Annotations — explicit type extraction for receiver resolution · Constructor Inference — infer receiver type from constructor calls (self/this resolution included for all languages) · Config — language toolchain config parsing (tsconfig, go.mod, etc.) · Frameworks — AST-based framework pattern detection · Entry Points — entry point scoring heuristics

Control flow (CFG, opt-in --pdg) — per-function control-flow graphs (BasicBlock nodes + CFG edges) feeding the PDG/taint substrate, currently TypeScript & JavaScript (#2081 M1); other languages planned. Off by default.

Multi-Repo Architecture

GitNexus uses a global registry so one MCP server can serve multiple indexed repos. No per-project MCP config needed — set it up once and it works everywhere.

Each gitnexus analyze stores the index in .gitnexus/ inside the repo (portable, gitignored) and registers a pointer in ~/.gitnexus/registry.json. When an AI agent starts, the MCP server reads the registry and can serve any indexed repo. LadybugDB connections are opened lazily on first query and evicted after 5 minutes of inactivity (max 5 concurrent). If only one repo is indexed, the repo parameter is optional on all tools — agents don't need to change anything.

Architecture diagram

flowchart TD
    subgraph CLI [CLI Commands]
        Setup["gitnexus setup"]
        Analyze["gitnexus analyze"]
        Clean["gitnexus clean"]
        List["gitnexus list"]
    end

    subgraph Registry ["~/.gitnexus/"]
        RegFile["registry.json"]
    end

    subgraph Repos [Project Repos]
        RepoA[".gitnexus/ in repo A"]
        RepoB[".gitnexus/ in repo B"]
    end

    subgraph MCP [MCP Server]
        Server["server.ts"]
        Backend["LocalBackend"]
        Pool["Connection Pool"]
        ConnA["LadybugDB conn A"]
        ConnB["LadybugDB conn B"]
    end

    Setup -->|"writes global MCP config"| CursorConfig["~/.cursor/mcp.json"]
    Analyze -->|"registers repo"| RegFile
    Analyze -->|"stores index"| RepoA
    Clean -->|"unregisters repo"| RegFile
    List -->|"reads"| RegFile
    Server -->|"reads registry"| RegFile
    Server --> Backend
    Backend --> Pool
    Pool -->|"lazy open"| ConnA
    Pool -->|"lazy open"| ConnB
    ConnA -->|"queries"| RepoA
    ConnB -->|"queries"| RepoB

Tool Examples

Impact Analysis

impact({target: "UserService", direction: "upstream", minConfidence: 0.8})

TARGET: Class UserService (src/services/user.ts)

UPSTREAM (what depends on this):
  Depth 1 (WILL BREAK):
    handleLogin [CALLS 90%] -> src/api/auth.ts:45
    handleRegister [CALLS 90%] -> src/api/auth.ts:78
    UserController [CALLS 85%] -> src/controllers/user.ts:12
  Depth 2 (LIKELY AFFECTED):
    authRouter [IMPORTS] -> src/routes/auth.ts

Options: maxDepth, minConfidence, relationTypes (CALLS, IMPORTS, EXTENDS, IMPLEMENTS), includeTests, limit (max symbols per depth, default 100), offset (pagination start per depth), summaryOnly (counts and risk only, omits symbol list)

Disambiguation — when several symbols share the target name, impact returns a ranked ambiguous candidate list instead of guessing. Narrow it with target_uid (exact, zero-ambiguity), file_path, or kind (Function, Class, Method, …). From the CLI these are --uid, --file, and --kind, matching gitnexus context:

gitnexus impact get_embeddings                       # → ambiguous: lists ranked candidates
gitnexus impact get_embeddings --file src/embed.py   # → resolves to the one in that file
gitnexus impact get_embeddings --uid "Function:src/embed.py:get_embeddings"  # exact

More examples: search · context · detect_changes · rename · Cypher

Process-Grouped Search

query({search_query: "authentication middleware"})

processes:
  - summary: "LoginFlow"
    priority: 0.042
    symbol_count: 4
    process_type: cross_community
    step_count: 7

process_symbols:
  - name: validateUser
    type: Function
    filePath: src/auth/validate.ts
    process_id: proc_login
    step_index: 2

definitions:
  - name: AuthConfig
    type: Interface
    filePath: src/types/auth.ts

Context (360-degree Symbol View)

context({name: "validateUser"})

symbol:
  uid: "Function:validateUser"
  kind: Function
  filePath: src/auth/validate.ts
  startLine: 15

incoming:
  calls: [handleLogin, handleRegister, UserController]
  imports: [authRouter]

outgoing:
  calls: [checkPassword, createSession]

processes:
  - name: LoginFlow (step 2/7)
  - name: RegistrationFlow (step 3/5)

Detect Changes (Pre-Commit)

detect_changes({scope: "all"})

summary:
  changed_count: 12
  affected_count: 3
  changed_files: 4
  risk_level: medium

changed_symbols: [validateUser, AuthService, ...]
affected_processes: [LoginFlow, RegistrationFlow, ...]

Rename (Multi-File)

rename({symbol_name: "validateUser", new_name: "verifyUser", dry_run: true})

status: success
files_affected: 5
total_edits: 8
graph_edits: 6     (high confidence)
text_search_edits: 2  (review carefully)
changes: [...]

Cypher Queries

-- Find what calls auth functions with high confidence
MATCH (c:Community {heuristicLabel: 'Authentication'})<-[:CodeRelation {type: 'MEMBER_OF'}]-(fn)
MATCH (caller)-[r:CodeRelation {type: 'CALLS'}]->(fn)
WHERE r.confidence > 0.8
RETURN caller.name, fn.name, r.confidence
ORDER BY r.confidence DESC

Wiki Generation

Generate LLM-powered documentation from your knowledge graph:

# Requires an LLM API key (OPENAI_API_KEY, etc.)
gitnexus wiki

# Use a custom model or provider (default model: minimax/minimax-m2.5)
gitnexus wiki --model gpt-4o
gitnexus wiki --base-url https://api.anthropic.com/v1

# Force full regeneration
gitnexus wiki --force

# Increase the timeout or retries for large codebases or slow LLM providers
gitnexus wiki --timeout <seconds>  # LLM request timeout in seconds (default: disabled)
gitnexus wiki --retries <n>        # Max LLM retry attempts per request (default: 3)

# Allow a specific LAN/self-hosted HTTP LLM host (HTTPS is preferred for remote endpoints)
gitnexus wiki --base-url http://llama-box.local:8080/v1 --allow-insecure-connection llama-box.local
# Or set a comma-separated host allowlist:
GITNEXUS_ALLOW_INSECURE_CONNECTION=llama-box.local,192.168.1.23

# Change the output language
gitnexus wiki --lang <lang>  # e.g. english, chinese, spanish, japanese

For safety, http:// LLM base URLs are allowed by default only for loopback hosts (localhost, 127.0.0.1, ::1). --allow-insecure-connection and GITNEXUS_ALLOW_INSECURE_CONNECTION accept exact hostnames or IP addresses only; do not include schemes, ports, paths, credentials, or wildcards.

The wiki generator reads the indexed graph structure, groups files into modules via LLM, generates per-module documentation pages, and creates an overview page — all with cross-references to the knowledge graph.

Web UI (browser-based)

A client-side graph explorer and AI chat — your code never leaves your machine.

Try it now: gitnexus.vercel.app — run npx gitnexus@latest serve locally and the page auto-connects to your local backend.

The web UI uses the same indexing pipeline as the CLI but runs entirely in WebAssembly (Tree-sitter WASM, LadybugDB WASM, in-browser embeddings). It's great for quick exploration but limited by browser memory for larger repos.

Local Backend Mode: run gitnexus serve and open the web UI — it auto-detects the server and shows all your indexed repos, with full AI chat support. No re-upload, no re-index. The agent's tools (Cypher queries, search, code navigation) route through the backend HTTP API automatically.

Run the frontend locally

git clone https://github.com/abhigyanpatwari/gitnexus.git
cd gitnexus/gitnexus-shared && npm install && npm run build
cd ../gitnexus-web && npm install
npm run dev
# Then in another terminal, start the backend the frontend connects to:
npx gitnexus@latest serve

Docker

docker compose up -d

This starts the server on http://localhost:4747 and the web UI on http://localhost:4173. The UI auto-detects the server because the browser runs on the host and reaches the container via the mapped port.

The official setup ships two signed images, published identically to GitHub Container Registry (GHCR) and Docker Hub — same build, same digest, same Cosign signature:

Purpose	GHCR (default in `docker-compose.yaml`)	Docker Hub mirror
CLI / `gitnexus serve` backend (HTTP API on port `4747`, MCP, indexer)	`ghcr.io/abhigyanpatwari/gitnexus:latest`	`akonlabs/gitnexus:latest`
Static web UI (port `4173`)	`ghcr.io/abhigyanpatwari/gitnexus-web:latest`	`akonlabs/gitnexus-web:latest`

A named volume (gitnexus-data) persists the global registry, indexes, and cloned repos at /data/gitnexus inside the server container. To make repos on your host machine indexable, set WORKSPACE_DIR before bringing the stack up:

WORKSPACE_DIR=$HOME/code docker compose up -d
# Inside the server container the directory is mounted read-only at /workspace.
docker compose exec gitnexus-server gitnexus index /workspace/my-repo

Heads-up — image rename. Earlier releases published the web UI under ghcr.io/abhigyanpatwari/gitnexus. That slug now hosts the CLI/server image and the UI moved to ghcr.io/abhigyanpatwari/gitnexus-web. Previous tags remain pullable, but new versions are only published under the new slugs — update your docker run / compose files (or just adopt the bundled compose).

Direct docker run & env file

# Server
docker run --rm -d \
  --name gitnexus-server \
  -p 4747:4747 \
  -v gitnexus-data:/data/gitnexus \
  ghcr.io/abhigyanpatwari/gitnexus:latest

# Web UI
docker run --rm -d \
  --name gitnexus-web \
  -p 4173:4173 \
  ghcr.io/abhigyanpatwari/gitnexus-web:latest

Optional env file (override image tags, container names, ports, workspace dir):

cp .env.example .env
docker compose --env-file .env up -d

Files:

Dockerfile.web — builds gitnexus-shared and gitnexus-web, then serves the production frontend.
Dockerfile.cli — builds the CLI/server (with its native deps) and runs gitnexus serve --host 0.0.0.0.
docker-compose.yaml — starts both signed images side by side.
.env.example — overrides for image names, container names, ports, and the workspace mount.

Versioning & supply-chain protection (Cosign signatures, provenance, Kubernetes admission policy)

The Docker images are version-locked to the npm package:

Stable images are only published from vX.Y.Z git tags (via docker.yml triggered directly by the tag push), and the workflow refuses to build unless the tag exactly matches gitnexus/package.json's version. So ghcr.io/abhigyanpatwari/gitnexus:1.6.2 (and its Docker Hub mirror akonlabs/gitnexus:1.6.2) is byte-for-byte the same release as npm install gitnexus@1.6.2 — no drift, no floating builds from main. Both registries receive the same digest from a single build step, so you can pull from either and the signature verifies identically.
Release-candidate images (e.g. :1.7.0-rc.1) are published alongside each RC npm release. They are built by publish.yml calling docker.yml as a reusable workflow after the RC tag is created and pushed.
:latest is auto-promoted only from non-prerelease tags by the Docker metadata action, so it always points at a real, npm-published version.

Both images are signed with Cosign keyless signing using the workflow's GitHub OIDC identity, and shipped with build provenance and SBOM attestations. This is your protection against supply-chain attacks: even if an attacker republishes a same-named image elsewhere (or somehow pushes to a typo-squatted registry), they cannot forge a Cosign signature tied to abhigyanpatwari/GitNexus's docker.yml. Always verify before pulling into sensitive environments.

Stable releases — signed from the v* tag ref:

cosign verify ghcr.io/abhigyanpatwari/gitnexus:1.6.2 \
  --certificate-identity-regexp '^https://github\.com/abhigyanpatwari/GitNexus/\.github/workflows/docker\.yml@refs/tags/v[0-9]+\.[0-9]+\.[0-9]+(-[a-zA-Z0-9.]+)?$' \
  --certificate-oidc-issuer https://token.actions.githubusercontent.com

# Same signature verifies the Docker Hub mirror (identical digest):
cosign verify docker.io/akonlabs/gitnexus:1.6.2 \
  --certificate-identity-regexp '^https://github\.com/abhigyanpatwari/GitNexus/\.github/workflows/docker\.yml@refs/tags/v[0-9]+\.[0-9]+\.[0-9]+(-[a-zA-Z0-9.]+)?$' \
  --certificate-oidc-issuer https://token.actions.githubusercontent.com

The regex pins the certificate identity to this repo's docker.yml workflow run from a v* tag — rejecting unsigned images, images signed by other workflows, and images signed from unprotected refs. It is identical for both registries because both sets of tags were signed at the same digest in one workflow run.

Release candidates — signed from refs/heads/main (the caller's ref when publish.yml invokes docker.yml as a reusable workflow):

cosign verify ghcr.io/abhigyanpatwari/gitnexus:1.7.0-rc.1 \
  --certificate-identity 'https://github.com/abhigyanpatwari/GitNexus/.github/workflows/docker.yml@refs/heads/main' \
  --certificate-oidc-issuer https://token.actions.githubusercontent.com

You can also inspect the build provenance and SBOM:

cosign download attestation ghcr.io/abhigyanpatwari/gitnexus:1.6.2 \
  --predicate-type https://slsa.dev/provenance/v1

Kubernetes: enforce signatures at admission. Ship the bundled ClusterImagePolicy so the Sigstore policy-controller rejects any GitNexus pod whose image is not signed by this repo's docker.yml running from a vX.Y.Z tag — the same identity the cosign verify snippet above pins.

# 1. Install the controller (one-time, cluster-wide)
helm repo add sigstore https://sigstore.github.io/helm-charts && helm repo update
helm install policy-controller -n cosign-system --create-namespace \
  sigstore/policy-controller

# 2. Opt your namespace in
kubectl label namespace <your-ns> policy.sigstore.dev/include=true

# 3. Apply the policy
kubectl apply -f deploy/kubernetes/cluster-image-policy.yaml

After this, attempting to deploy an unsigned image — or one signed by anything other than abhigyanpatwari/GitNexus's docker.yml at a v* tag — fails the admission webhook before a pod is ever created. This turns the verifiable signature into an enforced policy, which is the supply-chain control most clusters actually need.

Enterprise

GitNexus is available as an enterprise offering — fully managed SaaS or self-hosted deployment. Commercial use of the OSS version is also available with proper licensing.

Enterprise includes:

PR Review — automated blast radius analysis on pull requests
Auto-updating Code Wiki — always up-to-date documentation (Code Wiki is also available in OSS)
Auto-reindexing — knowledge graph stays fresh automatically
Multi-repo support — unified graph across repositories
OCaml support — additional language coverage
Priority feature/language support — request new languages or features

Upcoming: auto regression forensics · end-to-end test generation

👉 Learn more at akonlabs.com — for commercial licensing or enterprise inquiries, ping us on Discord or email founders@akonlabs.com

Community Integrations

Built by the community — not officially maintained, but worth checking out.

Project	Author	Description
pi-gitnexus	@tintinweb	GitNexus plugin for pi — `pi install npm:pi-gitnexus`
gitnexus-stable-ops	@ShunsukeHayashi	Stable ops & deployment workflows (Miyabi ecosystem)
KiloCode MCP workflow	@oktanishq	Guide to connect GitNexus MCP to Kilo Code and verify tools.

Have a project built on GitNexus? Open a PR to add it here!

Roadmap

Actively building:

LLM Cluster Enrichment — semantic cluster names via LLM API
AST Decorator Detection — parse @Controller, @Get, etc.
Incremental Indexing — only re-index changed files

Recently completed:

Constructor-Inferred Type Resolution, self/this Receiver Mapping
Wiki Generation, Multi-File Rename, Git-Diff Impact Analysis
Process-Grouped Search, 360-Degree Context, Claude Code Hooks
Multi-Repo MCP, Zero-Config Setup, 14 Language Support
Community Detection, Process Detection, Confidence Scoring
Hybrid Search, Vector Index

Development

ARCHITECTURE.md — packages, index → graph → MCP flow, where to change code
RUNBOOK.md — analyze, embeddings, stale index, MCP recovery, CI snippets
GUARDRAILS.md — safety rules and operational "Signs" for contributors and agents
CONTRIBUTING.md — license, setup, commits, and pull requests
TESTING.md — test commands for gitnexus and gitnexus-web

Tech Stack

Layer	CLI	Web
Runtime	Node.js (native)	Browser (WASM)
Parsing	Tree-sitter native bindings	Tree-sitter WASM
Database	LadybugDB native	LadybugDB WASM
Embeddings	HuggingFace transformers.js (GPU/CPU)	transformers.js (WebGPU/WASM)
Search	BM25 + semantic + RRF	BM25 + semantic + RRF
Agent Interface	MCP (stdio)	LangChain ReAct agent
Visualization	—	Sigma.js + Graphology (WebGL)
Frontend	—	React 18, TypeScript, Vite, Tailwind v4
Clustering	Graphology	Graphology
Concurrency	Worker threads + async	Web Workers + Comlink

Security & Privacy

CLI: everything runs locally on your machine. No network calls. Index stored in .gitnexus/ (gitignored). Global registry at ~/.gitnexus/ stores only paths and metadata.
Web: everything runs in your browser. No code uploaded to any server. API keys stored in localStorage only.
Open source — audit the code yourself.

Star History

Acknowledgments

Tree-sitter — AST parsing
LadybugDB — embedded graph database with vector support (formerly KuzuDB)
Sigma.js — WebGL graph rendering
transformers.js — browser ML
Graphology — graph data structures
MCP — Model Context Protocol

README.md Unescape Escape