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

docs: optimize context files for LLM accuracy and token efficiency (#857 )

* docs: optimize context files for LLM accuracy and token efficiency

Fix factual errors across all five root context files and optimize
for LLM context window efficiency.

Corrections:
- Web UI: "runs entirely in WASM" -> thin client backed by HTTP API
- Pre-commit hook: "typecheck + tests" -> formatting + typecheck only
- MCP tools: 7 -> 16 (added api_impact, route_map, tool_map,
  shape_check, group_list/query/sync/contracts/status)
- Default serve port: 3741 -> 4747
- E2E tests: "5 tests" -> 7 spec files
- ESLint: "no config" -> eslint.config.mjs exists with TS/React rules
- npm test: "vitest run test/unit" -> "vitest run" (full suite)
- Removed nonexistent test:all script
- ci-quality.yml: added missing format + lint job descriptions
- Pipeline phase deps: added missing structure dep on mro/communities/processes
- Ingestion entry: added missing run-analyze.ts intermediate orchestrator
- Tools Quick Reference: added missing list_repos
- Group tool examples: fixed param name (group -> name)
- Removed stale vite-plugin-wasm gotcha
- Added gitnexus-shared to repository layout tables

New documentation:
- ARCHITECTURE.md: language-agnostic graph feeding (provider pattern,
  unified capture tags, import resolution tiers, chunked parse, MRO)
- ARCHITECTURE.md: full analysis flow (10 stages with progress %)
- ARCHITECTURE.md: storage layout, LadybugDB schema, embeddings, search
- ARCHITECTURE.md: DAG runner internals (Kahn's sort, dep isolation, error handling)

Token optimization:
- Removed filler prose, compressed descriptions into dense tables
- Front-loaded key facts in every section
- Eliminated redundancy between sections
- AGENTS.md: 219 -> 201 lines. ARCHITECTURE.md: 192 -> 298 lines
  (more info in fewer tokens via tables and structure)

* docs: optimize GUARDRAILS.md for LLM context efficiency

Tighten prose without losing information:
- Compressed intro, scope section, and Signs format labels
- Shortened Sign headers (removed "Sign:" prefix)
- Replaced verbose "Instruction/Reason" labels with "Do/Why"
- Removed trailing whitespace and redundant emphasis

2026-04-16 08:43:11 +01:00

3.7 KiB

Raw Permalink Blame History

Testing — GitNexus

How we structure tests and which commands to run locally and in CI.

Packages

Package	Path	Runner	Notes
CLI + MCP core	`gitnexus/`	Vitest	Primary test surface in CI
Web UI	`gitnexus-web/`	Vitest	Unit/component tests
Web UI E2E	`gitnexus-web/`	Playwright	Run when changing UI flows

Commands (local)

From repository root, unless noted:

gitnexus (CLI / library)

cd gitnexus
npm install
npm run build
npm test                    # full suite: vitest run
npm run test:unit           # unit only: vitest run test/unit
npm run test:integration    # integration suite
npm run test:coverage
npx tsc --noEmit            # typecheck (matches CI)

gitnexus-web

cd gitnexus-web
npm install
npm test                    # unit tests (vitest)
npx tsc -b --noEmit         # typecheck (matches CI)
npm run test:coverage
npm run test:e2e            # Playwright (requires gitnexus serve + npm run dev)

Pre-commit hook

A husky pre-commit hook (.husky/pre-commit) runs automatically on every git commit:

Formatting — lint-staged runs prettier on staged files
gitnexus-web/ files staged → tsc -b --noEmit
gitnexus/ files staged → tsc --noEmit

Tests do not run in the pre-commit hook — they run in CI (ci-tests.yml) only.

Skip with git commit --no-verify (use sparingly).

Test categories

Unit — Pure logic, parsers, graph/query helpers; fast; no network.
Integration — Real combinations (filesystem, MCP wiring, larger pipelines) as already organized under gitnexus/test/integration.
Eval-style / golden sets — For agent- or classification-style behavior, keep labeled inputs and expected outputs (JSON or table-driven tests) and run them in CI when relevant.
E2E (web) — Critical user paths only; prefer data-testid attributes for stable selectors. Tests run against real backend (gitnexus serve) and Vite dev server.

Performance metrics (targets)

Set targets to match team expectations, then tune to this repo’s CI reality:

Metric	Target (initial)	Notes
Unit coverage	Align with CI	CI runs Vitest with coverage in `gitnexus`
Unit wall time	Fast PR feedback	Use `vitest run test/unit` for tight loop
Integration duration	< few minutes	Guard heavy tests with env flags if needed

Regression testing

Re-run the full relevant suite when:

Prompt or agent-behavior documentation changes (if tests encode behavior)
Model or embedding-related code paths change
Graph schema, query contracts, or MCP tool shapes change
Dependencies with parsing or runtime impact upgrade

CI integration

GitHub Actions (.github/workflows/ci.yml) orchestrate:

ci-quality.yml — prettier format check, eslint lint, tsc --noEmit for gitnexus/, tsc -b --noEmit for gitnexus-web/
ci-tests.yml — vitest run with coverage (ubuntu) + cross-platform (macOS, Windows)
ci-e2e.yml — Playwright E2E tests, gated on gitnexus-web/** changes

Local checks before pushing:

cd gitnexus && npx tsc --noEmit && npm test
cd ../gitnexus-web && npx tsc -b --noEmit && npm test

Or rely on the pre-commit hook which runs these automatically for staged files.

User acceptance / beta (optional)

For staged releases or UI betas: deploy to a staging environment, collect structured feedback, watch errors and latency, then iterate before a wider release.

3.7 KiB Raw Permalink Blame History Unescape Escape