Core concepts

Graph diff

Compare two Software Graph snapshots to understand exactly what changed — nodes added, removed, or modified, and edges gained or lost.

How it works

The diff engine performs an O(n+m) set-based comparison using HashMap lookups on deterministic node and edge IDs. It compares two graph JSON files and produces a structured diff with added, removed, and modified nodes plus added and removed edges.

Run a diff

Build two graph snapshots (e.g. from different branches or commits), then diff them. The output shows exactly what structural changes occurred.

TERMINAL

ontoly build . --output base-graph
git checkout feature-branch
ontoly build . --output head-graph
ontoly diff base-graph/SoftwareGraph.json head-graph/SoftwareGraph.json

Diff output

The diff contains six sections. Modified nodes track which specific fields changed — type, name, file, package, span, or metadata.

addedNodes — nodes in head but not in base
removedNodes — nodes in base but not in head
modifiedNodes — nodes in both with changed fields
addedEdges — relationships in head but not in base
removedEdges — relationships in base but not in head
summary — counts of added, removed, modified, unchanged

TERMINAL

ontoly diff base.json head.json --json

Design decisions

The v1 diff engine does not perform rename detection. A renamed function appears as a remove plus an add — this preserves determinism and avoids false-positive rename matches. Identity-based comparison means the diff is always reproducible.