Egonex-AI Diff Analyzer: Deep Impact Analysis for Code Changes

The Egonex-AI Diff Analyzer transforms Git diffs into detailed impact reports by mapping changed files onto a Knowledge Graph and calculating one-hop ripple effects, containment relationships, and architectural layer impacts.

The Egonex-AI Diff Analyzer is the core intelligence engine in the Egonex-AI/Understand-Anything repository that converts a simple list of modified files into a comprehensive, graph-based impact assessment. Operating directly on the Knowledge Graph produced by the @understand-anything/core static analysis engine, it identifies not only what changed, but precisely which components, layers, and relationships are affected downstream.

How the Diff Analyzer Maps Changes to Impact

The analyzer processes changes through a deterministic pipeline defined in understand-anything-plugin/src/diff-analyzer.ts. Each stage extracts deeper context from the static analysis graph to build a complete picture of the change blast radius.

File-to-Node Resolution

The process begins in buildDiffContext at lines 31-38, where the analyzer iterates over the changedFiles array and matches each file path to corresponding GraphNode.filePath entries. Unmatched files are collected in unmappedFiles for later risk assessment.

// From understand-anything-plugin/src/diff-analyzer.ts#L31-L38
if (node.filePath === file) {
  changedNodeIds.add(node.id);
}

Child Containment Traversal

Changed files often contain multiple functions, classes, or methods. The analyzer performs a second pass at lines 44-48 to walk type === "contains" edges, ensuring that child entities within modified files are also flagged as changed components.

// From understand-anything-plugin/src/diff-analyzer.ts#L44-L48
if (edge.type === "contains" && changedNodeIds.has(edge.source)) {
  changedNodeIds.add(edge.target);
}

One-Hop Ripple Detection

To identify affected components, the analyzer executes a neighbor search at lines 57-69. It collects any node directly linked to a changed node via imports, calls, reads, or other relationships, storing these in affectedNodeIds and capturing the crossing relationships in impactedEdges.

Impact Analysis Capabilities

The diff analyzer provides six concrete capabilities that quantify how changes propagate through the codebase:

• File-to-node mapping: Precise alignment between filesystem changes and graph nodes (changedNodeIds, lines 31-38).
• Child containment: Automatic inclusion of functions and classes residing within changed files (contains edge handling, lines 44-48).
• One-hop dependency ripple: Direct identification of all nodes linked to changed components via any edge type (affectedNodeIds, lines 57-69).
• Architectural layer impact: Calculation of which layers (API, Service, Data, etc.) contain affected nodes by intersecting layer nodeIds with the changed and affected sets (lines 74-77).
• Relationship visibility: Enumeration of specific edges that cross the changed/affected boundary (impactedEdges).
• Risk metrics: Computation of complexity scores, cross-layer spread counts, blast radius size, and unmapped file presence (lines 60-90 in formatDiffAnalysis).

These capabilities enable developers to prioritize code reviews based on actual downstream impact rather than line counts.

Generating Markdown Reports

The formatDiffAnalysis function (lines 93-199) converts the internal DiffContext into a human-readable markdown report. It structures output into distinct sections:

1. Changed Components – Direct matches and their contained children.
2. Affected Components – One-hop neighbors at risk of breakage.
3. Affected Layers – Architectural layers touching the change.
4. Impacted Relationships – Specific edges linking changed and affected nodes.
5. Risk Assessment – Flags for high-complexity components, cross-layer impact, wide blast radius (>5 affected nodes), and unmapped files.

This structured output integrates directly with LLM prompts, CI pipelines, or developer dashboards.

Integration Example

Below is a complete workflow demonstrating how to analyze a Git diff using the Egonex-AI Diff Analyzer:

import { buildDiffContext, formatDiffAnalysis } from "./diff-analyzer.js";
import type { KnowledgeGraph } from "@understand-anything/core";

// Load the knowledge graph produced by the core analyzer
const graph: KnowledgeGraph = await fetch("/graph.json").then(r => r.json());

// Provide changed files from git diff --name-only
const changedFiles = ["src/service.ts", "src/unknown.ts"];

// Build the diff context
const ctx = buildDiffContext(graph, changedFiles);

// Render markdown report
const markdown = formatDiffAnalysis(ctx);
console.log(markdown);

Executing this against the test suite's sample graph (src/__tests__/diff-analyzer.test.ts) produces output like:

# Diff Analysis: test-project

## Changed Components

- **service.ts** (file) — Service
  - File: `src/service.ts`
  - Complexity: complex
- **process** (function) — Process function
  - File: `src/service.ts`
  - Complexity: complex

## Affected Components

- **routes.ts** (file) — Routes
- **db.ts** (file) — Database

## Risk Assessment

- **High complexity**: 2 complex component(s) changed: service.ts, process
- **Cross-layer impact**: Changes span 2 architectural layers
- **New/unmapped files**: 1 files not in the knowledge graph (may need re-analysis)

Summary

• The Diff Analyzer in understand-anything-plugin/src/diff-analyzer.ts bridges Git diffs and Knowledge Graphs to produce deterministic impact reports.
• It tracks changed components (direct matches + contained children) and affected components (one-hop neighbors).
• Risk metrics automatically flag high-complexity changes, cross-layer propagation, wide blast radii, and unmapped files.
• The formatDiffAnalysis function renders structured markdown suitable for automated pipelines and manual review.
• All logic is verified by unit tests in src/__tests__/diff-analyzer.test.ts.

Frequently Asked Questions

How does the Egonex-AI Diff Analyzer determine which components are affected by a change?

The analyzer calculates affected components by performing a one-hop neighbor search across the Knowledge Graph. After identifying changed nodes through file path matching, it traverses all edges at lines 57-69 in diff-analyzer.ts to collect any node directly linked to a changed node that is not itself changed. These become the affectedNodeIds, representing the immediate blast radius of the modification.

What happens if a changed file is not in the Knowledge Graph?

Unmapped files are captured in the unmappedFiles array during the initial path matching phase (lines 31-38). The formatDiffAnalysis function explicitly surfaces these in the Unmapped Files section and flags them in the Risk Assessment as potential blind spots requiring re-analysis or graph regeneration.

How does the analyzer handle nested structures like classes inside changed files?

The analyzer treats containment relationships as change propagation channels. At lines 44-48, it walks all edges where type === "contains" and adds their targets to changedNodeIds. This ensures that functions, classes, and methods defined within a changed file are automatically marked as changed components, even if their specific line ranges weren't modified.

Can the Diff Analyzer integrate with CI pipelines?

Yes. The buildDiffContext and formatDiffAnalysis functions are pure TypeScript with no DOM dependencies, making them suitable for Node.js CI environments. The markdown output can be posted as PR comments, stored as artifacts, or consumed by downstream LLM agents for automated code review, as demonstrated in the repository's test suite at understand-anything-plugin/src/__tests__/diff-analyzer.test.ts.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}