How the Diff-Overlay Tracks Git Changes Within the Knowledge Graph

The diff-overlay tracks Git changes by mapping modified file paths to existing knowledge graph nodes, propagating impact through "contains" relationships and one-hop edges, then persisting the enriched context as JSON for dashboard visualization.

The diff-overlay feature in the Egonex-AI/Understand-Anything repository bridges Git version control with knowledge graph visualization. When developers run the /understand-diff skill, the system analyzes commit differences and overlays change data onto the architectural graph, highlighting exactly which components changed and what depends on them.

Mapping Git File Changes to Knowledge Graph Nodes

Identifying Changed Files in the Graph

The process begins in understand-anything-plugin/src/diff-analyzer.ts where the buildDiffContext function receives the list of files changed between two Git commits. It iterates through every node in the knowledge graph, comparing each node's filePath property against the Git-reported changes (lines 31-42):

for (const file of changedFiles) {
  // ...
  if (node.filePath === file) {
    changedNodeIds.add(node.id);
    // ...
  }
}

Files that match existing nodes are added to the changedNodeIds set, while unmatched paths are tracked separately as unmapped files—indicating the graph may need re-analysis to include new components.

Propagating Changes to Child Nodes

Changes cascade downward through "contains" relationships. When a file node is modified, all child nodes (such as classes or functions inside that file) are also marked as changed (lines 44-49):

if (edge.type === "contains" && changedNodeIds.has(edge.source)) {
  changedNodeIds.add(edge.target);
}

This propagation ensures that the changedNodeIds set captures both the modified files and their internal components.

Computing Affected Nodes and Relationships

One-Hop Impact Analysis

After identifying changed nodes, the analyzer calculates affected nodes—entities that share direct relationships with changed components. The system examines every edge where either the source or target is a changed node (lines 57-69):

if (sourceChanged || targetChanged) {
  impactedEdges.push(edge);
  // ...
  affectedNodeIds.add(edge.target);
  // ...
}

These edges become impactedEdges, and the opposite endpoints become affected nodes, creating a complete picture of immediate architectural impact.

Layer-Based Impact Detection

The analyzer then determines which architectural layers (API, Service, UI, etc.) contain changed or affected nodes (lines 74-77):

layers.filter(layer => layer.nodeIds.some(id => allImpactedIds.has(id)))

This filtering allows the dashboard to highlight entire architectural slices that require attention during the commit review.

Generating the Diff-Overlay Output

Once the context is built, formatDiffAnalysis converts the DiffContext into a structured markdown report (lines 90-197 in diff-analyzer.ts). The skill then serializes the full context to .understand-anything/diff-overlay.json (lines 79-87):

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

async function generateOverlay(graph: KnowledgeGraph, changedFiles: string[]) {
  const ctx = buildDiffContext(graph, changedFiles);
  const markdown = formatDiffAnalysis(ctx);
  await Deno.writeTextFile(".understand-anything/diff-overlay.json", JSON.stringify(ctx));
  return markdown;
}

The resulting JSON includes the project name, original file list, changed node IDs, affected node IDs, impacted edges, affected layers, and any unmapped files.

Visualizing Changes in the Dashboard

The dashboard dev server serves the overlay via a route configured in understand-anything-plugin/packages/dashboard/vite.config.ts (lines 295-296), mapping /diff-overlay.json to the physical file. The front-end loads this data in understand-anything-plugin/packages/dashboard/src/App.tsx (line 168):

const overlayUrl = dataUrl("diff-overlay.json", accessToken);
const overlay = await fetch(overlayUrl).then(res => res.json());

The visualization layer applies distinct highlighting:

• Red-tinted nodes for changed components
• Layer-colored nodes for affected components
• Highlighted edges showing impacted relationships
• Unmapped files list alerting users to graph coverage gaps

Summary

• The diff-overlay correlates Git file changes with knowledge graph nodes by matching filePath properties in understand-anything-plugin/src/diff-analyzer.ts.
• Child propagation through "contains" edges ensures internal components inherit change status from their parent files.
• One-hop impact analysis identifies related nodes and edges that connect to changed components, mapping architectural ripple effects.
• Layer detection groups changes by architectural slice (API, Service, UI) for quick assessment of affected domains.
• The system persists results to .understand-anything/diff-overlay.json and serves them via the dashboard's Vite dev server for real-time visualization.

Frequently Asked Questions

How does the diff-overlay handle files not yet in the knowledge graph?

Files reported by Git that lack corresponding nodes in the graph are tracked as unmapped files in the DiffContext object. The dashboard displays these separately, alerting users that the graph may need re-analysis to include new or renamed components.

What determines whether a node is "affected" versus "changed"?

Changed nodes directly correspond to files modified in the Git commit or their children via "contains" relationships. Affected nodes are those connected to changed nodes by any edge type within one hop—their immediate architectural neighbors that may experience impact from the changes.

Can the diff-overlay track changes across multiple commits?

The buildDiffContext function accepts any array of file paths, typically generated by comparing two Git commits. While the example shows single commit comparisons, the underlying logic supports arbitrary file lists, allowing the skill to analyze ranges or custom change sets by adjusting the Git command that feeds the changedFiles parameter.

Where is the diff-overlay data stored and how is it accessed?

The overlay persists as JSON to .understand-anything/diff-overlay.json in the project root. The dashboard's Vite configuration (understand-anything-plugin/packages/dashboard/vite.config.ts) maps requests for /diff-overlay.json to this physical file, enabling the front-end to fetch it via standard HTTP requests using the dataUrl helper with appropriate access tokens.

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