# How the detect_changes Tool in GitNexus Maps Git Diffs to Affected Processes > Discover how GitNexus detect_changes maps git diffs to affected business processes. Understand file changes, symbol mapping, and process impact analysis. - Repository: [Abhigyan Patwari/GitNexus](https://github.com/abhigyanpatwari/GitNexus) - Tags: internals - Published: 2026-03-08 --- **The detect_changes tool in GitNexus analyzes git diffs by first building a safe file list from the requested scope, then querying the knowledge graph to map changed files to indexed symbols, and finally tracing STEP_IN_PROCESS relationships to identify exactly which business processes are impacted and at which step.** The **detect_changes** tool serves as GitNexus’s pre-commit impact analysis engine, transforming raw git diffs into actionable intelligence about affected business processes. By leveraging the indexed knowledge graph and `STEP_IN_PROCESS` relationships implemented in the [`local-backend.ts`](https://github.com/abhigyanpatwari/GitNexus/blob/main/local-backend.ts) module, the tool bridges the gap between code changes and process-level impact assessment. ## Three-Stage Architecture The `detectChanges` function in [`src/mcp/local/local-backend.ts`](https://github.com/abhigyanpatwari/GitNexus/blob/main/src/mcp/local/local-backend.ts) operates through three distinct logical stages to convert git output into process impact data. ### Stage 1: Building the Git Diff The tool constructs a safe git diff command based on the requested **scope** parameter. The implementation uses `execFileSync` with explicit argument arrays to prevent shell injection. ```typescript // From src/mcp/local/local-backend.ts#L52-L68 switch (scope) { case 'unstaged': diffArgs = ['diff', '--name-only']; break; case 'staged': diffArgs = ['diff', '--staged', '--name-only']; break; case 'all': diffArgs = ['diff', 'HEAD', '--name-only']; break; case 'compare': diffArgs = ['diff', base_ref, '--name-only']; break; } ``` The raw output is split into the `changedFiles` array. If no files changed, the tool returns immediately with `changed_count: 0` and `risk_level: 'none'`. ### Stage 2: File-to-Symbol Mapping Each file path is normalized to use `/` separators and queried against the knowledge graph. The Cypher query searches for any node whose `filePath` property contains the changed file path. ```typescript // From src/mcp/local/local-backend.ts#L88-L106 const query = ` MATCH (n) WHERE n.filePath CONTAINS $filePath RETURN n.id as id, n.name as name, n.type as type, n.filePath as filePath LIMIT 20 `; ``` The results populate the `changedSymbols` array with objects containing `id`, `name`, `type`, `filePath`, and a static `change_type: 'Modified'`. These symbols represent the concrete code elements (functions, classes, methods) affected by the diff. ### Stage 3: Process Tracing and Risk Assessment For each changed symbol, the tool traces `STEP_IN_PROCESS` relationships to identify impacted business processes. The Cypher query locates all processes that contain the symbol and extracts the specific step number. ```typescript // From src/mcp/local/local-backend.ts#L111-L140 const processQuery = ` MATCH (n {id: $nodeId})-[r:CodeRelation {type: 'STEP_IN_PROCESS'}]->(p:Process) RETURN p.id as processId, p.name as processName, p.type as processType, p.stepCount as stepCount, r.step as step `; ``` Results are accumulated in a `Map` called `affectedProcesses`. For each process discovered, the tool builds a `changed_steps` array that records which symbol caused the impact and at which step number it appears. Duplicate process entries are merged to ensure unique process listings. The final **risk level** is calculated based on the total count of distinct affected processes: ```typescript const risk = processCount === 0 ? 'low' : processCount <= 5 ? 'medium' : processCount <= 15 ? 'high' : 'critical'; ``` ## Implementation Details ### Scope Handling and Safety The tool supports four distinct analysis scopes defined in [`src/mcp/tools.ts`](https://github.com/abhigyanpatwari/GitNexus/blob/main/src/mcp/tools.ts) (lines 31-49): - **`unstaged`**: Working directory changes not yet staged (default) - **`staged`**: Changes in the git index ready for commit - **`all`**: All changes since the last commit (`HEAD`) - **`compare`**: Changes between current state and a specific `base_ref` The implementation strictly avoids shell interpolation by passing arguments as arrays to `execFileSync`, mitigating injection risks when handling file paths or branch names. ### Knowledge Graph Queries The mapping relies on two critical Cypher query patterns: 1. **File containment**: `MATCH (n) WHERE n.filePath CONTAINS $filePath` — flexible matching for partial paths 2. **Process membership**: `MATCH (n)-[r:CodeRelation {type: 'STEP_IN_PROCESS'}]->(p:Process)` — explicit relationship traversal These queries execute against the Neo4j-backed knowledge graph maintained by the GitNexus backend, with a `LIMIT 20` clause on symbol lookups to prevent excessive memory consumption on large diffs. ## Working with the Tool ### CLI Usage Invoke the tool through the GitNexus CLI using the `gitnexus_detect_changes` command: ```typescript // Pre-commit: analyze unstaged changes gitnexus_detect_changes({ scope: 'unstaged' }) // Compare feature branch against main gitnexus_detect_changes({ scope: 'compare', base_ref: 'main' }) ``` The CLI handler in [`src/cli/eval-server.ts`](https://github.com/abhigyanpatwari/GitNexus/blob/main/src/cli/eval-server.ts) formats results as markdown tables for terminal display. ### Programmatic API Integrate directly with the Node.js backend for custom workflows: ```typescript import { Backend } from '@gitnexus/mcp' async function analyzeImpact() { const backend = new Backend() const result = await backend.callTool('detect_changes', { scope: 'staged' }) console.log(`Risk Level: ${result.summary.risk_level}`) console.table(result.affected_processes) } ``` ### Interpreting Results The tool returns a structured JSON object with three top-level keys: ```json { "summary": { "changed_count": 3, "affected_count": 2, "changed_files": 2, "risk_level": "medium" }, "changed_symbols": [ { "name": "UserService.login", "type": "Function", "filePath": "src/auth/userService.ts", "change_type": "Modified" } ], "affected_processes": [ { "id": "proc-42", "name": "UserLogin", "process_type": "workflow", "step_count": 7, "changed_steps": [ { "symbol": "UserService.login", "step": 3 } ] } ] } ``` The `changed_steps` array provides precise traceability, indicating exactly which symbol impacts which step in each process. This enables targeted code reviews and selective context gathering via complementary GitNexus tools. ## Summary - **The detect_changes tool in GitNexus** executes a three-stage pipeline: git diff construction, file-to-symbol mapping via knowledge graph queries, and process tracing through `STEP_IN_PROCESS` relationships. - **Safety mechanisms** include `execFileSync` with array arguments to prevent shell injection, and a `LIMIT 20` clause on symbol lookups to control resource usage. - **Risk assessment** categorizes impact as low, medium, high, or critical based on the count of distinct affected processes (0, ≤5, ≤15, >15 respectively). - **Precise traceability** is achieved through the `changed_steps` array, which records exactly which symbol affects which step in each impacted process. ## Frequently Asked Questions ### How does the detect_changes tool handle different git states like staged vs unstaged files? The tool accepts a `scope` parameter that supports four distinct values: `unstaged` (default), `staged`, `all`, and `compare`. Based on the scope, the tool constructs the appropriate git diff command—using `--staged` for staged changes, `HEAD` for all changes since the last commit, or a specific `base_ref` for comparison scenarios. This logic is implemented in the switch statement within [`src/mcp/local/local-backend.ts`](https://github.com/abhigyanpatwari/GitNexus/blob/main/src/mcp/local/local-backend.ts) lines 52-68. ### What Cypher queries does the detect_changes tool use to find affected processes? The tool executes two primary Cypher query patterns against the Neo4j knowledge graph. First, it uses `MATCH (n) WHERE n.filePath CONTAINS $filePath` to locate symbols within changed files, limiting results to 20 per file. Second, for each changed symbol, it queries `MATCH (n {id: $nodeId})-[r:CodeRelation {type: 'STEP_IN_PROCESS'}]->(p:Process)` to trace `STEP_IN_PROCESS` relationships and identify exactly which processes contain the modified code and at which step. ### How is the risk level calculated in the detect_changes tool? The risk level is determined by a simple threshold-based heuristic applied to the count of distinct affected processes discovered during analysis. The logic assigns `low` risk for zero affected processes, `medium` for 1-5 processes, `high` for 6-15 processes, and `critical` for more than 15 processes. This calculation appears in [`src/mcp/local/local-backend.ts`](https://github.com/abhigyanpatwari/GitNexus/blob/main/src/mcp/local/local-backend.ts) and provides developers with an immediate quantitative sense of change magnitude. ### Can the detect_changes tool be used programmatically outside of the CLI? Yes, the tool exposes a programmatic API through the GitNexus MCP backend. Developers can import the `Backend` class from `@gitnexus/mcp` and invoke `backend.callTool('detect_changes', { scope: 'staged' })` to receive the structured JSON result containing the summary, changed symbols, and affected processes. This enables integration into custom CI/CD pipelines, pre-commit hooks, or automated testing workflows without requiring CLI interaction.