From 6c3c47edc3cf4e7e498938637d2f5ff7ea3d8e48 Mon Sep 17 00:00:00 2001 From: abhigyanpatwari Date: Thu, 5 Feb 2026 05:13:48 +0530 Subject: [PATCH] resources implemented and agents.md and skills updated to use it --- .claude/skills/gitnexus/debugging/SKILL.md | 103 ++++++ .claude/skills/gitnexus/exploring/SKILL.md | 111 +++++++ .../skills/gitnexus/impact-analysis/SKILL.md | 113 +++++++ .claude/skills/gitnexus/refactoring/SKILL.md | 118 +++++++ .cursor/plans/enhance_523ca41c.plan.md | 239 -------------- .cursorrules | 5 + .gitignore | 3 + .windsurfrules | 5 + AGENTS.md | 81 +++++ CLAUDE.md | 75 +++++ gitnexus/skills/debugging.md | 119 +++---- gitnexus/skills/exploring.md | 129 ++++---- gitnexus/skills/impact-analysis.md | 120 +++---- gitnexus/skills/refactoring.md | 134 +++----- gitnexus/src/cli/ai-context.ts | 76 ++--- gitnexus/src/mcp/local/local-backend.ts | 31 -- gitnexus/src/mcp/resources.ts | 311 ++++++++++++++++++ gitnexus/src/mcp/server.ts | 104 +++--- gitnexus/src/mcp/tools.ts | 17 - 19 files changed, 1219 insertions(+), 675 deletions(-) create mode 100644 .claude/skills/gitnexus/debugging/SKILL.md create mode 100644 .claude/skills/gitnexus/exploring/SKILL.md create mode 100644 .claude/skills/gitnexus/impact-analysis/SKILL.md create mode 100644 .claude/skills/gitnexus/refactoring/SKILL.md delete mode 100644 .cursor/plans/enhance_523ca41c.plan.md create mode 100644 .cursorrules create mode 100644 .windsurfrules create mode 100644 AGENTS.md create mode 100644 CLAUDE.md create mode 100644 gitnexus/src/mcp/resources.ts diff --git a/.claude/skills/gitnexus/debugging/SKILL.md b/.claude/skills/gitnexus/debugging/SKILL.md new file mode 100644 index 000000000..3d8dab1b7 --- /dev/null +++ b/.claude/skills/gitnexus/debugging/SKILL.md @@ -0,0 +1,103 @@ +--- +name: gitnexus-debugging +description: Trace bugs through call chains using knowledge graph +--- + +# Debugging with GitNexus + +## Quick Start +``` +1. gitnexus_search({query}) → Find code related to error +2. gitnexus_explore({name, type: "symbol"}) → Get callers and callees +3. READ gitnexus://process/{name} → Trace execution flow +``` + +## When to Use +- "Why is this function failing?" +- "Trace where this error comes from" +- "Who calls this method?" +- "Debug the payment issue" + +## Workflow Checklist +``` +Bug Investigation: +- [ ] Understand the symptom (error message, behavior) +- [ ] gitnexus_search to find related code +- [ ] Identify the suspect function +- [ ] gitnexus_explore to see callers/callees +- [ ] READ gitnexus://process/{name} if suspect is in a process +- [ ] READ gitnexus://schema for Cypher query help +- [ ] gitnexus_cypher for custom traces +``` + +## Resource Reference + +### gitnexus://schema +Graph schema for writing Cypher queries: +```yaml +nodes: [Function, Class, Method, File, Community, Process] +relationships: [CALLS, IMPORTS, EXTENDS, IMPLEMENTS, MEMBER_OF, STEP_IN_PROCESS] +example_queries: + find_callers: | + MATCH (caller)-[:CodeRelation {type: 'CALLS'}]->(f:Function {name: "X"}) + RETURN caller.name +``` + +### gitnexus://process/{name} +Trace execution flow to find where bug might occur: +```yaml +name: CheckoutFlow +trace: + 1: handleCheckout + 2: validateCart + 3: processPayment ← bug here? + 4: sendConfirmation +``` + +## Tool Reference + +### gitnexus_search +Find code related to error or symptom: +``` +gitnexus_search({query: "payment validation error", depth: "full"}) +``` + +### gitnexus_explore +Get symbol context: +``` +gitnexus_explore({name: "validatePayment", type: "symbol"}) +→ Callers: processCheckout, webhookHandler +→ Callees: verifyCard, fetchRates +``` + +### gitnexus_cypher +Custom graph queries for tracing: +```cypher +// Trace call chain (2 hops) +MATCH path = (a)-[:CodeRelation {type: 'CALLS'}*1..2]->(b:Function {name: "validatePayment"}) +RETURN [n IN nodes(path) | n.name] AS chain +``` + +## Example: "Payment endpoint returns 500 intermittently" + +``` +1. gitnexus_search({query: "payment error handling"}) + → validatePayment, handlePaymentError, PaymentException + +2. gitnexus_explore({name: "validatePayment", type: "symbol"}) + → Callees: verifyCard, fetchRates (external API!) + +3. READ gitnexus://process/CheckoutFlow + → Step 3: validatePayment → calls external API + +4. Root cause: fetchRates calls external API without proper timeout +``` + +## Debugging Patterns + +| Symptom | Approach | +|---------|----------| +| Error message | Search for error text, trace throw sites | +| Wrong return value | Trace data flow through callees | +| Intermittent failure | Look for external calls, timeouts | +| Performance issue | Find hot paths via callers count | diff --git a/.claude/skills/gitnexus/exploring/SKILL.md b/.claude/skills/gitnexus/exploring/SKILL.md new file mode 100644 index 000000000..2baa7f31e --- /dev/null +++ b/.claude/skills/gitnexus/exploring/SKILL.md @@ -0,0 +1,111 @@ +--- +name: gitnexus-exploring +description: Navigate unfamiliar code using GitNexus knowledge graph +--- + +# Exploring Codebases + +## Quick Start +``` +1. READ gitnexus://context → Get codebase overview (~150 tokens) +2. READ gitnexus://clusters → See all functional clusters +3. READ gitnexus://cluster/{name} → Deep dive on specific cluster +``` + +## When to Use +- "How does authentication work?" +- "What's the project structure?" +- "Show me the main components" +- "Where is the database logic?" + +## Workflow Checklist +``` +Exploration Progress: +- [ ] READ gitnexus://context for codebase overview +- [ ] READ gitnexus://clusters to list all clusters +- [ ] Identify the relevant cluster by name +- [ ] READ gitnexus://cluster/{name} for cluster details +- [ ] Use gitnexus_explore for specific symbols +``` + +## Resource Reference + +### gitnexus://context +Codebase overview. **Read first.** +```yaml +project: my-app +stats: + files: 42 + symbols: 918 + clusters: 12 + processes: 45 +tools_available: [search, explore, impact, overview, cypher] +resources_available: [clusters, processes, cluster/{name}, process/{name}] +``` + +### gitnexus://clusters +All functional clusters with cohesion scores. +```yaml +clusters: + - name: "Auth" + symbols: 47 + cohesion: 92% + - name: "Database" + symbols: 32 + cohesion: 88% +``` + +### gitnexus://cluster/{name} +Members of a specific cluster. +```yaml +name: Auth +symbols: 47 +cohesion: 92% +members: + - name: validateUser + type: Function + file: src/auth/validator.ts +``` + +### gitnexus://process/{name} +Full execution trace. +```yaml +name: LoginFlow +type: cross_community +steps: + 1: handleLogin (src/auth/handler.ts) + 2: validateUser (src/auth/validator.ts) + 3: createSession (src/auth/session.ts) +``` + +## Tool Reference (When Resources Aren't Enough) + +### gitnexus_explore +For detailed symbol context with callers/callees: +``` +gitnexus_explore({name: "validateUser", type: "symbol"}) +→ Callers: loginHandler, apiMiddleware +→ Callees: checkToken, getUserById +``` + +### gitnexus_search +For finding code by query: +``` +gitnexus_search({query: "payment validation", depth: "full"}) +``` + +## Example: "How does payment processing work?" + +``` +1. READ gitnexus://context + → 918 symbols, 12 clusters + +2. READ gitnexus://clusters + → Clusters: Auth, Payment, Database, API... + +3. READ gitnexus://cluster/Payment + → Members: processPayment, validateCard, PaymentService + +4. READ gitnexus://process/CheckoutFlow + → handleCheckout → validateCart → processPayment → sendConfirmation +``` diff --git a/.claude/skills/gitnexus/impact-analysis/SKILL.md b/.claude/skills/gitnexus/impact-analysis/SKILL.md new file mode 100644 index 000000000..8f8db0084 --- /dev/null +++ b/.claude/skills/gitnexus/impact-analysis/SKILL.md @@ -0,0 +1,113 @@ +--- +name: gitnexus-impact-analysis +description: Analyze blast radius before making code changes +--- + +# Impact Analysis + +## Quick Start +``` +1. gitnexus_impact({target, direction: "upstream"}) → What depends on this +2. READ gitnexus://clusters → Check affected areas +3. READ gitnexus://processes → Affected execution flows +``` + +## When to Use +- "Is it safe to change this function?" +- "What will break if I modify X?" +- "Show me the blast radius" +- "Who uses this code?" + +## Understanding Output + +| Depth | Risk Level | Meaning | +|-------|-----------|---------| +| d=1 | WILL BREAK | Direct callers/importers | +| d=2 | LIKELY AFFECTED | Indirect dependencies | +| d=3 | MAY NEED TESTING | Transitive effects | + +## Workflow Checklist +``` +Impact Analysis: +- [ ] gitnexus_impact(target, "upstream") to find dependents +- [ ] READ gitnexus://clusters to understand affected areas +- [ ] Check high-confidence (>0.8) dependencies first +- [ ] Count affected clusters (cross-cutting = higher risk) +- [ ] If >10 processes affected, consider splitting change +``` + +## Resource Reference + +### gitnexus://clusters +Check which clusters might be affected: +```yaml +clusters: + - name: Auth + symbols: 47 + - name: API + symbols: 32 +``` + +### gitnexus://processes +Find which processes touch the target: +```yaml +processes: + - name: LoginFlow + type: cross_community + steps: 5 +``` + +## Tool Reference + +### gitnexus_impact +Analyze blast radius: +``` +gitnexus_impact({ + target: "validateUser", + direction: "upstream", + minConfidence: 0.8, + maxDepth: 3 +}) + +→ d=1 (WILL BREAK): + - loginHandler (src/auth/login.ts:42) [CALLS, 100%] + - apiMiddleware (src/api/middleware.ts:15) [CALLS, 100%] + +→ d=2 (LIKELY AFFECTED): + - authRouter (src/routes/auth.ts:22) [CALLS, 95%] + +→ Affected Processes: LoginFlow, TokenRefresh +→ Risk: MEDIUM (3 processes) +``` + +## Risk Assessment + +| Affected | Risk | +|----------|------| +| <5 symbols, 1 cluster | LOW | +| 5-15 symbols, 1-2 clusters | MEDIUM | +| >15 symbols or 3+ clusters | HIGH | +| Critical path (auth, payments) | CRITICAL | + +## Pre-Change Checklist +``` +Before Committing: +- [ ] Run impact analysis +- [ ] Review all d=1 (WILL BREAK) items +- [ ] Verify test coverage for affected processes +- [ ] If risk > MEDIUM, get code review +- [ ] If cross-cluster, coordinate with other teams +``` + +## Example: "What breaks if I change validateUser?" + +``` +1. gitnexus_impact({target: "validateUser", direction: "upstream"}) + → d=1: loginHandler, apiMiddleware + → d=2: authRouter, sessionManager + +2. READ gitnexus://clusters + → Auth and API clusters affected + +3. Decision: 2 direct callers, 2 clusters = MEDIUM risk +``` diff --git a/.claude/skills/gitnexus/refactoring/SKILL.md b/.claude/skills/gitnexus/refactoring/SKILL.md new file mode 100644 index 000000000..1513a2ed6 --- /dev/null +++ b/.claude/skills/gitnexus/refactoring/SKILL.md @@ -0,0 +1,118 @@ +--- +name: gitnexus-refactoring +description: Plan safe refactors using blast radius and dependency mapping +--- + +# Refactoring with GitNexus + +## Quick Start +``` +1. gitnexus_impact({target, direction: "upstream"}) → Map all dependents +2. READ gitnexus://schema → Understand graph structure +3. gitnexus_cypher → Find all references +``` + +## When to Use +- "Rename this function safely" +- "Extract this into a module" +- "Split this service" +- "Refactor without breaking things" + +## Checklists + +### Rename Symbol +``` +Rename Refactoring: +- [ ] gitnexus_impact(oldName, "upstream") — find all callers +- [ ] gitnexus_search(oldName) — find string literals +- [ ] Check for reflection/dynamic references +- [ ] Update in order: interface → implementation → usages +- [ ] Run tests for affected processes +``` + +### Extract Module +``` +Extract Module: +- [ ] gitnexus_explore(target, "symbol") — map dependencies +- [ ] gitnexus_impact(target, "upstream") — find callers +- [ ] READ gitnexus://cluster/{name} — check cohesion +- [ ] Define new module interface +- [ ] Update imports across affected files +``` + +### Split Function +``` +Split Function: +- [ ] gitnexus_explore(target, "symbol") — understand callees +- [ ] Group related logic +- [ ] gitnexus_impact — verify callers won't break +- [ ] Create new functions +- [ ] Update callers +``` + +## Resource Reference + +### gitnexus://schema +Graph structure for Cypher queries: +```yaml +nodes: [Function, Class, Method, Community, Process] +relationships: [CALLS, IMPORTS, EXTENDS, MEMBER_OF] + +example_queries: + find_callers: | + MATCH (caller)-[:CodeRelation {type: 'CALLS'}]->(f:Function {name: "X"}) + RETURN caller.name +``` + +### gitnexus://cluster/{name} +Check if extraction preserves cohesion: +```yaml +name: Payment +cohesion: 92% +members: [processPayment, validateCard, PaymentService] +``` + +## Tool Reference + +### Finding all references +```cypher +MATCH (caller)-[:CodeRelation {type: 'CALLS'}]->(f:Function {name: "validateUser"}) +RETURN caller.name, caller.filePath +ORDER BY caller.filePath +``` + +### Finding imports of a module +```cypher +MATCH (importer)-[:CodeRelation {type: 'IMPORTS'}]->(f:File {name: "utils.ts"}) +RETURN importer.name, importer.filePath +``` + +## Example: Safely Rename `validateUser` to `authenticateUser` + +``` +1. gitnexus_impact({target: "validateUser", direction: "upstream"}) + → loginHandler, apiMiddleware, testUtils + +2. gitnexus_search({query: "validateUser"}) + → Found in: config.json (dynamic reference!) + +3. READ gitnexus://processes + → LoginFlow, TokenRefresh, APIGateway + +4. Plan update order: + 1. Update declaration in auth.ts + 2. Update config.json string reference + 3. Update loginHandler + 4. Update apiMiddleware + 5. Run tests for LoginFlow, TokenRefresh +``` + +## Refactoring Safety Rules + +| Risk Factor | Mitigation | +|-------------|------------| +| Many callers (>5) | Update in small batches | +| Cross-cluster | Coordinate with other teams | +| String references | Search for dynamic usage | +| Reflection | Check for dynamic invocation | +| External exports | May break downstream repos | diff --git a/.cursor/plans/enhance_523ca41c.plan.md b/.cursor/plans/enhance_523ca41c.plan.md deleted file mode 100644 index 471e13f67..000000000 --- a/.cursor/plans/enhance_523ca41c.plan.md +++ /dev/null @@ -1,239 +0,0 @@ ---- -name: Enhance -overview: Restructure GitNexus LLM tools to leverage clusters and processes for better code understanding. Remove unused highlight tool, add new tools (explore, overview), enhance existing tools with cluster/process context, and improve impact analysis reliability. -todos: [] ---- - -# Enhanced LLM Tools with Cluster and Process Integration - -## Summary - -Consolidate GitNexus from 6 tools to **7 focused tools** that leverage the pre-computed clusters (Communities) and processes for richer context. Remove the highlight tool, add `explore` and `overview` tools, and enhance `search` and `blastRadius` with cluster/process awareness. - -## Final Tool Set - -| Tool | Status | Purpose ||------|--------|---------|| `search` | Enhance | Hybrid search + group results by process/cluster || `grep` | Keep | Regex pattern search || `read` | Keep | Read file content || `explore` | **New** | Deep dive on one symbol, cluster, or process || `overview` | **New** | Codebase map (all clusters + all processes) || `impact` | Enhance | Rename from blastRadius, add process/cluster context, increase limits || `cypher` | Keep | Raw graph queries || `highlight` | **Remove** | No longer needed | - -## Architecture - -```mermaid -flowchart TD - subgraph tools [LLM Tools Layer] - search[search] - grep[grep] - read[read] - explore[explore] - overview[overview] - impact[impact] - cypher[cypher] - end - - subgraph graph [Knowledge Graph] - nodes[Nodes: File, Function, Class...] - communities[Community Nodes] - processes[Process Nodes] - edges[CodeRelation Edges] - memberOf[MEMBER_OF Edges] - stepIn[STEP_IN_PROCESS Edges] - end - - search --> edges - search --> communities - search --> processes - explore --> communities - explore --> processes - explore --> memberOf - explore --> stepIn - overview --> communities - overview --> processes - impact --> edges - impact --> communities - impact --> processes - cypher --> graph -``` - - - -## File Changes - -### 1. Remove Highlight Tool - -**File:** [gitnexus/src/core/llm/tools.ts](gitnexus/src/core/llm/tools.ts) - -- Delete the `highlightTool` definition (lines ~395-414) -- Remove `highlightTool` from the returned array (line ~862) -- Remove highlight marker logic from `blastRadius` output (line ~814-816) - -**File:** [gitnexus/src/core/llm/agent.ts](gitnexus/src/core/llm/agent.ts) - -- Remove highlight references from system prompt (lines 70, 77) -- Update tool list in prompt to reflect new tools - -**File:** [gitnexus/src/core/llm/types.ts](gitnexus/src/core/llm/types.ts) - -- Remove `'highlight'` from `AgentStreamChunk.type` union (line 180) -- Remove `highlightNodeIds` property (line 187-188) - -### 2. Add `explore` Tool - -**File:** [gitnexus/src/core/llm/tools.ts](gitnexus/src/core/llm/tools.ts)New tool that auto-detects target type and returns comprehensive context: - -```typescript -explore({ - target: string, // Name of symbol, cluster, or process - type?: 'symbol' | 'cluster' | 'process' // Optional, auto-detected -}) -``` - -**Functionality:** - -- For symbols: Query node, get MEMBER_OF cluster, get STEP_IN_PROCESS processes, get 1-hop connections -- For clusters: Query Community node, get members via MEMBER_OF, get processes that touch this cluster -- For processes: Query Process node, get steps via STEP_IN_PROCESS with step order, get clusters touched - -**Cypher queries needed:** - -```cypher --- Symbol cluster membership -MATCH (s {name: $name})-[:CodeRelation {type: 'MEMBER_OF'}]->(c:Community) -RETURN c.label, c.description - --- Symbol process participation -MATCH (s {name: $name})-[r:CodeRelation {type: 'STEP_IN_PROCESS'}]->(p:Process) -RETURN p.label, r.step, p.stepCount - --- Process steps in order -MATCH (s)-[r:CodeRelation {type: 'STEP_IN_PROCESS'}]->(p:Process {id: $processId}) -RETURN s.name, s.filePath, r.step -ORDER BY r.step -``` - - - -### 3. Add `overview` Tool - -**File:** [gitnexus/src/core/llm/tools.ts](gitnexus/src/core/llm/tools.ts)New tool that returns codebase structure: - -```typescript -overview() // No parameters -``` - -**Functionality:** - -- Query all Community nodes with member counts -- Query all Process nodes with step counts and types -- Calculate cluster dependencies (cross-cluster CALLS) -- Identify critical paths (most connected processes) - -**Output format:** - -```javascript -CLUSTERS (N total): -| Cluster | Symbols | Cohesion | Description | -... - -PROCESSES (N total): -| Process | Steps | Type | Clusters | -... - -CRITICAL PATHS: -- LoginFlow (45 edges) -... -``` - - - -### 4. Enhance `search` Tool - -**File:** [gitnexus/src/core/llm/tools.ts](gitnexus/src/core/llm/tools.ts)Modify existing search to group results by process:**Current:** Returns flat list with 1-hop connections**Enhanced:** Groups results by process, adds cluster context**Changes:** - -- After hybrid search, query STEP_IN_PROCESS for each result -- Group results by process ID -- Sort processes by number of matching results (relevance) -- Add cluster label for each result via MEMBER_OF query -- Keep 1-hop connections as optional detail - -**New parameter:** - -```typescript -search({ - query: string, - groupByProcess?: boolean, // Default: true - limit?: number -}) -``` - - - -### 5. Enhance `impact` Tool (rename from blastRadius) - -**File:** [gitnexus/src/core/llm/tools.ts](gitnexus/src/core/llm/tools.ts)**Rename:** `blastRadiusTool` to `impactTool`**Enhancements:** - -1. Increase LIMIT clauses: 100 to 300 (depth 1), 100 to 200 (depth 2), 50 to 100 (depth 3) -2. Add affected processes section (query STEP_IN_PROCESS for all affected symbols) -3. Add affected clusters section (query MEMBER_OF for all affected symbols) -4. Add risk assessment summary -5. Surface confidence scores more prominently (group by confidence level) - -**New output sections:** - -```javascript -AFFECTED PROCESSES: -- LoginFlow - BROKEN at step 2 -- SignupFlow - BROKEN at step 1 - -AFFECTED CLUSTERS: -- Authentication (direct) -- API Routes (indirect) - -RISK: CRITICAL -- N direct callers -- N processes affected -- N clusters affected -``` - - - -### 6. Increase Process Detection Limits - -**File:** [gitnexus/src/core/ingestion/process-processor.ts](gitnexus/src/core/ingestion/process-processor.ts)Change default config (lines 27-32): - -```typescript -const DEFAULT_CONFIG: ProcessDetectionConfig = { - maxTraceDepth: 10, // Keep - maxBranching: 4, // Was 3 - maxProcesses: 75, // Was 50 - minSteps: 2, // Keep -}; -``` - - - -### 7. Update System Prompt - -**File:** [gitnexus/src/core/llm/agent.ts](gitnexus/src/core/llm/agent.ts)Update BASE_SYSTEM_PROMPT to reflect new tools: - -```javascript -## TOOLS -- **search** - Hybrid search. Results grouped by process with cluster context. -- **grep** - Regex pattern search for exact strings. -- **read** - Read file content. -- **explore** - Deep dive on a symbol, cluster, or process. Shows membership, participation, connections. -- **overview** - Codebase map showing all clusters and processes. -- **impact** - Impact analysis. Shows affected processes, clusters, and risk level. -- **cypher** - Raw Cypher queries against the graph. - -## GRAPH SCHEMA -Nodes: File, Folder, Function, Class, Interface, Method, Community, Process -Relations: CodeRelation with type: CONTAINS, DEFINES, IMPORTS, CALLS, EXTENDS, IMPLEMENTS, MEMBER_OF, STEP_IN_PROCESS -``` - - - -## Implementation Order - -1. Remove highlight tool (cleanup) -2. Increase process detection limits -3. Add overview tool (simplest new tool) -4. Add explore tool -5. Enhance impact tool \ No newline at end of file diff --git a/.cursorrules b/.cursorrules new file mode 100644 index 000000000..397f42422 --- /dev/null +++ b/.cursorrules @@ -0,0 +1,5 @@ +# AI Agent Rules + +Follow .gitnexus/RULES.md for all project context and coding guidelines. + +This project uses GitNexus MCP for code intelligence. See .gitnexus/RULES.md for available tools and best practices. diff --git a/.gitignore b/.gitignore index 0d9b76fbb..a92662bcb 100644 --- a/.gitignore +++ b/.gitignore @@ -41,3 +41,6 @@ coverage/ .env*.local .gitnexus + +# Generated files (should not be indexed) +repomix-output* diff --git a/.windsurfrules b/.windsurfrules new file mode 100644 index 000000000..397f42422 --- /dev/null +++ b/.windsurfrules @@ -0,0 +1,5 @@ +# AI Agent Rules + +Follow .gitnexus/RULES.md for all project context and coding guidelines. + +This project uses GitNexus MCP for code intelligence. See .gitnexus/RULES.md for available tools and best practices. diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 000000000..662b1f929 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,81 @@ +# AI Agent Rules + +Follow .gitnexus/RULES.md for all project context and coding guidelines. + +This project uses GitNexus MCP for code intelligence. See .gitnexus/RULES.md for available tools and best practices. + + +# GitNexus MCP + +This project is indexed by GitNexus, providing AI agents with deep code intelligence. + +## Project: GitnexusV2 + +| Metric | Count | +|--------|-------| +| Files | 150 | +| Symbols | 930 | +| Relationships | 2411 | +| Communities | 280 | +| Processes | 75 | + +## Quick Start + +``` +1. READ gitnexus://context → Get codebase overview (~150 tokens) +2. READ gitnexus://clusters → See all functional clusters +3. READ gitnexus://cluster/{name} → Deep dive on specific cluster +4. gitnexus_search(query) → Find code by query +``` + +## Available Resources + +| Resource | Purpose | +|----------|---------| +| `gitnexus://context` | Codebase stats, tools, and resources overview | +| `gitnexus://clusters` | All clusters with symbol counts and cohesion | +| `gitnexus://cluster/{name}` | Cluster members and details | +| `gitnexus://processes` | All execution flows with types | +| `gitnexus://process/{name}` | Full process trace with steps | +| `gitnexus://schema` | Graph schema for Cypher queries | + +## Available Tools + +| Tool | Purpose | When to Use | +|------|---------|-------------| +| `search` | Semantic + keyword search | Finding code by query | +| `overview` | List clusters & processes | Understanding architecture | +| `explore` | Deep dive on symbol/cluster/process | Detailed investigation | +| `impact` | Blast radius analysis | Before making changes | +| `cypher` | Raw graph queries | Complex analysis | + +## Workflow Examples + +### Exploring the Codebase +``` +READ gitnexus://context → Stats and overview +READ gitnexus://clusters → Find relevant cluster +READ gitnexus://cluster/Auth → Explore Auth cluster +gitnexus_explore("validateUser", "symbol") → Detailed symbol info +``` + +### Planning a Change +``` +gitnexus_impact("UserService", "upstream") → See what breaks +READ gitnexus://processes → Check affected flows +gitnexus_explore("LoginFlow", "process") → Trace execution +``` + +## Graph Schema + +**Nodes:** File, Function, Class, Interface, Method, Community, Process + +**Relationships:** CALLS, IMPORTS, EXTENDS, IMPLEMENTS, DEFINES, MEMBER_OF, STEP_IN_PROCESS + +```cypher +// Example: Find callers of a function +MATCH (caller)-[:CodeRelation {type: 'CALLS'}]->(f:Function {name: "myFunc"}) +RETURN caller.name, caller.filePath +``` + + diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 000000000..69c4aed5a --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,75 @@ + +# GitNexus MCP + +This project is indexed by GitNexus, providing AI agents with deep code intelligence. + +## Project: GitnexusV2 + +| Metric | Count | +|--------|-------| +| Files | 150 | +| Symbols | 930 | +| Relationships | 2411 | +| Communities | 280 | +| Processes | 75 | + +## Quick Start + +``` +1. READ gitnexus://context → Get codebase overview (~150 tokens) +2. READ gitnexus://clusters → See all functional clusters +3. READ gitnexus://cluster/{name} → Deep dive on specific cluster +4. gitnexus_search(query) → Find code by query +``` + +## Available Resources + +| Resource | Purpose | +|----------|---------| +| `gitnexus://context` | Codebase stats, tools, and resources overview | +| `gitnexus://clusters` | All clusters with symbol counts and cohesion | +| `gitnexus://cluster/{name}` | Cluster members and details | +| `gitnexus://processes` | All execution flows with types | +| `gitnexus://process/{name}` | Full process trace with steps | +| `gitnexus://schema` | Graph schema for Cypher queries | + +## Available Tools + +| Tool | Purpose | When to Use | +|------|---------|-------------| +| `search` | Semantic + keyword search | Finding code by query | +| `overview` | List clusters & processes | Understanding architecture | +| `explore` | Deep dive on symbol/cluster/process | Detailed investigation | +| `impact` | Blast radius analysis | Before making changes | +| `cypher` | Raw graph queries | Complex analysis | + +## Workflow Examples + +### Exploring the Codebase +``` +READ gitnexus://context → Stats and overview +READ gitnexus://clusters → Find relevant cluster +READ gitnexus://cluster/Auth → Explore Auth cluster +gitnexus_explore("validateUser", "symbol") → Detailed symbol info +``` + +### Planning a Change +``` +gitnexus_impact("UserService", "upstream") → See what breaks +READ gitnexus://processes → Check affected flows +gitnexus_explore("LoginFlow", "process") → Trace execution +``` + +## Graph Schema + +**Nodes:** File, Function, Class, Interface, Method, Community, Process + +**Relationships:** CALLS, IMPORTS, EXTENDS, IMPLEMENTS, DEFINES, MEMBER_OF, STEP_IN_PROCESS + +```cypher +// Example: Find callers of a function +MATCH (caller)-[:CodeRelation {type: 'CALLS'}]->(f:Function {name: "myFunc"}) +RETURN caller.name, caller.filePath +``` + + diff --git a/gitnexus/skills/debugging.md b/gitnexus/skills/debugging.md index ac75c13d2..3d8dab1b7 100644 --- a/gitnexus/skills/debugging.md +++ b/gitnexus/skills/debugging.md @@ -6,9 +6,11 @@ description: Trace bugs through call chains using knowledge graph # Debugging with GitNexus ## Quick Start -1. `gitnexus_search(query)` → Find code related to the error -2. `gitnexus_explore(name, "symbol")` → Get callers and callees -3. `gitnexus_cypher` → Trace specific dependency paths +``` +1. gitnexus_search({query}) → Find code related to error +2. gitnexus_explore({name, type: "symbol"}) → Get callers and callees +3. READ gitnexus://process/{name} → Trace execution flow +``` ## When to Use - "Why is this function failing?" @@ -16,92 +18,80 @@ description: Trace bugs through call chains using knowledge graph - "Who calls this method?" - "Debug the payment issue" -## Workflow +## Workflow Checklist ``` Bug Investigation: - [ ] Understand the symptom (error message, behavior) - [ ] gitnexus_search to find related code - [ ] Identify the suspect function - [ ] gitnexus_explore to see callers/callees -- [ ] Check which processes the suspect is in -- [ ] Trace dependencies with gitnexus_cypher -- [ ] Form hypothesis and verify +- [ ] READ gitnexus://process/{name} if suspect is in a process +- [ ] READ gitnexus://schema for Cypher query help +- [ ] gitnexus_cypher for custom traces +``` + +## Resource Reference + +### gitnexus://schema +Graph schema for writing Cypher queries: +```yaml +nodes: [Function, Class, Method, File, Community, Process] +relationships: [CALLS, IMPORTS, EXTENDS, IMPLEMENTS, MEMBER_OF, STEP_IN_PROCESS] +example_queries: + find_callers: | + MATCH (caller)-[:CodeRelation {type: 'CALLS'}]->(f:Function {name: "X"}) + RETURN caller.name +``` + +### gitnexus://process/{name} +Trace execution flow to find where bug might occur: +```yaml +name: CheckoutFlow +trace: + 1: handleCheckout + 2: validateCart + 3: processPayment ← bug here? + 4: sendConfirmation ``` ## Tool Reference ### gitnexus_search -Find code related to error or symptom. +Find code related to error or symptom: ``` -gitnexus_search({ - query: "payment validation error", - depth: "full", - groupByProcess: true -}) -→ validatePayment, handlePaymentError, PaymentException -→ Grouped by: CheckoutFlow, RefundFlow +gitnexus_search({query: "payment validation error", depth: "full"}) ``` -### gitnexus_explore (for symbol) -Get symbol context. +### gitnexus_explore +Get symbol context: ``` gitnexus_explore({name: "validatePayment", type: "symbol"}) → Callers: processCheckout, webhookHandler → Callees: verifyCard, fetchRates -→ Cluster: Payment -→ Processes: CheckoutFlow, RefundFlow ``` ### gitnexus_cypher -Custom graph queries for tracing. - -**Find all callers of a function:** -``` -gitnexus_cypher({query: ` - MATCH (caller)-[:CodeRelation {type: 'CALLS'}]->(f:Function {name: "validatePayment"}) - RETURN caller.name, caller.filePath -`}) -``` - -**Find what a function calls:** -``` -gitnexus_cypher({query: ` - MATCH (f:Function {name: "validatePayment"})-[:CodeRelation {type: 'CALLS'}]->(callee) - RETURN callee.name, callee.filePath -`}) -``` - -**Trace call chain (2 hops):** -``` -gitnexus_cypher({query: ` - MATCH path = (a)-[:CodeRelation {type: 'CALLS'}*1..2]->(b:Function {name: "validatePayment"}) - RETURN [n IN nodes(path) | n.name] AS chain -`}) +Custom graph queries for tracing: +```cypher +// Trace call chain (2 hops) +MATCH path = (a)-[:CodeRelation {type: 'CALLS'}*1..2]->(b:Function {name: "validatePayment"}) +RETURN [n IN nodes(path) | n.name] AS chain ``` ## Example: "Payment endpoint returns 500 intermittently" -1. **Search for payment error handling** - ``` - gitnexus_search({query: "payment error handling", depth: "full"}) - ``` +``` +1. gitnexus_search({query: "payment error handling"}) → validatePayment, handlePaymentError, PaymentException -2. **Explore the suspect function** - ``` - gitnexus_explore({name: "validatePayment", type: "symbol"}) - ``` - → Callers: processCheckout, webhookHandler - → Callees: verifyCard, **fetchRates** (external API!) +2. gitnexus_explore({name: "validatePayment", type: "symbol"}) + → Callees: verifyCard, fetchRates (external API!) -3. **Form hypothesis** - `fetchRates` calls external currency API → intermittent failures when API is slow +3. READ gitnexus://process/CheckoutFlow + → Step 3: validatePayment → calls external API -4. **Verify** - Read `fetchRates` source to check timeout/error handling - -5. **Root cause** - `fetchRates` doesn't handle timeout properly → fix with retry logic +4. Root cause: fetchRates calls external API without proper timeout +``` ## Debugging Patterns @@ -111,12 +101,3 @@ gitnexus_cypher({query: ` | Wrong return value | Trace data flow through callees | | Intermittent failure | Look for external calls, timeouts | | Performance issue | Find hot paths via callers count | -| Recent regression | Check recently modified files | - -## When to Use Something Else - -| Need | Use Instead | -|------|-------------| -| Explore unfamiliar code | `gitnexus-exploring` skill | -| Check change impact | `gitnexus-impact-analysis` skill | -| Plan refactoring | `gitnexus-refactoring` skill | diff --git a/gitnexus/skills/exploring.md b/gitnexus/skills/exploring.md index 8488c13ae..2baa7f31e 100644 --- a/gitnexus/skills/exploring.md +++ b/gitnexus/skills/exploring.md @@ -6,9 +6,11 @@ description: Navigate unfamiliar code using GitNexus knowledge graph # Exploring Codebases ## Quick Start -1. `gitnexus_context` → Get codebase stats and hotspots -2. `gitnexus_overview` → See all clusters and processes -3. `gitnexus_explore(name, "cluster")` → Deep dive on a cluster +``` +1. READ gitnexus://context → Get codebase overview (~150 tokens) +2. READ gitnexus://clusters → See all functional clusters +3. READ gitnexus://cluster/{name} → Deep dive on specific cluster +``` ## When to Use - "How does authentication work?" @@ -16,81 +18,94 @@ description: Navigate unfamiliar code using GitNexus knowledge graph - "Show me the main components" - "Where is the database logic?" -## Workflow +## Workflow Checklist ``` -Exploring Codebase: -- [ ] Call gitnexus_context to get codebase overview -- [ ] Call gitnexus_overview to list clusters +Exploration Progress: +- [ ] READ gitnexus://context for codebase overview +- [ ] READ gitnexus://clusters to list all clusters - [ ] Identify the relevant cluster by name -- [ ] Call gitnexus_explore(clusterName, "cluster") to see members -- [ ] Call gitnexus_explore(symbolName, "symbol") for specific functions +- [ ] READ gitnexus://cluster/{name} for cluster details +- [ ] Use gitnexus_explore for specific symbols ``` -## Tool Reference +## Resource Reference -### gitnexus_context -Get codebase overview. **Call first.** -``` -gitnexus_context() -→ Stats: 2,400 nodes, 12 clusters, 45 processes -→ Hotspots: most connected functions +### gitnexus://context +Codebase overview. **Read first.** +```yaml +project: my-app +stats: + files: 42 + symbols: 918 + clusters: 12 + processes: 45 +tools_available: [search, explore, impact, overview, cypher] +resources_available: [clusters, processes, cluster/{name}, process/{name}] ``` -### gitnexus_overview -List all clusters and processes. +### gitnexus://clusters +All functional clusters with cohesion scores. +```yaml +clusters: + - name: "Auth" + symbols: 47 + cohesion: 92% + - name: "Database" + symbols: 32 + cohesion: 88% ``` -gitnexus_overview({showClusters: true, showProcesses: true}) -→ Clusters: Auth, Database, API, ... -→ Processes: LoginFlow, CheckoutFlow, ... + +### gitnexus://cluster/{name} +Members of a specific cluster. +```yaml +name: Auth +symbols: 47 +cohesion: 92% +members: + - name: validateUser + type: Function + file: src/auth/validator.ts ``` +### gitnexus://process/{name} +Full execution trace. +```yaml +name: LoginFlow +type: cross_community +steps: + 1: handleLogin (src/auth/handler.ts) + 2: validateUser (src/auth/validator.ts) + 3: createSession (src/auth/session.ts) +``` + +## Tool Reference (When Resources Aren't Enough) + ### gitnexus_explore -Deep dive on symbol, cluster, or process. +For detailed symbol context with callers/callees: ``` -gitnexus_explore({name: "Auth", type: "cluster"}) -→ Members: validateUser, checkToken, hashPassword -→ Processes using this cluster - gitnexus_explore({name: "validateUser", type: "symbol"}) → Callers: loginHandler, apiMiddleware → Callees: checkToken, getUserById -→ Cluster: Auth +``` -gitnexus_explore({name: "LoginFlow", type: "process"}) -→ Steps: handleLogin → validateUser → createSession → respond +### gitnexus_search +For finding code by query: +``` +gitnexus_search({query: "payment validation", depth: "full"}) ``` ## Example: "How does payment processing work?" -1. **Get overview** - ``` - gitnexus_context() - ``` - → 2,400 nodes, 12 clusters, 45 processes +``` +1. READ gitnexus://context + → 918 symbols, 12 clusters -2. **Find payment cluster** - ``` - gitnexus_overview({showClusters: true}) - ``` - → Clusters: Auth, **Payment**, Database, API, ... +2. READ gitnexus://clusters + → Clusters: Auth, Payment, Database, API... -3. **Explore payment cluster** - ``` - gitnexus_explore({name: "Payment", type: "cluster"}) - ``` - → Members: processPayment, validateCard, PaymentService, ... - → Processes: CheckoutFlow, RefundFlow +3. READ gitnexus://cluster/Payment + → Members: processPayment, validateCard, PaymentService -4. **Trace the checkout flow** - ``` - gitnexus_explore({name: "CheckoutFlow", type: "process"}) - ``` +4. READ gitnexus://process/CheckoutFlow → handleCheckout → validateCart → processPayment → sendConfirmation - -## When to Use Something Else - -| Need | Use Instead | -|------|-------------| -| Debug failing code | `gitnexus-debugging` skill | -| Check change impact | `gitnexus-impact-analysis` skill | -| Plan refactoring | `gitnexus-refactoring` skill | +``` diff --git a/gitnexus/skills/impact-analysis.md b/gitnexus/skills/impact-analysis.md index cc3a85e8f..8f8db0084 100644 --- a/gitnexus/skills/impact-analysis.md +++ b/gitnexus/skills/impact-analysis.md @@ -6,9 +6,11 @@ description: Analyze blast radius before making code changes # Impact Analysis ## Quick Start -1. `gitnexus_impact(target, "upstream")` → What depends on this (will break) -2. Review affected processes and clusters -3. Assess risk level +``` +1. gitnexus_impact({target, direction: "upstream"}) → What depends on this +2. READ gitnexus://clusters → Check affected areas +3. READ gitnexus://processes → Affected execution flows +``` ## When to Use - "Is it safe to change this function?" @@ -24,84 +26,61 @@ description: Analyze blast radius before making code changes | d=2 | LIKELY AFFECTED | Indirect dependencies | | d=3 | MAY NEED TESTING | Transitive effects | -| Confidence | Meaning | -|------------|---------| -| 1.0 | Certain (static analysis) | -| 0.8+ | High confidence | -| <0.8 | Fuzzy match (may be false positive) | - -## Workflow +## Workflow Checklist ``` Impact Analysis: - [ ] gitnexus_impact(target, "upstream") to find dependents -- [ ] Review affected processes +- [ ] READ gitnexus://clusters to understand affected areas - [ ] Check high-confidence (>0.8) dependencies first - [ ] Count affected clusters (cross-cutting = higher risk) - [ ] If >10 processes affected, consider splitting change ``` +## Resource Reference + +### gitnexus://clusters +Check which clusters might be affected: +```yaml +clusters: + - name: Auth + symbols: 47 + - name: API + symbols: 32 +``` + +### gitnexus://processes +Find which processes touch the target: +```yaml +processes: + - name: LoginFlow + type: cross_community + steps: 5 +``` + ## Tool Reference ### gitnexus_impact -Analyze blast radius. +Analyze blast radius: ``` gitnexus_impact({ target: "validateUser", direction: "upstream", minConfidence: 0.8, - maxDepth: 3, - includeTests: false + maxDepth: 3 }) + +→ d=1 (WILL BREAK): + - loginHandler (src/auth/login.ts:42) [CALLS, 100%] + - apiMiddleware (src/api/middleware.ts:15) [CALLS, 100%] + +→ d=2 (LIKELY AFFECTED): + - authRouter (src/routes/auth.ts:22) [CALLS, 95%] + +→ Affected Processes: LoginFlow, TokenRefresh +→ Risk: MEDIUM (3 processes) ``` -**Parameters:** -- `target` — Function, class, or file name -- `direction` — "upstream" (what depends on this) or "downstream" (what this depends on) -- `minConfidence` — Filter out fuzzy matches (default: 0.7) -- `maxDepth` — How far to trace (default: 3) -- `includeTests` — Include test files (default: false) - -**Output:** -``` -Impact Analysis for "validateUser": - -d=1 (WILL BREAK): -- loginHandler (src/auth/login.ts:42) [CALLS, 100%] -- apiMiddleware (src/api/middleware.ts:15) [CALLS, 100%] - -d=2 (LIKELY AFFECTED): -- authRouter (src/routes/auth.ts:22) [CALLS, 95%] -- sessionManager (src/session/manager.ts:88) [CALLS, 90%] - -Affected Processes: LoginFlow, TokenRefresh, APIGateway -Affected Clusters: Auth, API - -Risk: MEDIUM (3 processes, 2 clusters) -``` - -## Example: "What breaks if I change validateUser?" - -1. **Run impact analysis** - ``` - gitnexus_impact({ - target: "validateUser", - direction: "upstream", - minConfidence: 0.8 - }) - ``` - -2. **Review output** - - d=1: loginHandler, apiMiddleware (WILL BREAK) - - d=2: authRouter, sessionManager (LIKELY AFFECTED) - - Processes: LoginFlow, TokenRefresh, APIGateway - - Risk: MEDIUM - -3. **Decision** - - 2 direct callers → manageable - - 3 processes → need to test all three - - Auth + API clusters → may need API team coordination - -## Risk Assessment Guide +## Risk Assessment | Affected | Risk | |----------|------| @@ -120,10 +99,15 @@ Before Committing: - [ ] If cross-cluster, coordinate with other teams ``` -## When to Use Something Else +## Example: "What breaks if I change validateUser?" -| Need | Use Instead | -|------|-------------| -| Explore unfamiliar code | `gitnexus-exploring` skill | -| Debug failing code | `gitnexus-debugging` skill | -| Plan large refactors | `gitnexus-refactoring` skill | +``` +1. gitnexus_impact({target: "validateUser", direction: "upstream"}) + → d=1: loginHandler, apiMiddleware + → d=2: authRouter, sessionManager + +2. READ gitnexus://clusters + → Auth and API clusters affected + +3. Decision: 2 direct callers, 2 clusters = MEDIUM risk +``` diff --git a/gitnexus/skills/refactoring.md b/gitnexus/skills/refactoring.md index 0bd0c84ea..1513a2ed6 100644 --- a/gitnexus/skills/refactoring.md +++ b/gitnexus/skills/refactoring.md @@ -6,9 +6,11 @@ description: Plan safe refactors using blast radius and dependency mapping # Refactoring with GitNexus ## Quick Start -1. `gitnexus_impact(target, "upstream")` → Map all dependents -2. `gitnexus_cypher` → Find all references -3. Plan changes in dependency order +``` +1. gitnexus_impact({target, direction: "upstream"}) → Map all dependents +2. READ gitnexus://schema → Understand graph structure +3. gitnexus_cypher → Find all references +``` ## When to Use - "Rename this function safely" @@ -33,10 +35,9 @@ Rename Refactoring: Extract Module: - [ ] gitnexus_explore(target, "symbol") — map dependencies - [ ] gitnexus_impact(target, "upstream") — find callers +- [ ] READ gitnexus://cluster/{name} — check cohesion - [ ] Define new module interface -- [ ] Move code to new module - [ ] Update imports across affected files -- [ ] Verify no circular dependencies ``` ### Split Function @@ -46,102 +47,65 @@ Split Function: - [ ] Group related logic - [ ] gitnexus_impact — verify callers won't break - [ ] Create new functions -- [ ] Update callers to use correct function +- [ ] Update callers +``` + +## Resource Reference + +### gitnexus://schema +Graph structure for Cypher queries: +```yaml +nodes: [Function, Class, Method, Community, Process] +relationships: [CALLS, IMPORTS, EXTENDS, MEMBER_OF] + +example_queries: + find_callers: | + MATCH (caller)-[:CodeRelation {type: 'CALLS'}]->(f:Function {name: "X"}) + RETURN caller.name +``` + +### gitnexus://cluster/{name} +Check if extraction preserves cohesion: +```yaml +name: Payment +cohesion: 92% +members: [processPayment, validateCard, PaymentService] ``` ## Tool Reference ### Finding all references -``` -gitnexus_cypher({query: ` - MATCH (caller)-[:CodeRelation {type: 'CALLS'}]->(f:Function {name: "validateUser"}) - RETURN caller.name, caller.filePath - ORDER BY caller.filePath -`}) +```cypher +MATCH (caller)-[:CodeRelation {type: 'CALLS'}]->(f:Function {name: "validateUser"}) +RETURN caller.name, caller.filePath +ORDER BY caller.filePath ``` -### Finding symbols by name pattern -``` -gitnexus_cypher({query: ` - MATCH (s) - WHERE s.name CONTAINS "Payment" - RETURN s.name, labels(s)[0] AS type, s.filePath -`}) -``` - -### Finding all imports of a module -``` -gitnexus_cypher({query: ` - MATCH (importer)-[:CodeRelation {type: 'IMPORTS'}]->(f:File {name: "utils.ts"}) - RETURN importer.name, importer.filePath -`}) -``` - -### Finding community/cluster members -``` -gitnexus_cypher({query: ` - MATCH (s)-[:CodeRelation {type: 'MEMBER_OF'}]->(c:Community {label: "Auth"}) - RETURN s.name, labels(s)[0] AS type -`}) +### Finding imports of a module +```cypher +MATCH (importer)-[:CodeRelation {type: 'IMPORTS'}]->(f:File {name: "utils.ts"}) +RETURN importer.name, importer.filePath ``` ## Example: Safely Rename `validateUser` to `authenticateUser` -1. **Map all callers** - ``` - gitnexus_impact({ - target: "validateUser", - direction: "upstream", - minConfidence: 0.9 - }) - ``` +``` +1. gitnexus_impact({target: "validateUser", direction: "upstream"}) → loginHandler, apiMiddleware, testUtils -2. **Check for string references** - ``` - gitnexus_search({query: "validateUser"}) - ``` +2. gitnexus_search({query: "validateUser"}) → Found in: config.json (dynamic reference!) -3. **Get affected processes** - ``` - gitnexus_explore({name: "validateUser", type: "symbol"}) - ``` - → Processes: LoginFlow, TokenRefresh, APIGateway +3. READ gitnexus://processes + → LoginFlow, TokenRefresh, APIGateway -4. **Plan update order** +4. Plan update order: 1. Update declaration in auth.ts 2. Update config.json string reference 3. Update loginHandler 4. Update apiMiddleware - 5. Update testUtils - 6. Run: LoginFlow, TokenRefresh, APIGateway tests - -## Example: Extract PaymentValidator Module - -1. **Understand current dependencies** - ``` - gitnexus_explore({name: "validatePayment", type: "symbol"}) - ``` - → Callees: verifyCard, checkAmount, fetchRates - → Callers: processCheckout, refundHandler - -2. **Map blast radius** - ``` - gitnexus_impact({target: "validatePayment", direction: "upstream"}) - ``` - → 2 direct callers, 3 processes - -3. **Create new module** - - Move validatePayment, verifyCard, checkAmount to PaymentValidator - - Keep fetchRates as external dependency (inject it) - -4. **Update callers** - - processCheckout: import { validatePayment } from './PaymentValidator' - - refundHandler: import { validatePayment } from './PaymentValidator' - -5. **Verify** - - Run tests for CheckoutFlow, RefundFlow processes + 5. Run tests for LoginFlow, TokenRefresh +``` ## Refactoring Safety Rules @@ -152,11 +116,3 @@ gitnexus_cypher({query: ` | String references | Search for dynamic usage | | Reflection | Check for dynamic invocation | | External exports | May break downstream repos | - -## When to Use Something Else - -| Need | Use Instead | -|------|-------------| -| Explore unfamiliar code | `gitnexus-exploring` skill | -| Debug failing code | `gitnexus-debugging` skill | -| Quick impact check | `gitnexus-impact-analysis` skill | diff --git a/gitnexus/src/cli/ai-context.ts b/gitnexus/src/cli/ai-context.ts index 8dcf1bd36..dcc8f3087 100644 --- a/gitnexus/src/cli/ai-context.ts +++ b/gitnexus/src/cli/ai-context.ts @@ -26,7 +26,7 @@ const GITNEXUS_START_MARKER = ''; const GITNEXUS_END_MARKER = ''; /** - * Generate the full GitNexus context content + * Generate the full GitNexus context content (resources-first approach) */ function generateGitNexusContent(projectName: string, stats: RepoStats): string { return `${GITNEXUS_START_MARKER} @@ -46,71 +46,67 @@ This project is indexed by GitNexus, providing AI agents with deep code intellig ## Quick Start -1. **Call \`context\` first** — Understand the codebase structure -2. **Use \`search\` for discovery** — Semantic search with graph context -3. **Use \`impact\` before refactoring** — Understand blast radius +\`\`\` +1. READ gitnexus://context → Get codebase overview (~150 tokens) +2. READ gitnexus://clusters → See all functional clusters +3. READ gitnexus://cluster/{name} → Deep dive on specific cluster +4. gitnexus_search(query) → Find code by query +\`\`\` + +## Available Resources + +| Resource | Purpose | +|----------|---------| +| \`gitnexus://context\` | Codebase stats, tools, and resources overview | +| \`gitnexus://clusters\` | All clusters with symbol counts and cohesion | +| \`gitnexus://cluster/{name}\` | Cluster members and details | +| \`gitnexus://processes\` | All execution flows with types | +| \`gitnexus://process/{name}\` | Full process trace with steps | +| \`gitnexus://schema\` | Graph schema for Cypher queries | ## Available Tools | Tool | Purpose | When to Use | |------|---------|-------------| -| \`context\` | Codebase overview | Start of conversation | -| \`search\` | Semantic + keyword search | Finding code | +| \`search\` | Semantic + keyword search | Finding code by query | | \`overview\` | List clusters & processes | Understanding architecture | | \`explore\` | Deep dive on symbol/cluster/process | Detailed investigation | | \`impact\` | Blast radius analysis | Before making changes | | \`cypher\` | Raw graph queries | Complex analysis | -## Tool Reference +## Workflow Examples -### \`context\` -Get codebase overview and stats. **Call this first.** - -### \`search\` +### Exploring the Codebase \`\`\` -search(query: "authentication middleware", depth: "full") -\`\`\` -- \`depth: "definitions"\` — Symbol signatures only (default) -- \`depth: "full"\` — Symbols + all relationships - -### \`explore\` -\`\`\` -explore(name: "validateUser", type: "symbol") -explore(name: "Authentication", type: "cluster") -explore(name: "LoginFlow", type: "process") +READ gitnexus://context → Stats and overview +READ gitnexus://clusters → Find relevant cluster +READ gitnexus://cluster/Auth → Explore Auth cluster +gitnexus_explore("validateUser", "symbol") → Detailed symbol info \`\`\` -### \`impact\` +### Planning a Change \`\`\` -impact(target: "UserService", direction: "upstream", minConfidence: 0.8) +gitnexus_impact("UserService", "upstream") → See what breaks +READ gitnexus://processes → Check affected flows +gitnexus_explore("LoginFlow", "process") → Trace execution \`\`\` -- \`upstream\` — What depends on this (will break if changed) -- \`downstream\` — What this depends on -### \`cypher\` -Execute Cypher queries on the knowledge graph. +## Graph Schema -**Schema:** -- Nodes: \`File\`, \`Folder\`, \`Function\`, \`Class\`, \`Interface\`, \`Method\`, \`Community\`, \`Process\` -- Edges: \`CALLS\`, \`IMPORTS\`, \`EXTENDS\`, \`IMPLEMENTS\`, \`DEFINES\`, \`MEMBER_OF\`, \`STEP_IN_PROCESS\` +**Nodes:** File, Function, Class, Interface, Method, Community, Process + +**Relationships:** CALLS, IMPORTS, EXTENDS, IMPLEMENTS, DEFINES, MEMBER_OF, STEP_IN_PROCESS \`\`\`cypher -// Find all callers of a function -MATCH (caller)-[:CodeRelation {type: 'CALLS'}]->(f:Function {name: "myFunction"}) +// Example: Find callers of a function +MATCH (caller)-[:CodeRelation {type: 'CALLS'}]->(f:Function {name: "myFunc"}) RETURN caller.name, caller.filePath \`\`\` -## Key Concepts - -| Concept | Description | -|---------|-------------| -| **Community** | Functional cluster detected by Leiden algorithm | -| **Process** | Execution flow from entry point to terminal | -| **Confidence** | Relationship trust score (1.0 = certain, <0.8 = fuzzy) | - ${GITNEXUS_END_MARKER}`; } + /** * Check if a file exists */ diff --git a/gitnexus/src/mcp/local/local-backend.ts b/gitnexus/src/mcp/local/local-backend.ts index 4bcd13bcf..43b2dad1b 100644 --- a/gitnexus/src/mcp/local/local-backend.ts +++ b/gitnexus/src/mcp/local/local-backend.ts @@ -169,8 +169,6 @@ export class LocalBackend { } switch (method) { - case 'context': - return this.getContext(); case 'search': return this.search(params); case 'cypher': @@ -188,35 +186,6 @@ export class LocalBackend { } } - private async getContext(): Promise { - if (!this._context || !this.repo) { - return 'Repository not indexed. Run: gitnexus analyze'; - } - - const stats = this.repo.meta.stats || {}; - return [ - `# GitNexus: ${this._context.projectName}`, - '', - '## Stats', - `- Files: ${stats.files || 0}`, - `- Nodes: ${stats.nodes || 0}`, - `- Edges: ${stats.edges || 0}`, - `- Communities: ${stats.communities || 0}`, - `- Processes: ${stats.processes || 0}`, - '', - `Indexed: ${this.repo.meta.indexedAt}`, - `Commit: ${this.repo.meta.lastCommit?.slice(0, 7)}`, - '', - '## Available Tools', - '- **analyze**: Index/re-index repository', - '- **search**: Hybrid semantic + keyword search', - '- **cypher**: Graph queries (Cypher)', - '- **overview**: List communities and processes', - '- **explore**: Deep dive on symbol/cluster/process', - '- **impact**: Change impact analysis', - ].join('\n'); - } - private async search(params: { query: string; limit?: number; depth?: string; groupByProcess?: boolean }): Promise { await this.ensureInitialized(); diff --git a/gitnexus/src/mcp/resources.ts b/gitnexus/src/mcp/resources.ts new file mode 100644 index 000000000..d184bd46a --- /dev/null +++ b/gitnexus/src/mcp/resources.ts @@ -0,0 +1,311 @@ +/** + * MCP Resources + * + * Provides structured on-demand data to AI agents. + * Resources complement tools by offering lightweight, cacheable data. + */ + +import type { LocalBackend } from './local/local-backend.js'; + +export interface ResourceDefinition { + uri: string; + name: string; + description: string; + mimeType: string; +} + +export interface ResourceTemplate { + uriTemplate: string; + name: string; + description: string; + mimeType: string; +} + +/** + * Static resources available when codebase is indexed + */ +export function getResourceDefinitions(projectName: string): ResourceDefinition[] { + return [ + { + uri: 'gitnexus://context', + name: `${projectName} Overview`, + description: 'Codebase stats, hotspots, and available tools', + mimeType: 'text/yaml', + }, + { + uri: 'gitnexus://clusters', + name: 'All Clusters', + description: 'List of all functional clusters with stats', + mimeType: 'text/yaml', + }, + { + uri: 'gitnexus://processes', + name: 'All Processes', + description: 'List of all execution flows with types', + mimeType: 'text/yaml', + }, + { + uri: 'gitnexus://schema', + name: 'Graph Schema', + description: 'Node types and relationships for Cypher queries', + mimeType: 'text/yaml', + }, + ]; +} + +/** + * Dynamic resource templates + */ +export function getResourceTemplates(): ResourceTemplate[] { + return [ + { + uriTemplate: 'gitnexus://cluster/{name}', + name: 'Cluster Detail', + description: 'Deep dive into a specific cluster', + mimeType: 'text/yaml', + }, + { + uriTemplate: 'gitnexus://process/{name}', + name: 'Process Trace', + description: 'Step-by-step execution trace', + mimeType: 'text/yaml', + }, + ]; +} + +/** + * Read a resource and return its content + */ +export async function readResource(uri: string, backend: LocalBackend): Promise { + // Static resources + if (uri === 'gitnexus://context') { + return getContextResource(backend); + } + if (uri === 'gitnexus://clusters') { + return getClustersResource(backend); + } + if (uri === 'gitnexus://processes') { + return getProcessesResource(backend); + } + if (uri === 'gitnexus://schema') { + return getSchemaResource(); + } + + // Dynamic resources + if (uri.startsWith('gitnexus://cluster/')) { + const name = uri.replace('gitnexus://cluster/', ''); + return getClusterDetailResource(name, backend); + } + if (uri.startsWith('gitnexus://process/')) { + const name = uri.replace('gitnexus://process/', ''); + return getProcessDetailResource(name, backend); + } + + throw new Error(`Unknown resource: ${uri}`); +} + +/** + * Context resource - codebase overview + */ +async function getContextResource(backend: LocalBackend): Promise { + const context = backend.context; + if (!context) { + return 'error: No codebase loaded. Run: gitnexus analyze'; + } + + const lines: string[] = [ + `project: ${context.projectName}`, + 'stats:', + ` files: ${context.stats.fileCount}`, + ` symbols: ${context.stats.functionCount}`, + ` clusters: ${context.stats.communityCount}`, + ` processes: ${context.stats.processCount}`, + '', + 'tools_available:', + ' - search: Hybrid semantic + keyword search', + ' - explore: Deep dive on symbol/cluster/process', + ' - impact: Blast radius analysis', + ' - overview: List all clusters and processes', + ' - cypher: Raw graph queries', + '', + 'resources_available:', + ' - gitnexus://clusters: All clusters', + ' - gitnexus://processes: All processes', + ' - gitnexus://cluster/{name}: Cluster details', + ' - gitnexus://process/{name}: Process trace', + ]; + + return lines.join('\n'); +} + +/** + * Clusters resource - list all clusters + */ +async function getClustersResource(backend: LocalBackend): Promise { + try { + const result = await backend.callTool('overview', { showClusters: true, showProcesses: false, limit: 50 }); + + if (!result.clusters || result.clusters.length === 0) { + return 'clusters: []\n# No clusters detected. Run: gitnexus analyze'; + } + + const lines: string[] = ['clusters:']; + + for (const cluster of result.clusters) { + const label = cluster.heuristicLabel || cluster.label || cluster.id; + lines.push(` - name: "${label}"`); + lines.push(` symbols: ${cluster.symbolCount || 0}`); + if (cluster.cohesion) { + lines.push(` cohesion: ${(cluster.cohesion * 100).toFixed(0)}%`); + } + } + + return lines.join('\n'); + } catch (err: any) { + return `error: ${err.message}`; + } +} + +/** + * Processes resource - list all processes + */ +async function getProcessesResource(backend: LocalBackend): Promise { + try { + const result = await backend.callTool('overview', { showClusters: false, showProcesses: true, limit: 50 }); + + if (!result.processes || result.processes.length === 0) { + return 'processes: []\n# No processes detected. Run: gitnexus analyze'; + } + + const lines: string[] = ['processes:']; + + for (const proc of result.processes) { + const label = proc.heuristicLabel || proc.label || proc.id; + lines.push(` - name: "${label}"`); + lines.push(` type: ${proc.processType || 'unknown'}`); + lines.push(` steps: ${proc.stepCount || 0}`); + } + + return lines.join('\n'); + } catch (err: any) { + return `error: ${err.message}`; + } +} + +/** + * Schema resource - graph structure for Cypher queries + */ +function getSchemaResource(): string { + return `# GitNexus Graph Schema + +nodes: + - File: Source code files + - Function: Functions and arrow functions + - Class: Class definitions + - Interface: Interface/type definitions + - Method: Class methods + - Community: Functional cluster (Leiden algorithm) + - Process: Execution flow trace + +relationships: + - CALLS: Function/method invocation + - IMPORTS: Module imports + - EXTENDS: Class inheritance + - IMPLEMENTS: Interface implementation + - DEFINES: File defines symbol + - MEMBER_OF: Symbol belongs to community + - STEP_IN_PROCESS: Symbol is step N in process + +example_queries: + find_callers: | + MATCH (caller)-[:CodeRelation {type: 'CALLS'}]->(f:Function {name: "myFunc"}) + RETURN caller.name, caller.filePath + + find_community_members: | + MATCH (s)-[:CodeRelation {type: 'MEMBER_OF'}]->(c:Community) + WHERE c.heuristicLabel = "Auth" + RETURN s.name, labels(s)[0] AS type + + trace_process: | + MATCH (s)-[r:CodeRelation {type: 'STEP_IN_PROCESS'}]->(p:Process) + WHERE p.heuristicLabel = "LoginFlow" + RETURN s.name, r.step + ORDER BY r.step +`; +} + +/** + * Cluster detail resource + */ +async function getClusterDetailResource(name: string, backend: LocalBackend): Promise { + try { + const result = await backend.callTool('explore', { name, type: 'cluster' }); + + if (result.error) { + return `error: ${result.error}`; + } + + const cluster = result.cluster; + const members = result.members || []; + + const lines: string[] = [ + `name: "${cluster.heuristicLabel || cluster.label || cluster.id}"`, + `symbols: ${cluster.symbolCount || members.length}`, + ]; + + if (cluster.cohesion) { + lines.push(`cohesion: ${(cluster.cohesion * 100).toFixed(0)}%`); + } + + if (members.length > 0) { + lines.push(''); + lines.push('members:'); + for (const member of members.slice(0, 20)) { + lines.push(` - name: ${member.name}`); + lines.push(` type: ${member.type}`); + lines.push(` file: ${member.filePath}`); + } + if (members.length > 20) { + lines.push(` # ... and ${members.length - 20} more`); + } + } + + return lines.join('\n'); + } catch (err: any) { + return `error: ${err.message}`; + } +} + +/** + * Process detail resource + */ +async function getProcessDetailResource(name: string, backend: LocalBackend): Promise { + try { + const result = await backend.callTool('explore', { name, type: 'process' }); + + if (result.error) { + return `error: ${result.error}`; + } + + const proc = result.process; + const steps = result.steps || []; + + const lines: string[] = [ + `name: "${proc.heuristicLabel || proc.label || proc.id}"`, + `type: ${proc.processType || 'unknown'}`, + `step_count: ${proc.stepCount || steps.length}`, + ]; + + if (steps.length > 0) { + lines.push(''); + lines.push('trace:'); + for (const step of steps) { + lines.push(` ${step.step}: ${step.name} (${step.filePath})`); + } + } + + return lines.join('\n'); + } catch (err: any) { + return `error: ${err.message}`; + } +} diff --git a/gitnexus/src/mcp/server.ts b/gitnexus/src/mcp/server.ts index 3e77a6fde..586dfcead 100644 --- a/gitnexus/src/mcp/server.ts +++ b/gitnexus/src/mcp/server.ts @@ -6,6 +6,7 @@ * communicate via stdin/stdout using the MCP protocol. * * Tools: context, search, cypher, overview, explore, impact, analyze + * Resources: context, clusters, processes, schema, cluster/{name}, process/{name} */ import { Server } from '@modelcontextprotocol/sdk/server/index.js'; @@ -15,46 +16,11 @@ import { ListToolsRequestSchema, ListResourcesRequestSchema, ReadResourceRequestSchema, + ListResourceTemplatesRequestSchema, } from '@modelcontextprotocol/sdk/types.js'; import { GITNEXUS_TOOLS } from './tools.js'; -import type { LocalBackend, CodebaseContext } from './local/local-backend.js'; - -/** - * Format context as markdown for the resource - */ -function formatContextAsMarkdown(context: CodebaseContext): string { - const { projectName, stats } = context; - - const lines: string[] = []; - - lines.push(`# GitNexus: ${projectName}`); - lines.push(''); - lines.push('## Stats'); - lines.push(`- Files: ${stats.fileCount}`); - lines.push(`- Functions: ${stats.functionCount}`); - if (stats.communityCount > 0) lines.push(`- Communities: ${stats.communityCount}`); - if (stats.processCount > 0) lines.push(`- Processes: ${stats.processCount}`); - lines.push(''); - - lines.push('## Available Tools'); - lines.push(''); - lines.push('- **context**: Codebase overview and stats'); - lines.push('- **search**: Hybrid semantic + keyword search'); - lines.push('- **cypher**: Execute Cypher queries on graph'); - lines.push('- **overview**: List communities and processes'); - lines.push('- **explore**: Deep dive on symbol/cluster/process'); - lines.push('- **impact**: Change impact analysis'); - lines.push('- **analyze**: Index/re-index repository'); - lines.push(''); - - lines.push('## Graph Schema'); - lines.push(''); - lines.push('**Nodes**: File, Function, Class, Interface, Method, Community, Process'); - lines.push(''); - lines.push('**Relations**: CALLS, IMPORTS, EXTENDS, IMPLEMENTS, DEFINES, MEMBER_OF, STEP_IN_PROCESS'); - - return lines.join('\n'); -} +import type { LocalBackend } from './local/local-backend.js'; +import { getResourceDefinitions, getResourceTemplates, readResource } from './resources.js'; export async function startMCPServer(backend: LocalBackend): Promise { const server = new Server( @@ -78,15 +44,27 @@ export async function startMCPServer(backend: LocalBackend): Promise { return { resources: [] }; } + const resources = getResourceDefinitions(context.projectName); return { - resources: [ - { - uri: 'gitnexus://codebase/context', - name: `GitNexus: ${context.projectName}`, - description: `Codebase context for ${context.projectName} (${context.stats.fileCount} files)`, - mimeType: 'text/markdown', - }, - ], + resources: resources.map(r => ({ + uri: r.uri, + name: r.name, + description: r.description, + mimeType: r.mimeType, + })), + }; + }); + + // Handle list resource templates request (for dynamic resources) + server.setRequestHandler(ListResourceTemplatesRequestSchema, async () => { + const templates = getResourceTemplates(); + return { + resourceTemplates: templates.map(t => ({ + uriTemplate: t.uriTemplate, + name: t.name, + description: t.description, + mimeType: t.mimeType, + })), }; }); @@ -94,35 +72,31 @@ export async function startMCPServer(backend: LocalBackend): Promise { server.setRequestHandler(ReadResourceRequestSchema, async (request) => { const { uri } = request.params; - if (uri === 'gitnexus://codebase/context') { - const context = backend.context; - - if (!context) { - return { - contents: [ - { - uri, - mimeType: 'text/plain', - text: 'No codebase loaded.', - }, - ], - }; - } - + try { + const content = await readResource(uri, backend); return { contents: [ { uri, - mimeType: 'text/markdown', - text: formatContextAsMarkdown(context), + mimeType: 'text/yaml', + text: content, + }, + ], + }; + } catch (err: any) { + return { + contents: [ + { + uri, + mimeType: 'text/plain', + text: `Error: ${err.message}`, }, ], }; } - - throw new Error(`Unknown resource: ${uri}`); }); + // Handle list tools request server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: GITNEXUS_TOOLS.map((tool) => ({ diff --git a/gitnexus/src/mcp/tools.ts b/gitnexus/src/mcp/tools.ts index f4d6e997c..1fd326330 100644 --- a/gitnexus/src/mcp/tools.ts +++ b/gitnexus/src/mcp/tools.ts @@ -46,23 +46,6 @@ Run this when: required: [], }, }, - { - name: 'context', - description: `Get GitNexus codebase context. CALL THIS FIRST before using other tools. - -Returns: -- Project name and stats (files, functions, classes) -- Hotspots (most connected/important nodes) -- Communities and processes count -- Tool usage guidance - -ALWAYS call this first to understand the codebase before searching or querying.`, - inputSchema: { - type: 'object', - properties: {}, - required: [], - }, - }, { name: 'search', description: `Hybrid search (keyword + semantic) across the codebase.