A codemod that migrates model classes to zorphy
using resolved AST analysis — not regex — so union variants, generics,
defaults, and @JsonKey renames are converted correctly.
Two input dialects are supported:
- freezed model classes (the original target), and
@ExchangeableObject/@ExchangeableEnumcustom codegen models — the annotations used by flutter_inappwebview forks (e.g. zikzak_inappwebview) that do not use Freezed at all. Without this dialect the tool silently no-ops on such packages (see zorphy #86); with it, the same seamless migration path applies.
Part of the zorphy 2.0 release. See the comparison for why teams switch.
dart pub global activate zorphy_migrator
# or: dart run zorphy_migrator ... (as a dev dependency)
zorphy_migrator migrate lib/ --dry-run # preview unified diff (default)
zorphy_migrator migrate lib/ --apply --report MIGRATION.md
zorphy_migrator migrate lib/ --apply --fail-on-manual # CI: exit 1 if a human is needed
zorphy_migrator lean . --dry-run # slim @Zorphy annotations
zorphy_migrator lean . --apply --report LEAN.mdExit codes: 0 = clean migration, 1 = items need manual attention (or
nothing to migrate was found), 2 = analysis error.
lean is the other direction: the project already runs on zorphy, and the
annotations ask for more than the code consumes. It rewrites each @Zorphy
annotation to the smallest flavor that still covers everything the package
actually uses, so the generated code shrinks without changing behaviour.
zorphy_migrator lean . --dry-run # unified diff + per-class report
zorphy_migrator lean . --apply # rewrite in place, then re-run build_runnerHow it decides, per annotated class:
- Dropped when the class names no consumer:
FooPatch,FooFields,copyWithFooFnand the JSON factories are all named after their class, so an absent name is proof the generated helper is dead, and the flag that requests it is removed. - Kept when a consumer exists: a class referenced anywhere else in the
scanned tree is live, keeps the preset its author chose, and only loses
opt-in flags it can prove unused.
toJsonandcopyWithFnare instance calls with no class in the name, so they are never dropped from a live class. - Untouched arguments: anything that is not one of the four feature flags
(
autoId,kind,hidePublicConstructor, …) is carried over verbatim.
Scan scope and safety:
- Generated files (
.g.dart,.zorphy.dart, and the shared parts underlib/_br_/) are excluded — scanning them would make every class look used. - Pointing at a package root also scans
test/andintegration_test/, since a feature used only by a test still has to be generated. A target without apubspec.yamlof its own gets no such extra scan, and says so on stderr: its tests and any consumer outside the tree are invisible to the decision. - One file that does not parse is reported and skipped, not fatal.
- The scan is syntactic (no resolution), so
zik_zak-sized trees finish in seconds rather than minutes.
lean targets applications. Liveness is derived from the scanned tree and
nothing else, so a class whose only consumers live outside it comes out
"unused" and is rewritten to preset: ZorphyPreset.lean. For a package whose
generated code is its public API that is a breaking change no scan of the
package itself can see. Run lean on an application, or on a package with
--dry-run and read the report before applying.
| freezed construct | zorphy output |
|---|---|
@freezed class Foo with _$Foo { const factory Foo({required String a, int? b}) = _Foo; } |
@Zorphy(preset: ZorphyPreset.lean) abstract class $Foo { String get a; int? get b; } |
Union: factory Foo.ok(T v) = Ok; |
@Zorphy(explicitSubTypes: [$Ok]) abstract class $$Foo {} + abstract class $Ok implements $$Foo { T get v; } |
factory Foo.fromJson(...) => _$FooFromJson(json); |
generateJson: true on the annotation |
@Default(expr) |
@JsonKey(defaultValue: expr) on the getter (never silently dropped) |
@JsonKey(...) |
preserved verbatim on the getter |
| Field types referencing other migrated classes | rewritten to $-prefixed form (List<CartItem> → List<$CartItem>) |
@ExchangeableObject construct |
zorphy output |
|---|---|
@ExchangeableObject() class Foo_ { T x; Foo_({required this.x}); } |
@Zorphy(kind: ZorphyKind.valueObject, generateJson: true, generateCompareTo: true) abstract class $Foo { T get x; } |
this.x = expr constructor default |
@JsonKey(defaultValue: expr) on the getter |
@ExchangeableEnum() class Foo_ { static const A = Foo_._internal(0); } |
plain enum Foo { A } (member names + declaration order preserved) |
Field type Bar_ where Bar is converted in the same run |
Bar (the codegen _ suffix is dropped; concrete sibling form, recovered by zorphy #351) |
Lean-preset inference: classes that provably use only lean features (no
union, no defaults) are emitted with preset: ZorphyPreset.lean and the
choice is noted in the report; everything else uses the standard preset
(byte-compatible with zorphy 1.x defaults).
@unfreezedmutable classes — zorphy is immutable-first- Custom getters/methods in the class body
- Non-factory constructors and asserts
@Defaultexpressions that reference their own field- For
@ExchangeableObject/@ExchangeableEnum: custom@ExchangeableObjectMethod/@ExchangeableObjectProperty/@ExchangeableObjectConstructormembers, instance fields that are not constructor parameters, and enum wire values that do not map onto a plain enum (non-sequential ints, string values differing from the member name)
Every skipped construct appears in the report with file:line and a
reason. The tool never deletes files — removing *.freezed.dart and
the freezed dependencies is a documented manual step.
- Remove
freezed/freezed_annotationfrom pubspec; addzorphy(dev) +zorphy_annotation. - Delete
*.freezed.dart; keep.g.dartonly wheregenerateJson: truewas emitted. - Update
partdirectives: drop.freezed.dart. Add no zorphy directive — as of 3.0build_runnerinserts the shared-partpartline itself. - Replace
when/mapcalls with Dart 3switchexpressions on the sealed base. dart run build_runner build, thendart analyze. build_runner 2.17 removed--delete-conflicting-outputsand ignores it with a warning, so delete any stale*.zorphy.dartfrom the 2.x layout yourself.
- Swap the internal-annotations import for
package:zorphy_annotation/zorphy_annotation.dart. No zorphypartline is needed:build_runnerwrites the shared-part directive for you. - Delete the stale codegen
.g.dart(regenerated by json_serializable). If the package'sbuild.yamlscopes entity generation to a specific directory (e.g.lib/src/domain/entities/**), move the converted files there first. - Update barrels to re-export the entity under the
_-stripped public name, and glue platform controllers (fromMap→fromJson,toMap→toJson, enum wire_value→.index/name, plus any platform-native enum translation that used_nativeValue).
- The target project must resolve (
dart pub getdone) — the migrator uses the analyzer's resolved AST. - Targets zorphy 2.0 (
zorphy_annotation ^2.0.0). @ExchangeableObject/@ExchangeableEnumclasses are matched by annotation name (any library), so no dependency on the fork's internal annotations package is needed.