Crate facet_diff 

facet-diff

facet-diff

Structural diffing for Facet types with human-readable output.

Overview

facet-diff computes differences between two values using reflection. It works on any type that implements Facet, without requiring manual diff implementations or PartialEq.

use facet_diff::{FacetDiff, format_diff};

let old = MyStruct { name: "alice", count: 1 };
let new = MyStruct { name: "alice", count: 2 };

let diff = old.diff(&new);
println!("{}", format_diff(&diff));
// Shows: count: 1 → 2

Features

• Reflection-based: Works on any Facet type automatically
• Human-readable output: Multiple output formats (colored, plain, compact)
• Sequence diffing: Uses Myers’ algorithm for optimal sequence alignment
• Float tolerance: Configure epsilon for floating-point comparisons

Usage

Basic Diffing

use facet_diff::FacetDiff;

let diff = old_value.diff(&new_value);

if diff.is_equal() {
    println!("Values are equal");
} else {
    println!("Changes detected");
}

Formatted Output

use facet_diff::{format_diff, format_diff_compact};

// Full colored diff
let output = format_diff(&diff);

// Compact single-line format
let compact = format_diff_compact(&diff);

With Options

use facet_diff::{DiffOptions, diff_new_peek_with_options};
use facet_reflect::Peek;

let options = DiffOptions::new()
    .with_float_tolerance(0.001);

let diff = diff_new_peek_with_options(
    Peek::new(&old),
    Peek::new(&new),
    &options,
);

Architecture

facet-diff uses facet-reflect to traverse values structurally:

1. Peek - facet’s reflection API provides access to fields and values
2. Myers’ algorithm - Optimal diff for sequences (lists, arrays)
3. Recursive comparison - Fields compared by structure, not equality
4. Layout rendering - facet-diff-core handles output formatting

Related Crates

• facet-diff-core: Core diff types and rendering
• facet-reflect: Reflection API for traversing Facet values
• facet-pretty: Pretty-printing for Facet values

Sponsors

Thanks to all individual sponsors:

…along with corporate sponsors:

…without whom this work could not exist.

Special thanks

The facet logo was drawn by Misiasart.

License

Licensed under either of:

• Apache License, Version 2.0 (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
• MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)

at your option.

Macros

debug

Emit a debug-level log message (no-op version).

trace

Emit a trace-level log message (no-op version).

trace_verbose

Emit an extremely verbose trace-level log message (no-op version).

Structs

AnsiBackend

ANSI backend - emits ANSI escape codes for terminal colors.

BuildOptions

Options for building a layout from a diff.

DiffFormat

Configuration for diff formatting.

DiffOptions

Configuration options for diff computation

DiffReport

A reusable diff plus its original inputs, allowing rendering in different output styles.

DiffSymbols

Symbols for diff rendering.

DiffTheme

Color theme for diff rendering.

Interspersed

An interspersed sequence of A and B values. Pattern: [A?, (B, A)*, B?]

JsonFlavor

JSON-style output flavor (JSONC with comments for type names).

LeafChange

A single leaf-level change in a diff, with path information.

Path

A path from root to a node.

PlainBackend

Plain backend - no styling, just plain text.

RenderOptions

Options for rendering a layout.

ReplaceGroup

A group of values being replaced (removals paired with additions).

RustFlavor

Rust-style output flavor.

Updates

Sequence updates: update groups interspersed with unchanged items.

UpdatesGroup

A group of updates containing replace groups interspersed with nested diffs.

XmlFlavor

XML-style output flavor.

Enums

ChangeKind

The kind of change for a diff element.

Diff

The difference between two values.

LeafChangeKind

The kind of leaf change.

PathSegment

A path segment describing how to reach a child.

Value

A set of updates, additions, deletions, insertions etc. for a tuple or a struct

Traits

ColorBackend

A backend that decides how to render semantic colors.

DiffFlavor

A diff output flavor that knows how to format values and present fields.

FacetDiff

Extension trait that provides a diff method for Facet types

Functions

build_layout

Build a Layout from a Diff.

collect_leaf_changes

Collect all leaf-level changes with their paths.

diff_new_peek

Computes the difference between two Peek values (backward compatibility wrapper)

diff_new_peek_with_options

Computes the difference between two Peek values with options

format_diff

Format the diff with the given configuration.

format_diff_compact

Format the diff in compact mode (path-based, no tree structure).

format_diff_compact_plain

Format the diff in compact mode without colors.

format_diff_default

Format the diff with default configuration.

render_to_string

Render a layout to a String.