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

docs: agent development framework, GitHub templates, eval refactor (#479 )

* ci: E2E workflow, web typecheck job, pre-commit hook, test suite

CI:
- ci.yml consolidated to reference ci-tests.yml
- ci-quality.yml: add typecheck-web job for gitnexus-web/
- ci-e2e.yml: E2E workflow with dorny/paths-filter (web changes only)
- ci-report.yml: remove dead integration-reports references
- CI gate allows skipped E2E status
- .gitignore: playwright artifacts, eval test artifacts

Pre-commit hook:
- .githooks/pre-commit: typecheck + unit tests for both packages
- Activated via git config core.hooksPath in prepare script

Test infrastructure:
- Vitest + React Testing Library: 58 unit tests
  (graph, server-connection, mermaid, settings, constants, utils, paths)
- Playwright E2E: 5 tests + manual recording harness
- vitest.config from vitest/config, engines.node >= 20
- Playwright artifacts retain-on-failure
- wait-on in devDependencies
- vitest/coverage-v8 aligned with vitest 4.x

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* chore: update gitnexus-web package-lock.json

Reflects devDependency additions (vitest, playwright, wait-on,
@testing-library, etc.) from package.json changes in this PR.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* fix(e2e): add missing process-list-loaded testid, increase CI timeouts

- Add data-testid="process-list-loaded" to ProcessesPanel (E2E tests
  were waiting for an element that didn't exist)
- Increase server connect timeouts from 5s to 10s for slower CI

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* fix(ci): run gitnexus-web unit tests in CI, remove unused variable

- Add gitnexus-web npm ci + vitest run to ci-tests.yml so web unit
  tests are gated by the CI status check (were only running locally)
- Remove unused IS_PLAYWRIGHT_AUTOMATION variable from E2E spec

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* fix(e2e): add process-row testid, wait for networkidle on page load

- Add data-testid="process-row" to ProcessItem component (E2E tests
  referenced it but it didn't exist in the source)
- Use waitUntil: 'networkidle' on page.goto to ensure Vite dev server
  is fully ready before interacting (fixes first-test timeout in CI)

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* fix(e2e): add process-view-button and process-highlight-button testids

E2E tests referenced these data-testid attributes but they didn't
exist in ProcessItem. All 6 E2E testids now have matching source
elements: status-ready, process-list-loaded, process-row,
process-view-button, process-highlight-button, server-url-input.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* fix(e2e): remove networkidle — Vite HMR WebSocket prevents it from resolving

networkidle waits for zero network activity for 500ms, but Vite's HMR
WebSocket stays open permanently, causing page.goto to timeout at 60s
on all tests after the first. The explicit toBeVisible waits on UI
elements are sufficient and deterministic.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* fix(e2e): wait for Server button visibility, add CI retry, all 5 tests pass locally

Root cause: test 1 clicked the Server button before React hydrated,
so the tab content never rendered and the input wasn't found.

Fixes:
- Wait for Server button toBeVisible before clicking
- Increase input wait to 15s
- Remove networkidle (Vite HMR WebSocket prevents it from resolving)
- Add retries: 1 in CI for transient cold-start flakiness

Verified locally: all 5 E2E tests pass, 198 unit tests pass, typecheck clean.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* fix(ci): tolerate LadybugDB native crash during analyze step

gitnexus analyze can crash with "double free or corruption" (known
issue #273) during the LadybugDB native addon shutdown. The index is
usually written successfully before the crash. The workflow now:
1. Allows analyze to exit non-zero with a warning
2. Verifies .gitnexus index was actually created
3. Only fails if no index exists (real failure)

All tests verified locally: 198 unit, 5 E2E pass, typecheck clean.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* fix(ci): fix shell quoting in analyze step, simplify to || true

The previous echo string had special characters that broke bash
quoting in GitHub Actions. Simplified to: analyze || true, then
check if .gitnexus exists.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* docs: add agent development framework, GitHub templates, eval refactor

Agent framework (layered docs for AI-assisted contributions):
- AGENTS.md: canonical instructions, impact analysis, MCP tools
- CLAUDE.md: Claude Code-specific deltas and hooks
- GUARDRAILS.md: safety boundaries, non-negotiables, escalation
- ARCHITECTURE.md: monorepo layout, data flow map
- TESTING.md: test structure, commands, categories
- RUNBOOK.md: copy-paste operations for dev/CI/MCP
- llms.txt: minimal LLM context pointer

Editor integration:
- .cursor/index.mdc + rules/100-monorepo.mdc

GitHub templates:
- PR template with areas-touched checkboxes
- Bug report + feature request issue forms

Eval harness:
- Refactored mcp_bridge, tool_registry, constants
- Error sanitization utilities
- Property-based tests via Hypothesis

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* fix(eval): use format_exception instead of format_exc in sanitize_exception

format_exc() returns the currently handled exception traceback, which
may be unrelated if called outside an active except block. Using
format_exception(type(exc), exc, exc.__traceback__) reliably captures
the passed exception's traceback.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* docs: update CONTRIBUTING.md and TESTING.md for current CI/hook setup

- CONTRIBUTING.md: add gitnexus-web typecheck command, pre-commit hook
  checklist item
- TESTING.md: add gitnexus-web typecheck command, pre-commit hook
  section (husky), update CI integration to list actual workflow files
  (ci-quality, ci-tests, ci-e2e)

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* docs: update testing docs to reflect CI/E2E changes from PR #486

- AGENTS.md: update test counts (CLI ~2000 unit, ~1850 integration),
  add gitnexus-web testing section (198 unit, 5 E2E with commands)
- RUNBOOK.md: fix Node requirement to >=20, fix E2E local repro command
- TESTING.md: E2E uses data-testid selectors + real servers, not mocks
- .cursor/rules/100-monorepo.mdc: add web test/E2E commands

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* docs: address context engineering review — deduplicate tokens, expand Cursor rules

- Remove ~100-line gitnexus:start block from CLAUDE.md (was duplicated from AGENTS.md)
- Fix gitnexus:start block inlined inside AGENTS.md Reference Docs bullet (doubled)
- Replace CLAUDE.md scope table with pointer to AGENTS.md (single source of truth)
- Expand .cursor/index.mdc with 5 non-negotiable safety rules for always-on context
- Add .cursor/rules/200-eval.mdc with Python/eval commands (glob-scoped to eval/**)
- Improve llms.txt with priority annotations and descriptions
- Bump version headers to 1.2.0, last-reviewed to 2026-03-24

Saves ~1,400 tokens/session with zero information loss.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Co-authored-by: Gergő Magyar <gergomagyar@icloud.com>

2026-03-25 06:48:41 +00:00

4.5 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

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.
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.
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.
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/`.

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.

4.5 KiB Raw Blame History