source-migration-visual-app

name	source-migration-visual-app
description	Use when an agent needs to run, extend, test, or explain the MigrateToWinUI visual migration app for Avalonia or WPF source migration to WinUI or Uno. Triggers on visual app workflows, migration dashboard, preview diffs, sessions, report export, target composition UI, validation history, rule browser, and src/MigrateToWinUI.App changes.

Visual Migration App Usage

Use this skill for the Uno Platform visual app in src/MigrateToWinUI.App/MigrateToWinUI.App. The app must route migration operations through shared library APIs, not by shelling out to the CLI. The first screen is the migration workspace.

Repo Entry Points

• App solution: src/MigrateToWinUI.App/MigrateToWinUI.App.sln
• App project: src/MigrateToWinUI.App/MigrateToWinUI.App/MigrateToWinUI.App.csproj
• App UI: src/MigrateToWinUI.App/MigrateToWinUI.App/MainPage.xaml
• App code-behind: src/MigrateToWinUI.App/MigrateToWinUI.App/MainPage.xaml.cs
• Dashboard view models: src/MigrateToWinUI.App/MigrateToWinUI.App/ViewModels
• Workspace/report services: src/MigrateToWinUI.App/MigrateToWinUI.App/Services
• Visual app contract: specs/001-migration-core/contracts/visual-app.md
• CLI/library behavior reference: specs/001-migration-core/contracts/cli.md
• Validation models: src/MigrateToWinUI.Core/Validation
• Session models: src/MigrateToWinUI.Core/Sessions

Required App Workflow

1. Browse.

   • Select input path with native file/folder picker.
   • Select output path for reports, staging, generated shells, or composed target projects.

2. Analyze.

   • Inputs: InputPath, SourceFramework, Target.
   • Output state: Findings, RewritePlans, Rules, summary counts, StatusText.
   • Use the shared migration engines that back CLI analyze, including project rules, C# rules, XAML rules, analyzer diagnostics, and JSON rule-pack diagnostics.

3. Preview.

   • Inputs: current report plus selected safe rewrites.
   • Output state: PreviewText, FileDiffs, selected rewrite summary.
   • Show side-by-side diffs without mutating source.

4. Stage.

   • Copy selected safe-rewritten output to a separate staging directory.
   • Preserve manual-review findings and skipped rewrite plans.

5. Generate shells.

   • Uno shell: deterministic Uno.Sdk target shell.
   • WinUI shell: deterministic unpackaged WinUI 3 target shell.
   • Do not overwrite existing files unless the user made an explicit overwrite choice.

6. Compose targets.

   • Inputs: generated shell, selected safe-rewritten source, asset map, reviewed manual items.
   • Output: composed Uno/WinUI project tree, composition preview summary, validation inputs, Reports/target-composition.json.
   • Rename .axaml files to .xaml in the target tree when required.

7. Validate.

   • Run static migration validation and any available target-shell validation.
   • Persist validation results and history.
   • Surface remediation links and manual-review blockers.

8. Export and session.

   • Export migration reports as JSON, Markdown, or SARIF.
   • Export migration plans as JSON or Markdown.
   • Save and load migration-session.json.

9. Rule browser and API coverage.

   • List in-memory built-in and rule-pack specs.
   • Show rule impact by findings, selected rewrite count, severity, category, and affected files.
   • Keep classification coverage separate from automation coverage.

Persistent Artifacts

Use the contract names when adding or validating app behavior:

• migration-session.json
• validation-history.json
• Reports/migration-report.{json|md|sarif}
• Reports/migration-plan.{json|md}
• Reports/api-coverage.{json|md|csv}
• Reports/api-rule-gaps.{json|md|csv}
• Reports/target-composition.json
• Staged/
• UnoApp/
• WinUI/
• TargetProjects/

Deterministic Checks

Use CLI commands as an oracle for expected app behavior, but do not implement app actions by shelling out:

dotnet run --project src/MigrateToWinUI.Cli -- analyze samples/AvaloniaInput --source avalonia --target both --format json --report artifacts/app-oracle-report.json
dotnet run --project src/MigrateToWinUI.Cli -- detail samples/WpfInput --source wpf --target both --format md --out artifacts/app-oracle-dashboard.md
dotnet run --project src/MigrateToWinUI.Cli -- compose samples/AvaloniaInput --source avalonia --target both --out artifacts/app-oracle-targets --project-name AppOracle --clean --allow-manual-review

Expected app parity:

• Same source framework and target profile semantics.
• Same finding ids, severities, rule categories, and safe rewrite plans.
• Same manual-review blockers.
• Same composition output shape for equivalent selected rewrites and reviewed manual items.

Build and Test

dotnet build src/MigrateToWinUI.App/MigrateToWinUI.App.sln
dotnet test --filter "FullyQualifiedName~MigrationDashboardSnapshotBuilderTests|FullyQualifiedName~MigrationSessionTests|FullyQualifiedName~ValidationHistoryTests|FullyQualifiedName~TargetProjectStagingServiceTests"

If the user asks to run the desktop app, use the app project:

dotnet run --project src/MigrateToWinUI.App/MigrateToWinUI.App/MigrateToWinUI.App.csproj

Guardrails

• Do not replace library calls with CLI process execution in the app.
• Do not make Apply Selected, Stage, or Compose operate on hidden selections. The selected rewrite set must be explicit and reproducible.
• Do not clear manual-review diagnostics after previewing or applying safe rewrites.
• Do not compose target projects from the original workspace when a staged selection exists; composition must use selected safe rewrite plans and copied source.
• Do not treat target build success as proof that manual-review migration decisions were resolved.
• On non-Windows hosts, WinUI validation is skipped and staged Uno builds may still fail for unresolved migration blockers.
• Keep visual app reports compatible with specs/001-migration-core/contracts/report.schema.json and the dashboard/report writers in src/MigrateToWinUI.Core/Reporting.