deep-diff-forge · Rust review engine

A diff isn’t a blob of lines. It’s a review.

A next-generation review engine for code changes — patch truth and semantic intent, together. Deep-Diff-Forge preserves the exact, apply-able patch while layering syntax-aware understanding, risk ranking, agent annotations and a terminal cockpit on top. Every layer a projection over one stable model; none allowed to corrupt the patch.

View on GitHub ↗ Install & build

L9

maturity · learning

12

narrow crates

721

tests

0

unsafe blocks

MIT / Apache-2.0

dual licensed

The first principle

“A diff engine must preserve patch truth while exposing semantic intent.”

Patch truth — the exact text that can be applied — is sacred and separable from every enrichment layer. Semantic analysis, risk ranking and AI annotations may be absent, partial, or wrong; they can never mutate the apply-able patch. The parser, projections, ranking, annotation layer and cluster scheduler all read the model. None rewrite it.

Three pioneer features

Built for humans reviewing AI-generated changes — and for the agents that drive review.

01

Semantic Patch Twin

Every change carries two synchronized representations — an apply-able patch twin and a syntax semantic twin, joined by stable anchors. Switch views without losing line anchors, comments, or applicability.

02

Review Intelligence Graph

A deterministic, explainable risk ranking that orders the review stream by likely impact — public-API surface, change size, new/deleted files, generated-file suppression — rather than raw file order.

03

Adaptive Diff Planner

Per-file, per-region strategy selection with explained, budgeted, conservative fallback. The engine chooses how to diff each region, and always degrades safely rather than guessing.

A review engine, not a syntax-highlighting pager.

Default, out-of-the-box behavior. Honest — it doesn’t yet do everything the rendering-focused tools do.

Capability

deep-diff-forge

delta

difftastic

diff-so-fancy

diff

Install & build

Bash-first, Claude-Code-first.

Every action has a deterministic command, machine-readable output (--json / --jsonl), stable exit codes, and works as a Unix filter with no daemon required. Requires Rust 1.85+ (edition 2024).

→Review a working tree, risk-ranked, highest impact first.

→Emit a schema-versioned review document for CI or an agent.

→Launch the interactive review cockpit, or render one frame headlessly.

# build the release binary
CARGO_TARGET_DIR=target cargo build \
  --release -p deep-diff-forge-cli
# risk-ranked review: what to look at first
git diff | deep-diff-forge \
  --stdin-patch --rank
# machine-readable review for an agent / CI
git diff | deep-diff-forge \
  --stdin-patch --json > review.json
# interactive review cockpit
git diff | deep-diff-forge review

Architecture

Twelve narrow crates, strictly acyclic.

Dependency flow is inward. core is pure vocabulary — no I/O, no parsing. Every feature crate depends on it, never the reverse. Patch truth is upstream of everything.

core

Stable model: IDs, patch/semantic twins, planner & graph vocabulary.

patch

Unified/Git patch parser, apply-able renderer, review.v0 JSON.

projection

Renderer-neutral inline & side-by-side projections.

pipeline

Composable Unix-filter stages, ingest/render, JSONL.

syntax

Tree-sitter detection, budgeted parse, symbol extraction.

graph

Review Intelligence Graph — deterministic risk ranking.

agent

Annotation provenance, grounding, sanitization, anchor validation.

tui

Review-first terminal UI (ratatui), tested headlessly.

cluster

Bounded parallel execution + deterministic joins + receipts.

learning

L9 local-only learning loop: receipts, scoring, gated promotion.

daemon

Optional UDS JSON-RPC service (std-first).

cli

Thin command entry point over the above.

Maturity ladder · L0–L9 shipped

L0 Bootstrap L1 Patch L2 Projection L3 Pipeline L4 Semantic L5 Review L6 Cluster L7 Daemon L8 Release L9 Learning

Risk ranking signals

Deterministic, explainable, identical for any worker count.

Higher score = review first. Parallelism never changes the result.

public_api_surface

lib.rs / mod.rs / api paths — strong boost.

large_change

≥ 80 changed lines.

many_hunks

≥ 5 hunks.

new / deleted_file

added or removed file.

binary_change

no reviewable text.

config_or_lockfile

Cargo.toml, *.lock, *.yaml.

test_only

de-prioritized below source.

generated_or_vendored

vendor/, target/, *.min.js — suppressed to 0.

Project status · honest limitations

An actively-built engine at L9 maturity. Everything documented is implemented, gated and live-proven. In the spirit of the paradigm, the current edges are stated plainly:

Full patch↔symbol join awaits a Git-input layer that supplies file bytes; semantic <file> proves the engine on whole files today.
The daemon serves connections sequentially; an async upgrade is deferred until a measured need.
v0.2.0 is publish-ready (clean cargo publish --dry-run); the crates.io upload is gated on a registry token.

Clone it. Review with it. Build on it.

Dual MIT / Apache-2.0. Zero unsafe. Supply-chain gated. The first engine off the CodaClave floor.

View on GitHub ↗ The paradigm behind it