whfmt.Analysis 1.1.0

whfmt.Analysis

Field-level semantic diff between binary files using whfmt.FileFormatCatalog definitions.

Instead of comparing raw bytes, whfmt.Analysis understands the structure of a file:

• Groups entries by logical key (e.g. filename inside a ZIP)
• Ignores noise fields (timestamps, padding, calculated offsets)
• Surfaces only meaningful structural changes
• Outputs rich text, JSON, or dark-themed HTML reports

Powered by 790+ whfmt format definitions covering Archives, Images, Executables, Documents, Audio, Databases, and more.

Install

dotnet add package whfmt.Analysis

Quick Start

using WhfmtAnalysis;
using WpfHexEditor.Core.Definitions;

var catalog = EmbeddedFormatCatalog.Instance;

// Compare two ZIP files semantically
var result = FormatDiff.Compare(catalog, "v1.zip", "v2.zip");

if (result.IsIdentical)
{
    Console.WriteLine("Files are semantically identical.");
}
else
{
    Console.WriteLine($"Format: {result.FormatName}");
    Console.WriteLine($"Changed fields: {result.ChangedCount}");

    foreach (var change in result.FieldChanges.Where(c => c.IsChanged))
        Console.WriteLine($"  {change.FieldName}: {change.ValueA} → {change.ValueB}");
}

API Reference

FormatDiff.Compare()

// From file paths — format auto-detected
DiffResult Compare(IEmbeddedFormatCatalog catalog, string fileA, string fileB)

// From byte arrays — format auto-detected from extension
DiffResult Compare(
    IEmbeddedFormatCatalog catalog,
    byte[] dataA, string nameA,
    byte[] dataB, string nameB)

DiffResult

FieldChange

DiffRenderer

// Plain text (console-friendly)
string text = DiffRenderer.RenderText(result);

// JSON (for tooling / CI pipelines)
string json = DiffRenderer.RenderJson(result);

// Dark-themed HTML (for reports)
string html = DiffRenderer.RenderHtml(result);

Output Examples

Text

whfmt.Analysis — Semantic Binary Diff
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  Format  : ZIP
  File A  : build-v1.zip (1,204,812 bytes)
  File B  : build-v2.zip (1,209,044 bytes)
  Delta   : +4,232 bytes

  Key fields:
  ✓ entry_count         00000023  →  00000024   CHANGED
  ✓ compression_method  00000008  →  00000008   unchanged
  ✓ crc32               A3F2019C  →  B7C3A4D1   CHANGED

  Ignored: timestamps (2), offsets (4)
  Result  : 2 field(s) changed

JSON

{
  "formatName": "ZIP",
  "fileA": "build-v1.zip",
  "fileB": "build-v2.zip",
  "sizeA": 1204812,
  "sizeB": 1209044,
  "rawByteDelta": 4232,
  "isIdentical": false,
  "changedCount": 2,
  "fieldChanges": [
    { "fieldName": "entry_count", "valueA": "00000023", "valueB": "00000024", "isChanged": true, "isIgnored": false },
    { "fieldName": "crc32",       "valueA": "A3F2019C", "valueB": "B7C3A4D1", "isChanged": true, "isIgnored": false }
  ]
}

Supported Formats with Semantic Diff

All 790+ catalog formats are supported for raw-byte fallback. Formats with a diff block in their .whfmt definition get full semantic key-field comparison.

CI Integration

# .github/workflows/binary-diff.yml
- name: Semantic binary diff
  run: |
    dotnet script diff.csx artifacts/v1/app.exe artifacts/v2/app.exe

// diff.csx
#r "nuget: whfmt.Analysis, 1.0.0"
using WhfmtAnalysis;
using WpfHexEditor.Core.Definitions;

var result = FormatDiff.Compare(EmbeddedFormatCatalog.Instance, Args[0], Args[1]);
Console.WriteLine(DiffRenderer.RenderText(result));
if (!result.IsIdentical) Environment.Exit(1);

Architecture

whfmt.Analysis
├── FormatDiff         — entry point, format detection, field extraction
├── DiffResult         — immutable result model
├── FieldChange        — per-field comparison record
└── DiffRenderer       — text / JSON / HTML output

Depends on: whfmt.FileFormatCatalog 1.3.0+ (zero other dependencies, cross-platform net8.0).

Related Packages

License

GNU AGPL v3.0 — © 2016–2026 Derek Tremblay / Pulsar Informatique