scriptoriumadmin/GitNexus
1
0
Fork 0
mirror of https://github.com/abhigyanpatwari/GitNexus.git synced 2026-09-20 00:11:37 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 8
GitNexus/ARCHITECTURE.md
Gergo Magyar 3c5079f044 feat: disambiguate overloaded method node IDs with #<paramCount> arity suffix 
Method and Constructor node IDs now include a #<paramCount> suffix to
distinguish overloaded methods: Method:file:Class.method#1 vs #2.

Core changes:
- Reorder parameter extraction before generateId in both parsing-processor.ts
  (sequential) and parse-worker.ts (worker) so arity is available at ID time
- Add arity suffix to findEnclosingFunctionId in both call-processor.ts and
  parse-worker.ts so CALLS/ACCESSES edge sourceIds match definition-phase IDs
- Strip #<arity> in extractFuncNameFromSourceId for receiver-type index lookups
- Fix resolveMethodReturnType to handle class names directly as receiver types
  (pre-existing latent bug surfaced by substituteThisReceiver + fixpoint interaction)
- Add MIGRATION.md documenting OVERRIDES → METHOD_OVERRIDES rename
- Update ARCHITECTURE.md Known Limitations with overload resolution status

Same-arity overloads (same param count, different types) remain collapsed —
deferred to future type-hash enhancement (issue #574).

All 2896 unit tests + 2213 integration tests pass.
2026-04-04 09:22:11 +01:00

5.6 KiB
Raw Blame History

Architecture — GitNexus

This repository is a monorepo with two main products: the CLI / MCP package (gitnexus/) and the browser UI (gitnexus-web/). Supporting folders ship editor integrations and plugins without changing the core graph engine.

Repository layout

Path Role
gitnexus/ Published npm package gitnexus: CLI, MCP server (stdio), local HTTP API for bridge mode, ingestion pipeline, LadybugDB graph, embeddings (optional).
gitnexus-web/ Vite + React UI: in-browser indexing (WASM), graph visualization, optional connection to gitnexus serve.
.claude/, gitnexus-claude-plugin/, gitnexus-cursor-integration/ Packaged skills and plugin metadata so agents discover the same workflows as documented in AGENTS.md.
eval/ Evaluation harnesses and docs for benchmarking tool usage.
.github/ CI workflows (quality, unit, integration, E2E) and composite actions.

End-to-end flow: index → graph → tools

  1. Ingestion (gitnexus analyze)

    • Entry: gitnexus/src/cli/analyze.ts → runPipelineFromRepo in gitnexus/src/core/ingestion/pipeline.ts.
    • Walks the git working tree, parses supported languages via Tree-sitter, resolves imports/calls/inheritance, detects communities and processes (execution flows), and builds an in-memory knowledge graph (gitnexus/src/core/graph/).
    • Output is loaded into LadybugDB under .gitnexus/ at the repo root (lbug/, meta.json, etc.). Optional FTS indexes and embeddings attach to the same store.
    • The repo is registered in ~/.gitnexus/registry.json so MCP can find it from any working directory.

  2. Persistence & metadata

    • gitnexus/src/storage/repo-manager.ts — paths, registry, cleanup of legacy Kuzu artifacts.
    • gitnexus/src/core/lbug/lbug-adapter.ts — graph load, queries, embedding restore batches.

  3. Query & agents

    • MCP (stdio): gitnexus/src/cli/mcp.ts → startMCPServer → LocalBackend (gitnexus/src/mcp/local/local-backend.ts) opens registered repos and serves tools from gitnexus/src/mcp/tools.ts and resources from gitnexus/src/mcp/resources.ts.
    • Bridge HTTP: gitnexus/src/cli/serve.ts → Express app in gitnexus/src/server/api.ts (CORS-limited) exposes REST + MCP-over-HTTP for the web UI.
    • CLI tools (no MCP): gitnexus query, context, impact, cypher in gitnexus/src/cli/tool.ts call the same backend for scripts and CI.

  4. Staleness

    • gitnexus/src/mcp/staleness.ts compares indexed lastCommit to HEAD and surfaces hints when the graph is behind git.

MCP tools (summary)

Tool Purpose
list_repos Discover indexed repositories when more than one is registered.
query Natural-language / keyword search over the graph (hybrid BM25 + optional vectors).
cypher Ad hoc Cypher against the schema (see resource gitnexus://repo/{name}/schema).
context Callers, callees, processes for one symbol (with disambiguation).
impact Blast radius (upstream/downstream) with depth and risk summary.
detect_changes Map git diffs to affected symbols and processes.
rename Graph-assisted rename with dry_run preview (graph vs text_search confidence).

Where to change what

If you are changing… Start in…
CLI commands / flags gitnexus/src/cli/ (index.ts, per-command modules).
Parsing or graph construction gitnexus/src/core/ingestion/ (pipeline, processors, resolvers, type-extractors).
Graph schema / DB access gitnexus/src/core/lbug/ (schema.ts, lbug-adapter.ts), gitnexus/src/mcp/core/lbug-adapter.ts if MCP-specific.
MCP protocol, tools, resources gitnexus/src/mcp/server.ts, tools.ts, resources.ts.
Search ranking gitnexus/src/core/search/ (BM25, hybrid fusion).
Embeddings gitnexus/src/core/embeddings/, phases in analyze.ts.
Wiki generation gitnexus/src/core/wiki/.
Web UI behavior gitnexus-web/src/ (components, workers, graph client).
CI .github/workflows/*.yml, .github/actions/setup-gitnexus/.

Known limitations

Overloaded method resolution

Method and Constructor node IDs include an arity suffix (#<paramCount>) to disambiguate overloaded methods. Two overloads with different parameter counts produce distinct graph nodes: Method:file:Class.method#1 vs Method:file:Class.method#2.

Remaining limitation — same-arity overloads: When two overloads share the same parameter count but differ only in types (e.g. save(int) vs save(String)), they still share a node ID. This is rare in practice; a future enhancement may add type-hash disambiguation for languages with reliable type extraction (see issue #574).

Confidence tiering for METHOD_IMPLEMENTS edges:

Match quality Confidence When
Exact parameter types match 1.0 Both sides have parameterTypes arrays and they match
Arity (count) matches 1.0 Both sides have parameterCount, types unavailable
Lenient (insufficient info) 0.7 One or both sides lack type and count data

Related docs

  • MIGRATION.md — breaking changes and migration guidance.
  • RUNBOOK.md — operational commands and recovery.
  • GUARDRAILS.md — safety boundaries for humans and agents.
  • TESTING.md — how to run tests.
  • AGENTS.md / CLAUDE.md — agent workflows and tool usage expectations for this repo when indexed by GitNexus.