whfmt.Analysis 1.1.1

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
• Side-by-side hex diff per changed field (BytesA / BytesB / DiffMask)
• Checksum validation — detects corrupted checksums (CRC32 / MD5 / SHA1 / SHA256)
• Structural diff — block-level OnlyInA / OnlyInB / InBoth using MD5 hashes
• Outputs rich text, JSON, CSV, Markdown, or dark-themed HTML reports

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

Full documentation: whfmt-Analysis-guide.md — API reference, architecture, integration guides, and usage examples.

What's New

v1.1.1 — Catalog 1.3.2 alignment

• Catalog bump to whfmt.FileFormatCatalog 1.3.2 (Phase B audit + 2 bug fixes, 799 definitions, schema v3 canonical).
• No Analysis API changes — drop-in upgrade from 1.1.0.

v1.1.0 — Hex diff, checksums, structural diff

• HexDiff — per-byte BytesA / BytesB / DiffMask rendered inline for changed binary fields
• ChecksumStatus — CRC32 / MD5 / SHA1 / SHA256 stored-vs-computed validation per file (CorruptedCountA, CorruptedCountB)
• StructuralDiff — block-level OnlyInA / OnlyInB / InBoth using MD5 block hashes
• FieldChange.IsCorrupted — surfaces fields with broken checksums in diff output
• DiffResult is now an immutable value-object (all properties init-only)
• CompareAsync() — file-path and stream overloads
• New renderers — DiffRenderer.ToCsv() and DiffRenderer.ToMarkdown() (GitHub-flavored tables with emoji status)
• Single-pass field extraction in FormatDiff — half the JSON iteration cost on large definitions

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)

FormatDiff.CompareAsync()

// Async from file paths
Task<DiffResult> CompareAsync(IEmbeddedFormatCatalog catalog, string fileA, string fileB)

// Async from streams
Task<DiffResult> CompareAsync(
    IEmbeddedFormatCatalog catalog,
    Stream streamA, string nameA,
    Stream streamB, string nameB)

DiffResult

FieldChange

DiffRenderer

// Plain text (console-friendly, includes hex diff + checksum + structural sections)
string text = DiffRenderer.RenderText(result);

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

// CSV (Field,ValueA,ValueB,IsChanged,IsIgnored,IsCorrupted,DifferentBytes)
string csv = DiffRenderer.ToCsv(result);

// GitHub Markdown table with emoji status
string md = DiffRenderer.ToMarkdown(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 799 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, single-pass field extraction
├── DiffResult         — immutable value-object result model
├── FieldChange        — per-field comparison (IsCorrupted, HexDiff)
├── ChecksumStatus     — stored vs computed checksum per entry
├── StructuralDiff     — block-level OnlyInA / OnlyInB / InBoth
└── DiffRenderer       — text / JSON / CSV / Markdown / HTML output

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

Related Packages

License

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