FolderDiffIL4DotNet / nildiff (English)

日本語版はこちら / Japanese version

FolderDiffIL4DotNet is distributed as the nildiff .NET global tool. It compares old/new build folders, reduces .NET assembly false positives from IL metadata noise, and writes review artifacts that can be archived for release sign-off.

Why this exists:

• Compare old/new builds without chasing false positives from MVIDs, timestamps, and other build metadata.
• Produce Markdown, interactive HTML, and JSON audit artifacts for human review.
• Keep release comparison self-contained and offline-friendly.

For the full usage and configuration reference, see USER_GUIDE.md.

Quick Start

Requires .NET SDK 8.x or later.

dotnet tool install -g nildiff
dotnet tool install -g dotnet-ildasm
nildiff "/path/to/old-folder" "/path/to/new-folder" "my-comparison" --no-pause

Open the reports folder:

nildiff --open-reports

Check IL disassembler detection:

nildiff --doctor

nildiff --version prints the same public SemVer used by the GitHub release and NuGet package. nildiff --doctor retains the detailed build/commit version for diagnostics.

When launched directly from an interactive console with stdin, stdout, and stderr unredirected, nildiff checks for a newer stable release and may offer update or skip choices. Redirected, piped, and automated runs skip the prompt. See Startup update notification for cache behavior, choices, platform examples, and the exact eligibility rule.

Build from source:

git clone https://github.com/Widthdom/FolderDiffIL4DotNet.git
cd FolderDiffIL4DotNet
dotnet build
dotnet run -- "/path/to/old-folder" "/path/to/new-folder" "my-comparison" --no-pause

Usage

nildiff <old-folder> <new-folder> [report-label] [options]

Common options:

Option	Purpose
--config <path>	Load a specific config.json.
--output <path>	Write reports under a custom output directory.
--skip-il	Skip IL comparison and use SHA256/text comparison only.
--threads <n>	Override comparison parallelism for this run.
--fail-on-diff	After generating all artifacts, exit with code 5 when final Added/Removed/Modified entries remain.
--print-config	Print the effective builder state after env-var and supported CLI overrides without semantic validation.
--validate-config	Validate config.json plus FOLDERDIFF_* environment-variable overrides before runtime CLI overrides are applied.
--open-reports	Open the reports folder and exit.
--version	Print the public release/NuGet SemVer and exit.
--doctor	Print build/commit diagnostics, probe dotnet-ildasm / ilspycmd availability, and show install guidance.

Full CLI behavior, HTML review workflow, integrity checks, semantic-change tables, and configuration details live in USER_GUIDE.md.

Configuration

config.json is optional; omitted keys use code-defined defaults. For normal diff runs, after loading config.json and applying environment-variable plus runtime CLI overrides, the effective configuration is validated before the comparison starts.

The detailed configuration table moved to USER_GUIDE.md. The annotated sample remains in doc/config.sample.jsonc, and the JSON Schema for IDE completion is doc/config.schema.json.

Current validated numeric constraints include InlineDiffContextLines >= 0 and ILCacheMaxMemoryMegabytes >= 0.

Generated Artifacts

By default each run writes a labeled report folder under Reports/<label>/:

