gitnexus 1.2.6 → 1.2.7

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -185,14 +185,14 @@ export async function startMCPServer(backend) {
185
185
  role: 'user',
186
186
  content: {
187
187
  type: 'text',
188
- text: `Analyze the impact of my current code changes before committing.
189
-
190
- Follow these steps:
191
- 1. Run \`detect_changes(${JSON.stringify({ scope, ...(baseRef ? { base_ref: baseRef } : {}) })})\` to find what changed and affected processes
192
- 2. For each changed symbol in critical processes, run \`context({name: "<symbol>"})\` to see its full reference graph
193
- 3. For any high-risk items (many callers or cross-process), run \`impact({target: "<symbol>", direction: "upstream"})\` for blast radius
194
- 4. Summarize: changes, affected processes, risk level, and recommended actions
195
-
188
+ text: `Analyze the impact of my current code changes before committing.
189
+
190
+ Follow these steps:
191
+ 1. Run \`detect_changes(${JSON.stringify({ scope, ...(baseRef ? { base_ref: baseRef } : {}) })})\` to find what changed and affected processes
192
+ 2. For each changed symbol in critical processes, run \`context({name: "<symbol>"})\` to see its full reference graph
193
+ 3. For any high-risk items (many callers or cross-process), run \`impact({target: "<symbol>", direction: "upstream"})\` for blast radius
194
+ 4. Summarize: changes, affected processes, risk level, and recommended actions
195
+
196
196
  Present the analysis as a clear risk report.`,
197
197
  },
198
198
  },
@@ -207,14 +207,14 @@ Present the analysis as a clear risk report.`,
207
207
  role: 'user',
208
208
  content: {
209
209
  type: 'text',
210
- text: `Generate architecture documentation for this codebase using the knowledge graph.
211
-
212
- Follow these steps:
213
- 1. READ \`gitnexus://repo/${repo || '{name}'}/context\` for codebase stats
214
- 2. READ \`gitnexus://repo/${repo || '{name}'}/clusters\` to see all functional areas
215
- 3. READ \`gitnexus://repo/${repo || '{name}'}/processes\` to see all execution flows
216
- 4. For the top 5 most important processes, READ \`gitnexus://repo/${repo || '{name}'}/process/{name}\` for step-by-step traces
217
- 5. Generate a mermaid architecture diagram showing the major areas and their connections
210
+ text: `Generate architecture documentation for this codebase using the knowledge graph.
211
+
212
+ Follow these steps:
213
+ 1. READ \`gitnexus://repo/${repo || '{name}'}/context\` for codebase stats
214
+ 2. READ \`gitnexus://repo/${repo || '{name}'}/clusters\` to see all functional areas
215
+ 3. READ \`gitnexus://repo/${repo || '{name}'}/processes\` to see all execution flows
216
+ 4. For the top 5 most important processes, READ \`gitnexus://repo/${repo || '{name}'}/process/{name}\` for step-by-step traces
217
+ 5. Generate a mermaid architecture diagram showing the major areas and their connections
218
218
  6. Write an ARCHITECTURE.md file with: overview, functional areas, key execution flows, and the mermaid diagram`,
219
219
  },
220
220
  },
