binary-decompile-analyze

name	binary-decompile-analyze
description	Use for MigrateToWinUI source-unavailable managed DLL/EXE migration work: inventory assumptions, decompile staging, analyze/convert reporting, safe rewrite preview checks, provenance review, BAML/resource manual gates, and validation against the binary migration contract.

Binary Decompile and Analyze

Use this skill when the input is a managed .dll or .exe instead of source. The binary lane is conservative: never patch original binaries, never claim generated source is original source, and never treat BAML-derived XAML as safe-rewrite input without explicit fixture-backed validation.

References

• CLI examples and current implemented commands: README.md
• CLI contract, including future binary inventory/decompile/analyze verbs: specs/001-migration-core/contracts/cli.md
• Binary migration contract: specs/001-migration-core/binary-migration.md
• Binary corpus and expected fixture categories: specs/001-migration-core/binary-migration-corpus.md
• Report schema: specs/001-migration-core/contracts/report.schema.json

Input Assumptions

Confirm these before running migration commands:

• The input path is a managed .dll or .exe with readable CLR metadata.
• --source is explicit when the binary is known WPF or Avalonia; use auto only when the evidence should decide.
• PDBs, .deps.json, .runtimeconfig.json, satellite assemblies, and loose resources are colocated or otherwise available.
• Reference roots are pinned and local. Do not restore packages, probe feeds, or choose latest framework versions during deterministic analysis.
• Output paths are outside the original binary directory unless the user explicitly requests otherwise.

Command Workflow

From the repository root, set stable shell variables:

INPUT=/absolute/path/to/App.dll
SOURCE=wpf
TARGET=both
OUT=out/binary/App
REPORT=out/binary/App/migration-report.json
PREVIEW=out/binary/App/rewrite-preview.txt

Check the CLI surface first:

dotnet run --project src/MigrateToWinUI.Cli -- --help
dotnet run --project src/MigrateToWinUI.Cli -- decompile --help

Run a read-only binary analysis report. Direct assembly inputs are detected by analyze; --decompile makes that behavior explicit:

dotnet run --project src/MigrateToWinUI.Cli -- analyze "$INPUT" --source "$SOURCE" --target "$TARGET" --format json --decompile --out "$OUT" --report "$REPORT"

Run the artifact-producing decompile pass:

dotnet run --project src/MigrateToWinUI.Cli -- decompile "$INPUT" --source "$SOURCE" --target "$TARGET" --out "$OUT" --report "$REPORT" --preview "$PREVIEW" --format json

Only include local UI-related references when the user wants reference assembly projections and accepts the larger review surface:

dotnet run --project src/MigrateToWinUI.Cli -- decompile "$INPUT" --source "$SOURCE" --target "$TARGET" --out "$OUT" --report "$REPORT" --preview "$PREVIEW" --format json --include-references

Use convert --decompile --dry-run when the user wants rewrite selection visibility without writing edits:

dotnet run --project src/MigrateToWinUI.Cli -- convert "$INPUT" --source "$SOURCE" --target "$TARGET" --dry-run --decompile --out "$OUT" --report "$REPORT" --preview "$PREVIEW"

If a future repo revision implements the contract-level binary verbs, prefer those for manifest-pinned runs:

dotnet run --project src/MigrateToWinUI.Cli -- binary inventory --manifest binary-migration-manifest.json --out out/binary/inventory.json --format json
dotnet run --project src/MigrateToWinUI.Cli -- binary decompile --manifest binary-migration-manifest.json --out out/binary/projection --format json
dotnet run --project src/MigrateToWinUI.Cli -- binary analyze --manifest binary-migration-manifest.json --target both --out out/binary/report --format json

Output Checks

After every run, verify:

• Exit code 0 means no error-level findings; exit code 2 means migration or validation failures that require review.
• The report exists at the requested path and records target, effective source framework, generated source paths, extracted resources, and manual-review diagnostics.
• The staged output contains decompiled C# projection files and recovered exact loose .xaml or .axaml resources when available.
• BAML files are extracted or reported, and any BAML-derived XAML is marked manual-review.
• Preview output contains only safe rewrite candidates requested by rule ids; absence of a preview means no rewrite claims were made.
• Provenance distinguishes PDB/Source Link locations from metadata-token, IL-offset, resource, and decompiler-synthetic locations.

Useful inspection commands:

find "$OUT" -maxdepth 3 -type f | sort
rg -n "BAML|manual|unsupported|unresolved|warning|Error|AW2U|WP2U" "$OUT" "$REPORT" "$PREVIEW"
dotnet run --project src/MigrateToWinUI.Cli -- verify "$OUT" --source "$SOURCE" --target "$TARGET"

Manual-Review Gates

Stop before recommending apply/compose when any gate is unresolved:

• Input is native, mixed-mode, packed, encrypted, single-file bundle-only, ReadyToRun-only, obfuscated beyond readable metadata, or otherwise inventory-only.
• Required references are unresolved or conflicting.
• Decompiler warnings affect migrated members.
• Source-map coverage is below the manifest or task threshold.
• Any BAML-derived XAML, approximate resource projection, unsupported resource, or copied binary resource lacks a manual-review diagnostic.
• The source framework is ambiguous or mixed and the user has not chosen avalonia or wpf.
• Safe rewrite candidates touch generated decompiler code whose provenance or semantic equivalence is uncertain.

Reporting Discipline

When summarizing results, separate:

• What was recovered exactly.
• What was decompiled approximately.
• What was inventoried only.
• What is safe-rewrite eligible.
• What requires manual migration.

Do not describe a binary migration as complete unless the report, provenance, resource limitations, and verification gates all pass.