How Egonex Diff Impact Analysis Tracks Ripple Effects Across Your Codebase

Egonex diff impact analysis tracks ripple effects by mapping changed files to knowledge graph nodes, propagating through "contains" edges, and walking the graph to identify affected neighbors, impacted edges, and architectural layers.

The Egonex-AI/Understand-Anything repository implements a sophisticated diff-impact analysis system that transforms a raw list of changed file paths into a comprehensive structural impact assessment. By operating on an in-memory knowledge graph, the analyzer traces how modifications propagate beyond directly edited files to reveal downstream components at risk.

The Core Architecture: From Git Diff to Knowledge Graph

The heart of the ripple-effect tracking lives in src/diff-analyzer.ts, specifically within the buildDiffContext function. This self-contained module executes three distinct phases to map local changes to global impact.

Mapping Changed Files to Graph Nodes

The analysis begins by correlating file system changes with the graph structure. For every file path returned by the diff (typically from git diff --name-only), the analyzer searches for a matching GraphNode where node.filePath equals the changed path.

As implemented in buildDiffContext (lines 31-42), this phase produces two critical sets: changed nodes (successfully matched entities) and unmapped files (paths present in the diff but absent from the graph, often indicating new files or incremental update needs).

Propagating Through Containment Relationships

Codebases organize logic hierarchically—directories contain files, classes contain methods. The analyzer respects these boundaries by scanning for edges where type === "contains" (lines 44-49). When a changed node is identified as a container, all immediate children (edge.target) are recursively added to the changed set.

This containment expansion ensures that editing a directory or high-level module automatically marks its constituents as changed, capturing structural relationships that file-path diffs alone would miss.

Walking the Graph for Ripple Effects

The final phase calculates true ripple effects by analyzing graph connectivity (lines 53-77). The system identifies:

• Affected nodes: One-hop neighbors of changed nodes (excluding already-marked changed nodes)
• Impacted edges: Every edge touching either a changed or affected node
• Affected layers: Architectural layers whose nodeIds intersect with the union of changed and affected IDs

This graph traversal surfaces dependencies that cross component boundaries, revealing which downstream systems may require testing or validation despite not being directly modified.

The DiffContext Data Structure

The buildDiffContext function returns a structured DiffContext object that captures the complete impact surface:

{
  projectName,
  changedFiles,
  changedNodes,
  affectedNodes,
  impactedEdges,
  affectedLayers,
  unmappedFiles
}

This data structure serves as the single source of truth for downstream reporting. It separates direct changes ( explicitly modified files) from indirect impacts (components connected via graph relationships), enabling precise risk assessment.

Generating Human-Readable Reports

Once the DiffContext is computed, the formatDiffAnalysis function (lines 58-94) transforms the graph data into a Markdown report. The formatter conditionally inserts sections based on impact severity, highlighting:

• Changed components with complexity metrics
• Downstream components requiring attention
• Cross-layer architectural impacts
• Boundary-crossing relationships
• Unmapped files for graph maintenance
• Automated risk scoring based on complexity, cross-layer impact, blast radius, and unmapped file presence

The entire pipeline operates purely on the in-memory graph—no external services are invoked, ensuring the analysis runs locally and rapidly even on large repositories.

Implementation Example

To integrate ripple-effect tracking into your workflow:

import { readKnowledgeGraph } from '@understand-anything/core';
import { buildDiffContext, formatDiffAnalysis } from '@understand-anything/plugin';

// 1️⃣  Load the persisted knowledge graph
const graph = await readKnowledgeGraph('/path/to/.understand-anything/knowledge-graph.json');

// 2️⃣  Gather changed files from your CI pipeline
const changedFiles = [
  'src/services/userService.ts',
  'src/utils/auth.ts',
];

// 3️⃣  Build the diff context – this is where ripple tracking happens
const diffCtx = buildDiffContext(graph, changedFiles);

// 4️⃣  Generate the markdown report
const report = formatDiffAnalysis(diffCtx);
console.log(report);

Running this snippet produces a Markdown document identical to the UI's "Diff Overlay" view, complete with risk assessments and architectural layer impacts.

Key Source Files

File	Role
src/diff-analyzer.ts	Core diff-impact logic containing buildDiffContext and formatDiffAnalysis
src/__tests__/diff-analyzer.test.ts	Test suite validating empty-diff handling, node mapping, and ripple calculations
packages/core/src/types.ts	TypeScript definitions for KnowledgeGraph, GraphNode, GraphEdge, and Layer
packages/core/src/graph-builder.ts	Generates the knowledge graph consumed by the diff analyzer
packages/dashboard/src/store.ts	UI store containing the diffMode flag that toggles the overlay visualization

Summary

• Egonex diff impact analysis operates on an in-memory knowledge graph to calculate change propagation beyond simple file diffs.
• The buildDiffContext function in src/diff-analyzer.ts executes a three-phase pipeline: node mapping, containment expansion, and graph walking.
• Ripple effects are tracked by identifying one-hop neighbors of changed nodes and the edges connecting them, plus architectural layers containing affected components.
• The system produces a DiffContext object capturing changed nodes, affected nodes, impacted edges, and unmapped files for comprehensive impact assessment.
• formatDiffAnalysis renders the results as a Markdown report with automated risk scoring based on complexity and blast radius.
• All analysis runs locally without external dependencies, making it suitable for CI/CD integration.

Frequently Asked Questions

How does Egonex diff impact analysis handle unmapped files?

Unmapped files—paths present in the git diff but lacking corresponding nodes in the knowledge graph—are collected separately in the unmappedFiles array of the DiffContext. These typically represent new files or components not yet indexed by the graph builder, and they contribute to the risk assessment score to flag potential blind spots in the analysis.

What constitutes an "affected node" in the ripple effect calculation?

An affected node is any one-hop neighbor of a changed node that is not already marked as changed. Specifically, when buildDiffContext iterates over edges (lines 53-77), if an edge touches a changed node, the opposite endpoint gets added to affectedNodeIds. This excludes containment relationships already processed in the expansion phase, focusing instead on dependency and reference edges that indicate downstream impact.

How is risk assessed in the diff analysis report?

Risk scoring occurs in the final block of formatDiffAnalysis (lines 58-94) and evaluates four factors: high complexity of changed components, cross-layer architectural impact, wide blast radius (number of affected nodes), and the presence of unmapped files. Each factor elevates the overall risk level, which is then displayed in the generated Markdown report to prioritize testing and review efforts.

Can the diff analyzer work without external services?

Yes. The entire analysis pipeline is self-contained and operates purely on the in-memory knowledge graph. The buildDiffContext function requires only the graph object and an array of changed file paths—no network calls, external APIs, or remote services are invoked. This local-first architecture ensures fast execution and privacy for sensitive codebases.

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