package/dist/mcp/tools.js CHANGED
@@ -7,14 +7,14 @@
7
7
  export const GITNEXUS_TOOLS = [
8
8
  {
9
9
  name: 'list_repos',
10
- description: `List all indexed repositories available to GitNexus.
11
-
12
- Returns each repo's name, path, indexed date, last commit, and stats.
13
-
14
- WHEN TO USE: First step when multiple repos are indexed, or to discover available repos.
15
- AFTER THIS: READ gitnexus://repo/{name}/context for the repo you want to work with.
16
-
17
- When multiple repos are indexed, you MUST specify the "repo" parameter
10
+ description: `List all indexed repositories available to GitNexus.
11
+
12
+ Returns each repo's name, path, indexed date, last commit, and stats.
13
+
14
+ WHEN TO USE: First step when multiple repos are indexed, or to discover available repos.
15
+ AFTER THIS: READ gitnexus://repo/{name}/context for the repo you want to work with.
16
+
17
+ When multiple repos are indexed, you MUST specify the "repo" parameter
18
18
  on other tools (query, context, impact, etc.) to target the correct one.`,
19
19
  inputSchema: {
20
20
  type: 'object',
@@ -24,17 +24,17 @@ on other tools (query, context, impact, etc.) to target the correct one.`,
24
24
  },
25
25
  {
26
26
  name: 'query',
27
- description: `Query the code knowledge graph for execution flows related to a concept.
28
- Returns processes (call chains) ranked by relevance, each with its symbols and file locations.
29
-
30
- WHEN TO USE: Understanding how code works together. Use this when you need execution flows and relationships, not just file matches. Complements grep/IDE search.
31
- AFTER THIS: Use context() on a specific symbol for 360-degree view (callers, callees, categorized refs).
32
-
33
- Returns results grouped by process (execution flow):
34
- - processes: ranked execution flows with relevance priority
35
- - process_symbols: all symbols in those flows with file locations
36
- - definitions: standalone types/interfaces not in any process
37
-
27
+ description: `Query the code knowledge graph for execution flows related to a concept.
28
+ Returns processes (call chains) ranked by relevance, each with its symbols and file locations.
29
+
30
+ WHEN TO USE: Understanding how code works together. Use this when you need execution flows and relationships, not just file matches. Complements grep/IDE search.
31
+ AFTER THIS: Use context() on a specific symbol for 360-degree view (callers, callees, categorized refs).
32
+
33
+ Returns results grouped by process (execution flow):
34
+ - processes: ranked execution flows with relevance priority
35
+ - process_symbols: all symbols in those flows with file locations
36
+ - definitions: standalone types/interfaces not in any process
37
+
38
38
  Hybrid ranking: BM25 keyword + semantic vector search, ranked by Reciprocal Rank Fusion.`,
39
39
  inputSchema: {
40
40
  type: 'object',
@@ -52,32 +52,32 @@ Hybrid ranking: BM25 keyword + semantic vector search, ranked by Reciprocal Rank
52
52
  },
53
53
  {
54
54
  name: 'cypher',
55
- description: `Execute Cypher query against the code knowledge graph.
56
-
57
- WHEN TO USE: Complex structural queries that search/explore can't answer. READ gitnexus://repo/{name}/schema first for the full schema.
58
- AFTER THIS: Use context() on result symbols for deeper context.
59
-
60
- SCHEMA:
61
- - Nodes: File, Folder, Function, Class, Interface, Method, CodeElement, Community, Process
62
- - Multi-language nodes (use backticks): \`Struct\`, \`Enum\`, \`Trait\`, \`Impl\`, etc.
63
- - All edges via single CodeRelation table with 'type' property
64
- - Edge types: CONTAINS, DEFINES, CALLS, IMPORTS, EXTENDS, IMPLEMENTS, MEMBER_OF, STEP_IN_PROCESS
65
- - Edge properties: type (STRING), confidence (DOUBLE), reason (STRING), step (INT32)
66
-
67
- EXAMPLES:
68
- • Find callers of a function:
69
- MATCH (a)-[:CodeRelation {type: 'CALLS'}]->(b:Function {name: "validateUser"}) RETURN a.name, a.filePath
70
-
71
- • Find community members:
72
- MATCH (f)-[:CodeRelation {type: 'MEMBER_OF'}]->(c:Community) WHERE c.heuristicLabel = "Auth" RETURN f.name
73
-
74
- • Trace a process:
75
- MATCH (s)-[r:CodeRelation {type: 'STEP_IN_PROCESS'}]->(p:Process) WHERE p.heuristicLabel = "UserLogin" RETURN s.name, r.step ORDER BY r.step
76
-
77
- TIPS:
78
- - All relationships use single CodeRelation table — filter with {type: 'CALLS'} etc.
79
- - Community = auto-detected functional area (Leiden algorithm)
80
- - Process = execution flow trace from entry point to terminal
55
+ description: `Execute Cypher query against the code knowledge graph.
56
+
57
+ WHEN TO USE: Complex structural queries that search/explore can't answer. READ gitnexus://repo/{name}/schema first for the full schema.
58
+ AFTER THIS: Use context() on result symbols for deeper context.
59
+
60
+ SCHEMA:
61
+ - Nodes: File, Folder, Function, Class, Interface, Method, CodeElement, Community, Process
62
+ - Multi-language nodes (use backticks): \`Struct\`, \`Enum\`, \`Trait\`, \`Impl\`, etc.
63
+ - All edges via single CodeRelation table with 'type' property
64
+ - Edge types: CONTAINS, DEFINES, CALLS, IMPORTS, EXTENDS, IMPLEMENTS, MEMBER_OF, STEP_IN_PROCESS
65
+ - Edge properties: type (STRING), confidence (DOUBLE), reason (STRING), step (INT32)
66
+
67
+ EXAMPLES:
68
+ • Find callers of a function:
69
+ MATCH (a)-[:CodeRelation {type: 'CALLS'}]->(b:Function {name: "validateUser"}) RETURN a.name, a.filePath
70
+
71
+ • Find community members:
72
+ MATCH (f)-[:CodeRelation {type: 'MEMBER_OF'}]->(c:Community) WHERE c.heuristicLabel = "Auth" RETURN f.name
73
+
74
+ • Trace a process:
75
+ MATCH (s)-[r:CodeRelation {type: 'STEP_IN_PROCESS'}]->(p:Process) WHERE p.heuristicLabel = "UserLogin" RETURN s.name, r.step ORDER BY r.step
76
+
77
+ TIPS:
78
+ - All relationships use single CodeRelation table — filter with {type: 'CALLS'} etc.
79
+ - Community = auto-detected functional area (Leiden algorithm)
80
+ - Process = execution flow trace from entry point to terminal
81
81
  - Use heuristicLabel (not label) for human-readable community/process names`,
82
82
  inputSchema: {
83
83
  type: 'object',
@@ -90,12 +90,12 @@ TIPS:
90
90
  },
91
91
  {
92
92
  name: 'context',
93
- description: `360-degree view of a single code symbol.
94
- Shows categorized incoming/outgoing references (calls, imports, extends, implements), process participation, and file location.
95
-
96
- WHEN TO USE: After query() to understand a specific symbol in depth. When you need to know all callers, callees, and what execution flows a symbol participates in.
97
- AFTER THIS: Use impact() if planning changes, or READ gitnexus://repo/{name}/process/{processName} for full execution trace.
98
-
93
+ description: `360-degree view of a single code symbol.
94
+ Shows categorized incoming/outgoing references (calls, imports, extends, implements), process participation, and file location.
95
+
96
+ WHEN TO USE: After query() to understand a specific symbol in depth. When you need to know all callers, callees, and what execution flows a symbol participates in.
97
+ AFTER THIS: Use impact() if planning changes, or READ gitnexus://repo/{name}/process/{processName} for full execution trace.
98
+
99
99
  Handles disambiguation: if multiple symbols share the same name, returns candidates for you to pick from. Use uid param for zero-ambiguity lookup from prior results.`,
100
100
  inputSchema: {
101
101
  type: 'object',
@@ -111,12 +111,12 @@ Handles disambiguation: if multiple symbols share the same name, returns candida
111
111
  },
112
112
  {
113
113
  name: 'detect_changes',
114
- description: `Analyze uncommitted git changes and find affected execution flows.
115
- Maps git diff hunks to indexed symbols, then traces which processes are impacted.
116
-
117
- WHEN TO USE: Before committing — to understand what your changes affect. Pre-commit review, PR preparation.
118
- AFTER THIS: Review affected processes. Use context() on high-risk symbols. READ gitnexus://repo/{name}/process/{name} for full traces.
119
-
114
+ description: `Analyze uncommitted git changes and find affected execution flows.
115
+ Maps git diff hunks to indexed symbols, then traces which processes are impacted.
116
+
117
+ WHEN TO USE: Before committing — to understand what your changes affect. Pre-commit review, PR preparation.
118
+ AFTER THIS: Review affected processes. Use context() on high-risk symbols. READ gitnexus://repo/{name}/process/{name} for full traces.
119
+
120
120
  Returns: changed symbols, affected processes, and a risk summary.`,
121
121
  inputSchema: {
122
122
  type: 'object',
@@ -130,14 +130,14 @@ Returns: changed symbols, affected processes, and a risk summary.`,
130
130
  },
131
131
  {
132
132
  name: 'rename',
133
- description: `Multi-file coordinated rename using the knowledge graph + text search.
134
- Finds all references via graph (high confidence) and regex text search (lower confidence). Preview by default.
135
-
136
- WHEN TO USE: Renaming a function, class, method, or variable across the codebase. Safer than find-and-replace.
137
- AFTER THIS: Run detect_changes() to verify no unexpected side effects.
138
-
139
- Each edit is tagged with confidence:
140
- - "graph": found via knowledge graph relationships (high confidence, safe to accept)
133
+ description: `Multi-file coordinated rename using the knowledge graph + text search.
134
+ Finds all references via graph (high confidence) and regex text search (lower confidence). Preview by default.
135
+
136
+ WHEN TO USE: Renaming a function, class, method, or variable across the codebase. Safer than find-and-replace.
137
+ AFTER THIS: Run detect_changes() to verify no unexpected side effects.
138
+
139
+ Each edit is tagged with confidence:
140
+ - "graph": found via knowledge graph relationships (high confidence, safe to accept)
141
141
  - "text_search": found via regex text search (lower confidence, review carefully)`,
142
142
  inputSchema: {
143
143
  type: 'object',
@@ -154,18 +154,18 @@ Each edit is tagged with confidence:
154
154
  },
155
155
  {
156
156
  name: 'impact',
157
- description: `Analyze the blast radius of changing a code symbol.
158
- Returns all symbols affected by modifying the target, grouped by depth with edge types and confidence.
159
-
160
- WHEN TO USE: Before making code changes — especially refactoring, renaming, or modifying shared code. Shows what would break.
161
- AFTER THIS: Review d=1 items (WILL BREAK). READ gitnexus://repo/{name}/processes to check affected execution flows.
162
-
163
- Depth groups:
164
- - d=1: WILL BREAK (direct callers/importers)
165
- - d=2: LIKELY AFFECTED (indirect)
166
- - d=3: MAY NEED TESTING (transitive)
167
-
168
- EdgeType: CALLS, IMPORTS, EXTENDS, IMPLEMENTS
157
+ description: `Analyze the blast radius of changing a code symbol.
158
+ Returns all symbols affected by modifying the target, grouped by depth with edge types and confidence.
159
+
160
+ WHEN TO USE: Before making code changes — especially refactoring, renaming, or modifying shared code. Shows what would break.
161
+ AFTER THIS: Review d=1 items (WILL BREAK). READ gitnexus://repo/{name}/processes to check affected execution flows.
162
+
163
+ Depth groups:
164
+ - d=1: WILL BREAK (direct callers/importers)
165
+ - d=2: LIKELY AFFECTED (indirect)
166
+ - d=3: MAY NEED TESTING (transitive)
167
+
168
+ EdgeType: CALLS, IMPORTS, EXTENDS, IMPLEMENTS
169
169
  Confidence: 1.0 = certain, <0.8 = fuzzy match`,
170
170
  inputSchema: {
171
171
  type: 'object',
package/package.json CHANGED
@@ -1,82 +1,82 @@
1
- {
2
- "name": "gitnexus",
3
- "version": "1.2.6",
4
- "description": "Graph-powered code intelligence for AI agents. Index any codebase, query via MCP or CLI.",
5
- "author": "Abhigyan Patwari",
6
- "license": "PolyForm-Noncommercial-1.0.0",
7
- "homepage": "https://github.com/abhigyanpatwari/GitNexus#readme",
8
- "repository": {
9
- "type": "git",
10
- "url": "git+https://github.com/abhigyanpatwari/GitNexus.git",
11
- "directory": "gitnexus"
12
- },
13
- "bugs": {
14
- "url": "https://github.com/abhigyanpatwari/GitNexus/issues"
15
- },
16
- "keywords": [
17
- "mcp",
18
- "model-context-protocol",
19
- "code-intelligence",
20
- "knowledge-graph",
21
- "cursor",
22
- "claude",
23
- "ai-agent",
24
- "gitnexus",
25
- "static-analysis",
26
- "codebase-indexing"
27
- ],
28
- "type": "module",
29
- "bin": {
30
- "gitnexus": "dist/cli/index.js"
31
- },
32
- "files": [
33
- "dist",
34
- "hooks",
35
- "skills",
36
- "vendor"
37
- ],
38
- "scripts": {
39
- "build": "tsc",
40
- "dev": "tsx watch src/cli/index.ts",
41
- "prepare": "npm run build"
42
- },
43
- "dependencies": {
44
- "@huggingface/transformers": "^3.0.0",
45
- "@modelcontextprotocol/sdk": "^1.0.0",
46
- "cli-progress": "^3.12.0",
47
- "commander": "^12.0.0",
48
- "cors": "^2.8.5",
49
- "express": "^4.19.2",
50
- "glob": "^11.0.0",
51
- "graphology": "^0.25.4",
52
- "graphology-indices": "^0.17.0",
53
- "graphology-utils": "^2.3.0",
54
- "kuzu": "^0.11.3",
55
- "lru-cache": "^11.0.0",
56
- "mnemonist": "^0.39.0",
57
- "pandemonium": "^2.4.0",
58
- "tree-sitter": "^0.21.0",
59
- "tree-sitter-c": "^0.21.0",
60
- "tree-sitter-c-sharp": "^0.21.0",
61
- "tree-sitter-cpp": "^0.22.0",
62
- "tree-sitter-go": "^0.21.0",
63
- "tree-sitter-java": "^0.21.0",
64
- "tree-sitter-javascript": "^0.21.0",
65
- "tree-sitter-python": "^0.21.0",
66
- "tree-sitter-rust": "^0.21.0",
67
- "tree-sitter-typescript": "^0.21.0",
68
- "typescript": "^5.4.5",
69
- "uuid": "^13.0.0"
70
- },
71
- "devDependencies": {
72
- "@types/cli-progress": "^3.11.6",
73
- "@types/cors": "^2.8.17",
74
- "@types/express": "^4.17.21",
75
- "@types/node": "^20.0.0",
76
- "@types/uuid": "^10.0.0",
77
- "tsx": "^4.0.0"
78
- },
79
- "engines": {
80
- "node": ">=18.0.0"
81
- }
82
- }
1
+ {
2
+ "name": "gitnexus",
3
+ "version": "1.2.7",
4
+ "description": "Graph-powered code intelligence for AI agents. Index any codebase, query via MCP or CLI.",
5
+ "author": "Abhigyan Patwari",
6
+ "license": "PolyForm-Noncommercial-1.0.0",
7
+ "homepage": "https://github.com/abhigyanpatwari/GitNexus#readme",
8
+ "repository": {
9
+ "type": "git",
10
+ "url": "git+https://github.com/abhigyanpatwari/GitNexus.git",
11
+ "directory": "gitnexus"
12
+ },
13
+ "bugs": {
14
+ "url": "https://github.com/abhigyanpatwari/GitNexus/issues"
15
+ },
16
+ "keywords": [
17
+ "mcp",
18
+ "model-context-protocol",
19
+ "code-intelligence",
20
+ "knowledge-graph",
21
+ "cursor",
22
+ "claude",
23
+ "ai-agent",
24
+ "gitnexus",
25
+ "static-analysis",
26
+ "codebase-indexing"
27
+ ],
28
+ "type": "module",
29
+ "bin": {
30
+ "gitnexus": "dist/cli/index.js"
31
+ },
32
+ "files": [
33
+ "dist",
34
+ "hooks",
35
+ "skills",
36
+ "vendor"
37
+ ],
38
+ "scripts": {
39
+ "build": "tsc",
40
+ "dev": "tsx watch src/cli/index.ts",
41
+ "prepare": "npm run build"
42
+ },
43
+ "dependencies": {
44
+ "@huggingface/transformers": "^3.0.0",
45
+ "@modelcontextprotocol/sdk": "^1.0.0",
46
+ "cli-progress": "^3.12.0",
47
+ "commander": "^12.0.0",
48
+ "cors": "^2.8.5",
49
+ "express": "^4.19.2",
50
+ "glob": "^11.0.0",
51
+ "graphology": "^0.25.4",
52
+ "graphology-indices": "^0.17.0",
53
+ "graphology-utils": "^2.3.0",
54
+ "kuzu": "^0.11.3",
55
+ "lru-cache": "^11.0.0",
56
+ "mnemonist": "^0.39.0",
57
+ "pandemonium": "^2.4.0",
58
+ "tree-sitter": "^0.21.0",
59
+ "tree-sitter-c": "^0.21.0",
60
+ "tree-sitter-c-sharp": "^0.21.0",
61
+ "tree-sitter-cpp": "^0.22.0",
62
+ "tree-sitter-go": "^0.21.0",
63
+ "tree-sitter-java": "^0.21.0",
64
+ "tree-sitter-javascript": "^0.21.0",
65
+ "tree-sitter-python": "^0.21.0",
66
+ "tree-sitter-rust": "^0.21.0",
67
+ "tree-sitter-typescript": "^0.21.0",
68
+ "typescript": "^5.4.5",
69
+ "uuid": "^13.0.0"
70
+ },
71
+ "devDependencies": {
72
+ "@types/cli-progress": "^3.11.6",
73
+ "@types/cors": "^2.8.17",
74
+ "@types/express": "^4.17.21",
75
+ "@types/node": "^20.0.0",
76
+ "@types/uuid": "^10.0.0",
77
+ "tsx": "^4.0.0"
78
+ },
79
+ "engines": {
80
+ "node": ">=18.0.0"
81
+ }
82
+ }
@@ -1,85 +1,85 @@
1
- ---
2
- name: gitnexus-debugging
3
- description: Trace bugs through call chains using knowledge graph
4
- ---
5
-
6
- # Debugging with GitNexus
7
-
8
- ## When to Use
9
- - "Why is this function failing?"
10
- - "Trace where this error comes from"
11
- - "Who calls this method?"
12
- - "This endpoint returns 500"
13
- - Investigating bugs, errors, or unexpected behavior
14
-
15
- ## Workflow
16
-
17
- ```
18
- 1. gitnexus_query({query: "<error or symptom>"}) → Find related execution flows
19
- 2. gitnexus_context({name: "<suspect>"}) → See callers/callees/processes
20
- 3. READ gitnexus://repo/{name}/process/{name} → Trace execution flow
21
- 4. gitnexus_cypher({query: "MATCH path..."}) → Custom traces if needed
22
- ```
23
-
24
- > If "Index is stale" → run `npx gitnexus analyze` in terminal.
25
-
26
- ## Checklist
27
-
28
- ```
29
- - [ ] Understand the symptom (error message, unexpected behavior)
30
- - [ ] gitnexus_query for error text or related code
31
- - [ ] Identify the suspect function from returned processes
32
- - [ ] gitnexus_context to see callers and callees
33
- - [ ] Trace execution flow via process resource if applicable
34
- - [ ] gitnexus_cypher for custom call chain traces if needed
35
- - [ ] Read source files to confirm root cause
36
- ```
37
-
38
- ## Debugging Patterns
39
-
40
- | Symptom | GitNexus Approach |
41
- |---------|-------------------|
42
- | Error message | `gitnexus_query` for error text → `context` on throw sites |
43
- | Wrong return value | `context` on the function → trace callees for data flow |
44
- | Intermittent failure | `context` → look for external calls, async deps |
45
- | Performance issue | `context` → find symbols with many callers (hot paths) |
46
- | Recent regression | `detect_changes` to see what your changes affect |
47
-
48
- ## Tools
49
-
50
- **gitnexus_query** — find code related to error:
51
- ```
52
- gitnexus_query({query: "payment validation error"})
53
- → Processes: CheckoutFlow, ErrorHandling
54
- → Symbols: validatePayment, handlePaymentError, PaymentException
55
- ```
56
-
57
- **gitnexus_context** — full context for a suspect:
58
- ```
59
- gitnexus_context({name: "validatePayment"})
60
- → Incoming calls: processCheckout, webhookHandler
61
- → Outgoing calls: verifyCard, fetchRates (external API!)
62
- → Processes: CheckoutFlow (step 3/7)
63
- ```
64
-
65
- **gitnexus_cypher** — custom call chain traces:
66
- ```cypher
67
- MATCH path = (a)-[:CodeRelation {type: 'CALLS'}*1..2]->(b:Function {name: "validatePayment"})
68
- RETURN [n IN nodes(path) | n.name] AS chain
69
- ```
70
-
71
- ## Example: "Payment endpoint returns 500 intermittently"
72
-
73
- ```
74
- 1. gitnexus_query({query: "payment error handling"})
75
- → Processes: CheckoutFlow, ErrorHandling
76
- → Symbols: validatePayment, handlePaymentError
77
-
78
- 2. gitnexus_context({name: "validatePayment"})
79
- → Outgoing calls: verifyCard, fetchRates (external API!)
80
-
81
- 3. READ gitnexus://repo/my-app/process/CheckoutFlow
82
- → Step 3: validatePayment → calls fetchRates (external)
83
-
84
- 4. Root cause: fetchRates calls external API without proper timeout
85
- ```
1
+ ---
2
+ name: gitnexus-debugging
3
+ description: Trace bugs through call chains using knowledge graph
4
+ ---
5
+
6
+ # Debugging with GitNexus
7
+
8
+ ## When to Use
9
+ - "Why is this function failing?"
10
+ - "Trace where this error comes from"
11
+ - "Who calls this method?"
12
+ - "This endpoint returns 500"
13
+ - Investigating bugs, errors, or unexpected behavior
14
+
15
+ ## Workflow
16
+
17
+ ```
18
+ 1. gitnexus_query({query: "<error or symptom>"}) → Find related execution flows
19
+ 2. gitnexus_context({name: "<suspect>"}) → See callers/callees/processes
20
+ 3. READ gitnexus://repo/{name}/process/{name} → Trace execution flow
21
+ 4. gitnexus_cypher({query: "MATCH path..."}) → Custom traces if needed
22
+ ```
23
+
24
+ > If "Index is stale" → run `npx gitnexus analyze` in terminal.
25
+
26
+ ## Checklist
27
+
28
+ ```
29
+ - [ ] Understand the symptom (error message, unexpected behavior)
30
+ - [ ] gitnexus_query for error text or related code
31
+ - [ ] Identify the suspect function from returned processes
32
+ - [ ] gitnexus_context to see callers and callees
33
+ - [ ] Trace execution flow via process resource if applicable
34
+ - [ ] gitnexus_cypher for custom call chain traces if needed
35
+ - [ ] Read source files to confirm root cause
36
+ ```
37
+
38
+ ## Debugging Patterns
39
+
40
+ | Symptom | GitNexus Approach |
41
+ |---------|-------------------|
42
+ | Error message | `gitnexus_query` for error text → `context` on throw sites |
43
+ | Wrong return value | `context` on the function → trace callees for data flow |
44
+ | Intermittent failure | `context` → look for external calls, async deps |
45
+ | Performance issue | `context` → find symbols with many callers (hot paths) |
46
+ | Recent regression | `detect_changes` to see what your changes affect |
47
+
48
+ ## Tools
49
+
50
+ **gitnexus_query** — find code related to error:
51
+ ```
52
+ gitnexus_query({query: "payment validation error"})
53
+ → Processes: CheckoutFlow, ErrorHandling
54
+ → Symbols: validatePayment, handlePaymentError, PaymentException
55
+ ```
56
+
57
+ **gitnexus_context** — full context for a suspect:
58
+ ```
59
+ gitnexus_context({name: "validatePayment"})
60
+ → Incoming calls: processCheckout, webhookHandler
61
+ → Outgoing calls: verifyCard, fetchRates (external API!)
62
+ → Processes: CheckoutFlow (step 3/7)
63
+ ```
64
+
65
+ **gitnexus_cypher** — custom call chain traces:
66
+ ```cypher
67
+ MATCH path = (a)-[:CodeRelation {type: 'CALLS'}*1..2]->(b:Function {name: "validatePayment"})
68
+ RETURN [n IN nodes(path) | n.name] AS chain
69
+ ```
70
+
71
+ ## Example: "Payment endpoint returns 500 intermittently"
72
+
73
+ ```
74
+ 1. gitnexus_query({query: "payment error handling"})
75
+ → Processes: CheckoutFlow, ErrorHandling
76
+ → Symbols: validatePayment, handlePaymentError
77
+
78
+ 2. gitnexus_context({name: "validatePayment"})
79
+ → Outgoing calls: verifyCard, fetchRates (external API!)
80
+
81
+ 3. READ gitnexus://repo/my-app/process/CheckoutFlow
82
+ → Step 3: validatePayment → calls fetchRates (external)
83
+
84
+ 4. Root cause: fetchRates calls external API without proper timeout
85
+ ```