Skip to content

Improve IL comparison normalization and report transparency - #256

Draft
Widthdom wants to merge 6 commits into
mainfrom
feature/robust-il-comparison
Draft

Improve IL comparison normalization and report transparency#256
Widthdom wants to merge 6 commits into
mainfrom
feature/robust-il-comparison

Conversation

@Widthdom

@Widthdom Widthdom commented Aug 14, 2026

Copy link
Copy Markdown
Owner

Summary

  • normalize build-variant IL values instead of discarding their entire lines
  • add configurable substring normalization with collision-free comparison-local markers
  • bound configured normalization by list size, value length, per-line replacement count, and normalized output size
  • render configured values and safety warnings unambiguously without allowing Markdown/HTML structure injection
  • remove ShouldIgnoreMVID and reject obsolete configuration explicitly in normal, validation, print-config, and clear-cache paths
  • replace the removed buildserver-winforms profile with creator-default, whose defaults now use normalization
  • add reproducible golden IL from the supported dotnet-ildasm and ilspycmd baselines
  • surface the effective normalization and ignore rules in Markdown and HTML report headers
  • align tests, report samples, configuration schema/sample, and English/Japanese documentation

Why

Disassembler output contains build-dependent values that can create false differences. Removing whole matching lines also hides meaningful content that happens to share those lines.

This change preserves the stable portions of IL while normalizing only known build-variant values: MVIDs, method RVAs, code sizes, and WinForms AxHost.TypeLibraryTimeStampAttribute payloads. ILSpy's multiline timestamp form is collapsed through its closing delimiter, while malformed or unterminated input remains raw and comparable.

Configured substring normalization remains separate from configured whole-line exclusion. Its replacement marker is selected per comparison so that it cannot collide with either raw IL input. The combined configured/profile list is limited to 256 entries of up to 4096 Unicode characters each. Across all configured rules, one line is limited to 65,536 non-overlapping replacements and 4,194,304 UTF-16 code units of normalized output; excess input fails before the expanded result is allocated.

Relationship diagnostics are bounded and configured values are rendered with safe, visible escapes in console, log, Markdown, and HTML output.

Breaking changes and migration

  • ShouldIgnoreMVID has been removed from the public configuration API. MVID values are always normalized. Supplying the former JSON key or FOLDERDIFF_SHOULDIGNOREMVID environment variable now fails with an explicit migration error, including --clear-cache.
  • The buildserver-winforms creator profile name has been removed without an alias. Use creator-default; the former name follows the normal invalid-profile path and exits with code 2, including early command paths.
  • This work is intended for the next major release. Version metadata is intentionally unchanged here and will be updated during release preparation.

Review and commit mapping

  1. ce04dc2 adds pinned, reproducible IL corpus data and applies .NET major-version roll-forward to tool probes and generation.
  2. d4d1ef0 removes ShouldIgnoreMVID, makes MVID handling unconditional, and rejects obsolete JSON/environment input consistently.
  3. bf85215 generalizes IL-output terminology from MVID-specific exclusion to the shared filtering pipeline.
  4. 8b975d4 implements built-in and configured normalization, collision-free markers, resource bounds, safe diagnostics, and report transparency.
  5. 4966a49 replaces the removed buildserver-winforms profile name with creator-default and applies invalid-profile handling before side-effecting early commands.
  6. e042deb migrates creator defaults from whole-line exclusion to substring normalization, applies profile values before configured values, and keeps AssemblyRef public-key-token changes visible.

Changed areas

  • comparison, configuration, creator-profile, CLI, and report-generation code under Common/, Models/, Runner/, and Services/
  • regression coverage and reproducible disassembler fixtures under FolderDiffIL4DotNet.Tests/
  • CHANGELOG.md, guides, package documentation, configuration schema/sample, and committed Markdown/HTML report samples

The PR contains 6 commits and changes 76 files.

Validation

  • Release build: succeeded with 0 warnings and 0 errors
  • Release test suite: 2,130 passed, 10 skipped, 0 failed
  • Every commit builds independently in Release with 0 warnings and 0 errors
  • Final adversarial review of main...HEAD: no actionable findings

@Widthdom
Widthdom force-pushed the feature/robust-il-comparison branch 8 times, most recently from 676c52f to c7e9ea1 Compare August 15, 2026 17:25
@Widthdom Widthdom changed the title Improve IL comparison normalization and auditability Improve IL comparison normalization and report transparency Aug 15, 2026
@Widthdom
Widthdom force-pushed the feature/robust-il-comparison branch from c7e9ea1 to e8d20af Compare August 15, 2026 18:06
@Widthdom
Widthdom force-pushed the feature/robust-il-comparison branch from e8d20af to e042deb Compare August 16, 2026 00:25
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant