# How Does the Diff Impact Analysis Feature (/understand-diff) Work in Understand-Anything?

> Explore how Understand Anything's `/understand-diff` feature analyzes Git diffs using knowledge graphs to assess downstream impact and risks effectively.

- Repository: [Yuxiang Lin/Understand-Anything](https://github.com/Lum1104/Understand-Anything)
- Tags: how-to-guide
- Published: 2026-06-02

---

**The `/understand-diff` command analyzes Git diffs by mapping changed files to knowledge graph nodes, propagating impact through one-hop dependencies, and generating a markdown risk assessment of downstream effects.**

The **diff impact analysis** feature in the Understand-Anything toolkit enables developers to evaluate the ripple effects of code changes without manual codebase inspection. By feeding a Git diff or pull request into the knowledge graph, the system identifies affected components, calculates risk levels, and produces structured reports for both human review and LLM consumption. This functionality centers on two core functions exported from the plugin's analyzer module.

## Core Architecture and Data Flow

The feature implements an eight-step pipeline defined in **[`understand-anything-plugin/skills/understand-diff/SKILL.md`](https://github.com/Lum1104/Understand-Anything/blob/main/understand-anything-plugin/skills/understand-diff/SKILL.md)** and executed through the **`buildDiffContext`** function in **[`understand-anything-plugin/src/diff-analyzer.ts`](https://github.com/Lum1104/Understand-Anything/blob/main/understand-anything-plugin/src/diff-analyzer.ts)**. The process transforms raw file changes into a comprehensive impact graph suitable for architectural review.

### Input Processing and Node Mapping

The pipeline begins when the skill obtains a list of changed file paths from the Git diff (typically via `git diff --name-only`). The **`buildDiffContext`** function iterates over these paths and searches the graph's `nodes` array for matching `node.filePath` values. Files that successfully match become **changed nodes**, while orphaned paths are recorded in `unmappedFiles` for later risk assessment.

According to the source code in [`diff-analyzer.ts`](https://github.com/Lum1104/Understand-Anything/blob/main/diff-analyzer.ts) (lines 31-42), this mapping establishes the foundation for all subsequent impact analysis by anchoring the diff to the knowledge graph's node structure.

### Containment Expansion and Impact Propagation

After direct mapping, the analyzer performs **containment expansion** to capture internal components. The function traverses **`contains`** edges to identify child nodes—such as functions or classes within a changed file—ensuring that modifications to a parent file surface all internal symbols that may require review (lines 44-49).

Next, the system executes **one-hop impact propagation** (lines 57-69). The analyzer scans every edge in the graph; if either endpoint connects to a changed node, the edge is added to `impactedEdges` and the opposite endpoint joins the **affected nodes** set. This bidirectional traversal captures both upstream callers and downstream dependencies, creating a complete blast radius of the change.

### Layer Aggregation and Context Assembly

With changed and affected nodes identified, the function aggregates **affected layers** by filtering the graph's `layers` array to include only those referencing nodes in the combined ID set (lines 74-77). The final **`DiffContext`** object (lines 79-87) encapsulates:

- Project metadata and raw file list
- Arrays of changed and affected nodes
- Impacted edge relationships
- Affected architectural layers
- Unmapped files requiring manual review

## Source Code Implementation

The analyzer's logic resides in **[`understand-anything-plugin/src/diff-analyzer.ts`](https://github.com/Lum1104/Understand-Anything/blob/main/understand-anything-plugin/src/diff-analyzer.ts)**, which exports two primary functions consumed by the skill definition:

1. **`buildDiffContext`** – Implements the graph traversal logic, node mapping, and layer aggregation described in the architectural walkthrough.
2. **`formatDiffAnalysis`** – Renders the `DiffContext` as structured markdown, including risk assessment calculations.

These functions are re-exported through **[`understand-anything-plugin/src/index.ts`](https://github.com/Lum1104/Understand-Anything/blob/main/understand-anything-plugin/src/index.ts)** to ensure availability for the skill implementation defined in [`SKILL.md`](https://github.com/Lum1104/Understand-Anything/blob/main/SKILL.md).

## Practical Usage Example

You can invoke the diff impact analysis programmatically using the exported functions:

```typescript
import { readFile } from "node:fs/promises";
import { buildDiffContext, formatDiffAnalysis } from "@understand-anything/skill";

// Load the persisted knowledge graph
const graph = JSON.parse(
  await readFile("./.understand-anything/knowledge-graph.json", "utf-8"),
);

// Define changed files (normally from git diff)
const changedFiles = ["src/service.ts", "src/routes.ts"];

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

// Generate human-readable markdown report
const markdown = formatDiffAnalysis(ctx);
console.log(markdown);

```

Executing this snippet against the test suite graph (see **[`diff-analyzer.test.ts`](https://github.com/Lum1104/Understand-Anything/blob/main/diff-analyzer.test.ts)**) produces a markdown report containing *Changed Components*, *Affected Components*, *Affected Layers*, and *Risk Assessment* sections.

## Risk Assessment and Dashboard Integration

The **`formatDiffAnalysis`** function (lines 93-195) constructs the final output through several markdown sections:

- **Changed Components** – Directly modified files and their contained symbols
- **Affected Components** – Nodes within the one-hop dependency radius
- **Affected Layers** – Architectural layers touched by the changes
- **Impacted Relationships** – Edges connecting changed and affected nodes
- **Unmapped Files** – Changed paths not found in the knowledge graph

The **Risk Assessment** section evaluates four specific factors: node complexity metrics, cross-layer dependency count, total blast radius size, and the presence of unmapped files that might indicate coverage gaps.

According to [`SKILL.md`](https://github.com/Lum1104/Understand-Anything/blob/main/SKILL.md) (lines 61-70), the skill additionally writes a JSON overlay to [`.understand-anything/diff-overlay.json`](https://github.com/Lum1104/Understand-Anything/blob/main/.understand-anything/diff-overlay.json), enabling the dashboard to visually highlight changed and affected nodes for interactive exploration.

## Summary

- The `/understand-diff` command leverages **`buildDiffContext`** in [`diff-analyzer.ts`](https://github.com/Lum1104/Understand-Anything/blob/main/diff-analyzer.ts) to map Git diffs onto the knowledge graph.
- **Containment edges** expand file changes to include internal symbols, while **one-hop edge traversal** identifies upstream and downstream dependencies.
- The system aggregates affected architectural layers and calculates risk based on complexity, cross-layer dependencies, and unmapped files.
- Output is rendered via **`formatDiffAnalysis`** as structured markdown and supplemented by a JSON overlay for dashboard visualization.
- All functionality is tested in **[`diff-analyzer.test.ts`](https://github.com/Lum1104/Understand-Anything/blob/main/diff-analyzer.test.ts)**, which documents expected behavior for node detection and impact propagation.

## Frequently Asked Questions

### How does the analyzer handle files not present in the knowledge graph?

Files that do not match any `node.filePath` in the graph are collected in the `unmappedFiles` array within the `DiffContext`. These unmapped files contribute to the risk assessment, as they represent changes that cannot be analyzed for downstream impact, potentially indicating gaps in the knowledge graph coverage or new files requiring ingestion.

### What types of relationships does the diff impact analysis traverse?

The analyzer specifically examines **`contains`** edges to expand parent files into their child symbols (functions, classes), and general **edges** for one-hop impact propagation. The one-hop traversal is bidirectional, capturing both dependencies pointing to changed nodes (callers) and dependencies originating from changed nodes (callees), ensuring comprehensive blast radius detection.

### Can I use the diff analyzer outside of the CLI skill interface?

Yes. The **`buildDiffContext`** and **`formatDiffAnalysis`** functions are exported from **[`understand-anything-plugin/src/index.ts`](https://github.com/Lum1104/Understand-Anything/blob/main/understand-anything-plugin/src/index.ts)** and can be imported programmatically into any TypeScript or JavaScript application. You must provide a valid knowledge graph object and an array of changed file paths, allowing integration into CI/CD pipelines, custom IDEs, or automated code review systems.

### Where is the risk level calculated in the source code?

The risk assessment logic resides in **`formatDiffAnalysis`** within [`diff-analyzer.ts`](https://github.com/Lum1104/Understand-Anything/blob/main/diff-analyzer.ts) (lines 158-195). The function evaluates node complexity, counts cross-layer dependencies, measures the total blast radius (number of affected nodes), and checks for unmapped files to generate a qualitative risk rating included in the markdown output.