v0.29.0—Sharper bug analysis, reliable resource cleanup, and stronger test and CI checks.See what's new

migrate

Migrate an entire project between C# and Calor.

Bash
calor migrate <path> [options]

Overview

The migrate command converts all applicable files in a project or directory. It:

  • Scans for convertible files
  • Creates a migration plan
  • Converts files in parallel (optional)
  • Generates detailed reports
  • Handles errors gracefully without stopping

Quick Start

Bash
# Preview migration (dry run)
calor migrate ./src --dry-run

# Migrate C# to Calor
calor migrate ./src

# Migrate with report
calor migrate ./src --report migration-report.md

# Migrate Calor back to C#
calor migrate ./src --direction calor-to-cs

Options

OptionShortDefaultDescription
--dry-run-nfalsePreview changes without writing files
--benchmark-bfalseInclude before/after metrics comparison
--direction-dcs-to-calorMigration direction
--parallel-ptrueRun conversions in parallel
--report-rNoneSave migration report to file (.md or .json)
--verbose-vfalseEnable verbose output
--skip-analyze—falseSkip the migration analysis phase
--skip-verify—falseSkip the Z3 contract verification phase
--verification-timeout—5000Z3 verification timeout per contract, in milliseconds
--explicit-call-closers—falseEmit explicit §/C for every §C call (v0.6.0-compatible output).
--lossy—falseAllow reported semantic substitutions or drops. The default is lossless migration

Migration Plan

Before converting, the command analyzes your codebase and creates a plan:

Bash
calor migrate ./src --dry-run

Output:

Example output (not checked)
=== Migration Plan ===

Direction: C# → Calor
Source: ./src

Files to Convert:
  ✓ 24 files fully convertible
  ⚠ 8 files partially convertible (will have warnings)
  ✗ 3 files skipped (unsupported constructs)

Benchmark Summary

Use --benchmark to see aggregate metrics:

Bash
calor migrate ./src --benchmark

Output includes:

Example output (not checked)
=== Benchmark Summary ===

Token Savings: 17,090 tokens (37.8% reduction)

Migration Reports

Generate detailed reports for documentation:

Bash
# Markdown report
calor migrate ./src --report migration-report.md

# JSON report
calor migrate ./src --report migration-report.json

Each file result in the JSON report carries losses[], where every entry names its path (interop, rescue, passthrough, lossy, or dropped) and, for rescues, the trigger and enabledBy that applied. It also carries conversionPaths, the same per-file summary calor convert --format json writes (see Which Path Preserved Each Member). The console summary adds one line when any member was preserved:

Plain Text
  Preservation paths: 1 by automatic rescue (parse-failure: 1; no passthrough request needed)

migrate rescues fewer members than convert. It rescues a member whose Calor does not parse, but not one whose Calor parses and then fails the C# round trip: migrate checks the round trip once for the whole project, not file by file. Such a file fails. In the default lossless mode one failed file means no file is written, so every file then reports outcome: "refused". Its counts still show what conversion did. calor migrate has no --passthrough option.

For example, take a two-file project: Inventory.cs converts natively, and Counter.cs has a statement label that fails the C# round trip. calor convert Counter.cs alone rescues Counter as §CSHARP and exits 0. calor migrate on the project exits 1, writes no .calr file, and reports outcome: "refused" for both files. The MCP calor_migrate and calor_batch tools give the same result. To migrate the rest, convert the failing file with calor convert (or fix the C# first), then migrate the others. The C# interoperability guide lists which C# shapes convert natively in 0.25 and which can fail the round trip.


Exit Codes

CodeMeaning
0No files failed; warnings alone do not fail the command
1The path was missing, one or more files failed, or migration raised a handled error

See Also