mirror of https://github.com/abhigyanpatwari/GitNexus.git synced 2026-08-28 05:25:25 +00:00

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

Find a file

DuduPhudu 223ac7010d feat: close reported graph blind spots in reference resolution, analyze and storage (#2856 ) * fix(mcp): report UNKNOWN risk when an upstream impact walk finds no callers `risk: LOW` asserts "safe to change" — a claim ABOUT callers. An upstream walk that resolved none has nothing to base it on: the symbol may be genuinely unused, or reached only through a reference class the index does not record (a property access on a plain object, a bare-identifier read of a module-scope const). Seeding LOW from an empty result is the false-safe signal `anyKnownRisk` already refuses to emit on the ambiguous-candidate path, and that #2687 removed by making an undetermined impactedCount `null` rather than `0`. Zero-caller upstream results now report risk UNKNOWN with a riskNote saying absence of edges is not evidence of disuse. Downstream is untouched: an empty downstream walk reports resolved callees, not safety. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> * feat(javascript): emit ACCESSES for bare-identifier reads of module-scope consts A constant read only as a bare identifier — `Math.max(LIMIT, n)`, a default parameter value, `return LIMIT` — minted no reference site at all, because JS captured only `@reference.read.member`, which requires a receiver a bare identifier does not have. So "who uses this constant?", the question behind every dead-code trim and constants refactor, answered with a confident zero in both directions. The rest of the machinery was already in place: `FIELD_KINDS` accepts `Const`, the scope query already declares it via `@declaration.const`, and `read` maps to ACCESSES for any resolved target. This adds the missing capture in VALUE POSITIONS ONLY (call arguments, default-parameter values, return statements) — a blanket `(identifier)` rule would mint a site for every token in the file, which is unaffordable at repo scale and would keep alive the block-local symbols `pruneLocalSymbols` exists to drop. Cross-file readers are NOT yet covered: the site exists and a call through the same import statement resolves, but a value-kind def does not link across the import edge. Recorded as a todo with the investigation. PARSE_CACHE_VERSION bumped 44 -> 45: this is parse-time capture emission, so a warm cache replays the pre-change capture set and the new edges never appear — observed directly, a full `analyze --force` produced a byte-identical graph until the cache was cleared by hand. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> * test(javascript): pin A1/A5 plain-object property acceptance criteria Fixture plus todo specs for the four shapes plain-object property access has to answer: object-literal keys indexed as Property nodes, a read through the holding variable, a property WRITE, and a read through an untyped param. Records the investigation so the work is resumable: the parse-query pattern scoped to literals bound to a variable matches correctly (verified against the raw JAVASCRIPT_QUERIES), but no Property node reaches the graph and local-symbol-pruner is not the cause — it drops only Const/Variable/Static. The remaining gate is in the parse worker's node-creation path. No production code — specs only, so the suite stays green. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> * feat(javascript): index object-literal keys of a named object as Property nodes Idiomatic JS models configuration as an object literal, not a class, but Property definition nodes existed only for DECLARED CLASS FIELDS. A config field therefore had no symbol at all: `context({name: 'exitMinAtrMult'})` answered "not found" for a field read and written throughout a live code path, and ACCESSES had no target to point at. Both halves are added for keys of a literal BOUND TO A VARIABLE — the parse query mints the graph node, the scope query mints the def the resolver can aim at. Unbound literals are deliberately excluded: an inline call argument or a JSX prop bag is call-site data, not a named surface other code references, so a node per key there would add volume without adding an answerable question. This lands the definition-node half only. The ACCESSES edges still require receiver resolution — typing the const that holds the literal to the literal's scope for the precise case, and name-based matching at reduced confidence for the untyped-param (option bag) case. Both are recorded as todos with the mechanism each needs. Also records a trap that cost a wrong conclusion: under vitest the parse worker runs the BUILT dist code (parse-impl resolves parse-worker.js, absent under src/, and falls back to dist), so parse-query changes are invisible to tests until `npm run build`. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> * test(cache): move the SCHEMA_BUMP pin to 45 The pin is the guard that makes two branches claiming one cache-schema number fail loudly instead of silently serving each other's entries, so a bump is only half-done until the pin moves with it. The bump itself landed with the JavaScript bare-identifier captures; this is the other half. Caught by the guard working exactly as designed — the suite failed with "expected 45 to be 44" rather than letting a mismatched pair through. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> * feat(scope-resolution): resolve plain-object property access by unique name Idiomatic JS reads configuration off an object whose receiver cannot be typed — an options bag passed as a parameter, a destructured handle, an imported literal. No precise pass resolves those, so a field read and written across a live code path produced no ACCESSES edge at all and "who reads this setting?" answered a confident zero. A last-resort pass runs after every precise pass and sees only what they left behind. For each still-unresolved read/write site it asks whether exactly ONE Property in the workspace carries that name. If so the read almost certainly means it. If two or more do, nothing is emitted and the site is COUNTED as ambiguous — a guess between them would be a coin flip, and a wrong edge in the pre-edit safety gate is worse than a missing one. Uniqueness is the right gate because it recovers exactly the names worth recovering: distinctive domain fields (exitMinAtrMult, bookNotionalUsdt) are unique in a repo and resolve, while generic keys (id, name, data) are not and are skipped — which is where name matching would over-connect. Bounded four ways: - Confidence 0.5, the global tier, with the inference named in the reason, so a consumer can filter inferences without losing scope-resolved edges. - Never second-guesses a precise result: sites already resolved are excluded, because first-write-wins stops a duplicate but NOT a second edge to a different target. - Honors `fieldFallbackOnMethodLookup`. A statically-typed language opts out of name matching precisely because it over-connects; inferring an ACCESSES edge by name is the same claim and must obey the same opt-out. - Requires an explicit receiver — a bare identifier is not a property access, and matching one by name would link a local to an unrelated key. Indexes graph nodes rather than scope defs because an object-literal key mints a Property NODE but no scope-resolution DEF: `localDefs` and `scope.bindings` are both empty for exactly the population this serves. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> * feat(analyze): record a collapsed graph write instead of reporting fresh The dangerous half of a broken refresh: metadata IS written, so the index reads as fresh, hooks re-arm, and every tool answers from a graph missing most of its edges — indistinguishable from a codebase that genuinely has no such relationships. Reported in the field as edges collapsing 23009 -> 2170 and as a CodeRelation table that never materialized. `analyze` now compares the relationship count the pipeline PRODUCED against what the DB hands back after the write. Both numbers are already in scope at the same point, so the shortfall is provable rather than inferred — no comparison against the previous index, which cannot distinguish a failed write from a repo that legitimately shrank. A missing relation table needs no special case: it reads back as a persisted count of zero. On a collapse the run records `graphWriteCollapsed` in metadata, which `getIndexIncompleteReasons` turns into `graph-write-collapsed` so status and the MCP resources report the index INCOMPLETE rather than fresh. A ratio, not equality: some relationship types do not round-trip one-for-one and `--pdg` writes MORE rows into the same table, so demanding equality would fire on healthy runs. Only a collapse is a defect. Fail-safe when the expected count is unavailable — an implementation that offloads relationships out of memory may not be able to report a total, and a false "your index is broken" is worse than a missed one. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> * fix(ingestion): qualify object-literal Property ids by their owning object Two config objects in one file that share a key name generated the same `Property:<file>:<key>` id and COLLAPSED INTO ONE node, so two distinct settings became a single symbol. Worse, the merged name then looked workspace-unique to name inference, which happily resolved reads of it to a node representing both — a wrong edge in the pre-edit safety gate, which is precisely what the unique-name pass is bounded to avoid. `objectLiteralOwnerInfo` already existed for exactly this ("so two constructors in one file that both define `bar` stay distinct nodes") but was gated to `Method`. `Property` now opts in. `findObjectLiteralBindingInfo` returns `ownerName` only when asked. Its `Method` ids must stay byte-identical — qualifying them would rewrite every object-literal method id in every indexed repo — while object-literal KEYS, indexed only since A1/A5, have no such history to preserve. Found by a test written for the ambiguity path rather than by review: the suite reported one node where two were expected, and an edge where none should exist. Both are now pinned, along with the detection boundaries of the B2 collapse check, which was previously an untestable inline expression and is now a pure function. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> * feat(typescript): index type aliases and shape members as symbols A TS frontend models its API contracts as `type X = { … }` and `interface`, so a field on one is exactly what "who breaks if I remove this?" is asked about. Three gaps made that unanswerable, all in the TypeScript queries: 1. No `type_alias_declaration` -> `@definition.type`, so an alias minted NO NODE AT ALL and a context() lookup on an exported contract type answered "Symbol not found". TypeScript was the ONLY language missing this — Rust (type_item), Kotlin (type_alias), Swift (typealias_declaration) and Dart all emit it. The alias was declared for scope resolution but never became a graph symbol. 2. No `property_signature` in the parse query, so INTERFACE members minted no Property nodes either — the upstream report's "class/interface index fine" holds only for the type, not its fields. 3. No `property_signature` in the scope query, so even with nodes present the resolver had no member declaration to aim at. Its sibling `method_signature` -> `@declaration.method` already existed; only properties were missing. Interface bodies and object-type aliases both spell members as property_signature, so one pattern per query covers both shapes. Lands the SYMBOLS, not yet the ACCESSES edges: the shape is already a class-like scope and now has member declarations, but no edge forms — the remaining link is owner/type-binding, recorded as todos with the diagnosis. Note TypeScript sets fieldFallbackOnMethodLookup:false, so unlike JavaScript there is deliberately no name-based fallback here; the precise path is the only route by design. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> * test(golden): accept interface members in the mini-repo snapshot Drift is entirely the new TypeScript shape-member indexing: the fixture's three interfaces (ValidationResult 2, DbRecord 3, LogEntry 3) contribute exactly 8 Property nodes, each with exactly one HAS_PROPERTY owner edge. Verified before regenerating rather than after: every pre-existing count is untouched (CALLS 9, IMPORTS 12, DEFINES 16, HAS_METHOD 1, MEMBER_OF 12, STEP_IN_PROCESS 12), so nothing was rewired — the digest moved only because 8 edges were added. The fixture's inline `return { valid: false, … }` literals correctly produced nothing, confirming the object-literal rule stays scoped to variable-bound literals. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> * fix(analyze): never report a collapse from a non-numeric count The B2 check reported healthy runs as total graph-write collapses. A non-numeric `expected` (a graph implementation reporting no total, a lightweight pipeline result) does not skip the guards — it INVERTS them: `undefined < 100` is false, so the small-repo exemption never fires, and `0 >= undefined * 0.5` is `0 >= NaN`, also false, so the ratio check "passes" as well. Both bounds silently evaporate and every such run is flagged. That is precisely the failure this check was written to catch, reproduced inside the check itself: an unmeasurable quantity treated as a measured zero. Both sides are now validated as finite numbers before any comparison. `persisted` is also passed as UNKNOWN rather than zero when the DB was not demonstrably readable: `getLbugStats` flattens "no connection", "query threw" and "empty table" all into `edges: 0`, so `stats.nodes > 0` is used as independent evidence the read happened at all. Caught by the existing run-analyze suites, not by the new unit tests — those exercised the pure function with well-formed numbers and were blind to the integration's actual inputs. Both cases are now pinned. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> * feat(typescript): make object-type aliases own their members A TS object-type alias declares the same `property_signature` members as the interface beside it and answers the same question, but was not a member owner: its fields were minted with bare ids and no owner edge, so two aliases in one file sharing a field name collapsed onto one node, while the identical interface resolved normally. `type_alias_declaration` joins CLASS_CONTAINER_TYPES (and CONTAINER_TYPE_TO_LABEL, as that set's invariant requires — a container missing there gets orphaned member edges or a wrong owner label). Aliases with no object type (`type Id = string`) declare no members, so they own nothing and are unaffected. This also lands the INTERFACE field -> consumer edges, verified on the mini-repo fixture rather than only on a purpose-built one: `saveToDb` now links to `ValidationResult.value`, and `formatLogEntry` to `LogEntry.level` and `LogEntry.message` — three real contract-field reads that previously had no graph path at all. Golden updated: +3 ACCESSES, no node changes. The ALIAS field -> consumer edge is still not linked and is recorded as a todo with the exact blocker: resolving a receiver typed as the alias needs the NAME to resolve to a class-like def, and `isClassLike` is Class\|Interface\|Struct\|Record\|Enum\|Trait. That predicate is read from ~12 sites including MRO and heritage, and every language mints TypeAlias, so widening it would enrol aliases in linearizations where they do not belong. Widening only the scope index was tried and reverted — the type-name walkers gate on it independently, so it fixed nothing and left dead code. That needs a deliberate "shape-like" concept, not more call-site widening. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> * docs(test): record the traced diagnosis for the unlinked alias field edge Traced to the end rather than left as "needs investigation", so the next attempt starts from facts: 1. Graph side is COMPLETE and symmetric with the interface — Property:...:LiveModeConfig.bookSlots is owner-qualified and carries HAS_PROPERTY. 2. Resolution DOES reach resolveClassBindingForName('LiveModeConfig') (instrumented) and misses. 3. It misses because the module scope binds LiveModeIface:Interface, renderAlias, renderIface — and not LiveModeConfig. The alias has no binding on the receiver's scope chain at all. 4. The TS scope query tags aliases @declaration.type, but normalizeNodeLabel accepts only typealias / type_alias and has no "type" case, so it returns undefined. Kotlin and Dart use @declaration.type_alias; TypeScript is alone on the dead tag. 5. Retagging is NECESSARY BUT NOT SUFFICIENT — tried, and the binding still does not appear, so a second gate exists in how a declaration anchored on a node that is ALSO a @scope.class anchor is attached: the alias appears to bind inside its own scope rather than hoisting to Module, where interface_declaration evidently does hoist. An isShapeLike predicate (the nominal-vs-structural split: shapes declare members, nominal types participate in MRO) plus a mirrored findShapeBindingInScope were built and REVERTED along with the retag. With no binding on the chain they never fire, and shipping inert widening is worse than shipping none — the same standard applied to the earlier scope-index attempt. The design is recorded here; it is worth doing once step 5 is fixed, and it also unblocks Rust's parked union_item, which the MEMBER_OWNER_NODE_TYPES comment documents as the same gap in another language. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> * feat(scope-resolution): resolve cross-file value references, skip block-locals Two halves of the same question, "who uses this constant?". CROSS-FILE. `resolveReferenceSites` runs against the registries and, as its own comment says, "imports live in finalized bindings the registries can't see" — which is why free CALLS need `emitFreeCallFallback`. Reads had no counterpart, so `import { LIMIT }` followed by a bare use resolved to nothing while a CALL through the very same import statement resolved fine. This adds the read/write counterpart, reusing `findValueBindingInScope` (which walks the FINALIZED chain) rather than inventing a lookup. Confidence 0.9: the import names the def, so this is precise resolution, not inference. BLOCK-LOCALS. Bare-identifier capture also matches a read of a block-local `const`, and an edge to one keeps alive exactly the inert locals `pruneLocalSymbols` exists to drop — a pruned node becomes a retained node plus an edge, in every function of every indexed repo. Emission now takes the set of value defs bound at MODULE scope and drops ACCESSES to Const/Variable/Static outside it. The cross-file pass carries the same guarantee structurally: a def in another file cannot be a block-local of this one, so it skips same-file hits entirely. The block-local leak was already shipped in the intra-file A2 commit and was found only because a test was written for the guard rather than the feature — the same way the object-literal id collision surfaced. Verified on the full resolver matrix: 3172 tests, golden unchanged. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> * fix(lbug): diagnose a vanished staging CSV instead of surfacing a Binder error A forced rebuild could fail with "COPY failed for File: Binder exception: No file found that matches the pattern .gitnexus/csv/file.csv" and then an ENOENT on .gitnexus/csv/rel_Folder_File.csv — two engine-level messages that name neither a cause nor a remedy, which is where several field reports end. Only tables with rows > 0 enter the COPY manifest (csv-generator.ts), so an absent file was WRITTEN during this run and removed since. Both COPY loops now preflight and say exactly that, with the row count, both causes the reports point at (a second `gitnexus analyze` on the same repo — they share .gitnexus/csv — or an external cleanup of .gitnexus/), and the action to take. Scope note, deliberately narrow: this does not attempt to fix WAL corruption or checkpoint rotation. Those already have detection and recovery hints (isWalCorruptionError, WAL_RECOVERY_SUGGESTION, the configurable wal-checkpoint-threshold), and the ~6000 lines added to lbug/ + storage/ since v1.6.9 — index-lock.ts most of all, which serializes writers and plausibly closes the concurrent-run class outright — postdate every report in the window. Guessing at unreproducible durability faults would be speculation; making the one failure with NO handling legible is not. An existing overlap test induced this exact scenario (a manifest entry pointing at a missing csv) and asserted on the engine's wording. Its intent — that a node-COPY failure is rethrown at the FK barrier rather than swallowed — is unchanged and still asserted; only the message it matches moved. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> * feat(scope-resolution): split shape-like from class-like, linking alias fields Completes A4: a field on a TypeScript object-type alias now links to the code that reads it, the last unanswerable half of "who breaks if I remove this?" for a TS frontend that models contracts as `type X = { … }`. `isClassLike` answered two questions that only coincide for classes: 1. does this declare MEMBERS I can look up? — a SHAPE (structural) 2. does this participate in inheritance / MRO? — a NOMINAL TYPE An object-type alias is (1) and emphatically not (2) — it has no supertypes and no place in a linearization. Widening `isClassLike` to buy (1) would have enrolled every language's aliases (Rust type_item, Kotlin/Swift/Dart typealias, C typedef) into MRO and heritage, so the two questions now get two predicates. Call sites split by which they ask, and their names already said which: `resolveInheritanceBaseInScope` and `resolveQualifiedInheritanceBase` keep `isClassLike`; receiver typing and member OWNERSHIP take `isShapeLike`. Three parts, each necessary and none sufficient alone: - `findShapeBindingInScope`, mirroring `findValueBindingInScope`'s established relationship to `findClassBindingInScope` (same walker, different accepted def-type), consulted only AFTER the class lookup misses so a class of the same name always wins. - `populateClassOwnedMembers` uses it, so alias members get an `ownerId` and are registered under the alias. Without this the receiver resolved to the alias and then found no members under it. - The TS scope query tags aliases `@declaration.type_alias`, not `@declaration.type`: `normalizeNodeLabel` accepts typealias / type_alias and has no "type" case, so the old tag mapped to NO label and TypeScript aliases produced no scope-resolution def at all. Kotlin and Dart already spelled it this way; TypeScript alone was on the dead tag. An earlier attempt concluded a further "scope-attachment gate" existed. That was wrong and is worth recording: scope extraction runs in the parse WORKER, which loads built `dist`, so the retag was never executed. Rebuilt, the alias hoists to Module scope exactly as the interface does. Same trap as the parse query — `src` edits to anything the worker runs are invisible until `npm run build`. Typedef and Union stay out of `isShapeLike` deliberately: they belong conceptually (the union_item note on MEMBER_OWNER_NODE_TYPES records the same gap) but neither is wired as a member container, so including them would widen a predicate nothing exercises. Verified on the full resolver matrix: 3173 tests, golden unchanged. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> * test(typescript): pin the type-alias capture to a tag that maps to a label The capture test asserted `@declaration.type`, the tag that `normalizeNodeLabel` does not recognize (it accepts typealias / type_alias and has no "type" case). So the test passed for as long as the tag was broken: it checked only that the capture FIRED, never that it resolved to anything, while TypeScript aliases produced no scope-resolution def at all. Updated to the working tag and given a second assertion that the derived kind string is one the label mapper accepts — the property that actually matters, and the one whose absence let a dead tag sit pinned. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> * fix(lbug): declare TypeAlias member pairs so analyze does not abort Making object-type aliases member owners emits HAS_PROPERTY from a `TypeAlias`, and the relation schema declared no such pair. The emit therefore threw `UndeclaredRelationPairError` and the ENTIRE analyze died on any repo containing `type X = { ... }` — a hard stop, not a dropped edge. Found by running the analyzer over a real 16k-node TypeScript repo, not by a test. `Method` is declared alongside `Property`: a member written `type Handler = { onClick(): void }` is a method_signature and would fail in exactly the same way. Why every existing test missed it: the resolver suites build an in-memory graph via `runPipelineFromRepo` and never write to LadybugDB, so the schema constraint was never exercised. `structural-pair-coverage.test.ts` is the one suite that does run the emitters against the declared pairs — and its own docstring names the gap: coverage is bounded by NON_BRIDGE_CORPUS, "a new structural emitter should land with an entry here". This adds that entry, pinning TypeAlias\|Property and Interface\|Property as sentinels. Verified the guard is not vacuous: removing the pair again makes the suite fail with undeclaredPairs: ["TypeAlias\|Property"]. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> * fix(processes): trace depth-first so multi-hop flows are detected D1 ("query ranks frontend components above the backend module that owns the concept") and D2 ("processes is dominated by trivial mechanical chains") are the same defect, and neither is about ranking or selection. The walk stops after a fixed NUMBER of traces, so traversal order decides which traces those are. Breadth-first reaches every shallow terminal before any deep one, so the quota filled with the shortest paths in the graph and the walk stopped — `maxTraceDepth: 10` was never approached. Measured on a real repo before the fix: of 300 processes NONE exceeded 7 steps and 90% were 3-4. A multi-hop business flow (signal → order → exit) therefore had no process that could represent it, and `query` could only rank the mechanical pairs that did exist. Step 4 of the caller already sorts by length and dedupes by endpoint — it was always asking for the deepest traces this walk could give it. Depth-first descends to a terminal first, so the same quota is spent on paths worth keeping. Cost is unchanged: same budget, same cycle guard, same depth ceiling — only the order differs. Measured on the same 16k-node repo, same build and flags, BFS vs DFS (an earlier comparison was discarded as confounded — it crossed builds and --pdg): steps 6-8: 50 → 168 (3.4x) totals: 844 → 806 and the reported query moved from `LiveSetupView → Cn` (a React component) to `ReconcilePositions → IsTpInProfit / WithHeld / ShouldNotify` — server-side exit management, which is what was asked for. `traceFromEntryPoint` is exported for the test. Traversal order is unobservable through `processProcesses`: `findEntryPoints` supplies several starting points, so a deep chain is traced from inside it whatever the order does. A test at that level passes under BOTH traversals — the first version of this test did exactly that and guarded nothing. Driving the walk directly, it fails under breadth-first with "expected 3 to be greater than 3". Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> * docs(test): correct a stale status note left behind by a later fix The A1/A5 header still said "edge resolution REMAINING ... neither is implemented". Both shapes resolve — the typeable receiver precisely, the untyped one by workspace-unique name — and the tests below assert exactly that, so the note contradicted the file it sat on. It was accurate when written and went stale when the work continued past it. Left as-is it would tell a reviewer that a landed feature is missing. The TRAP note is kept: the parse worker still runs built dist under vitest, and that is still the trap it describes. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> * feat(scope-resolution): index literals behind identity-preserving wrappers `export const INERT_EXIT_CONTRACT = Object.freeze({ ... })` minted no `Property` node for any of its keys. The object-literal rule matches `variable_declarator > value: (object)` as a DIRECT child, and freezing puts a call expression in between — so the shape whose fields are most worth querying was the one shape the rule could not see. Freezing a config object is how JS publishes an immutable contract, which is why this reads as a confident zero on exactly the fields a reader cares about. The allowlist is three functions, not "any call". `Object.freeze`, `seal` and `preventExtensions` RETURN THE ARGUMENT THEY WERE GIVEN, which is what makes the literal's keys members of the bound name. For `const x = compute({ a: 1 })` the literal is an argument and `x` holds compute's return value, so attributing `a` to `x` would be a fabrication. Two negative controls, because the obvious one is vacuous: a bare-identifier callee is rejected structurally and would pass with no allowlist at all, so the assertion that actually pins the predicate uses `Object.entries` — identical shape, differing only by name. Verified load-bearing by adding `entries` to the allowlist and watching that test alone fail. SCHEMA_BUMP 46 -> 47: parse-time emission, so a warm cache replays the pre-fix capture set. Observed as a false negative first — `analyze --force` returned the old node set until the on-disk cache was removed by hand. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> * fix(scope-resolution): narrow multi-candidate property names by scope Workspace uniqueness was the wrong denominator. Measured on the reporting repo: `exitMinAtrMult` has 26 `Property` definitions — 16 in one-off `scripts/`, 7 in the frontend, one in a test, and exactly ONE in the backend that reads it. Every backend read was refused because of competitors the reader cannot see. The gate was not too permissive or too strict, it was scope-blind. A name with several definitions is now narrowed before being abandoned: same-file first, then files the reading file directly imports, using the finalized import graph rather than a path-shape heuristic. Exactly one survivor at the first non-empty tier resolves; anything else stays refused. A tier holding several candidates stops the walk instead of falling through — local evidence that is itself ambiguous still contradicts reaching further out. Confidence stays 0.5 at every tier. Narrowing changes which candidate is chosen, not the kind of claim: it is still a name match, and the round-1 contract is that filtering on confidence drops all name inference at once. The reason string now names the tier that fired. Ambiguity reporting goes from a count to the actual names (capped), because a count says a gap exists while the names say which fields are unanswerable. Measured on that repo, backend readers of `exitMinAtrMult` go 0 -> 24 and total readers 9 -> 45, including the two call sites in `oppositeSignalExitManager.js` the report singled out. Both narrowing tests were mutation-checked by dropping the import evidence and confirming they, and only they, fail. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> * feat(scope-resolution): capture destructured parameter keys as property reads `function exit({ exitMinAtrMult = 0 })` reads that property off whatever the caller passes, exactly as `cfg.exitMinAtrMult` would. It never appears in a member_expression, so it had no reference site at all — and this is the shape the function that IMPLEMENTS a behaviour uses, so the most relevant reader was the one systematically missing from "who reads this setting?". Uses a distinct `@reference.read.destructured` anchor rather than `@reference.read.member`. The latter is filtered emit-side to matches with a member_expression ancestor, because calls and writes share its shape, and a destructuring pattern has none — reusing the tag would have been silently dropped by that filter. The `read.` head already maps to a read kind, so no mapping change is needed. Scoped to formal_parameters. A destructuring binding elsewhere (`const { x } = require('m')`) is frequently an import rather than a field read, and minting a property read there would attribute module bindings to unrelated same-named keys. All three cases (default value, bare shorthand, renamed key) mutation-checked by removing the patterns and confirming those three tests, and only those, fail. The renamed case also asserts the edge points at the KEY and that the local alias mints nothing. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> * fix(scope-resolution): link type consumers to the type they name An exported contract type owned its members after round 1 and still answered `incoming: {}`, so "what breaks if I remove this field?" — the question a contract type exists to answer — had no edge to walk. Measured on the reporting repo: all 324 TypeAlias nodes AND every Interface node had DEFINES as their only incoming edge. Two independent causes, and the second is why the first was not enough. TypeScript captured no type references at all — only cpp and csharp did — so an annotation naming a declared type minted no reference site. Added for annotations, generic arguments and `as` assertions, anchored to those contexts rather than a bare `(type_identifier)`, which would also match the name in `type X = …` and make every declaration a consumer of itself. That alone fixed interfaces and left aliases still empty. `TypeAlias` was missing from `LINKABLE_LABELS`, so alias graph nodes were never indexed in `nodeLookup` and `resolveDefGraphId` could not bridge a def to its node — the edge was dropped AFTER a successful lookup. `CLASS_KINDS` has always listed TypeAlias and the ClassRegistry returned the def correctly, which is what made this read as a resolution failure; instrumenting the lookup showed it returning the right def all along and moved the search one table over. Exactly the bug already documented two entries above it for Trait. Fixes every language that spells an alias this way — TypeScript, Kotlin, Dart and Rust all emit `@declaration.type_alias`. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> * feat(scope-resolution): capture record construction as property writes The read side answered well after the narrowing work while "who SETS this field?" still missed the code that stamps the value. A record built inline — `return { exitContract: { exitMinAtrMult: settings.x } }` — is bound to no variable, so it minted no definition and its keys referenced nothing. Modelled as WRITE REFERENCES, deliberately not definitions. The round-1 rule already mints Property nodes for literals bound to a variable; minting more for anonymous records would add same-named competitors to the very name-narrowing that makes these fields resolvable — measured at 26 competing definitions for one field on the reporting repo, which is what made every backend read unanswerable in the first place. A construction site is a USE of a field, not another declaration of it. Two positions only: nested under a key, and returned. Both are records with a name attached (the key, or the function). An inline call argument (`doThing({ id: 1 })`) stays excluded for the same reason round 1 excluded it from definitions — it is call-site data, not a named surface — and is asserted as such. The enclosing literal is the receiver and it is anonymous, so these route through the same narrowing and the same refusal-to-guess as every other untyped receiver. Verified on the reporting repo: `entryPlan.js` went from no rows to `selectExitEnvelope` as a writer of `exitMinAtrMult`. Both captures mutation-checked. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> * feat(processes): select round-robin by terminal so the list is not one flow repeated Ranking was `sort by length` alone, so the top of the list was one behaviour described many ways: eleven of the top fourteen processes on the reporting repo were four entry points crossed with three terminals of the SAME date-window utility cluster. Genuine call chains, but a reader learns one thing from fourteen entries, and the repo's own domain flows sat below them. Selection now round-robins across TERMINALS, deepest first. Depth still orders within a terminal and still leads the list; what changes is that no terminal takes a second slot until every other has had a first. Keying on the entry point was tried first and made it worse — many files declare a `main`, so each was a distinct entry that round-robin then awarded its own slot, and `Main -> AlignWindowEnd` went from one row to eight. The repetition was never in where a flow starts. Measured on that repo: distinct terminals in the top 20 went 3 -> 20, and its domain flows (`ReconcilePositions -> ...`) moved into the top 4%. Two things this deliberately does not claim. The reported cause — ranking rewarding fan-in, promoting chains ending in widely-called helpers — measured FALSE: those terminals have one caller each (`alignWindowStart` 1, `validateSymbol` 1). A fan-in discount was implemented against that hypothesis, measured, and reverted for moving nothing. And a business flow still cannot be a process in its own right: the walk only emits at a leaf, at max depth, or on a cycle, so a flow whose meaningful endpoint calls onward survives only as whatever leaf it bottoms out in. Both are recorded in the code so neither reads as settled. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> * test(structural-pairs): pin the type-annotation USES pair R2-2 emits USES INTO a `TypeAlias`, so the pair is `Function\|TypeAlias` — a different table from the `TypeAlias\|Property` entry added in round 1, and one that entry stays green without. `TypeAlias` is on the eleven-table list this suite exists for, and an undeclared pair does not degrade: it throws `UndeclaredRelationPairError` and kills the entire analyze on any repo containing an annotated type. Every resolver suite still passes, because they build an in-memory graph and never write to the DB. That exact failure shipped once in this PR already. Two emitters into the same label, each with its own way to reach a released build. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> * fix(scope-resolution): build the module-level set before the out-of-core seal Review blocker. Under `GITNEXUS_DISK_SCOPE_INDEX=1` the seal replaces every ParsedFile with a scope-STRIPPED copy, and the block-local filter's set was built after it — so it walked `scopes: []` for every file, came out empty, and the filter read that as "no def is module-level" and dropped EVERY `Const`/`Variable`/`Static` ACCESSES edge in the repo. All languages, all files, including the module-scope-const edges this PR exists to add. Nothing threw and nothing logged, on the path the largest repos take: the exact confident-empty answer the PR is about. Built above the seal now, from `parsedFiles`, and passed as `undefined` rather than an empty set when no scope was inspectable — an empty set is a legitimate answer ("this repo has no module-level value defs") and must not be indistinguishable from "could not look". Fails open; the block-local exclusion is still asserted under the seal, since that is correctness rather than optimization. Also widens module level past `kind === 'Module'`. A `Namespace` scope (TS `namespace`, Rust `mod`, C++/C# `namespace`) holds importable values too, and treating its consts as function-locals dropped their reads. Included only when the whole chain to the root is Module/Namespace, so a namespace declared inside a function body stays local — asserted both ways. That fixture then failed for a third reason: `@reference.read.identifier` existed ONLY in the JavaScript query, so A2 did not work for TypeScript at all. Added there, and both languages widened to `variable_declarator value:` and `binary_expression` operands — the gaps review named between what A2 claimed and what it matched. Nothing covered `GITNEXUS_DISK_SCOPE_INDEX`. The new parity test asserts the seal changes no edge, and was verified against an emulation of the original bug: same-file readers vanish and only the cross-file reader survives. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> * fix(typescript): anchor property_signature to declared shapes Review blocker, and it reproduces end to end. `property_signature` occurs in EVERY object_type in the TS grammar, not only in an interface body or an alias's object type, so inline parameter types, inline return types and nested object types all matched — and the enclosing-container walk hung each one off the nearest class, interface or alias. Measured against the unanchored rule, all four appeared as members of shapes that do not have them: Property:contracts.ts:Svc.inlineParamOnlyKey Property:contracts.ts:Repo.inlineQueryOnlyKey Property:contracts.ts:NestedConfig.nestedOnlyKey Property:contracts.ts:buildInline.inlineReturnOnlyKey@46:33 When the inline member shares a name with a real one — `run(opts: { retries: number })` inside a class that declares `retries` — `addNode` is first-write-wins and the two distinct symbols merge onto one node, so every context()/impact()/rename() answer about that field describes the merge. The sibling JS object-literal rule in this same PR is anchored for exactly this reason; this is the TypeScript half of the same fix. `(A (B))` matches DIRECT children, so nested object types are excluded by the same anchor rather than by a second rule. The first version of these tests was VACUOUS and is recorded here because the reason generalizes: a collision and a correct exclusion both leave exactly one node behind, so counting ids cannot distinguish them. Every inline member in the fixture is now uniquely named, which is the only thing that discriminates — verified by restoring the unanchored rule and watching exactly those four assertions fail. A fifth test asserts anchoring costs no real member. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> * fix(analyze): correct the numbers feeding the graph-write-collapse guard Review blocker. The predicate itself held under adversarial probing; every defect was in what it was handed and what happened after it fired. (a) `expected` was wrong twice. Under `GraphEmitSink` streaming the bulk types leave the heap at parse time and never enter `relationshipCount`, so the count understated the real volume by most of it and the ratio passed trivially — on `force === true` runs, which include crash recovery AND the `analyze --force` retry this check's own warning tells the operator to run. Adds the manifest totals, the same correction the buffer-pool hint in this file already makes for the same reason. Separately, an incremental run persists only the changed subgraph while both counts are whole-scope: a 10,000-edge index that lost 200 replacements reads 9,800 and is certified complete. The check is skipped on that path rather than answered wrongly. (b) A throwing edge count became a measured zero. `getLbugStats` initialised its total to 0 and ran the query in a swallowing catch, so WAL/lock contention during finalize — documented on this exact call — reported a healthy index as a total collapse. It now returns `number \| undefined`, and the caller requires both a readable node count and a defined edge count. (c) A total loss was exempted for being small. The min-edges rule tested `expected` before looking at `persisted` at all, so `expected = 99, persisted = 0` — every edge gone — stayed fresh and reported success. Total loss is now decided first. The existing test asserted the defect; it now asserts a PARTIAL shortfall, which is the case the exemption was written for. (d) A detected collapse reported success and exited 0. It is different in kind from the other incomplete reasons: those describe a run that did what it said and left work for later, this one means most of your edges are gone and every query answers a confident empty. The CLI now prints INCOMPLETE with the counts and sets a non-zero exit code, and the flag crosses IPC so the worker cannot send a clean `complete` either. Nothing exercised this wiring — only the pure helper. Adds tests for all four, each written so the pre-fix arithmetic fails it. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> * fix(scope-resolution): keep unique-name property inference inside one language The pass indexed `Property` nodes from the whole shared graph. Per-language gating decides whether it RUNS for a language; it never restricted which nodes could be TARGETS. So the only carrier of a name could be in another language entirely, and a read here resolved to it on name uniqueness alone — no owner, no file, no call path. Reproduced: a Java class declaring `private int loyaltyPointsBalance` and a JS `cfg.loyaltyPointsBalance` on an untyped parameter produced an ACCESSES edge from the JS function to the Java private field. Confidence does not mitigate it, because `minConfidence` defaults to 0 — the tier is only a filter for consumers who ask for one. Candidates are now restricted to files in the language's own `parsedFiles`, which is a precise restriction rather than a heuristic and needs no new node property. Every other fixture in the suite is single-language, so this could not be caught anywhere by construction. The new fixture is deliberately polyglot and asserts both halves: no cross-language edge, and a same-language unique name still resolves. Known and not addressed here: the index is still O(total graph nodes) and is rebuilt once per qualifying language, the per-language whole-graph-scan pattern `phase.ts` hoisted out for `sharedNodeLookup`. Hoisting it belongs with that machinery rather than in this fix. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> * fix(processes): explore siblings in source order, log the exhausted budget `slice(0, maxBranching)` selected the FIRST N callees while `pop()` explored them LAST-first, so the trace budget went to the last-declared branch. For `main() { init(); loadConfig(); run(); shutdown(); }` the walk spends itself on `shutdown` and can drop `init` — the earliest steps of a flow, which is the opposite of what a process describes. Selecting first-N and exploring last-first was simply inconsistent; pushing in reverse makes the stack pop in source order. Measured on the reporting repo, this costs depth: 6-8 step processes go 168 -> 146 of 816. Still roughly three times the pre-PR baseline of 50, and the right trade — a deep branch is no longer reached by accident of being declared last. The remaining limit is the BUDGET, not the traversal: with a fixed quota a deep branch declared after enough shallow ones is not reached at all. That is now asserted in both directions rather than left implicit, and the walk logs when it stops with branches unexplored — a silently truncating cap reads as "this is everything", the same confident-empty answer this work is about, and the repo already sets that precedent for `dispatchFanoutSkipped`. Removes the second depth test, which was vacuous: the note twelve lines above it already said a `processProcesses`-level depth assertion passes under BOTH traversals, and measured it does — breadth-first yields the same deepest stepCount of 8, so it passed with the production change reverted. Traversal order is asserted against `traceFromEntryPoint` directly; what is observable at the pipeline level is which traces survive selection, which the diversity tests cover. Also renames `queue` to `stack` and corrects the BFS references in the module docstring and the function's own JSDoc, which is what an IDE hover shows. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> * fix(impact): carry riskNote onto ambiguous candidates and separate UNKNOWN's two meanings Two problems on the ambiguous fan-out, which builds its own candidate object rather than returning the single-symbol shape. The narrowed type had no `riskNote` field and never read one, so a candidate that resolved and found no callers reported `risk: UNKNOWN` with nothing attached — losing the entire point of the change on the path where the reader has the least context, since the name is ambiguous there by definition. And `UNKNOWN` used to mean exactly one thing on this path: the probe threw. The zero-caller branch gives it a second meaning, so an all-UNKNOWN fan-out could no longer be told apart from a broken one. Candidates now carry `probeFailed`, and the comment asserting the old reading is corrected. Also aligns `gitnexus-web`, which review flagged as giving a different verdict for the same symbol. That surface answers in prose rather than an enum, and its message said the symbol "appears to be unused (not called by anything)" — the identical false certainty in words. It now carries the same MEANING rather than the same field. Downstream wording is unchanged: no outgoing dependencies really is a fact about the symbol itself. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> * test: replace assertions that cannot fail Four from review, each satisfied by the defect it was meant to catch. `new Set(props).size === 2` over two different literal strings can only ever be 2, so it could not detect the node merge its title promises — that is a difference in COUNT, now asserted on the raw array. The ambiguity test asserted only an empty edge set, which is satisfied equally by "the gate fired" and "the name was never looked up". It now also requires the ambiguity counter to have moved. `Interface\|Property` was listed as a structural-pair sentinel beside `TypeAlias\|Property`, but both its labels are in the SCOPE_BRIDGE cross-product so the pair is generated by construction and the sentinel cannot fail. Dropped rather than left reading as coverage; `TypeAlias\|Property` is the load-bearing one. `TypeAlias\|Method` was declared in the schema with no fixture emitting it — a declared pair no emitter exercises is indistinguishable from a missing one until an analyze aborts on a real repo. Adds a method-shaped alias member, and the suite requires sentinels to actually appear, so it is not vacuous. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> * docs: document the new incomplete reason, the UNKNOWN verdict and the id churn Review found the code changes landed without the guidance around them, and an agent following this repo's own rules would have been told the wrong thing. `graph-write-collapsed` joined `INDEX_INCOMPLETE_REASONS` with no Sign block and no recovery section, while the precedent it cites (`embedding-checkpoint-pending`) has both — so `gitnexus status` would surface a new string naming silent wrong answers with nothing explaining trigger or remedy. Added to RUNBOOK and GUARDRAILS, including why this reason alone also fails the exit code. `AGENTS.md` said MUST warn on HIGH or CRITICAL and never mentioned UNKNOWN, and the shipped impact skill's risk table had no UNKNOWN row and still implied few-callers ⇒ LOW. An agent obeying those rules literally sees `risk: UNKNOWN` and proceeds, which negates the change the verdict exists to make. Both copies of both skills updated. `MIGRATION.md` now records that process ids do not survive this release — positional ids plus depth-first tracing, source-order siblings and round-robin selection mean `proc_7_handle` is a different flow afterwards. Bounded honestly: nothing in-repo joins on a raw process id, so it is index churn, not a broken consumer. `ARCHITECTURE.md`'s scope-resolution stage list gains the two new stages. The guide skill's node list gains `Property` and `TypeAlias` — the two node types this work most prominently creates. Also, on the pair-CSV preflight review asked to confirm: the hard abort IS deliberate, because a fallback recovering zero rows is the confident-empty failure this work targets. But the transient the message itself names — a second concurrent analyze sharing `.gitnexus/csv` — is a race, so the check now re-looks three times over ~150ms before declaring the file gone. Long enough to ride out a rename, far too short to mask a file that is genuinely missing. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> * fix: drop redundant TypeAlias pairs and keep bare identifiers off class members Two regressions the full suite caught after the review fixes, both real. `schema-pair-coverage` failed with eleven hand-declared pairs that a rule now generates. Adding `TypeAlias` to `LINKABLE_LABELS` — needed so `resolveDefGraphId` can bridge an alias def to its node — also makes it a SCOPE_BRIDGE source and target, so the cross-product produces `File\|TypeAlias`, `TypeAlias\|Property` and nine others that round 1 had declared by hand. Removed; the invariant is that no pair is both generated and hand-declared. This also changes what the structural-pair sentinel means, and the comment is corrected rather than left overstating it: `TypeAlias\|Property` is no longer load-bearing because the label is off the generated grid — it is load-bearing because it now depends on `TypeAlias` being IN `LINKABLE_LABELS`. Remove it and the pair stops being generated while the hand declaration is gone, which is the same state that silently breaks alias consumer edges. `block-scope-shadowing` failed because a bare identifier resolved to a class `Property`. `class Box { baseUrl = '...'; pick() { const baseUrl = ...; return baseUrl; } }` linked the block-local read to `Box.baseUrl`, duplicating the legitimate `this.baseUrl` edge. A bare identifier is not a member access: with no receiver there is no object whose property it could be, and in JS/TS a field read needs `this.`. Receiver-less read/write sites no longer accept `Property` hits; callables stay reachable, so `cb = save` naming a top-level function is unaffected. That defect PREDATES this branch's TypeScript captures — JavaScript has emitted bare-identifier reads since A2 and no class fixture exercised the shadow. The TS parity added here is what surfaced it. Golden snapshot regenerated after verifying the drift line by line: exactly +5 USES from type annotations in the mini-repo, every pre-existing count unchanged, so nothing was rewired. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> * perf(scope-resolution): share the property-name index across language passes Review follow-up. `indexPropertyNodesByName` scanned every node in the graph and was rebuilt inside each qualifying language pass, reintroducing exactly the pattern `phase.ts` hoisted out for `sharedNodeLookup` — whose comment records why it matters: "the previous per-language rebuild burned that CPU+heap N times and, on a huge repo, a tiny language's full-graph copy overlapped the next language's — a real contributor to the scope-resolution memory peak." Built once in `phase.ts` beside `sharedNodeLookup` and `sharedFnNodeIndex`, and threaded through the same `prebuilt` seam, so tests and isolated calls still build their own. Sharing is only safe because the per-language restriction MOVED rather than disappeared: the shared index is whole-graph, and candidates are filtered to the language's own files at lookup time. That also fixes a subtlety the per-language build had backwards — the cap now applies to the FILTERED set, so a name carried by forty properties across a polyglot monorepo but only two in the language being resolved is still answerable, where a global cap would have refused it. The tri-state at the lookup boundary is deliberate and the three outcomes are not interchangeable: no property of this name in this language (nothing to say, and NOT an ambiguity), too many to choose between (reportable), or a list to narrow. Caught mid-change by the polyglot fixture: an intermediate state shared the index without moving the filter, and the cross-language edge came straight back. That test earning its keep twice is the reason it exists. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> feat(scope-resolution): report when a field's only anchor is another language Round 3, found OUT-OF-SAMPLE — six field names appearing in no prior report, so nothing here was tuned against them. All six answered 0 backend ACCESSES while their definitions sat in `apps/research-dashboard/*`: TypeScript only. The in-sample set scored 5/5 and the out-of-sample set 0/6, and the gap is entirely this. Per-language inference (`3c5eadc7`) is right and stays. What was wrong is that declining is INVISIBLE: an empty result for a field anchored only in TypeScript is byte-identical to an empty result for a field nobody reads. One says "look in the other language or grep"; the other says "delete it". That is the same confident-empty failure this series exists to remove, one surface over — and this time the missing fact is about the ANALYZER's reach rather than the code. Declines are now counted and named, with the languages the anchors actually live in, kept SEPARATE from ambiguity because the remedies differ: ambiguity wants better receiver typing, this wants an anchor in the reading language. Collapsing them would tell a reader the wrong thing to do. A non-zero count warns at analyze time regardless of dev mode. The facts are published as `PipelineResult.propertyInference`, which they had to be for any of this to be testable — and that exposed a second defect. The round-2 ambiguity assertion, which I told the reviewer of #2856 I had strengthened, read its stat off a `scopeResolution` field that does not exist on PipelineResult: the `if (undefined) return` guard swallowed it and the test passed with the production code deleted. Both that assertion and the new ones now read the published field, and the guard is an assertion rather than an escape. Verified by deleting the counter and watching them fail. Reported by the same round-3 method note that caught it: verifying a fix against the cases it was written for only proves those cases pass. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> feat(context): explain an empty property result caused by a cross-language anchor The other half of R3-1. The analyze pass now knows which fields it declined to link because every definition of the name lives in another language; this puts that fact where it is actually read. `context()` on such a field previously returned an incoming list byte-identical to a genuinely unread field. The two demand opposite actions — "look in the other language, or grep" versus "delete it" — so the difference has to travel with the answer: unresolved: property reads of this name were NOT linked: every definition of it is typescript, and name inference does not cross languages. An empty or short incoming list here is not evidence the field is unused — confirm with a text search, or give it an anchor in the reading language. anchorLanguages: ['typescript'] Carried through repo meta because the graph cannot answer it: the unlinked reads mint no edge and no node, so the only record is the pass that declined them. Keyed on the NAME, not on the resolved label. Gating on `=== 'Property'` was tried first and is wrong — the label reads `''` on this path for a plain Property node, so the gate silently suppressed the entire feature while every test still passed. Caught by asserting the field is DEFINED rather than guarding on it, which is the same anti-pattern that made two earlier assertions vacuous. The meta list only ever contains property names, so matching the name is itself the type check. Cached per (index, indexedAt): `ensureInitialized` deliberately avoids a per-call `loadMeta` because every tool routes through it, so this re-reads exactly when a re-analyze could have changed the answer and never otherwise. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> * feat(scope-resolution): report declined property reads for opt-out languages too Generalizing R3-1 rather than waiting for it to be re-reported in the other direction. The reported case was a JavaScript read whose only anchor was TypeScript; the mirror — a TypeScript read anchored only in JavaScript — was still silent, because a language that sets `fieldFallbackOnMethodLookup: false` had the whole pass skipped, and skipping emission also skipped REPORTING. Detection is not inference. Counting what could not be linked asserts nothing about what it means, so `reportOnly` runs the pass for its facts while emitting no edge, and the opt-out keeps protecting exactly what it protected before. Two things this turned up that a single-instance fix would have missed: The cross-language fixture could NOT prove `reportOnly` is load-bearing — the per-language candidate filter already blocks those edges, so the assertion passed with the flag forced off. The case that discriminates is a SAME-language TypeScript read that name inference could legitimately link and the opt-out forbids; forcing the flag off there emits `readsTsOnly -> tsOnlyBudget`, which is the violation. Getting to that case surfaced a sibling gap, recorded but NOT fixed here: the object-literal `Property` rule is JavaScript-only, so `const CONFIG = { ... }` in a `.ts` file mints no node and its keys are invisible. The first draft of this fixture used exactly that shape and could not discriminate for that reason. It is the TypeScript half of R2-1a and wants its own change, not a rider on this one. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> * feat(typescript): index object-literal keys, as JavaScript already did The sibling recorded in `0c5a4f64` and deliberately left out of it. Both the named object-literal rule (A1/A5) and the identity-wrapper rule (R2-1a) lived only in JAVASCRIPT_QUERIES, so the single most common config idiom in TypeScript — export const tsRuntimeConfig = { tsConfigRetries: 3 }; — minted no node for any key. `context()` answered "Symbol not found" and a precise read through the holding variable had nothing to resolve to. TypeScript sets `fieldFallbackOnMethodLookup: false`, so these gain no name-based inference. What they gain is the PRECISE path, which is the route TypeScript is meant to use: `tsRuntimeConfig.tsConfigRetries` has a typeable receiver and now resolves. A read through an untyped receiver stays unresolved and, since `0c5a4f64`, is reported as such rather than answering an empty set. Scoped exactly as the JavaScript rules are — bound to a variable, and for the wrapper only the three functions that return the argument they were given — with the same `Object.entries` negative control pinning the allowlist. Found by fixture, not by report: the first draft of the `reportOnly` test used a TS `const CONFIG = { ... }` as its discriminator and could not discriminate, because the shape mints nothing. That is the whole argument for sweeping a class instead of waiting for each instance to be filed. SCHEMA_BUMP 47 -> 48: parse-time, so a warm cache replays ParsedFiles carrying none of these matches and the keys stay invisible. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> * feat(scope-resolution): anchor anonymous returned object literals to their function The last gap round 3 named, and the dominant shape in idiomatic JS: 437 `return {` sites in a single backend directory of the reporting repo, including the ~25-field payload of its entire signal pipeline. The literal binds to nothing, so its keys could not even be named — "who reads wickRatio?" had no symbol to ask about. The enclosing FUNCTION is the owner: the literal is that function's return shape, a contract its callers consume. Keys qualify as `<function>.<key>`, so two functions returning the same name stay two shapes rather than one merged symbol, and multiple returns in one function stay distinct by position. RECONCILING THIS WITH R2-1b, which deliberately modelled returned keys as WRITES to avoid adding same-named competitors to narrowing. These are definitions, but narrowing now ranks DECLARED anchors — named literals, class fields, interface and alias members — strictly above return shapes. A name that already resolved keeps resolving to what it resolved to before, so the competitor problem R2-1b was avoiding cannot come back. Mutation-checked: dropping that ranking breaks five pre-existing R2 resolutions. That also required an R2-1b assertion to change, and the change is a strengthening rather than a concession. It asserted `toHaveLength(1)` — no new definition — as a proxy for "adding definitions must not move an existing answer". The proxy is now false while the property still holds, so the property itself is asserted directly. No `HAS_PROPERTY` edge from the function: that would be a `Function\|Property` relation pair the schema does not declare, and an undeclared pair does not degrade — it throws and kills the whole analyze. That already shipped once in this PR. Two things found by dumping rather than assuming, both fixed here: SHORTHAND keys were not matched at all. `return { symbol, interval, score }` is the commonest spelling and the reporting repo's own payload is mostly this form, but tree-sitter models it as `shorthand_property_identifier`, which `(pair)` does not match. Caught by dumping the golden fixture and seeing a literal returning `{ level, message, timestamp: Date.now() }` had indexed only `timestamp`. Now covered in return position AND in the variable-bound rule, which had the same gap. Provenance was flagged by owner-presence, which mislabelled the anonymous case: a callback's return shape yields no name to qualify by, so it looked like a DECLARED anchor and would have outranked real declarations. Flagged by position now — a different question from whether a name could be derived. SCHEMA_BUMP 48 -> 49. Within one PR the version only has to differ from main's, but a build stamped 48 was installed and used to analyze before these captures existed, so caches stamped 48 carry none of them — the intermediate-build hazard this ledger already records for 33/34. Golden regenerated after verifying the drift: exactly +10 Property and +10 DEFINES, every pre-existing count unchanged. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> * fix(scope-resolution): rank production anchors above test fixtures Found by testing R3-4 on the reporting repo instead of on its fixtures. Anchoring returned literals took `wickRatio` from 6 definitions to 13 — and backend reads still resolved to nothing, because SEVEN of the new JavaScript anchors compete and four of them are in `tests/`. A test constructs throwaway shapes carrying production field names; a read in shipped code cannot mean one of them. Applied before the declared/return-shape split, because "is this the shipped program" is the stronger signal — a declaration inside a test fixture is still a test fixture. Skipped when the READER is itself a test, since a read there legitimately means the test's own shape. The first version of this test was vacuous and the mutation check caught it: the reader sat in the same file as the production anchor, so the same-file tier resolved it whether or not this tier existed. The reader now lives in a file that imports neither anchor, which leaves production-vs-test as the only thing that can decide. Honest about what this does NOT do: it narrows `wickRatio` from seven candidates to three, and three functions in different files each returning that field is GENUINELY ambiguous — refusing is correct, and the ambiguity is now counted and named rather than silent. The reported question ("who reads wickRatio?") is answerable only where one producer exists; where several do, the honest answer is the list of producers, which R3-4 made nameable for the first time. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> * feat(scope-resolution): resolve members through a call result's return shape The question three rounds of reports could not answer, and the one narrowing must refuse by design: a field produced by SEVERAL functions. A read of `spike.wickRatio` could mean any producer, so name inference correctly declines and no amount of tier-tuning changes that. It needs evidence, not inference. The evidence existed in two halves that had never been joined. The call-result type binding (`const alert = formatSpikeAlert(row)` binds `alert` to a TypeRef whose rawName is the callee) predates all of this work; it simply had nothing to resolve to when the callee returned an anonymous literal, because an anonymous literal named nothing. R3-4 gave it a name. Joining them: const alert = formatSpikeAlert(row); alert.wickRatio -> Property:...:formatSpikeAlert.wickRatio Precise, at ordinary emission confidence, and it works EXACTLY where narrowing cannot: several producers sharing a field name stop being competitors because the receiver says which one. Runs before the name fallback and claims its sites, so a precise answer is never second-guessed by a name match. Measured on the reporting repo: 1,410 precise edges, and all six fields round 3 verified OUT-OF-SAMPLE go from 0 backend readers to 7, 11, 10, 7, 6 and 14. Round 3 scored 0/6 on that set; this is 6/6. The bound is asserted, not just documented: a read off a BARE PARAMETER has no binding here, because typing it needs the caller's type to flow in — that is inter-procedural and genuinely larger. Those reads still fall through to name inference and are still reported when it declines. The fixture has two producers sharing a field name precisely so the test cannot pass by name matching, and mutation-checking the owner lookup fails it. No SCHEMA_BUMP: this is scope resolution, not parse-time capture, so a warm cache already carries everything it reads. Noted in the ledger because the reflex on this branch has been to bump, and an unnecessary bump costs every user a full re-parse. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> * Revert "return-shape anchoring" (R3-4/R3-5): it degrades query Reverts `af5eec5c`, `c764847a` and 4f93f32e. The capability was real and measured — all six fields round 3 verified OUT-OF-SAMPLE went from 0 backend readers to 7/11/10/7/6/14, 0/6 to 6/6, via 1,410 precise return-shape edges. It is reverted anyway, because it costs more than it buys in its current form. `cli-limit-e2e` caught it. Bisected to `af5eec5c`: on the mini-repo fixture, `query('message')` returned two processes before and NONE after. The mechanism is not window displacement — that hypothesis was tested with a partition that kept function-local property keys from taking window slots, and it changed nothing. Indexing the keys of every returned literal adds many nodes whose names are ordinary words, which moves the BM25 CORPUS statistics: "message" gets less discriminating, and `createLogEntry` — the callable that actually carries the processes — stops ranking at all. A corpus-level effect is not repairable by a tie-break. Trading a regression in `query`, one of the core tools, for coverage in `context` is the wrong trade, and shipping it because the number was good would be the same mistake this PR spent three rounds removing: a confident answer that is worse than the honest one. What the work established, and what re-landing needs: - The mechanism is right. Joining the existing call-result type binding to a named return shape resolves `alert.wickRatio` by EVIDENCE, which is why it succeeds exactly where name inference must refuse. - The cost is search dilution, and it needs to be measured on BM25 ranking BEFORE the capture lands — not discovered by a downstream e2e test. - The likely shape of the fix is keeping return-shape keys out of the text search corpus while keeping them in the graph, which needs persisted provenance rather than the in-memory flag used here. Kept: everything through `8972d223`, which is verified green. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> * feat(search): give the index a notion of DETAIL symbols, and re-land R3-4/R3-5 Reverts the revert. The return-shape work was correct and measured — 1,410 precise edges, and all six fields round 3 verified out-of-sample going 0/6 to 6/6 — and it was dropped for a regression that was really a MISSING LAYER: the search index had no way to say "this symbol is queryable but is not a concept a text search should surface on its own". Indexing the keys of anonymous returned literals adds many nodes whose names are ordinary words (`message`, `value`, `timestamp`). Without that notion they compete on equal terms in FTS, push the CALLABLES named after the same concept past the search's row cap, and `query('message')` returned two processes before and none after. The layer, rather than a workaround: - `Property.isDetail`, persisted. A Property-only column, which that table already precedents with `declaredType`, set where the key is minted. - `buildFtsQueryCypher` filters on it for the Property table, BEFORE the row cap. That placement is the whole point: rows crowded out never reach the caller, so no downstream re-ranking can recover them. Two downstream fixes were tried first — a tie-break and a partition of the merge window — and recovered nothing, which is what located the real seam. - `IS NULL`-tolerant, so an index written before the column existed still answers instead of returning nothing. Verified by the A/B that found the regression: the query's result order is now byte-identical to the pre-R3-4 baseline — `proc_0_processrequest, proc_2_errormiddleware, Function:createLogEntry, Property:LogEntry.message` — with the return-shape coverage retained. The determinism guard then caught prose in the new DDL comment containing the token this repo scans for, which would have read as an unordered query. Reworded; that suite is doing exactly its job. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> * feat(processes): let a flow end where the program reaches outward The item three rounds kept circling. A trace was only emitted at a node with NO outgoing calls, so a real flow — scan, score, arm, PLACE THE ORDER — is always a PREFIX of some longer chain that runs on into date helpers, and could never be a process in its own right. Ranking could not fix that; the flow was never a candidate to rank. What blocked it was signal granularity, and the fix is the layer that was missing rather than a heuristic. GitNexus already knew where the program reaches outward: the parse phase collects fetch calls and ORM queries carrying `filePath` + `lineNumber`. Those facts only ever produced FILE-level edges (`File -[FETCHES]-> Route`), which cannot end a trace — every function in a file containing one would qualify. Attributing each site to the function whose range CONTAINS it turns the same facts into the function-level signal the walk needs: no new extraction, no new relation pair, no schema change. Innermost wins, so a closure that performs the call is the sink rather than the function spanning it. Three touch points, and the second is the one that makes or breaks it: - the walk emits at a sink AND CONTINUES, so `placeOrder` is an endpoint while `placeOrder -> formatDate` still exists separately; - subset-removal PRESERVES sink-terminated traces. A sink flow is by definition a prefix of the chain that runs past it, so emitting one at the walk and deleting it one step later would have been a no-op. Mutation- checked: removing this preservation fails all three sink tests, including the one asserting the sink is reached at all; - selection ranks sink-terminated above leaf-terminated, then by depth. `processes` now declares `parse` as a dependency. It historically avoided that on the grounds the dependency was spurious for a progress counter — it is no longer spurious, so it is declared rather than reached for implicitly, and the read fails open so a pipeline without that output detects no sinks instead of losing every process. Bounded honestly: this fires where fetch/ORM extraction fires. On the reporting repo it will do nothing until route detection handles hand-rolled dispatchers, since that codebase routes with `pathname === '/api/...'` on raw node:http and produces zero Route nodes — a separate gap, and the next one worth closing. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> * docs(processes): the comment above the sink ranking still described it as unreachable R3-6 taught the walk what a sink is, but the block explaining the ranking still carried the paragraph written when that was out of reach — "a business flow still cannot be a process in its own right ... fixing that means teaching the walk what a sink is" — sitting directly above the code that does exactly that. A reader arriving at `rankedByInterest` would take the limitation as current. The measured-false fan-in finding stays; it is still true and still worth not re-deriving. What replaces the stale half is the bound that IS current: sinks fire where fetch/ORM extraction fires, so a codebase whose outward calls are not detected as such still sees leaf-terminated traces only. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> * feat(routes): read a route that is declared by a comparison, not by a framework `route_map` on the reporting repo returned {"routes": [], "total": 0, "message": "No routes found in this project."} for a codebase with SEVENTEEN route modules, an `apiRouteTable.js`, and 113 path comparisons. Not a partial answer — a statement about the code, and a false one. Same confident-empty class as the rest of this branch, except here it takes out a whole tool. Four route-discovery paths existed — filesystem convention, single-file framework route, cross-file framework route, decorator — and every one of them needs a FRAMEWORK to declare the route. A raw `node:http` server declares it the only way the language offers: if (req.method === 'GET' && pathname === '/api/live/portfolio') { … } A path, a verb, and a handler. Nothing in the pipeline could read it. The failure modes are not symmetric, so the rules are weighted accordingly: a route this misses is a coverage limit, a route it invents is `route_map` asserting something false. A comparison therefore qualifies only against a demonstrable request path (`pathname`, `.pathname`, `req.url`; `path` is excluded — in Node it is overwhelmingly `node:path` or a file location), and anything untranslatable is dropped rather than approximated: - `pathname.startsWith('/api/')` is a namespace test; minting `/api` would claim a route nobody serves; - a bare `pathname === '/'` with no verb is more often the static-file normalisation branch (`pathname === '/' ? '/index.html' : pathname`) than a route — WITH a verb the intent is unambiguous, so that form IS taken; - an anchored regex converts only when its body is a literal path plus single-segment wildcards, so `/^\/api\/research-runs\/[^/]+$/` becomes `/api/research-runs/{param1}` while an optional group or an alternation bails. Three things went in that nobody reported, each found by measuring rather than by a second report. `switch (pathname) { case '/api/x': }` is the same dispatch in different syntax, and waiting for a bug report per shape is how a graph stays permanently one idiom behind the code it indexes. The reconciliation had to move up a level. The reporting repo keeps its path table (`isKnownApiPath`) in one module and its handlers in sixteen others, so a per-file rule sees each half separately and lists every route twice — once verb-less with the table as its "handler", once properly. Measured: 22 of the first 94 routes were that shadow. Only the whole registry can tell them apart, so the rule lives in the routes phase and touches dispatch-guard routes only — a framework route without a verb is method-agnostic BY DECLARATION (a Django function view, a Laravel resource), a fact rather than a weaker observation. And a path composed from a constant needed folding. One of those seventeen modules writes every one of its routes as `` `${autoTradeBasePath}/rules` ``, where the base is an alias of a module-level literal. Refusing that lost the whole file — and lost it INVISIBLY, since a module with unfoldable paths and a module with no routes are the same empty answer. Same-file only, literals only, one alias hop, and it refuses on ambiguity: a name declared twice with different values is dropped rather than guessed, because a partially-folded path is a wrong route and a wrong route is the failure this module exists to avoid. Wiring is a LanguageProvider hook, not a language check in shared code. `extractDecoratorRoutes` was already the general "route from this file's own AST" channel rather than a decorator-only one — express routes have flowed through it as `decorator-express.get` for a while — so the transport, the `(method, url)` dedup and the handler-symbol resolution all apply unchanged. `ExtractedDecoratorRoute.source` carries the one thing that genuinely differs: a decorator route is DECLARED, a dispatch-guard route is INFERRED. The walk is gated behind a substring pre-filter so it costs nothing on files that cannot produce a route, and the gate is sound by construction — every rule reaches a route only through `isPathExpression`, which needs one of exactly those tokens. SCHEMA_BUMP 49 -> 51, two entries. Decorator routes are worker output carried in the parse cache, so a warm cache replays results predating the extractor and `route_map` stays empty — the symptom this fixes, wearing the mask of "the extractor does not work". The second bump is the v34 hazard tripping again: a build stamped 50 had already been used to analyze before folding existed, so caches stamped 50 carry the unfolded route set. Caught by measuring — the post-folding run came back suspiciously fast and would have reported the pre-folding number. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> fix(scope-resolution): ask whether a value def is FUNCTION-LOCAL, not whether it is module-level The locality filter for value references was written as an ALLOWLIST of module-scope defs, and that shape cannot express a class member. A value def has three homes, not two: module level, a function body, and a CLASS body. Java and C# fields and Python class attributes live in the third, so an allowlist keyed on "module level" excludes every one of them by construction. The guard written to make that safe could not fire either. The set arms whenever a Module scope is FOUND, and Java has module scopes while having no module-level values at all — so for Java it armed permanently empty, which is exactly the state the guard exists to distinguish from "there genuinely are none". Inverting it removes the class. A blocklist of defs positively identified as function-local fails safe: a Java field, a Python class attribute, or a language whose scopes could not be inspected is emitted rather than dropped. That also retires the arming flag — an empty blocklist and an uninspected one mean the same thing, and both mean "emit". The failure mode moves from "silently deletes an edge class" to "retains an inert local", which is the right direction for a tool whose stated principle is that a confident empty answer is the worst outcome. MEASURED, because the review that prompted this reported it as a P0 deleting every Java/C#/Python field ACCESSES edge, and that half does not reproduce. Instrumenting the bridge over `java-write-access` shows ZERO value-ACCESSES candidates reaching the filter: Java field references resolve to a `Property` target and `isValueDefinitionLabel` covers only Const/Static/Variable, so the filter is never consulted there. Pipeline-level edge sets are byte-identical with the filter forced on and forced off, across four shapes — Java cross-file field writes, Java cross-file constant reads, Java bare same-class constant reads, and a Python module-constant/class-attribute mix. The defect is real and latent; the blast radius is not. Fixed anyway, because the predicate asks the wrong question and the next change that makes the bridge the sole emitter would ship the deletion for real. New `value-ref-locality.test.ts` pins the invariant triple — local dropped, module-scope kept, class member kept — by TARGET rather than by `reason`. The per-language suites filter on `rel.reason === 'read'\|'write'` while the bridge stamps `scope-resolution: read\|write`, so they are blind to bridge-side change in both directions. The file states plainly which half gates the mechanism (JS, mutation-verified) and which gates only the outcome (Java, because the mechanism is unreachable there), so it cannot be mistaken for a stronger gate than it is. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> * fix(docs): restore the agent guidance a generated-block refresh deleted Commit 8f8261021's message is entirely about cross-language anchor reporting; it also regenerated the `gitnexus:start` block in AGENTS.md and CLAUDE.md against a LOCAL, non-PDG index and swept six documentation/config files along with it. The review caught this and it is correct. Restored: - the index stats, which regressed 248612 symbols / 565510 relationships / 918 flows -> 29969 / 118986 / 762 — my machine's index described as the project's; - the whole `pdg_query` bullet and the PDG half of the impact bullet, while both capabilities remain live in `mcp/tools.ts` and `local-backend.ts`; - the "Inline staleness signal" section in the guide skill, content that never left `origin/main` and that this branch had no reason to touch; - `.mcp.json`, which had moved from `npx -y gitnexus@latest mcp` to a bare `gitnexus` — a fresh clone with no global install gets a dead MCP server. The worst of it is self-inflicted in a specific way worth naming: commit `411cac9b9`, four hours earlier on this same branch, ADDED the instruction telling agents not to read `risk: UNKNOWN` as an all-clear. The refresh deleted it. So the branch shipped a new UNKNOWN verdict and simultaneously removed the guidance for reading it — the exact false-safe this PR exists to remove, reintroduced one layer up in the docs. Re-applied that guidance, and found the drift is wider than reported. The review noted the `.claude/` copy contradicting the plugin mirror; in fact the UNKNOWN block was present in ONE of five shipped distributions. `gitnexus/skills/` (the npm package), `gitnexus-cursor-integration/`, and `.agents/` were missing it too, so every non-Claude consumer of this skill had the old table. `shipped-skills-sync.test.ts` passed 54/54 through all of that. Its byte-identical check covers only the plan/work/review/lfg family, and the standard skills are guarded solely by per-skill fragment lists — so a fragment nobody listed is a fragment nothing protects. Added the UNKNOWN fragments to that list, plus a `copies.length > 1` assertion so an empty copy list cannot make the loop vacuous. Verified it fails against the pre-fix tree. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> * fix(scope-resolution): require the return-shape producer to RESOLVE, not merely to name-match Review finding 2, reached independently by three Claude lanes and two Codex legs, and reproduced here. `emitReturnShapeMemberAccesses` took the receiver's type binding, then filtered a WHOLE-GRAPH property index with `idNamesMember` — a textual match on the node id. Any node whose id happened to read `<producer>.<member>` qualified, in any file and any language, and it emitted at the 0.9 PRECISE tier where a `minConfidence` floor cannot filter it out. The sibling unique-name pass was given a per-language restriction for exactly this hazard; this pass consumed the same shared index with none. Three guards, catching different shapes: - the producer must RESOLVE to a definition (`findCallableBindingInScope` — a CALLABLE lookup: the producer is the function whose return shape owns the member, and it resolves through finalized import bindings so a producer in another file still yields its own file); - the member must live in that definition's file; - that file must belong to the language being resolved. The third is not redundant with the second, which is the part worth recording. A receiver typed by CONSTRUCTION (`const bound = new Loyalty()`) resolves through the shared class registry, which is polyglot — so the producer resolves into `Loyalty.java`, its members legitimately live in that same file, and file equality waves the cross-language edge straight through. Also fixes the sibling P2: a site where the receiver IS typed to a producer that owns no such member now claims the site. That branch is the strongest negative evidence the pipeline can produce, and letting it fall through meant the 0.5 name fallback answered a question the precise pass had just DISPROVED — measured, linking a read to an unrelated same-named key in another file. `polyglot-property-isolation` gains the bound-receiver arm the review asked for, and it is the right arm: the pre-existing case has an untyped receiver and so only ever exercised the unique-name pass, while one extra token routes an identical read through this one. Mutation-verified — restoring the pre-fix matching makes exactly the new leak assertion fail. The first version of that arm was silently vacuous (it introduced a JS key of the same name, which destroyed the fixture's Java-only premise), which is why it now asserts on the TARGET FILE rather than on the absence of a name. KNOWN LIMIT, stated rather than papered over: a member-call producer (`const r = svc.make()`) binds `svc.make`, which resolves to no callable, so this pass now declines it. Codex B3 raised that converse case and it is real. Fixing it means typing `svc` and then finding `make` on that type — a larger piece of work, queued for the follow-up PR. Declining is the correct interim behaviour: the alternative is matching `make.<member>` by name across the graph, which is the fabrication this commit removes. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> * fix(scope-resolution): resolve the import map by point lookup so the seal cannot empty it Review finding 4, reproduced end-to-end by two lanes: the same commit and the same repo produced a DIFFERENT graph depending on `GITNEXUS_DISK_SCOPE_INDEX`. `buildDirectImportMap` built `scopeToFile` by walking `parsed.scopes`. The out-of-core seal replaces `emitParsedFiles` with a scope-STRIPPED copy — that is its documented contract, scopes are reachable only via `scopeTree.getScope` afterwards — so under the seal the map came out empty, every `directImports` lookup returned undefined, and tier-2 narrowing died repo-wide. The reporting is the worse half. The loss surfaced as `ambiguous`, which means "several candidates and the pass refused to choose". The truth was "the evidence was discarded one function earlier". A reader acting on that would go looking for better receiver typing to fix a problem that was not there. This is the SECOND consumer of `parsed.scopes` on this branch to hit the seal. The first was hoisted above it. This one is converted to the point lookup instead, which is the stronger fix: a point lookup survives the seal by contract, so there is no ordering left for a future edit to get wrong. The parity assertion that would have caught it now exists. The sealed harness in `javascript-const-references` already ran the fixture both ways, but every assertion in it pinned ONE field's readers — which is exactly how a second instance slipped in, since no assertion happened to cover a narrowed name. It now also compares the WHOLE ACCESSES edge set between the two runs, as a sorted diff so a failure names the edges that moved, with a non-empty guard so two empty sets cannot compare equal and assert nothing. Mutation-verified: forcing the map empty fails it. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> * fix(scope-resolution): bind a producer's own returned key to itself, and stop claiming uniqueness for a ranked answer Review finding 3, accepting the two defects it demonstrates and declining the remedy it proposes. Both halves are mutation-verified. 1. A SITE INSIDE ITS OWN RETURN SHAPE NOW BINDS TO ITS OWN KEY. `export function buildB(row) { return { tickIntervalMs: row.b } }` writes the key that IS `buildB.tickIntervalMs`. Ranking declared anchors above return shapes is correct for a READ through a receiver, but applied to this site it handed the write to a same-named module const that `buildB` never touches — a wrong edge — while the node the key actually defines was left with no writer at all. Both halves wrong from one rule applied to the wrong shape. Checked before every other rule, because it is evidence rather than ranking: the owner qualifier on the candidate id and the enclosing callable are the same symbol. Nothing outranks that. 2. THE TIER NO LONGER LIES. `workspace-unique` is a claim that exactly one node in the workspace carries the name — a fact about the graph, and the label a reader trusts most. An answer reached by FILTERING (tests down-ranked, return shapes down-ranked) is a weaker claim, and it was reported under the same label. The edge is unchanged; what it is allowed to say about itself is not. `narrowed` now counts these correctly too, since it keys off the tier. WHAT I AM NOT DOING, and why. The review proposes dropping the same-file and imported-file tiers "and keeping only genuine workspace-uniqueness". That would revert the measured R2 result taking backend readers of `exitMinAtrMult` from 0 to 24. Workspace uniqueness was already measured too strict on that repo: the field carries 26 Property definitions — 16 in one-off scripts, 7 in the frontend, one in a test, and exactly one in the backend that reads it. Strict uniqueness declines all 24. The alternative suggestion — require the receiver to bind to the owning object — has the same effect by another route: the population this pass exists for is the untyped option bag, whose receiver binds to nothing. Requiring a binding turns the pass off for its own use case. So the two demonstrated defects are fixed and the capability around them is kept, at half confidence, naming its inference in the reason string, and honoured only where `fieldFallbackOnMethodLookup` allows. The R3-5 precision test needed rescoping rather than relaxing: it asserted that EVERY edge to the contested field is a precise return-shape edge, which the producer's own (correct, name-tier) write now violates. It asserts the reader edges are precise and the producer's write binds to its own key — two different claims reached two different ways, which is what the code now models. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> * test(bench): re-baseline the JS/TS scope-capture fingerprints for this branch's capture additions The `Cross-language scope-capture fingerprint + scaling guards` CI step was failing on TypeScript and JavaScript, and it had been failing for the whole PR — the branch changed both SCOPE queries without ever updating the guard's baseline. It only surfaced now because a merge conflict had prevented CI from running at all, so nothing reported it. Re-baselined per the file's own instruction ("re-baseline intentionally on a legitimate capture change"), and verified first rather than rubber-stamped. The capture-name sets in both scope queries, diffed against `origin/main`: TypeScript + @reference.read.identifier (A2, bare-identifier reads) + @reference.type (R2-2, type references) JavaScript + @reference.read.identifier (A2) + @reference.read.destructured (R2-1c) + @reference.write.property-key (R2-1b) Nothing removed on either side. A pure superset is the check that no EXISTING capture moved — which is the failure mode a fingerprint guard exists to catch, and the reason to look before regenerating. Consistent everywhere else too: `capture_groups_small`/`_large` are unchanged (4503/14403) because those measure the SYNTHETIC scaling source this branch does not touch, so only the fixture-corpus number moves — 2097 -> 2338 across 21 new lang-resolution fixtures, 146 -> 151 files. Scaling stayed linear and inside budget (typescript 1.116, javascript 1.010, both < 1.5), so the added rules cost no super-linear time. Prior and new hashes are recorded in the baseline note, as every previous entry in that file does. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> * test(bench): re-baseline the receiver-resolution drop guard for the new WRITE site kind Second of the two bench guards that had been failing for the whole PR without anyone seeing it — CI could not run while the branch was conflicted, so both went unreported until the merge cleared. The drift is a new site KIND, not a movement in an existing one: totalDropsAllKinds 129 -> 140 bySiteKind {call: 102, read: 27} -> {call: 102, read: 27, write: 11} `call` and `read` are byte-identical, which is the check that matters. This branch added write-site captures the corpus never had — `@reference.write. property-key` (R2-1b record construction) and the destructured-read rules — so write sites reach receiver resolution for the first time, and 11 of them have a receiver that does not resolve. A drop is the honest outcome for those; the alternative is the name-inferred guess this series spent three rounds bounding. Verified it is NOT caused by this session's review fixes before re-baselining: removing the `memberNotOnShape` site-claim added in `69047086` and re-running gives the identical 129 -> 140 / write: 11 drift, so the movement predates today and belongs to the capture work, exactly as the arithmetic above says. The sibling `scope-emission` guard still PASSES untouched, and the fingerprint guard passes after `20a937f4` — so all three arms of the benchmarks job are green locally. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> * fix(routes): track boolean polarity in dispatch guards, so a negated condition cannot invent a route Reproduced exactly as reported. `dispatch-guard.ts` refuses to inherit a verb from an `if` whose `else` branch holds the comparison — the module's own doc comment explains why: that branch runs precisely when the condition did NOT hold, so attributing it is backwards. `!` is the same fact written as an operator, and it was not handled. A stated invariant with half an implementation, which is worse than an absent one, because the comment reads as though it were covered. Measured against the real extractor before fixing: if (!(pathname === '/api/admin')) -> '' /api/admin INVENTED if (!(req.method === 'GET') && pathname === '/x') -> GET /x INVERTED if (!(req.method === 'POST' && pathname === '/w')) -> POST /w BOTH And the review is right that this is not additive-only. Driven through the real pipeline with a policy module that serves nothing plus a one-line route table, the invented `GET /api/report` collected into `verbedUrls` and `reconcileDispatchGuardRoutes` then EVICTED the true verb-less route for that path. A false route deleted a real one. After the fix that repo yields exactly one route, verb-less, path intact. Parity, not presence: `!!x` is `x`, so counting negations and testing the parity is the only rule that keeps a doubly-negated guard working. A negated VERB drops to verb-less rather than dropping the route — `!(method === 'GET')` means every method except GET, which no single value expresses, while the path evidence is untouched. Applies to the regex arm too; `!/^\/api\/x$/.test(pathname)` had the identical hole. Deliberately NOT keeping the `statement_block` break from the suggested patch. It is unreachable — the `!` in `if (!cond) { … }` lives in the condition, a SIBLING of the block, never an ancestor of anything inside it, and the only shape that puts a `!` above a block is an IIFE, which the function-boundary stop catches first. Unreachable in the UNSAFE direction, too: breaking early under-counts negations, and an under-count reads a negated guard as positive and invents the route. Verified by mutation — with the break present, deleting it fails nothing; the other three guards each fail a test when removed. Six new cases, all previously absent (`grep -c '!(' ` over both test files was 0, and the only negation covered was `!==`, the form that already worked). Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> * test(bench): re-baseline the emit-persistence byte-identity fingerprint for the isDetail column The third bench guard this branch left red, and the one the earlier rebaseline pass missed: the `benchmarks (GITNEXUS_BENCH)` job has never succeeded once in eleven attempts, and since step 11 aborts the job, the two steps after it — the streaming PDG-emit guard and the cross-language pipeline benchmarks — have never executed at all. [emit-persistence --check] FAIL: byte-identity fingerprint drift (got 4ee15e74…, expected 69e9182a…) Cause is this branch's own `isDetail` BOOLEAN on the Property table (PROPERTY_SCHEMA), which `streamAllCSVsToDisk` writes as one more header field and one more cell per Property row. Verified header-only rather than regenerated on faith. Dumping every CSV the bench emits on both `origin/main` and this branch and diffing them per file (name, byte length, sha256): the file set is identical at 35 CSVs, 34 of the 35 are byte-identical, and the sole difference is property.csv growing 68 -> 77 bytes as the header gains `,isDetail`. The synthetic graph mints no Property nodes, so not one data row moved — which is the thing this fingerprint exists to catch. Both timing gates were green throughout (scaling_ratio 0.783 against a 1.8 budget, elapsed_ms_large 229ms against the 1000ms backstop), so no throughput claim is being rebaselined away. Justification recorded in a `_rebaselined_<reason>` key, the convention bench/scope-capture/baselines.json already sets, and the note now says so explicitly so the next regeneration records its reasoning too. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01BCptYZWRgnnJ821rzebQyj * perf(processes): build each trace key once, not once per comparison `deduplicateTraces` held its `join('->')` inside the `some()` callback, so every already-kept trace had its key rebuilt from scratch against every candidate: O(TU) joins of O(depth id-length) characters. The allocation, not the substring scan, is what the pass spends its time on. Nothing about breadth-first search made that safe. It only hid the cost by keeping traces short — measured on this repo the walk averaged 4.3 steps before D1 and 9.4 after, which roughly doubles both the number of surviving traces and the length of every key, so the same quadratic that was affordable under BFS is about six times the work under DFS. That is the whole of the slowdown D1 was carrying; the depth-first walk itself is cheaper than the queue it replaced (`pop()` against an O(frontier) `shift()`), and its frontier is bounded by depth rather than by breadth. Hoisting the join into a `uniqueKeys` array removes the multiplication. Measured back to back on one host, 5 reps, 25k callables, production sink path (main -> this branch before -> this branch after): deep_chain 876.8ms -> 1233.1ms -> 101.9ms mixed_cycles 731.4ms -> 1130.6ms -> 132.8ms shallow_wide 572.5ms -> 531.8ms -> 49.6ms and on the real gitnexus/src corpus (11,490 symbols) process detection goes 204ms -> 89ms against main, having been slower than main before. Output is unchanged, which is the property that matters here: swapping the file back and forth and diffing every non-timing field across all sixteen shape x scale x sink-variant configurations gives no difference, and the real corpus returns the same 936 processes / 4,648 steps either way. Sink keys are pushed alongside the traces they belong to, so the comparison set is the same set it always was. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01BCptYZWRgnnJ821rzebQyj * fix(processes): type the parse-output read as ParseOutput The R3-6 sink read declared its own structural shape for the parse output instead of naming `ParseOutput`, which made it the only one of the five parse consumers in the repo not bound to the real type — cross-file.ts, orm.ts, routes.ts and tools.ts all pass the type argument. `getPhaseOutput` is a raw `as T` cast, so a local shape checks nothing at runtime and only severs the compile-time link: renaming `allFetchCalls` on `ParseOutput` would still compile here and silently detect zero sinks forever. Verified with a real `tsc --noEmit --strict` run over exactly that rename — the typed consumers error, this one did not. The runtime `.filter` stays, since it is the only thing actually guarding the cast. Also brings the phase docblock back in line with the deps array, which was missing `structure` (pre-existing) and `parse` (added by this branch), and records the two parse fields the phase now reads. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01BCptYZWRgnnJ821rzebQyj --------- Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com> Co-authored-by: Gergő Magyar <gergomagyar@icloud.com> Co-authored-by: Gergo Magyar <gergomagyar0@gmail.com>		2026-08-08 09:58:14 +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	chore(deps): bump docker/login-action from 4.4.0 to 4.6.0 (#2851 )	2026-08-06 08:19:19 +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	feat: close reported graph blind spots in reference resolution, analyze and storage (#2856 )	2026-08-08 09:58:14 +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	feat: close reported graph blind spots in reference resolution, analyze and storage (#2856 )	2026-08-08 09:58:14 +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