• diff_report.md
• diff_report.html
• audit_log.json
• Optional SBOM files when SBOM generation is enabled.
• Optional IL/old/*.txt and IL/new/*.txt when IL text output is enabled.

diff_report.html is a standalone review document with filters, notes, reviewed-download export, and SHA256 integrity verification.

Documentation

Need	Document
Full user guide	USER_GUIDE.md
Configuration sample	doc/config.sample.jsonc
Troubleshooting	doc/TROUBLESHOOTING.md
Runtime architecture and contributor guardrails	doc/DEVELOPER_GUIDE.md
Test strategy and local commands	doc/TESTING_GUIDE.md
Shared AI-agent instructions	AGENT_GUIDE.md
Security model and reporting path	SECURITY.md
Release notes	CHANGELOG.md

Review responsibility: This tool reduces review noise, but it does not guarantee zero false negatives and must not replace human release judgment. Before shipping, a human reviewer should confirm the final decision against the relevant commit/PR diff, source code, and built artifacts.

License

MIT. See LICENSE.

FolderDiffIL4DotNet / nildiff（日本語）

English version

FolderDiffIL4DotNet は nildiff という .NET global tool として配布されます。旧/新ビルドフォルダを比較し、.NET アセンブリの IL メタデータ由来ノイズを減らし、リリースサインオフ用に保存できるレビュー成果物を出力します。

このツールの目的:

• MVID、timestamp、その他のビルドメタデータによる false positive を追いかけずに old/new ビルドを比較する。
• Markdown、インタラクティブ HTML、JSON 監査ログを human review 用に出力する。
• リリース比較を自己完結・オフライン対応にする。

詳細な使い方と設定リファレンスは USER_GUIDE.md に移動しました。

クイックスタート

.NET SDK 8.x 以降が必要です。

dotnet tool install -g nildiff
dotnet tool install -g dotnet-ildasm
nildiff "/path/to/old-folder" "/path/to/new-folder" "my-comparison" --no-pause

レポートフォルダを開く:

nildiff --open-reports

IL 逆アセンブラ検出を確認する:

nildiff --doctor

nildiff --version は GitHub リリースおよび NuGet パッケージと同じ公開 SemVer を表示します。nildiff --doctor では診断用の詳細なビルド／コミットバージョンを引き続き確認できます。

stdin・stdout・stderr がリダイレクトされていない対話型コンソールから直接起動すると、nildiff は新しい安定版を確認し、更新またはスキップの選択肢を表示する場合があります。リダイレクト、パイプ、自動実行ではプロンプトをスキップします。キャッシュ、各選択肢、OS 別の例、正確な判定条件は起動時の更新通知を参照してください。

ソースからビルドする:

git clone https://github.com/Widthdom/FolderDiffIL4DotNet.git
cd FolderDiffIL4DotNet
dotnet build
dotnet run -- "/path/to/old-folder" "/path/to/new-folder" "my-comparison" --no-pause

使い方

nildiff <old-folder> <new-folder> [report-label] [options]

よく使うオプション:

オプション	用途
--config <path>	指定した config.json を読み込みます。
--output <path>	カスタム出力ディレクトリ配下にレポートを書き出します。
--skip-il	IL 比較をスキップし、SHA256/text 比較のみを使います。
--threads <n>	この実行だけ比較並列度を上書きします。
--fail-on-diff	全成果物の生成後、最終的な Added/Removed/Modified が残る場合にコード 5 で終了します。
--print-config	環境変数と対応 CLI オーバーライドを適用した builder 状態を、セマンティック検証なしでそのまま出力するため、範囲外を含む effective config の診断にも使えます。
--validate-config	config.json に FOLDERDIFF_* 環境変数オーバーライドを適用した状態を、実行時 CLI オーバーライド適用前に検証します。
--open-reports	レポートフォルダを開いて終了します。
--version	公開リリース／NuGet と同じ SemVer を表示して終了します。
--doctor	ビルド／コミット診断を表示し、dotnet-ildasm / ilspycmd の利用可否確認とインストール案内を行います。

CLI の詳細、HTML レビュー手順、整合性検証、セマンティック変更テーブル、設定詳細は USER_GUIDE.md を参照してください。

設定

config.json は任意です。省略したキーはコード定義の既定値を使います。通常の diff 実行では、config.json の読み込み後、環境変数および実行時 CLI オーバーライドを適用した実効設定に範囲外の値がある場合、比較開始前に検証エラーになります。

詳細な設定表は USER_GUIDE.md に移動しました。注釈付きサンプルは doc/config.sample.jsonc、IDE 補完用 JSON Schema は doc/config.schema.json です。

現在の数値制約には InlineDiffContextLines >= 0 と ILCacheMaxMemoryMegabytes >= 0 が含まれます。

生成物

既定では、各実行で Reports/<label>/ 配下に次を出力します。

• diff_report.md
• diff_report.html
• audit_log.json
• SBOM 生成が有効な場合は SBOM ファイル。
• IL テキスト出力が有効な場合は IL/old/*.txt と IL/new/*.txt。

diff_report.html は、フィルタ、メモ、レビュー済み HTML ダウンロード、SHA256 整合性検証を備えた自己完結型レビュー文書です。

ドキュメント

目的	ドキュメント
詳細ユーザーガイド	USER_GUIDE.md
設定サンプル	doc/config.sample.jsonc
トラブルシューティング	doc/TROUBLESHOOTING.md
ランタイム設計とコントリビューター向け注意点	doc/DEVELOPER_GUIDE.md
テスト方針とローカルコマンド	doc/TESTING_GUIDE.md
AI エージェント向け共通指示	AGENT_GUIDE.md
セキュリティモデルと報告先	SECURITY.md
変更履歴	CHANGELOG.md

レビュー責任: このツールはレビューのノイズを減らしますが、false negative がゼロであることは保証せず、人間のリリース判断の代替にはなりません。出荷前に、関連する commit / PR diff、ソースコード、ビルド成果物と照合して最終判断してください。

ライセンス

MIT。詳細は LICENSE を参照してください。