mirror of
https://github.com/abhigyanpatwari/GitNexus.git
synced 2026-08-28 05:25:25 +00:00
545 lines
64 KiB
Markdown
545 lines
64 KiB
Markdown
# Architecture — GitNexus
|
||
|
||
Monorepo: **CLI/MCP** (`gitnexus/`) + **browser UI** (`gitnexus-web/`).
|
||
|
||
## Repository layout
|
||
|
||
| Path | Role |
|
||
| --------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
|
||
| `gitnexus/` | npm package `gitnexus`: CLI, MCP server (stdio), HTTP API, ingestion pipeline, LadybugDB graph, embeddings. |
|
||
| `gitnexus-web/` | Vite + React thin client: graph explorer + AI chat. All queries via `gitnexus serve` HTTP API. |
|
||
| `gitnexus-shared/` | Shared TypeScript types and constants (consumed by CLI and Web). |
|
||
| `.claude/`, `gitnexus-claude-plugin/`, `gitnexus-cursor-integration/` | Agent skills and plugin metadata. |
|
||
| `eval/` | Evaluation harnesses for benchmarking tool usage. |
|
||
| `.github/` | CI workflows + composite actions (`setup-gitnexus/`, `setup-gitnexus-web/`). |
|
||
|
||
## End-to-end flow: index → graph → tools
|
||
|
||
1. **Ingestion** — `analyze.ts` → `runFullAnalysis` (`run-analyze.ts`) → `runPipelineFromRepo` (`pipeline.ts`). The default DAG of 19 phases builds a `KnowledgeGraph` in memory, then loads into LadybugDB under `.gitnexus/`. Repo registered in `~/.gitnexus/registry.json` for MCP discovery.
|
||
|
||
2. **Persistence** — `repo-manager.ts` (paths, registry, LadybugDB cleanup). `lbug-adapter.ts` (graph load, queries, embedding batches).
|
||
|
||
3. **Query layer** — three interfaces to the same backend:
|
||
- **MCP (stdio):** `mcp.ts` → `LocalBackend` → tools (`tools.ts`) + resources (`resources.ts`)
|
||
- **HTTP bridge:** `serve.ts` → Express (`api.ts`, `mcp-http.ts`) for web UI
|
||
- **CLI direct:** `gitnexus query|context|impact|cypher` in `tool.ts`
|
||
|
||
4. **Staleness** — `staleness.ts` compares indexed `lastCommit` to `HEAD`, surfaces hints.
|
||
|
||
## MCP tools
|
||
|
||
| Tool | Purpose |
|
||
| ---------------- | ------------------------------------------------------------------------------------------------------------------------------ |
|
||
| `list_repos` | Discover indexed repos |
|
||
| `query` | Hybrid BM25 + vector search over the graph |
|
||
| `cypher` | Ad hoc Cypher against the schema |
|
||
| `context` | Callers, callees, processes for one symbol |
|
||
| `impact` | Blast radius (upstream/downstream) with risk summary |
|
||
| `detect_changes` | Map git diffs to affected symbols and processes |
|
||
| `rename` | Graph-assisted multi-file rename with `dry_run` preview |
|
||
| `api_impact` | Pre-change impact report for an API route handler |
|
||
| `trace` | Shortest directed path between two symbols (call + class-member edges); group-aware (`repo: "@<group>"`) for cross-repo traces |
|
||
| `route_map` | API route → handler → consumer mappings |
|
||
| `tool_map` | MCP/RPC tool definitions and handlers |
|
||
| `shape_check` | Response shape vs consumer property access mismatches |
|
||
| `explain` | Persisted taint findings (source→sink data flows) — needs `analyze --pdg` |
|
||
| `pdg_query` | Control/data dependence — CDG (`mode: controls`) / REACHING_DEF (`mode: flows`) — needs `analyze --pdg` |
|
||
| `group_list` | List repo groups or details for one group |
|
||
| `group_sync` | Rebuild group Contract Registry (`contracts.json`) and bridge graph |
|
||
|
||
`query`, `context`, and `impact` are group-aware: pass `repo: "@<groupName>"` (or `"@<groupName>/<memberPath>"` to scope to one member) plus optional `service: "<monorepo/path>"`. Group-mode `query` merges per-repo results via Reciprocal Rank Fusion; group-mode `impact` runs the local walk in the chosen member and fans out across boundaries via the Contract Bridge (`gitnexus/src/core/group/cross-impact.ts`). `trace` is also group-aware via `repo: "@<groupName>"` — but, unlike the others, it resolves `from`/`to` across **all** members (a `@<groupName>/<memberPath>` suffix is advisory for trace, not a scope); pass `from_uid`/`to_uid` to disambiguate a symbol name that occurs in more than one member.
|
||
|
||
Group-mode `trace` (`gitnexus/src/core/group/cross-trace.ts`) stitches a path that crosses repositories: it resolves `from`/`to` across all members, and when they live in different repos it joins the home-repo segment to the target-repo segment over a single `ContractLink` boundary (an HTTP consumer→provider link, joined on `Contract.symbolUid`), reported as a `CONTRACT_LINK` hop in `crossings[]`. The crossing is clamped to one boundary (`MAX_SUPPORTED_CROSS_DEPTH`, shared with cross-impact); deeper `crossDepth` is reported via `notes[]`. With `pdg: true` (experimental, opt-in), each boundary-adjacent segment is enriched with its intra-procedural REACHING_DEF data-flow when that repo was indexed with `--pdg` (reusing the same anchored `flows` query as `pdg_query`); data flow never crosses the repo boundary, and a missing PDG layer degrades to call-level hops with a note. Two stores meet only at the `symbolUid` grain — the per-repo PDG/call graph and the group bridge — so this is the documented join; full cross-program (SDG-like) data flow across the boundary remains deferred (see `docs/plans/2026-06-18-002-feat-unified-pdg-impact-evaluation-plan.md`). The previously-planned `group_query`, `group_context`, `group_impact`, `group_contracts`, `group_status` MCP tools are intentionally not introduced — group-level state is exposed via resources instead:
|
||
|
||
| Resource URI | Purpose |
|
||
| ----------------------------------- | -------------------------------------------------------- |
|
||
| `gitnexus://group/{name}/contracts` | Contract Registry (provider/consumer rows + cross-links) |
|
||
| `gitnexus://group/{name}/status` | Per-member index + Contract Registry staleness |
|
||
|
||
## Where to change what
|
||
|
||
| Concern | Start in |
|
||
| ------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ |
|
||
| CLI commands/flags | `src/cli/` (`index.ts`, per-command modules) |
|
||
| Parsing/graph construction | `src/core/ingestion/pipeline-phases/` + `pipeline.ts` |
|
||
| Graph schema/DB | `src/core/lbug/` (`schema.ts`, `lbug-adapter.ts`) |
|
||
| MCP tools/resources | `src/mcp/server.ts`, `tools.ts`, `resources.ts` |
|
||
| Cross-repo groups (sync, contracts, `@<group>` routing) | `src/core/group/` (`service.ts`, `cross-impact.ts`, `sync.ts`, `bridge-db.ts`) |
|
||
| Search ranking | `src/core/search/` (BM25, hybrid fusion) |
|
||
| Embeddings | `src/core/embeddings/` + `src/core/run-analyze.ts` |
|
||
| Wiki generation | `src/core/wiki/` |
|
||
| Language support | `src/core/ingestion/languages/` + `tree-sitter-queries.ts` + `gitnexus-shared/src/languages.ts` |
|
||
| Import resolution | `src/core/ingestion/import-processor.ts` + `import-resolvers/configs/` + `model/resolution-context.ts` |
|
||
| Call resolution/inheritance/MRO | `src/core/ingestion/scope-resolution/` (pipeline, passes, graph-bridge) |
|
||
| Type extraction | `src/core/ingestion/type-extractors/` |
|
||
| Worker pool | `src/core/ingestion/workers/` |
|
||
| Web UI | `gitnexus-web/src/` |
|
||
| CI | `.github/workflows/*.yml`, `.github/actions/` |
|
||
|
||
> Paths above are relative to `gitnexus/` unless they start with `gitnexus-web/` or `.github/`.
|
||
|
||
---
|
||
|
||
## Pipeline Phase DAG
|
||
|
||
19 default phases are defined in `gitnexus/src/core/ingestion/pipeline-phases/`, each with explicit `deps` and typed output. `--pdg` adds `taintSummaries` and `callSummaries` (21 total).
|
||
|
||
```
|
||
scan → structure → [springConfig, markdown, cobol] → parse → [routes, tools, orm]
|
||
→ crossFile → scopeResolution → [springAutoConfiguration, springAop]
|
||
→ pruneLocalSymbols → mro → springAopInheritance → di → communities → processes
|
||
```
|
||
|
||
| Phase | File | Deps | Output |
|
||
| ------------------------- | -------------------------------------- | ------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||
| `scan` | `scan.ts` | (root) | File paths + sizes |
|
||
| `structure` | `structure.ts` | `scan` | File/Folder nodes, CONTAINS edges, `allPathSet` |
|
||
| `springConfig` | `spring-config.ts` | `structure` | Spring configuration-property nodes and metadata |
|
||
| `markdown` | `markdown.ts` | `structure` | Section nodes, cross-link edges from .md/.mdx |
|
||
| `cobol` | `cobol.ts` | `structure` | COBOL program/paragraph/section nodes (regex, no tree-sitter) |
|
||
| `parse` | `parse.ts` + `parse-impl.ts` | `structure`, `markdown`, `cobol` | Symbol nodes, IMPORTS/CALLS/EXTENDS edges, extracted routes/tools/ORM queries |
|
||
| `routes` | `routes.ts` | `parse` | Route nodes + HANDLES_ROUTE edges (Next.js, Expo, PHP, decorators, and JS/TS static route sources — see below) |
|
||
| `tools` | `tools.ts` | `parse` | Tool nodes + HANDLES_TOOL edges |
|
||
| `orm` | `orm.ts` | `parse` | QUERIES edges (Prisma, Supabase) |
|
||
| `crossFile` | `cross-file.ts` + `cross-file-impl.ts` | `parse`, `routes`, `tools`, `orm` | Cross-file type propagation in topological import order |
|
||
| `scopeResolution` | `scope-resolution/pipeline/phase.ts` | `parse`, `crossFile`, `structure` | Binding/reference + inheritance edges; disposes BindingAccumulator |
|
||
| `springAutoConfiguration` | `spring-auto-configuration.ts` | `structure`, `scopeResolution` | DECLARES and CONDITIONAL_ON metadata for Spring configuration candidates |
|
||
| `springAop` | `spring-aop.ts` | `scopeResolution` | Direct declarative/advice ADVISED_BY edges and pointcut evidence |
|
||
| `pruneLocalSymbols` | `prune-local-symbols.ts` | `scopeResolution` | Drops inert block-local `Const`/`Variable`/`Static` nodes (only a `File→DEFINES` edge) post-resolution |
|
||
| `mro` | `mro.ts` | `crossFile`, `scopeResolution`, `pruneLocalSymbols`, `structure` | METHOD_OVERRIDES + METHOD_IMPLEMENTS edges |
|
||
| `springAopInheritance` | `spring-aop.ts` | `springAop`, `mro` | Propagates declarative behavior through class/interface inheritance decisions |
|
||
| `di` | `di.ts` | `mro` | INJECTS edges from consumer Classes or factory Methods to provider Classes/declaration CodeElements (framework-neutral DI resolution; per-language matchers registered in `di-extractors/`) |
|
||
| `communities` | `communities.ts` | `mro`, `pruneLocalSymbols`, `structure` | Community nodes + MEMBER_OF edges (Leiden algorithm) |
|
||
| `processes` | `processes.ts` | `communities`, `routes`, `tools`, `pruneLocalSymbols`, `structure` | Process nodes + STEP_IN_PROCESS edges |
|
||
|
||
**Non-phase files in the same directory:** `parse-impl.ts`, `cross-file-impl.ts` (implementation), `wildcard-synthesis.ts` (whole-module import expansion), `types.ts`, `runner.ts`, `index.ts`.
|
||
|
||
### DAG runner
|
||
|
||
`runner.ts` — static phase graph, no plugins, compile-time type safety.
|
||
|
||
1. **Validation** — Kahn's topological sort. Rejects on: duplicate names, missing deps, cycles (DFS traces the concrete cycle path, e.g., `A -> B -> C -> A`, plus count of transitively blocked dependents).
|
||
|
||
2. **Execution** — sequential in topological order. Each phase receives:
|
||
- `ctx: PipelineContext` — shared mutable `KnowledgeGraph`, `repoPath`, progress callback, options
|
||
- `deps: ReadonlyMap<string, PhaseResult>` — **declared deps only** (runner filters the results map to prevent hidden coupling)
|
||
|
||
3. **Error handling** — wraps phase errors with the phase name, emits terminal `error` progress event, swallows progress handler errors to preserve the original cause.
|
||
|
||
4. **Timing** — per-phase `durationMs` in `PhaseResult`, dev-mode console logging.
|
||
|
||
**Design patterns:**
|
||
|
||
- **Single graph accumulator** — all phases mutate the same `KnowledgeGraph` in `ctx`; the graph is the primary output.
|
||
- **Typed phase access** — `getPhaseOutput<T>(deps, 'name')` for type-safe upstream results.
|
||
- **Binding accumulator lifecycle** — created in `parse`, disposed by `crossFile` (in `finally`). No other phase should take ownership.
|
||
- **Skippable phases** — `skipGraphPhases` omits MRO/di/communities/processes (faster tests); `pruneLocalSymbols` still runs (it is graph cleanup, not analysis). `skipWorkers` is no longer a sequential escape hatch — it (like `--workers 0` / `GITNEXUS_WORKER_POOL_SIZE=0`) is rejected with an actionable error, since the worker pool is the sole parse path (§ Chunked parse-and-resolve).
|
||
- **Local-symbol pruning** — `pruneLocalSymbols` removes inert block-local value symbols after scope resolution has consumed them. Opt out per-call with `PipelineOptions.keepLocalValueSymbols` or globally with the `GITNEXUS_KEEP_LOCAL_VALUE_SYMBOLS` env var.
|
||
|
||
### How to add a new phase
|
||
|
||
1. Create `pipeline-phases/my-phase.ts` with a `PipelinePhase<MyOutput>` (name, deps, execute)
|
||
2. Export from `pipeline-phases/index.ts`
|
||
3. Add to `buildPhaseList()` in `pipeline.ts`
|
||
|
||
```typescript
|
||
import type { PipelinePhase, PhaseResult } from './types.js';
|
||
import { getPhaseOutput } from './types.js';
|
||
import type { ParseOutput } from './parse.js';
|
||
|
||
export interface MyPhaseOutput {
|
||
/* ... */
|
||
}
|
||
|
||
export const myPhase: PipelinePhase<MyPhaseOutput> = {
|
||
name: 'myPhase',
|
||
deps: ['parse'],
|
||
async execute(ctx, deps) {
|
||
const { allPaths } = getPhaseOutput<ParseOutput>(deps, 'parse');
|
||
// ... write to ctx.graph ...
|
||
return {
|
||
/* typed output */
|
||
};
|
||
},
|
||
};
|
||
```
|
||
|
||
### Where routes come from
|
||
|
||
`route-extractors/` holds four independent ways a route can be discovered, all
|
||
converging on the routes phase's `(method, url)` registry:
|
||
|
||
| Source | Shape | Examples |
|
||
| --- | --- | --- |
|
||
| Filesystem convention | path → URL, no parsing | Next.js `app/`, Expo, PHP |
|
||
| Single-file framework route | `isRouteFile` + worker extraction | Laravel `routes/*.php` |
|
||
| Cross-file framework route | `discoverRootRouteFiles` + `extractRoutes` | Django `urlpatterns` |
|
||
| AST-level route in a normal file | `extractDecoratorRoutes` | Spring, FastAPI, NestJS (`@Controller` + `@Get`/`@Post`/…; URLs are controller-relative — `setGlobalPrefix` and URI versioning live in the bootstrap file and are not applied), **JS/TS dispatch guards and static data route tables** |
|
||
|
||
The last row is the one whose name undersells it. A route is DECLARED by a
|
||
decorator, but it can also be **inferred** from a raw `node:http` server's own
|
||
dispatch — `if (req.method === 'GET' && pathname === '/api/x')` is a route with
|
||
a path, a verb and a handler, and nothing else in the pipeline could see it.
|
||
`route-extractors/dispatch-guard.ts` reads that shape; the transport, dedup and
|
||
handler resolution are shared with decorator routes, and
|
||
`ExtractedDecoratorRoute.source` carries the provenance difference through to
|
||
the `HANDLES_ROUTE` edge.
|
||
|
||
JS/TS data route tables share that transport when a route-named array contains
|
||
direct object literals with static `path`, `method`, and `handler` fields and a
|
||
same-scope `for...of` dispatcher positively compares the path and method before
|
||
directly invoking the handler. Dynamic values, computed keys, spreads,
|
||
inline/called handlers, unknown verbs, and ambiguous handler bindings are
|
||
suppressed. Bare import aliases and single-level member handlers are attributed
|
||
only through declared import and owner provenance; an unproven receiver never
|
||
falls back to a global name guess.
|
||
|
||
That extractor is deliberately **precision-weighted**: `route_map` presents its
|
||
output as fact, so a `startsWith` namespace test, a bare `pathname === '/'`
|
||
without a verb, and any regex it cannot translate exactly are all dropped rather
|
||
than guessed at. A missing route is a coverage limit; an invented one is a lie.
|
||
|
||
Two rules there need more than one comparison to decide, and are worth knowing
|
||
about before changing either:
|
||
|
||
- **Same-file constant folding.** `` pathname === `${basePath}/rules` `` is
|
||
common enough that refusing it loses whole route modules — and loses them
|
||
invisibly, since a module with unfoldable paths and a module with no routes
|
||
produce the same empty answer. Folding is same-file, string literals only, one
|
||
alias hop, and refuses on ambiguity (a name declared twice with different
|
||
values is dropped, never guessed).
|
||
- **Whole-repo reconciliation** (`reconcileDispatchGuardRoutes`, applied in the
|
||
routes phase). A split route table — one module listing every path it
|
||
recognises so the dispatcher can 404 early, handlers in others — otherwise
|
||
lists every route twice, once verb-less with the table as its "handler". It
|
||
applies to dispatch-guard routes only: a framework route with no verb is
|
||
method-agnostic *by declaration*, which is a fact, not a weaker observation.
|
||
|
||
---
|
||
|
||
## Semantic model
|
||
|
||
`SemanticModel` (`gitnexus/src/core/ingestion/model/semantic-model.ts`) is the authoritative store for every symbol-indexed lookup (by `nodeId`, `simpleName`, `qualifiedName`, or `filePath`). The scope-resolution pipeline reads from here: `findOwnedMember`, `pickOverload`, and `findExportedDefByName` all consult `model.methods` / `model.fields` / `model.symbols`.
|
||
|
||
`ParsedFile` (`gitnexus-shared/src/scope-resolution/parsed-file.ts`) is the single per-file artifact the scope-resolution pipeline consumes. Scope-resolution passes MUST NOT build a parallel parse representation. If a per-language hook needs AST-level facts that `ParsedFile` doesn't expose, it should reuse the orchestrator's `treeCache` (`RunScopeResolutionInput.treeCache`) rather than re-invoking `parser.parse(...)` on its own — the C# `populateNamespaceSiblings` hook is the reference implementation of this pattern.
|
||
|
||
The scope-resolution pipeline additionally carries `WorkspaceResolutionIndex` for `Scope`-valued lookups (`classScopeByDefId`, `moduleScopeByFile`) that `SemanticModel` structurally cannot hold. No symbol-indexed duplicates exist outside `SemanticModel`.
|
||
|
||
**Write / read phase contract.** The model is mutable during three ordered phases and read-only afterward:
|
||
|
||
```
|
||
Phase 1: parse ──► symbolTable.add fans into types/methods/fields
|
||
Phase 2: scope-resolution ──► reconcileOwnership() registers corrected ownerIds
|
||
Phase 3: finalize ──► model.attachScopeIndexes(bundle) — one-shot freeze
|
||
─────────────────────────── phase boundary ───────────────────────────
|
||
Read phase: all resolution passes + MCP + HTTP + embeddings see
|
||
SemanticModel (read-only handle); writes are type-errors.
|
||
```
|
||
|
||
`runScopeResolution` narrows `MutableSemanticModel` → `SemanticModel` at the phase boundary so downstream passes physically cannot mutate the model even accidentally.
|
||
|
||
**Reconciliation pass.** `reconcileOwnership` (`scope-resolution/pipeline/reconcile-ownership.ts`) is a shim for languages whose parse-time extractor doesn't resolve `enclosingClassId` at parse time (Python class-body methods are the canonical case). It walks `parsed.localDefs[i].ownerId` after `populateOwners` and registers any missed methods/fields into the model. Idempotent — safe to re-run, safe alongside languages whose extractor already carries `ownerId` (C#).
|
||
|
||
The architectural end state is for every language's parse-time extractor to emit the correct `ownerId` directly, making reconciliation a no-op (tracked as a follow-up refactor). The dev-mode validator `validateOwnershipParity` surfaces any drift via `onWarn` under `NODE_ENV !== 'production' && VALIDATE_SEMANTIC_MODEL !== '0'`.
|
||
|
||
References: `semantic-model.ts` file-head (full write/read contract); `contract/scope-resolver.ts` Contract Invariant I9 (scope-resolution-side rule).
|
||
|
||
---
|
||
|
||
## Scope-Resolution Pipeline (RFC #909 Ring 3)
|
||
|
||
Language-agnostic scope-resolution resolver. This is the resolution path for every language — it owns CALLS/ACCESSES/USES emission and inheritance edges. Adding a language is one interface implementation (`ScopeResolver`) plus one registration in the `SCOPE_RESOLVERS` map — no changes to shared code, no new pipeline phase. (RING4-1 #942 removed the legacy call-resolution DAG and the per-language `MIGRATED_LANGUAGES` flag, so `SCOPE_RESOLVERS` registration is all that's needed.)
|
||
|
||
### Pipeline stages
|
||
|
||
```
|
||
ParsedFile[] (extractParsedFile per file)
|
||
│ finalizeScopeModel (+ provider hooks)
|
||
▼
|
||
ScopeResolutionIndexes
|
||
│ resolveReferenceSites (via MethodRegistry.lookup)
|
||
▼
|
||
ReferenceIndex
|
||
│ emitReceiverBoundCalls ── FIRST
|
||
│ emitFreeCallFallback ── THEN
|
||
│ emitReferencesViaLookup ── uses handledSites + deferred-site skip set
|
||
│ emitPropertyDispatchCalls ── registration USES + conservative CALLS
|
||
│ emitCallableValueFlow ── assigned/passed callable invocation CALLS
|
||
│ emitImportedValueReferences ── cross-file value reads via finalized imports
|
||
│ emitUniqueNamePropertyAccesses ── LAST-RESORT property reads by name,
|
||
│ narrowed same-file → direct-import, refusing to choose otherwise
|
||
│ emitImportEdges
|
||
▼
|
||
KnowledgeGraph (IMPORTS / CALLS / ACCESSES / INHERITS / USES)
|
||
```
|
||
|
||
Orchestrator: `runScopeResolution(input, provider)` in `scope-resolution/pipeline/run.ts`.
|
||
Pipeline phase: `scopeResolutionPhase` in `scope-resolution/pipeline/phase.ts` — iterates the registered `SCOPE_RESOLVERS` over the worker-serialized `ParsedFile`s. (Per-language `emitScopeCaptures` hooks may reuse a cached Tree via the orchestrator's `treeCache`, but in worker-pool runs that cache is empty — Trees can't cross MessageChannels — so they consume the pre-extracted `ParsedFile` instead; § Performance notes.)
|
||
|
||
### Callable-value flow
|
||
|
||
First-class callable values use a language-neutral inclusion analysis in `passes/callable-value-flow.ts`. Providers recognize their own syntax and emit JSON-safe `CallableFlowSite` facts (`seed`, `copy`, `alias`, `address`, `load`, `store`, `formal`, `argument`, and `invoke`) into `ParsedFile`; shared ingestion never branches on a language name. These always-on facts cross workers and the durable parse store, whose schema is bumped whenever their semantic shape changes.
|
||
|
||
The emit stage defers only invocation sites proven to reference a flow cell. Ordinary receiver/free/reference passes still resolve direct callees first and record exact callee IDs by file/line/column. Property dispatch then runs before callable flow because a property-dispatched wrapper call can seed actual-to-formal propagation. The callable solver consumes those direct targets, propagates callable sets through lexical cells and formals, and emits `CALLS` at the real indirect invocation site with reason `callable-value-flow` (confidence 0.8 for a singleton, 0.7 for a bounded multi-target set).
|
||
|
||
The solver is flow-insensitive but bounded: dependency-indexed work items rerun only when a cell they read changes; target/address sets cap at 32; a hostile fact graph has a finite work budget; overflow or budget exhaustion emits no partial `CALLS` and produces a structured warning. Lexical shadowing is function/block aware, invocation/constructor results are not reinterpreted as callable designators, and overload selection uses provider-supplied signature metadata. C/C++ additionally associate visible prototypes with unique definitions so actual-to-formal flow crosses translation units; the provider-owned `hasFileLocalCallableLinkage` hook prevents `static` declarations or definitions from leaking across files. C++ member-function pointers preserve parameter/cv shape, keep non-virtual targets exact, and expand virtual targets through `MethodDispatchIndex`/MRO.
|
||
|
||
Property-key dispatch remains a separate conservative fallback. Its per-key fan-out cap is 32; capped keys synthesize no partial calls and are reported at warning level with language, skipped-key count, dropped key names (bounded), and cap; the count also travels in `RunScopeResolutionStats.propertyDispatchSkippedKeys`.
|
||
|
||
Interface-dispatch fan-out walks the subtype closure of the receiver's interface and is **generic-instantiation aware** (#2912): a call through `IValidator<string>` must not reach an implementor of `IValidator<int>`, which shares its declaration and therefore its subtype list. Each heritage clause's arguments reach resolution by one of three routes — read off the `@reference.inherits` anchor's own spelling where that anchor spans the whole base (most languages, no query change), through the `@reference.type-arguments` sub-tag where the anchor is the bare name and moving it would renumber inheritance edge ids (Rust `impl T<A> for S`, Dart `extends`), or on a heritage MARKER payload for clauses that never become reference sites (Dart `implements`/`with`). Whichever pass emits the edge records the pair through one sink: `preEmitInheritanceEdges` for heritage clauses, `ScopeResolver.emitHeritageEdges` for the rest.
|
||
|
||
The walk then carries a substitution: a subtype's own type parameters bind to the receiver's arguments, so `class Wrapper<T> : IValidator<T>` stays reachable from every instantiation while `class IntValidator : IValidator<int>` is pruned from the `string` one. Receiver arguments come from the declared type (Case 4), a class-level field's declared type (Case 6), or — for a compound receiver such as `this._repo` — the spelling the compound fold typed that position from, reported back through `recordReceiverType` and accepted only when it names the class the fold returned.
|
||
|
||
The filter prunes only on positive evidence: an unknown instantiation on either side, an argument list whose arity does not line up, a name that may be a type variable the language's captures never recorded, or an unresolved spelling whose simple name matches all keep the target. A type parameter of the declaration ENCLOSING either side is recognised as such and never compared — `void Run<T>(IValidator<T> v)` writes a receiver with no known instantiation, so it keeps the unfiltered fan-out. That recognition is what generic METHODS now carry `@declaration.type-parameters` for in C#, Java and Kotlin (TypeScript already did): without it an unbounded `T` grounds to nothing and a bounded one grounds to its BOUND, and both compare unequal to an implementor's concrete argument. Languages that capture neither type arguments nor type parameters therefore emit exactly the pre-#2912 fan-out. The fan-out cap (32, `GITNEXUS_MAX_INTERFACE_DISPATCH_FANOUT`) and its skipped-target reporting are unchanged and apply after filtering. Note the fan-out itself still fires only for a receiver whose folded type is an `Interface` symbol, so a Rust `Trait` or a Dart abstract `Class` receiver emits no secondary targets to filter in the first place.
|
||
|
||
Standalone (regex-based) providers such as COBOL participate via `ScopeResolver.scopeResolutionEdgeMode: 'callable-flow-only'`: `runScopeResolution` runs for them, but every ordinary emission path — heritage, interface implementations, receiver-bound, free-call fallback, reference/import edges, post-resolution hooks — is gated off, so their legacy phase (e.g. `cobolPhase`) remains the sole owner of structural edges and the callable solver's `CALLS` are purely additive. A callable-flow-only provider whose files emitted no callable facts exits early, before finalize, keeping the opt-in proportional to source scanning.
|
||
|
||
### Receiver chains and the drop census (#2766)
|
||
|
||
A compound receiver (`svc.getUser().address.save()`) is captured as a compact string on `ReferenceSite.receiverChain`. `utils/receiver-chain-codec.ts` is the ONE encoder/decoder — capture emitters, the scope-resolution fold, and the durable ParsedFile store all import it rather than hand-rolling the format.
|
||
|
||
Wire format is **v2**: `2|<base>|<step>|<step>…`, one-character version prefix, then base-first steps, each a one-character kind sigil plus the member name (`c` = call, `f` = field). `a` (await) and `i` (index) are **name-free** and encode as a bare sigil — an awaited call's name already lives on its `c` step, and a subscript key is a value, not a lookup-able identifier. The version went 1 → 2 when those two kinds were added, and a decoder REFUSES a foreign version rather than decoding the prefix it understands: a chain missing its await/index hop decodes cleanly as a different, shorter chain and would type the receiver against the wrong member. The format is unescaped (`|` and `~` cannot occur in an identifier), so an unencodable name is refused rather than escaped, and the payload is capped at `MAX_RECEIVER_CHAIN_BYTES` / `MAX_CHAIN_DEPTH` steps. Because these strings live in the incremental parse cache and the durable ParsedFile store, a format change requires a `PARSE_CACHE_VERSION` schema bump — a stale cache would otherwise replay v1 chains this build discards.
|
||
|
||
Receivers the resolver could not type are not silently dropped. Each records a `ResolutionOutcome` (`scope-resolution/resolution-outcome.ts`) carrying the receiver's *shape* (`classifyReceiverShape`: `chain-call` / `chain-field` / `chain-mixed` / `chain-unwrap` / `no-chain` — the bench censuses these) and its *origin* (`in-program` / `external` / `unknown`). `scope-resolution/unresolved-receivers.ts` aggregates them per member name into the index-persisted `unresolvedReceiverMembers` summary, keeping in-program and external counts under separate keys. Only in-program drops make a count short: an external-rooted call (`System.out.println`, `fetch(...)`) has no in-graph node an edge could have reached, so it is reported but does not hedge. `impact` / `context` read that summary and publish `epistemic: 'exact' | 'lower-bound'`, prose `boundaries`, and the machine-readable `causes` split (`EpistemicCauses` in `mcp/local/local-backend.ts`).
|
||
|
||
### Optional CFG/PDG emission (`--pdg`, #2081–#2086)
|
||
|
||
On a `--pdg` run the parse worker builds a per-function control-flow graph from the tree-sitter AST (`LanguageProvider.cfgVisitor`; TypeScript/JavaScript today) and serializes it onto `ParsedFile.cfgSideChannel` as plain data. Scope-resolution then emits the program-dependence layers from that side-channel **inside Phase 4 of `runScopeResolution`, while the disk-backed ParsedFile store is still live** — the only window where the worker-built CFGs are loaded (the store is cleared right after the phase returns). A standalone post-`mro` phase would read an empty store, so the emit deliberately lives in-phase, mirroring the `applyCaptureSideChannel` pattern. The opt-in is off by default (graph byte-identical), folded into the parse-cache key (a pdg-off warm cache is never reused on a `--pdg` run), and each layer is bounded by a per-function edge cap that logs any dropped edges. All layers are `BasicBlock → BasicBlock` edges in the single `CodeRelation` table, keyed by `type`; there is **no** `Function → BasicBlock` edge — the symbol↔block join is reconstructed from the BasicBlock id prefix + line span. The layers build on each other:
|
||
|
||
- **M1 — CFG** (#2081): `BasicBlock` nodes + `CFG` edges. Edge _kind_ (`seq`/`cond-true`/`loop-back`/…) rides the `reason` column (CFG is one `CodeRelation` type, not one per kind).
|
||
- **M2 — REACHING_DEF** (#2082): GEN/KILL def→use data dependence from a pure fixpoint solver; the variable name rides `reason`.
|
||
- **M3/M4 — TAINTED / SANITIZES / TAINT_PATH** (#2083–#2084): intra- and inter-procedural taint (source→sink) — the `explain` tool's data.
|
||
- **M5 — CDG** (#2085): Ferrante control dependence over a Cooper–Harvey–Kennedy post-dominator tree (the EXIT-rooted reverse CFG); branch sense (`'T'`/`'F'`) rides `reason`. A CFG whose EXIT is unreachable from some block is skipped for CDG (post-dominance would be unsound) while its CFG/REACHING_DEF layers are kept.
|
||
- **M6 — read surface** (#2086): the `pdg_query` MCP tool answers "what gates X?" (CDG, `mode: controls`) and "where does Y flow?" (REACHING_DEF, `mode: flows`); `explain` is the taint consumer. Both are always anchored + `LIMIT`-bounded (LadybugDB has no rel-property index) and share one `resolveBlockAnchor` helper. These PDG edge types are deliberately kept out of the default `VALID_RELATION_TYPES` / web schema.
|
||
- **Cross-repo trace enrichment**: group-mode `trace` (`pdg: true`) reuses the same anchored REACHING_DEF `flows` query to annotate a boundary-adjacent segment with how a value reaches the cross-repo call — strictly intra-procedural (data flow never crosses the repo boundary). See the group-aware tools note above.
|
||
|
||
See `core/ingestion/cfg/` (emit + the pure CFG / post-dominator / control-dependence / reaching-defs / taint passes) and `mcp/local/local-backend.ts` (`_pdgQueryImpl`, `_explainImpl`, the shared `resolveBlockAnchor`).
|
||
|
||
### `ScopeResolver` contract
|
||
|
||
Single interface a language implements to plug into the pipeline. Contract fully documented in `scope-resolution/contract/scope-resolver.ts`.
|
||
|
||
| Hook | Purpose |
|
||
| ------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||
| `languageProvider` | Base `LanguageProvider` (tree-sitter query, `emitScopeCaptures`, import/binding interpreters, hooks) |
|
||
| `populateOwners(parsed)` | Fill deferred `ownerId` fields on method defs (captures can't always know the owning class at parse time) |
|
||
| `buildMro(graph, parsed, nodeLookup)` | Produce `mroByClassDefId: Map<DefId, DefId[]>` — C3, Ruby-mixin, or first-wins per language |
|
||
| `resolveImportTarget(target, fromFile, allFiles)` | `(rawImportPath, sourceFile) → targetFilePath` (PEP-328 for Python, etc.) |
|
||
| `isNamespaceImport(parsedImport, targetFile, fromFile)` | Optionally reclassify a resolved named import as a namespace handle when the imported symbol is itself a module |
|
||
| `mergeBindings(existing, incoming, scopeId)` | Shadowing / LEGB precedence |
|
||
| `arityCompatibility` | Provider consumed by registry during `MethodRegistry.lookup` Step 2 |
|
||
| `importEdgeReason` | Confidence-tier string for IMPORTS edge reason field |
|
||
| `propagatesReturnTypesAcrossImports?` | Opt out of cross-file return-type propagation (default on) |
|
||
| `fieldFallbackOnMethodLookup?` | Statically-typed languages turn this OFF — the heuristic over-connects (default on) |
|
||
| `elementTypeOf?` | `(containerType, via: {kind:'index'} \| {kind:'accessor',name}) → elementType \| undefined` — element type of a container, reached by subscript (`repos[0]`) or by a property-style collection view (`data.Values`). ONE hook for both routes (it replaced the split `unwrapCollectionAccessor` / `unwrapCollectionElement`, where implementing one silently answered nothing for the other). Consulted only where the source actually performed the access — never as a general type-name normalizer |
|
||
| `stripTypePreservingDecoration?` | `(typeName) → strippedName \| undefined` — strip ONE layer of TYPE-PRESERVING decoration (pointer, reference, `const`, nullable, borrow, sigil) so a receiver declared `*Host` still finds the `Host` binding (#2766). Never a container: unwrapping `Repo[]` here would fold `repos.find(x)` to `Repo.find` — that is `elementTypeOf`'s job, and only after a real subscript. Consulted only after every undecorated lookup fails, and only by receiver-chain base/step resolution — default off |
|
||
| `collapseMemberCallsByCallerTarget?` | One CALLS edge per (caller, target) instead of per-site — default off |
|
||
| `populateNamespaceSiblings?` | Cross-file implicit visibility (compiler-implicit namespace sharing) — default off; ctx carries `treeCache` |
|
||
| `hoistTypeBindingsToModule?` | Walk up to Module scope when looking up a method's return-type typeBinding — default off; enable only when bindings are stored at module level |
|
||
| `hasFileLocalCallableLinkage?` | Precise internal-linkage predicate used only when joining callable declarations/prototypes to cross-file definitions; C/C++ use it for `static` free functions |
|
||
| `constructorCallTargetsClass?` | A constructor-form call `Type(...)` links to the Class def rather than its explicit Constructor def — default off; Swift and Dart opt in |
|
||
| `constructionSyntax?` | How the language spells construction, so an INLINE constructor receiver (`Service(db).m()`, `new Service(db).m()`, `Service.new.m()`) can be typed — `bare` / `keyword` / `selector`; default off, opt in per language only where measured to be needed (#2708) |
|
||
|
||
### Per-language registration
|
||
|
||
1. Implement `ScopeResolver` in `languages/<lang>/scope-resolver.ts`.
|
||
2. Add entry to `SCOPE_RESOLVERS` in `scope-resolution/pipeline/registry.ts`.
|
||
|
||
CI auto-discovers the set via `tsx`. No workflow edit required.
|
||
|
||
### Code references
|
||
|
||
| Module | Purpose |
|
||
| --------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
|
||
| `scope-resolution/contract/scope-resolver.ts` | `ScopeResolver` interface + shared types |
|
||
| `scope-resolution/pipeline/run.ts` | Generic orchestrator |
|
||
| `scope-resolution/pipeline/phase.ts` | Pipeline-phase wrapper (deps: `parse`, `structure`) |
|
||
| `scope-resolution/pipeline/registry.ts` | `SCOPE_RESOLVERS` map |
|
||
| `scope-resolution/passes/*.ts` | Reference-resolution passes (receiver-bound, free-call fallback, compound-receiver, MRO, cross-file return-type propagation) |
|
||
| `scope-resolution/graph-bridge/*.ts` | CLI-local translation from resolved references → `KnowledgeGraph` edges |
|
||
| `scope-resolution/scope/*.ts` | Generic scope-chain walkers + namespace targets |
|
||
| `scope-resolution/workspace-index.ts` | Build-once O(1) lookup index |
|
||
| `languages/python/index.ts` | Python `ScopeResolver` hooks + known-limitation docs |
|
||
| `languages/python/captures.ts` | `emitPythonScopeCaptures` (honors cross-phase Tree cache) |
|
||
| `languages/csharp/index.ts` | C# `ScopeResolver` hooks + known-limitation docs |
|
||
| `languages/csharp/captures.ts` | `emitCsharpScopeCaptures` (honors cross-phase Tree cache) |
|
||
| `languages/csharp/namespace-siblings.ts` | Cross-file implicit-namespace visibility hook (reads `treeCache`) |
|
||
|
||
### Performance notes
|
||
|
||
- **Cross-phase Tree cache**: the orchestrator's `treeCache` (`RunScopeResolutionInput.treeCache`) lets a scope-resolution per-language hook (`emitScopeCaptures`) reuse a tree instead of re-parsing. Workers leave it empty — Trees can't cross MessageChannels — so in normal (worker-pool) runs scope-resolution does NOT rely on it: workers serialize each file's `ParsedFile` (+ capture side-channel) and stream them in, so scope-resolution consumes the pre-extracted artifact rather than re-parsing on the main thread (§ Chunked parse-and-resolve). `PROF_SCOPE_RESOLUTION=1` emits hit/miss counters and a worker-engaged warning.
|
||
- **Typed relationship iteration**: heritage + MRO walk only the EXTENDS / IMPLEMENTS / HAS_METHOD edges via `iterRelationshipsByType`, not the full relationship map.
|
||
- **Workspace-resolution-index**: O(1) `findOwnedMember` / `findExportedDef` / `classScopeByDefId` built once per run.
|
||
- **Callable-value worklist**: dependency-indexed inclusion propagation is linear in a reverse-ordered copy-chain fixture; target/address sets cap at 32 and the whole worklist has a finite budget with no partial edge emission on exhaustion.
|
||
- **SCC-ordered cross-file return-type propagation** (PR #1050): `propagateImportedReturnTypes` walks `indexes.sccs` in reverse-topological order (leaves first), so multi-hop alias chains like `models.User → service.user → app.user` collapse to the terminal class in a single linear pass. Within each importer, the source module's `typeBindings` is chain-followed BEFORE mirroring (so we mirror terminal types, not intermediate refs), and the importer's own `typeBindings` is chain-followed AFTER mirroring (so local `const x = importedFn()` resolves before downstream importers run). Cyclic SCCs reach a partial fixpoint within a single pass without iterating to convergence — see the `ts-circular` cross-file-binding fixture which only asserts pipeline-no-throw. PROF output (`PROF_SCOPE_RESOLUTION=1`) splits `finalize` from `propagate` so quadratic regressions in the chain-follow surface independently.
|
||
|
||
---
|
||
|
||
## Language-agnostic graph feeding
|
||
|
||
16 languages → single unified graph. Four abstraction layers:
|
||
|
||
```
|
||
Unified Graph Schema (44 node types, 21 relationship types)
|
||
↑
|
||
Scope-Resolution Pipeline (registry lookup + 3-tier import resolution + MRO)
|
||
↑
|
||
Language Providers (import semantics, type config, export checker, MRO strategy)
|
||
↑
|
||
Tree-Sitter Queries (per-language S-expressions, unified capture tags)
|
||
```
|
||
|
||
### Language providers
|
||
|
||
Each language implements `LanguageProvider` (`language-provider.ts`). Key fields:
|
||
|
||
| Field | Purpose |
|
||
| ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||
| `id`, `extensions` | Language identity and file matching |
|
||
| `treeSitterQueries` | S-expression queries for AST extraction |
|
||
| `importSemantics` | `named` / `wildcard-leaf` / `wildcard-transitive` / `namespace` |
|
||
| `importResolver` | Language-specific path → file resolution |
|
||
| `exportChecker` | Public/exported symbol detection |
|
||
| `typeConfig` | Type annotation extraction rules |
|
||
| `mroStrategy` | `first-wins` / `c3` / `none` |
|
||
| `descriptionExtractor` | Optional hook returning a symbol's doc-comment text as its `description`; feeds the embedding metadata header so doc-only terms are semantically searchable (issue #2270). Most languages register `createLeadingDocDescriptionExtractor` (shared, language-neutral; per-language comment/wrapper config passed at the call site) |
|
||
| `definitionPropertiesExtractor` | Optional language-owned hook for structured, clone-safe definition metadata. Shared ingestion persists these properties opaquely; the owning provider supplies the extraction semantics. |
|
||
|
||
16 providers in `languages/index.ts` via `satisfies Record<SupportedLanguages, LanguageProvider>` — missing a language is a compile error.
|
||
|
||
### Unified capture tags
|
||
|
||
Per-language tree-sitter queries use different AST node names but produce the **same semantic capture tags**: `@definition.class`, `@definition.function`, `@call.name`, `@import.source`, `@reference.inherits`. Downstream extraction needs no language branching. Defined in `tree-sitter-queries.ts`.
|
||
|
||
### Import resolution
|
||
|
||
Per-language import resolution uses the **configs + factory** pattern (like call/method/class extractors). Each language declares an `ImportResolutionConfig` in `import-resolvers/configs/`, listing an ordered chain of `ImportResolverStrategy` functions. `createImportResolver()` (in `resolver-factory.ts`) composes them: first non-null result wins. Low-level helpers shared across strategies live alongside the configs in `import-resolvers/` (e.g. `go.ts`, `rust.ts`, `python.ts`).
|
||
|
||
Unified 3-tier algorithm (`model/resolution-context.ts`), per-language `importSemantics` controls which tier activates:
|
||
|
||
| Tier | Confidence | Mechanism |
|
||
| ----------------- | ---------- | ---------------------------------------------------------------------- |
|
||
| 1 — same-file | 0.95 | Symbol table for caller's file |
|
||
| 2 — import-scoped | 0.9 | `NamedImportMap` chains (named) or all files in `importMap` (wildcard) |
|
||
| 3 — global | 0.5 | O(1) index lookups: class, impl, callable. Fallback only |
|
||
|
||
| Import strategy | Languages | Behavior |
|
||
| --------------------- | ----------------------------------- | ---------------------------------------------- |
|
||
| `named` | TS, JS, Java, C#, Rust, PHP, Kotlin | Only explicitly imported names visible |
|
||
| `wildcard-leaf` | Go, Ruby, Swift, Dart | Whole-package import, no transitive re-exports |
|
||
| `wildcard-transitive` | C, C++ | `#include` closure chains through re-exports |
|
||
| `namespace` | Python | Module aliases resolved at call site |
|
||
|
||
### Chunked parse-and-resolve
|
||
|
||
`parse` processes files in ~20 MB byte-budget chunks to bound memory. Per chunk:
|
||
|
||
1. Worker pool dispatches files (the sole parse path — there is no sequential fallback; `skipWorkers`, `--workers 0`, and `GITNEXUS_WORKER_POOL_SIZE=0` are rejected with an actionable error)
|
||
2. Each worker: detect language → load grammar → run queries → return unified `ParseWorkerResult`
|
||
3. Synthesize wildcard bindings (`wildcard-synthesis.ts`)
|
||
4. Resolve imports
|
||
5. Collect `BindingAccumulator` entries for cross-file propagation
|
||
|
||
Inheritance edges are emitted later, by the scope-resolution phase (`preEmitInheritanceEdges` + `emitHeritageEdges`), not during `parse`.
|
||
|
||
Workers: `workers/worker-pool.ts`, `workers/parse-worker.ts`.
|
||
|
||
**Worker-serialized ParsedFiles (#2038).** To index very large repos (e.g. the Linux kernel) without OOM, the worker pool is the _sole_ parse path and workers serialize each file's `ParsedFile` (plus its capture side-channel) in parallel, streaming them to scope-resolution through a disk-backed store. Scope-resolution consumes the pre-extracted artifact instead of re-parsing every file on the main thread — tree-sitter's native input buffers are not GC-reclaimable, so the former main-thread re-parse leaked native memory until the process died. Pool creation is lazy / cache-miss-gated, so a warm all-cache-hit run replays cached worker output without spawning a worker (hence `usedWorkerPool` can be false even when the repo has parseable files).
|
||
|
||
### Inheritance and MRO
|
||
|
||
Inheritance is captured by the `@reference.inherits` tag and emitted by the scope-resolution phase: `preEmitInheritanceEdges` resolves each base in scope, then `emitHeritageEdges` writes the `EXTENDS`/`IMPLEMENTS` edges. The phase then computes method resolution order via each `ScopeResolver`'s `buildMro` hook, feeding a `MethodDispatchIndex` used for owner-scoped lookups. Per-language strategy:
|
||
|
||
- **`first-wins`** — Java, C#, C++, TS, Ruby, Go
|
||
- **`c3`** — Python (C3 linearization)
|
||
- **`ruby-mixin`** — Ruby (mixin-aware linearization)
|
||
- **`none`** — single-inheritance languages
|
||
|
||
---
|
||
|
||
## Full analysis flow
|
||
|
||
`runFullAnalysis` in `run-analyze.ts` orchestrates everything around the pipeline:
|
||
|
||
```
|
||
CLI (analyze.ts) → runFullAnalysis(repoPath, options, callbacks)
|
||
1. Early exit if lastCommit == HEAD (unless --force) [0%]
|
||
2. Cache existing embeddings from prior index [0%]
|
||
3. runPipelineFromRepo() → KnowledgeGraph [0-60%]
|
||
4. Clean up legacy KuzuDB files [60%]
|
||
5. initLbug() → loadGraphToLbug() via CSV streaming [60-85%]
|
||
6. Create FTS indexes (File, Function, Class, Method...) [85-90%]
|
||
7. Restore cached embeddings (batch insert) [88%]
|
||
8. Generate new embeddings if --embeddings [90-98%]
|
||
9. Save metadata + register repo + update .gitignore [98-100%]
|
||
10. Generate AI context files (AGENTS.md, CLAUDE.md) [100%]
|
||
```
|
||
|
||
**Options:** `--force` (rebuild regardless), `--embeddings` (opt-in, skipped if >50k nodes), `--skipGit`, `--noStats`.
|
||
|
||
## Storage
|
||
|
||
```
|
||
<repo>/.gitnexus/
|
||
├── lbug # LadybugDB database
|
||
├── lbug.wal # Write-ahead log
|
||
├── lbug.shadow # Shadow sidecar (checkpoint staging)
|
||
├── lbug.lock # Single-writer lock
|
||
├── lbug.{wal,shadow}.dirty-recovery # parked sidecars from a crashed run; safe to delete
|
||
├── gitnexus.json # lastCommit, indexedAt, stats (primary metadata file)
|
||
└── meta.json # legacy mirror of gitnexus.json, kept in sync (see MIGRATION.md)
|
||
|
||
~/.gitnexus/
|
||
└── registry.json # Global repo registry (MCP discovery)
|
||
```
|
||
|
||
Managed by `repo-manager.ts`.
|
||
|
||
## LadybugDB schema
|
||
|
||
Defined in `lbug/schema.ts`. Separate node tables per type, single `CodeRelation` table.
|
||
|
||
**Node tables:** File, Folder, Function, Class, Interface, Method, Constructor, CodeElement, Struct, Enum, Macro, Typedef, Union, Namespace, Trait, Impl, TypeAlias, Const, Static, Property, Record, Delegate, Annotation, Template, Module, Community, Process, Route, Tool, Section, Embedding.
|
||
|
||
**Relation types** (`CodeRelation.type`): CONTAINS, DEFINES, CALLS, IMPORTS, INHERITS, EXTENDS, IMPLEMENTS, USES, DECORATES, HAS_METHOD, HAS_PROPERTY, ACCESSES, METHOD_OVERRIDES, METHOD_IMPLEMENTS, MEMBER_OF, STEP_IN_PROCESS, HANDLES_ROUTE, FETCHES, HANDLES_TOOL, ENTRY_POINT_OF, WRAPS, QUERIES, INJECTS, CONDITIONAL_ON, DECLARES, ADVISED_BY, BINDS_EVENT_HANDLER, EMITS_EVENT.
|
||
|
||
**Optional `--pdg` additions** (off by default, opt-in via `gitnexus analyze --pdg`; see _Optional CFG/PDG emission_ above): a `BasicBlock` node table, plus the PDG relation types `CFG`, `REACHING_DEF`, `CDG`, `TAINTED`, `SANITIZES`, and `TAINT_PATH` on the same `CodeRelation` table. These are deliberately kept out of the default `VALID_RELATION_TYPES` / web graph schema — query them via `cypher`, `explain`, or `pdg_query`.
|
||
|
||
## Embeddings and search
|
||
|
||
**Embeddings** (`src/core/embeddings/`): Snowflake arctic-embed-xs (384D). Embeddable: File, Function, Class, Method, Interface. Incremental via SHA1 content hash. Separate `Embedding` table.
|
||
|
||
**Search** (`src/core/search/`): Hybrid BM25 + semantic vector, merged via Reciprocal Rank Fusion (K=60).
|
||
|
||
## Known limitations
|
||
|
||
### Overloaded method resolution
|
||
|
||
Node IDs use arity suffix (`#<paramCount>`): `Method:file:Class.method#1` vs `#2`.
|
||
|
||
**Same-arity disambiguation:** type-hash suffix `~type1,type2` when collision detected and type annotations present. Languages without types (Python, Ruby, JS) use arity-only. TS/JS overload signatures excluded (collapse to implementation body). See #651.
|
||
|
||
**C++ const-qualified:** `$const` suffix after type-hash when non-const collision exists: `Method:file:Container.begin#0$const`.
|
||
|
||
**Generic/template types:** type-hash uses `rawType` (full AST text including generics): `~vector<int>` vs `~vector<std::string>`.
|
||
|
||
**ID stability:** collision-only tags mean IDs change when overloads are added. `save#1` becomes `save#1~int` when `save(String)` is added.
|
||
|
||
**Variadic matching:** confidence 0.7 when one side is variadic and the other has fixed count.
|
||
|
||
**METHOD_IMPLEMENTS confidence tiering:**
|
||
|
||
| Match quality | Confidence |
|
||
| ------------------------------ | ---------- |
|
||
| Exact parameter types match | 1.0 |
|
||
| Arity match, types unavailable | 1.0 |
|
||
| Variadic vs fixed | 0.7 |
|
||
| Insufficient info | 0.7 |
|
||
|
||
## Related docs
|
||
|
||
- [MIGRATION.md](MIGRATION.md) — breaking changes and migration guidance
|
||
- [RUNBOOK.md](RUNBOOK.md) — operational commands and recovery
|
||
- [GUARDRAILS.md](GUARDRAILS.md) — safety boundaries for humans and agents
|
||
- [TESTING.md](TESTING.md) — how to run tests
|
||
- `AGENTS.md` / `CLAUDE.md` — agent workflows and tool usage
|