@veewo/gitnexus 1.3.4

package/README.md

@@ -0,0 +1,234 @@
+# GitNexus
+
+**Graph-powered code intelligence for AI agents.** Index any codebase into a knowledge graph, then query it via MCP or CLI.
+
+Works with **Cursor**, **Claude Code**, **Windsurf**, **Cline**, **OpenCode**, and any MCP-compatible tool.
+
+[![npm version](https://img.shields.io/npm/v/gitnexus.svg)](https://www.npmjs.com/package/gitnexus)
+[![License: PolyForm Noncommercial](https://img.shields.io/badge/License-PolyForm%20Noncommercial-blue.svg)](https://polyformproject.org/licenses/noncommercial/1.0.0/)
+
+---
+
+## Why?
+
+AI coding tools don't understand your codebase structure. They edit a function without knowing 47 other functions depend on it. GitNexus fixes this by **precomputing every dependency, call chain, and relationship** into a queryable graph.
+
+**Three commands to give your AI agent full codebase awareness.**
+
+## Quick Start
+
+```bash
+# Index your repo (run from repo root)
+npx gitnexus analyze
+```
+
+That's it. This indexes the codebase, installs agent skills, registers Claude Code hooks, and creates `AGENTS.md` / `CLAUDE.md` context files — all in one command.
+
+To configure MCP for your editor, run `npx gitnexus setup` once — or set it up manually below.
+
+`gitnexus setup` auto-detects your editors and writes the correct global MCP config. You only need to run it once.
+
+## Team Deployment and Distribution
+
+For small-team rollout (single stable channel only), follow:
+- [CLI Deployment and Distribution](../docs/cli-release-distribution.md)
+
+Key links:
+- [npm publish workflow](../.github/workflows/publish.yml)
+- [CLI package config](./package.json)
+
+### Editor Support
+
+| Editor | MCP | Skills | Hooks (auto-augment) | Support |
+|--------|-----|--------|---------------------|---------|
+| **Claude Code** | Yes | Yes | Yes (PreToolUse) | **Full** |
+| **Cursor** | Yes | Yes | — | MCP + Skills |
+| **Windsurf** | Yes | — | — | MCP |
+| **OpenCode** | Yes | Yes | — | MCP + Skills |
+
+> **Claude Code** gets the deepest integration: MCP tools + agent skills + PreToolUse hooks that automatically enrich grep/glob/bash calls with knowledge graph context.
+
+### Community Integrations
+
+| Agent | Install | Source |
+|-------|---------|--------|
+| [pi](https://pi.dev) | `pi install npm:pi-gitnexus` | [pi-gitnexus](https://github.com/tintinweb/pi-gitnexus) |
+
+## MCP Setup (manual)
+
+If you prefer to configure manually instead of using `gitnexus setup`:
+
+### Claude Code (full support — MCP + skills + hooks)
+
+```bash
+claude mcp add gitnexus -- npx -y gitnexus@latest mcp
+```
+
+### Cursor / Windsurf
+
+Add to `~/.cursor/mcp.json` (global — works for all projects):
+
+```json
+{
+  "mcpServers": {
+    "gitnexus": {
+      "command": "npx",
+      "args": ["-y", "gitnexus@latest", "mcp"]
+    }
+  }
+}
+```
+
+### OpenCode
+
+Add to `~/.config/opencode/config.json`:
+
+```json
+{
+  "mcp": {
+    "gitnexus": {
+      "command": "npx",
+      "args": ["-y", "gitnexus@latest", "mcp"]
+    }
+  }
+}
+```
+
+## How It Works
+
+GitNexus builds a complete knowledge graph of your codebase through a multi-phase indexing pipeline:
+
+1. **Structure** — Walks the file tree and maps folder/file relationships
+2. **Parsing** — Extracts functions, classes, methods, and interfaces using Tree-sitter ASTs
+3. **Resolution** — Resolves imports and function calls across files with language-aware logic
+4. **Clustering** — Groups related symbols into functional communities
+5. **Processes** — Traces execution flows from entry points through call chains
+6. **Search** — Builds hybrid search indexes for fast retrieval
+
+The result is a **KuzuDB graph database** stored locally in `.gitnexus/` with full-text search and semantic embeddings.
+
+## MCP Tools
+
+Your AI agent gets these tools automatically:
+
+| Tool | What It Does | `repo` Param |
+|------|-------------|--------------|
+| `list_repos` | Discover all indexed repositories | — |
+| `query` | Process-grouped hybrid search (BM25 + semantic + RRF) | Optional |
+| `context` | 360-degree symbol view — categorized refs, process participation | Optional |
+| `impact` | Blast radius analysis with depth grouping and confidence | Optional |
+| `detect_changes` | Git-diff impact — maps changed lines to affected processes | Optional |
+| `rename` | Multi-file coordinated rename with graph + text search | Optional |
+| `cypher` | Raw Cypher graph queries | Optional |
+
+> With one indexed repo, the `repo` param is optional. With multiple, specify which: `query({query: "auth", repo: "my-app"})`.
+
+## MCP Resources
+
+| Resource | Purpose |
+|----------|---------|
+| `gitnexus://repos` | List all indexed repositories (read first) |
+| `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 |
+
+## MCP Prompts
+
+| 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 |
+
+## CLI Commands
+
+```bash
+gitnexus setup                    # Configure MCP for your editors (one-time)
+gitnexus analyze [path]           # Index a repository (or update stale index)
+gitnexus analyze --force          # Force full re-index
+gitnexus analyze --embeddings     # Enable semantic embeddings (off by default)
+gitnexus analyze --scope-prefix Assets/NEON/Code --scope-prefix Packages/com.veewo.*  # Scoped multi-directory indexing
+gitnexus analyze --scope-manifest ./scope.txt --repo-alias neonspark-v1-subset         # Scoped indexing + stable repo alias
+gitnexus mcp                     # Start MCP server (stdio) — serves all indexed repos
+gitnexus serve                   # Start local HTTP server (multi-repo) for web UI
+gitnexus list                    # List all indexed repositories
+gitnexus status                  # Show index status for current repo
+gitnexus clean                   # Delete index for current repo
+gitnexus clean --all --force     # Delete all indexes
+gitnexus wiki [path]             # Generate LLM-powered docs from knowledge graph
+gitnexus wiki --model <model>    # Wiki with custom LLM model (default: gpt-4o-mini)
+gitnexus benchmark-unity ../benchmarks/unity-baseline/v1 --profile quick --target-path ../benchmarks/fixtures/unity-mini
+gitnexus benchmark-unity ../benchmarks/unity-baseline/v1 --profile full --target-path ../benchmarks/fixtures/unity-mini
+```
+
+For scoped indexing, `analyze` logs scope overlap dedupe counts and any normalized path collisions to help diagnose multi-directory merge safety.
+
+## Unity Benchmark
+
+Run reproducible Unity/C# accuracy and regression checks:
+
+```bash
+gitnexus benchmark-unity ../benchmarks/unity-baseline/v1 --profile quick --target-path ../benchmarks/fixtures/unity-mini
+gitnexus benchmark-unity ../benchmarks/unity-baseline/v1 --profile full --target-path ../benchmarks/fixtures/unity-mini
+```
+
+Reports are written to `.gitnexus/benchmark/benchmark-report.json` and `.gitnexus/benchmark/benchmark-summary.md`.
+
+Hard gates:
+
+| Metric | Threshold |
+|--------|-----------|
+| Query precision | `>= 0.90` |
+| Query recall | `>= 0.85` |
+| Context/impact F1 | `>= 0.80` |
+| Smoke pass rate | `= 1.00` |
+| Analyze time regression | `<= +15%` |
+
+## Multi-Repo Support
+
+GitNexus supports indexing multiple repositories. Each `gitnexus analyze` registers the repo in a global registry (`~/.gitnexus/registry.json`). The MCP server serves all indexed repos automatically.
+
+## Supported Languages
+
+TypeScript, JavaScript, Python, Java, C, C++, C#, Go, Rust
+
+## Agent Skills
+
+GitNexus ships with skill files that teach AI agents how to use the tools effectively:
+
+- **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
+
+Installation rules:
+
+- `gitnexus analyze` installs repo-local skills to `.agents/skills/gitnexus/` and updates `AGENTS.md` / `CLAUDE.md`.
+- `gitnexus setup` installs global skills to `~/.agents/skills/gitnexus/`.
+- If needed, create editor-specific symlinks yourself (for example map `.claude/skills/gitnexus` to `~/.agents/skills/gitnexus`).
+
+## Requirements
+
+- Node.js >= 18
+- Git repository (uses git for commit tracking)
+
+## Privacy
+
+- All processing happens locally on your machine
+- No code is sent to any server
+- Index stored in `.gitnexus/` inside your repo (gitignored)
+- Global registry at `~/.gitnexus/` stores only paths and metadata
+
+## Web UI
+
+GitNexus also has a browser-based UI at [gitnexus.vercel.app](https://gitnexus.vercel.app) — 100% client-side, your code never leaves the browser.
+
+**Local Backend Mode:** Run `gitnexus serve` and open the web UI locally — it auto-detects the server and shows all your indexed repos, with full AI chat support. No need to re-upload or re-index. The agent's tools (Cypher queries, search, code navigation) route through the backend HTTP API automatically.
+
+## License
+
+[PolyForm Noncommercial 1.0.0](https://polyformproject.org/licenses/noncommercial/1.0.0/)
+
+Free for non-commercial use. Contact for commercial licensing.

package/dist/benchmark/agent-context/evaluators.d.ts

@@ -0,0 +1,9 @@
+import type { AgentContextCheck, AgentContextCheckResult } from './types.js';
+type StepOutput = Record<string, any>;
+export declare function evaluateCheckT(stepOutputs: StepOutput[], expectedUid: string): AgentContextCheckResult;
+export declare function evaluateCheckE(toolCalls: number, maxToolCalls: number): AgentContextCheckResult;
+export declare function evaluateScenarioChecks(stepOutputs: StepOutput[], checks: AgentContextCheck[], options?: {
+    targetUid?: string;
+    toolCalls?: number;
+}): AgentContextCheckResult[];
+export {};

package/dist/benchmark/agent-context/evaluators.js

@@ -0,0 +1,196 @@
+function normalize(value) {
+    return value.trim().toLowerCase();
+}
+function pushUid(into, uid) {
+    if (typeof uid === 'string' && uid.trim()) {
+        into.add(uid.trim());
+    }
+}
+function collectUids(stepOutputs) {
+    const hits = new Set();
+    for (const output of stepOutputs) {
+        pushUid(hits, output?.symbol?.uid);
+        pushUid(hits, output?.target?.id);
+        for (const row of output?.process_symbols || []) {
+            pushUid(hits, row?.id);
+        }
+        for (const row of output?.definitions || []) {
+            pushUid(hits, row?.id);
+        }
+        for (const row of output?.candidates || []) {
+            pushUid(hits, row?.uid);
+        }
+        for (const list of Object.values(output?.byDepth || {})) {
+            if (!Array.isArray(list)) {
+                continue;
+            }
+            for (const row of list) {
+                pushUid(hits, row?.id);
+            }
+        }
+    }
+    return [...hits];
+}
+function countIncoming(stepOutputs) {
+    let count = 0;
+    for (const output of stepOutputs) {
+        for (const rows of Object.values(output?.incoming || {})) {
+            if (Array.isArray(rows)) {
+                count += rows.length;
+            }
+        }
+    }
+    return count;
+}
+function countOutgoing(stepOutputs) {
+    let count = 0;
+    for (const output of stepOutputs) {
+        for (const rows of Object.values(output?.outgoing || {})) {
+            if (Array.isArray(rows)) {
+                count += rows.length;
+            }
+        }
+    }
+    return count;
+}
+function countImpacted(stepOutputs) {
+    let total = 0;
+    for (const output of stepOutputs) {
+        total += Number(output?.impactedCount || 0);
+    }
+    return total;
+}
+function collectNames(stepOutputs) {
+    const names = new Set();
+    const addName = (name) => {
+        if (typeof name === 'string' && name.trim()) {
+            names.add(name.trim());
+        }
+    };
+    for (const output of stepOutputs) {
+        addName(output?.symbol?.name);
+        addName(output?.target?.name);
+        for (const row of output?.process_symbols || []) {
+            addName(row?.name);
+        }
+        for (const row of output?.definitions || []) {
+            addName(row?.name);
+        }
+        for (const row of output?.candidates || []) {
+            addName(row?.name);
+        }
+        for (const rows of Object.values(output?.incoming || {})) {
+            if (!Array.isArray(rows)) {
+                continue;
+            }
+            for (const row of rows) {
+                addName(row?.name);
+            }
+        }
+        for (const rows of Object.values(output?.outgoing || {})) {
+            if (!Array.isArray(rows)) {
+                continue;
+            }
+            for (const row of rows) {
+                addName(row?.name);
+            }
+        }
+        for (const rows of Object.values(output?.byDepth || {})) {
+            if (!Array.isArray(rows)) {
+                continue;
+            }
+            for (const row of rows) {
+                addName(row?.name);
+            }
+        }
+    }
+    return [...names];
+}
+export function evaluateCheckT(stepOutputs, expectedUid) {
+    const expected = normalize(expectedUid);
+    const pass = collectUids(stepOutputs).some((uid) => {
+        const n = normalize(uid);
+        return n === expected || n.endsWith(expected) || expected.endsWith(n);
+    });
+    return {
+        id: 'T',
+        pass,
+        detail: pass ? undefined : `target uid not found: ${expectedUid}`,
+    };
+}
+export function evaluateCheckE(toolCalls, maxToolCalls) {
+    const pass = toolCalls <= maxToolCalls;
+    return {
+        id: 'E',
+        pass,
+        detail: pass ? undefined : `tool calls ${toolCalls} exceed max ${maxToolCalls}`,
+    };
+}
+function evaluateCheckU(stepOutputs, minIncoming) {
+    const incoming = countIncoming(stepOutputs);
+    return {
+        id: 'U',
+        pass: incoming >= minIncoming,
+        detail: incoming >= minIncoming ? undefined : `incoming refs ${incoming} < ${minIncoming}`,
+    };
+}
+function evaluateCheckD(stepOutputs, minOutgoing) {
+    const outgoing = countOutgoing(stepOutputs);
+    return {
+        id: 'D',
+        pass: outgoing >= minOutgoing,
+        detail: outgoing >= minOutgoing ? undefined : `outgoing refs ${outgoing} < ${minOutgoing}`,
+    };
+}
+function evaluateCheckB(stepOutputs, minImpacted) {
+    const impacted = countImpacted(stepOutputs);
+    return {
+        id: 'B',
+        pass: impacted >= minImpacted,
+        detail: impacted >= minImpacted ? undefined : `impacted count ${impacted} < ${minImpacted}`,
+    };
+}
+function evaluateCheckI(stepOutputs, anchors, minInternalHits) {
+    const loweredAnchors = anchors.map((anchor) => normalize(anchor));
+    const names = collectNames(stepOutputs).map((name) => normalize(name));
+    const matched = new Set();
+    for (const anchor of loweredAnchors) {
+        if (names.some((name) => name.includes(anchor))) {
+            matched.add(anchor);
+        }
+    }
+    return {
+        id: 'I',
+        pass: matched.size >= minInternalHits,
+        detail: matched.size >= minInternalHits ? undefined : `internal anchors matched ${matched.size} < ${minInternalHits}`,
+    };
+}
+export function evaluateScenarioChecks(stepOutputs, checks, options) {
+    const results = [];
+    for (const check of checks) {
+        switch (check.id) {
+            case 'T':
+                results.push(evaluateCheckT(stepOutputs, check.required_uid || options?.targetUid || ''));
+                break;
+            case 'U':
+                results.push(evaluateCheckU(stepOutputs, check.min_incoming ?? 0));
+                break;
+            case 'D':
+                results.push(evaluateCheckD(stepOutputs, check.min_outgoing ?? 0));
+                break;
+            case 'B':
+                results.push(evaluateCheckB(stepOutputs, check.min_impacted ?? 0));
+                break;
+            case 'I':
+                results.push(evaluateCheckI(stepOutputs, check.internal_anchors || [], check.min_internal_hits ?? 0));
+                break;
+            case 'E':
+                results.push(evaluateCheckE(options?.toolCalls ?? stepOutputs.length, check.max_tool_calls ?? Number.MAX_SAFE_INTEGER));
+                break;
+            default:
+                results.push({ id: check.id, pass: false, detail: `unsupported check id: ${check.id}` });
+                break;
+        }
+    }
+    return results;
+}

package/dist/benchmark/agent-context/evaluators.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/benchmark/agent-context/evaluators.test.js

@@ -0,0 +1,39 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { evaluateCheckE, evaluateCheckT, evaluateScenarioChecks } from './evaluators.js';
+test('evaluates mandatory target disambiguation check T', () => {
+    const stepOutputs = [
+        {
+            symbol: { uid: 'Class:Sample:Target' },
+            target: { id: 'Class:Sample:Target' },
+            process_symbols: [{ id: 'Class:Sample:Target', name: 'Target' }],
+            definitions: [],
+        },
+    ];
+    const result = evaluateCheckT(stepOutputs, 'Class:Sample:Target');
+    assert.equal(result.pass, true);
+});
+test('evaluates efficiency check E by tool call budget', () => {
+    const result = evaluateCheckE(3, 4);
+    assert.equal(result.pass, true);
+});
+test('evaluates internal coverage check I from context/impact result names', () => {
+    const stepOutputs = [
+        {
+            incoming: {
+                calls: [{ id: 'Method:Sample:RefreshScreen', name: 'RefreshScreen' }],
+            },
+            outgoing: {
+                calls: [{ id: 'Method:Sample:HidePanel', name: 'HidePanel' }],
+            },
+            byDepth: {
+                depth_1: [{ id: 'Method:Sample:SyncState', name: 'SyncState' }],
+            },
+        },
+    ];
+    const checks = [
+        { id: 'I', internal_anchors: ['Refresh', 'Sync'], min_internal_hits: 2 },
+    ];
+    const [result] = evaluateScenarioChecks(stepOutputs, checks);
+    assert.equal(result.pass, true);
+});

package/dist/benchmark/agent-context/io.d.ts

@@ -0,0 +1,2 @@
+import type { AgentContextDataset } from './types.js';
+export declare function loadAgentContextDataset(root: string): Promise<AgentContextDataset>;

package/dist/benchmark/agent-context/io.js

@@ -0,0 +1,23 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+export async function loadAgentContextDataset(root) {
+    const thresholds = JSON.parse(await fs.readFile(path.join(root, 'thresholds.json'), 'utf-8'));
+    const scenarios = await readJsonl(path.join(root, 'scenarios.jsonl'), ['scenario_id', 'target_uid', 'tool_plan', 'checks']);
+    return { thresholds, scenarios };
+}
+async function readJsonl(file, required) {
+    const raw = await fs.readFile(file, 'utf-8');
+    const rows = raw
+        .split('\n')
+        .map((line) => line.trim())
+        .filter(Boolean)
+        .map((line) => JSON.parse(line));
+    for (const row of rows) {
+        for (const key of required) {
+            if (!(key in row)) {
+                throw new Error(`missing required field: ${key}`);
+            }
+        }
+    }
+    return rows;
+}

package/dist/benchmark/agent-context/io.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/benchmark/agent-context/io.test.js

@@ -0,0 +1,19 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import path from 'node:path';
+import { loadAgentContextDataset } from './io.js';
+test('loadAgentContextDataset validates required scenario fields', async () => {
+    const invalidRoot = path.resolve('src/benchmark/agent-context/__fixtures__/invalid/missing-checks');
+    await assert.rejects(() => loadAgentContextDataset(invalidRoot), /missing required field/i);
+});
+test('loadAgentContextDataset loads valid thresholds and scenarios', async () => {
+    const validRoot = path.resolve('src/benchmark/agent-context/__fixtures__/valid');
+    const ds = await loadAgentContextDataset(validRoot);
+    assert.equal(ds.scenarios.length, 1);
+    assert.ok(ds.thresholds.coverage.minPerScenario > 0);
+});
+test('v1 scenario dataset loads exactly 3 scenarios', async () => {
+    const v1Root = path.resolve('../benchmarks/agent-context/neonspark-refactor-v1');
+    const ds = await loadAgentContextDataset(v1Root);
+    assert.equal(ds.scenarios.length, 3);
+});

package/dist/benchmark/agent-context/report.d.ts

@@ -0,0 +1,2 @@
+import type { AgentContextBenchmarkResult } from './runner.js';
+export declare function writeAgentContextReports(reportDir: string, result: AgentContextBenchmarkResult): Promise<void>;

package/dist/benchmark/agent-context/report.js

@@ -0,0 +1,59 @@
+import { writeReports } from '../report.js';
+function buildFailureClassRows(result) {
+    const counts = new Map();
+    for (const scenario of result.scenarios) {
+        for (const check of scenario.checks) {
+            if (!check.pass) {
+                counts.set(check.id, (counts.get(check.id) || 0) + 1);
+            }
+        }
+    }
+    return [...counts.entries()]
+        .map(([id, count]) => ({ id, count }))
+        .sort((a, b) => b.count - a.count);
+}
+function buildTriageRows(result) {
+    const failing = result.scenarios
+        .map((scenario) => {
+        const failedChecks = scenario.checks.filter((check) => !check.pass).map((check) => check.id);
+        return {
+            scenarioId: scenario.scenarioId,
+            coverage: scenario.coverage,
+            failedChecks,
+        };
+    })
+        .filter((row) => row.failedChecks.length > 0)
+        .sort((a, b) => a.coverage - b.coverage || b.failedChecks.length - a.failedChecks.length);
+    return failing.map((row, index) => `${index + 1}. ${row.scenarioId} (coverage=${row.coverage.toFixed(3)}, failed_checks=${row.failedChecks.join(', ')})`);
+}
+export async function writeAgentContextReports(reportDir, result) {
+    const jsonReport = {
+        generatedAt: new Date().toISOString(),
+        pass: result.pass,
+        failures: result.failures,
+        metrics: result.metrics,
+        scenarios: result.scenarios,
+    };
+    const failureClasses = buildFailureClassRows(result);
+    const triageRows = buildTriageRows(result);
+    const markdown = [
+        '# Agent-Context Benchmark Summary',
+        '',
+        `- Pass: ${result.pass ? 'YES' : 'NO'}`,
+        `- Average Coverage: ${result.metrics.avgCoverage.toFixed(3)}`,
+        `- Average Tool Calls: ${result.metrics.avgToolCalls.toFixed(3)}`,
+        `- Mandatory Target Pass Rate: ${result.metrics.mandatoryTargetPassRate.toFixed(3)}`,
+        '',
+        '## Scenarios',
+        ...result.scenarios.map((scenario) => `- ${scenario.scenarioId}: coverage=${scenario.coverage.toFixed(3)}, calls=${scenario.toolCalls}, gate=${scenario.gatePass ? 'PASS' : 'FAIL'}`),
+        '',
+        '## Top Failure Classes',
+        ...(failureClasses.length > 0
+            ? failureClasses.map((row) => `- ${row.id}: ${row.count}`)
+            : ['- none']),
+        '',
+        '## Recommended Triage Order',
+        ...(triageRows.length > 0 ? triageRows : ['1. none']),
+    ].join('\n');
+    await writeReports(reportDir, jsonReport, markdown);
+}

package/dist/benchmark/agent-context/report.test.d.ts

@@ -0,0 +1 @@
+export {};