Skip to content

feat(zorphy)!: 3.0.0 β€” shared parts, lean-flavor migrator - #166

Merged
arrrrny merged 11 commits into
masterfrom
142-v3-0-0-refactor
Nov 17, 2026
Merged

arrrrny merged 11 commits into
masterfrom
142-v3-0-0-refactor

Conversation

@arrrrny

@arrrrny arrrrny commented Nov 17, 2026

Copy link
Copy Markdown
Owner

Closes #142.

Phase 2 of the two-part release: 2.5.0 (#160) aligned the SDK floor and dependency set; this is the major that changes the generated layout and adds the tool that slims existing projects.

Breaking

Generated output is now one shared part per library. The builder declares adds_to_library: true and emits <library>.part.dart under lib/_br_/ (via LibrarySourceSink), and build_runner inserts the part directive itself. 2.x wrote a <file>.zorphy.dart beside every source file. On zorphy/example that is 71 generated files collapsed into 71 parts in one directory; consumers write no zorphy part line at all and rebuild once with --delete-conflicting-outputs.

The deprecated zorphy2Builder (lib/builder2.dart) is removed β€” it had been a no-op alias since 2.0.

zorphy_migrator lean <path>

The other direction from migrate: the project already runs on zorphy and its annotations ask for more than the code consumes. The subcommand rewrites each @Zorphy annotation to the smallest flavor that still covers real usage.

Evidence is class-attributed and syntactic (no resolution), so a tree the size of zik_zak scans in ~15s instead of minutes:

  • FooPatch / FooFields / copyWithFooFn name their class β€” an absent name proves the helper dead, so the opt-in flag is dropped.
  • toJson / copyWithFn are instance calls with no class in the name, so they are only dropped for a class nothing else references.
  • A live class (referenced anywhere else in the tree) keeps the preset its author chose; only unreferenced classes go to lean.
  • Non-feature arguments (autoId, kind, …) are carried over verbatim; shared parts under lib/_br_/ are excluded so generated code cannot make every class look used; a package-root target also scans test/ and integration_test/; a file that fails to parse is reported and skipped, not fatal.

Measured: 2-class project with one dead class, generated part 7686 β†’ 5303 bytes with dart analyze clean. zorphy/example (deliberately uses every feature) β†’ 0 changes. zik_zak β†’ 40 slims, all generateFilter flags whose XFields symbol appears nowhere in lib or test. dart_web_scraper β†’ 1.

Fix found on the way

update<Type>At emitted applyTo(updatedList[index] as Foo) where the receiver is already List<Foo>, so every consumer shipped an unnecessary_cast warning. The example masked it by excluding lib/_br_/** from analysis; a real consumer sees it.

Verification

  • zorphy: 366/366 tests, dart analyze . clean, example builds 178 outputs and analyzes clean.
  • zorphy_migrator: 45/45 tests, dart analyze . clean; smoke test now asserts the shared-part contract (lib/_br_/models.part.dart, no .zorphy.dart).
  • Analyzer compatibility: with analyzer 13.3.0 pinned, dart analyze lib clean and 366/366 tests pass.
  • scripts/check_version_sync.sh β†’ both packages at 3.0.0; format gate clean.

Local CI note: scripts/local_ci.sh runs version_sync, format and migrator end to end. The prepare job's artifact archive step cannot write /prepared-workspace.tar.gz locally, so the artifact-dependent jobs (analyze, test, build_runner_smoke, analyzer_compat) fail on restore; their underlying commands were run directly instead and are reported above.

πŸ€– Generated with Claude Code

Full spec-kit bundle for zorphy 3.0.0:
- spec.md: shared-part generation via LibrarySourceSink + lean-flavor auto-migration tool
- plan.md: custom build.Builder (source_gen PartBuilder lacks sink), migrator lean_detector
- research.md: R1-R8 grounded API findings (build 5.0.0, source_gen 4.3.1, build_runner 2.17.1)
- data-model.md: SharedPartBuilder, LeanFlavorProposal, detection rules
- tasks.md: T1-T16 across 3 phases
- quickstart.md: consumer + contributor + smoke steps
Replace the per-class PartBuilder output with one shared part per library
through BuildStep.librarySourceSink (build 5.0.0 / build_runner 2.17.1).

- new lib/src/shared_part_builder.dart: custom build.Builder that calls
  sink.add(output); falls back to a standalone part file if no sink
- lib/builder.dart: zorphyBuilder now returns the shared-part builder
- lib/builder2.dart: removed the deprecated zorphy2Builder alias
- build.yaml: adds_to_library: true, build_extensions -> .part.dart,
  dropped applies_builders combining_builder
- example: build_runner ^2.17.1 (build 5.0.0 for the sink API), exclude
  lib/_br_ from analysis, strip stale 'part *.zorphy.dart' directives

Verified on zorphy/example: 71 .part.dart emitted, 0 .zorphy.dart,
build_runner green, 'dart analyze .' -> No issues found.

build_runner writes shared parts to lib/_br_/<name>.part.dart and inserts
the part directive into the library automatically, so zorphy and
json_serializable contributions land in one compilation unit.
…dart)

16 test files read generated fixtures by path; build_runner now writes
them to lib/_br_/<name>.part.dart for builders that opt into
adds_to_library. Rewrote the example/lib/<path>.zorphy.dart references to
example/lib/_br_/<path>.part.dart.

doctor_test.dart is unchanged on purpose: it exercises the doctor's
detection of stale .zorphy.dart files, which 3.0.0 must still clean up.

Verified: dart test test/generation/ -j 2 -> 178 tests, all passed.
The generated helper declared `var updatedList = List<Foo>.from(list)` and
then wrote `applyTo(updatedList[index] as Foo)`. The cast can never be
needed, so every consumer of an update-at helper shipped an
`unnecessary_cast` warning. Nothing in the repo caught it because the
example excludes `lib/_br_/**` from analysis; a real consumer sees it.
`zorphy_migrator lean <path>` scans a package and rewrites each
`@Zorphy` annotation to the smallest flavor that still covers what the
project consumes, so generated files shrink without losing behavior.

Evidence is class-attributed and syntactic β€” no resolution, so a package
the size of zik_zak scans in seconds:

- `FooPatch` / `FooFields` / `copyWithFooFn` name their class, so an
  unused one is proven unused and its opt-in flag is dropped.
- `toJson` / `copyWithFn` are instance calls with no class in the name,
  so they are only dropped for a class nothing else references.
- A class referenced anywhere else in the target is live and keeps the
  preset its author chose; only unreferenced classes go to `lean`.
- Every other named argument (`autoId`, `kind`, …) is carried over
  verbatim, and shared parts under `lib/_br_/` are excluded so
  generated code cannot make everything look used.

Also: a package-root target now includes `test/` and
`integration_test/` (a feature used only by tests still has to be
generated), and a file that fails to parse is reported and skipped
rather than aborting the scan.

Measured on a two-class project, one dead class: generated part 7686 β†’
5303 bytes, `dart analyze` clean. zik_zak: 40 annotations slim
(filter flags only), zik_zak's serialized classes keep JSON.
- zorphy / zorphy_annotation / zorphy_migrator all at 3.0.0; zorphy now
  depends on `zorphy_annotation: ^3.0.0` and the release tests assert the
  new pins and the new CHANGELOG entries.
- README: the manual class example no longer declares a zorphy part (the
  builder emits a shared part under lib/_br_/ and build_runner writes the
  directive), and troubleshooting says to rebuild with
  --delete-conflicting-outputs instead of adding a per-file part.
- zorphy_migrator README documents the new lean subcommand.
- dart format over zorphy/ β€” 22 files were non-conforming and the format
  gate is blocking.
@coderabbitai

coderabbitai Bot commented Nov 17, 2026 •

Copy link
Copy Markdown
Contributor

Important

Review skipped

Too many files!

This PR contains 125 files, which is 25 over the limit of 100.

To get a review, reduce the PR to 100 files or fewer by splitting it into smaller PRs or changing its base branch.

Upgrade to a paid plan to raise the limit.

This review couldn't start because sufficient usage credits or metered capacity aren't available. Add credits or update usage-based reviews in the billing tab, then retry.

Run configuration

  • Source mode: Auto
  • Repository: Unavailable
  • Branch: Unavailable
  • File: No configuration file from this repository applied
  • Commit: Unavailable
  • Layers: Organization UI
  • Review profile: CHILL
  • Plan: Advanced
  • Run ID: c7037380-35a0-45ad-adbe-c66f60b7a580
Commits

Reviewing files that changed from the base of the PR and between f682cde and f9e3644.

Files ignored due to path filters: 3

  • zorphy/example/pubspec.lock is excluded by !**/*.lock
  • zorphy/pubspec.lock is excluded by !**/*.lock
  • zorphy_migrator/pubspec.lock is excluded by !**/*.lock
Files selected for processing: 125

  • .gitignore
  • README.md
  • specs/142-v3-0-0-refactor/data-model.md
  • specs/142-v3-0-0-refactor/plan.md
  • specs/142-v3-0-0-refactor/quickstart.md
  • specs/142-v3-0-0-refactor/research.md
  • specs/142-v3-0-0-refactor/spec.md
  • specs/142-v3-0-0-refactor/tasks.md
  • zorphy/.gitignore
  • zorphy/CHANGELOG.md
  • zorphy/build.yaml
  • zorphy/example/analysis_options.yaml
  • zorphy/example/lib/comparison/vs_freezed_nested_patch.dart
  • zorphy/example/lib/comparison/vs_freezed_simple.dart
  • zorphy/example/lib/comparison/vs_freezed_union.dart
  • zorphy/example/lib/comprehensive/comprehensive_example.dart
  • zorphy/example/lib/src/domain/entities/account/account.dart
  • zorphy/example/lib/src/domain/entities/address/address.dart
  • zorphy/example/lib/src/domain/entities/advanced_options/advanced_options.dart
  • zorphy/example/lib/src/domain/entities/assitant_message/assistant_message.dart
  • zorphy/example/lib/src/domain/entities/attachment/attachment.dart
  • zorphy/example/lib/src/domain/entities/base_config/base_config.dart
  • zorphy/example/lib/src/domain/entities/car/car.dart
  • zorphy/example/lib/src/domain/entities/category_node/category_node.dart
  • zorphy/example/lib/src/domain/entities/chat/chat.dart
  • zorphy/example/lib/src/domain/entities/chat_message/chat_message.dart
  • zorphy/example/lib/src/domain/entities/company/company.dart
  • zorphy/example/lib/src/domain/entities/display_mode/default_mode.dart
  • zorphy/example/lib/src/domain/entities/display_mode/display_mode.dart
  • zorphy/example/lib/src/domain/entities/display_mode/immersive_mode.dart
  • zorphy/example/lib/src/domain/entities/file_attachment/file_attachment.dart
  • zorphy/example/lib/src/domain/entities/image_file_attachment/image_file_attachment.dart
  • zorphy/example/lib/src/domain/entities/link_attachment/link_attachment.dart
  • zorphy/example/lib/src/domain/entities/options/options.dart
  • zorphy/example/lib/src/domain/entities/shape/shape.dart
  • zorphy/example/lib/src/domain/entities/special_config/special_config.dart
  • zorphy/example/lib/src/domain/entities/truck/truck.dart
  • zorphy/example/lib/src/domain/entities/user/user.dart
  • zorphy/example/lib/src/domain/entities/user_message/user_message.dart
  • zorphy/example/lib/src/domain/entities/user_with_address/user_with_address.dart
  • zorphy/example/lib/src/domain/entities/vehicle/vehicle.dart
  • zorphy/example/lib/various/auto_id_example.dart
  • zorphy/example/lib/various/basic_example.dart
  • zorphy/example/lib/various/compare_test.dart
  • zorphy/example/lib/various/complex_example.dart
  • zorphy/example/lib/various/cross_entity_example.dart
  • zorphy/example/lib/various/decorator_preservation.dart
  • zorphy/example/lib/various/enum_example.dart
  • zorphy/example/lib/various/factory_test.dart
  • zorphy/example/lib/various/filter_generic_example.dart
  • zorphy/example/lib/various/filter_non_generic_example.dart
  • zorphy/example/lib/various/generic_example.dart
  • zorphy/example/lib/various/hash_code_test.dart
  • zorphy/example/lib/various/initialization_params_example.dart
  • zorphy/example/lib/various/interface_copywithfield_example.dart
  • zorphy/example/lib/various/issue117_ref/issue117_ref.dart
  • zorphy/example/lib/various/issue117_repro/issue117_repro.dart
  • zorphy/example/lib/various/issue127_value_equality_example.dart
  • zorphy/example/lib/various/issue138_endpoint.dart
  • zorphy/example/lib/various/issue138_spark.dart
  • zorphy/example/lib/various/issue138_zik.dart
  • zorphy/example/lib/various/issue_105_bare_function_field.dart
  • zorphy/example/lib/various/issue_109_extends_value_object.dart
  • zorphy/example/lib/various/issue_131_copywithfield_example.dart
  • zorphy/example/lib/various/issue_140_listing.dart
  • zorphy/example/lib/various/issue_148_list_map_cast_example.dart
  • zorphy/example/lib/various/issue_2054_unknown_enum_value.dart
  • zorphy/example/lib/various/issue_304_extends.dart
  • zorphy/example/lib/various/issue_88_doc_comment_list_marker.dart
  • zorphy/example/lib/various/issue_89_function_typed_getter.dart
  • zorphy/example/lib/various/json_example.dart
  • zorphy/example/lib/various/map_field_test.dart
  • zorphy/example/lib/various/nested_example.dart
  • zorphy/example/lib/various/no_patch_example.dart
  • zorphy/example/lib/various/nullable_test.dart
  • zorphy/example/lib/various/params.dart
  • zorphy/example/lib/various/preset_example.dart
  • zorphy/example/lib/various/query_example.dart
  • zorphy/example/lib/various/sealed_class_example.dart
  • zorphy/example/lib/various/static_method_test.dart
  • zorphy/example/lib/various/test_debug.dart
  • zorphy/example/lib/various/value_object_example.dart
  • zorphy/example/lib/various/zorphy2_alias_example.dart
  • zorphy/example/pubspec.yaml
  • zorphy/lib/builder.dart
  • zorphy/lib/builder2.dart
  • zorphy/lib/src/helpers.dart
  • zorphy/lib/src/shared_part_builder.dart
  • zorphy/pubspec.yaml
  • zorphy/test/generation/cross_entity_reference_test.dart
  • zorphy/test/generation/decorator_preservation_e2e_test.dart
  • zorphy/test/generation/enum_list_fromjson_test.dart
  • zorphy/test/generation/framework_gaps_test.dart
  • zorphy/test/generation/interface_copywithfield_test.dart
  • zorphy/test/generation/issue_109_extends_test.dart
  • zorphy/test/generation/issue_117_cross_entity_import_test.dart
  • zorphy/test/generation/issue_131_copywithfield_test.dart
  • zorphy/test/generation/issue_140_deep_hierarchy_fixture_test.dart
  • zorphy/test/generation/issue_148_list_map_cast_test.dart
  • zorphy/test/generation/issue_2054_unknown_enum_value_test.dart
  • zorphy/test/generation/issue_304_extends_test.dart
  • zorphy/test/generation/issue_88_doc_comment_list_marker_test.dart
  • zorphy/test/generation/preset_generation_test.dart
  • zorphy/test/generation/zorphy2_alias_compat_test.dart
  • zorphy/test/regression/issue_127_value_equality_test.dart
  • zorphy/test/release/dependency_constraints_unchanged_test.dart
  • zorphy/test/release/version_sync_test.dart
  • zorphy_annotation/CHANGELOG.md
  • zorphy_annotation/pubspec.yaml
  • zorphy_migrator/CHANGELOG.md
  • zorphy_migrator/LICENSE
  • zorphy_migrator/README.md
  • zorphy_migrator/lib/src/cli.dart
  • zorphy_migrator/lib/src/lean_detector.dart
  • zorphy_migrator/pubspec.yaml
  • zorphy_migrator/pubspec_overrides.yaml
  • zorphy_migrator/test/fixtures/lean/dead_class.dart
  • zorphy_migrator/test/fixtures/lean/live_class.dart
  • zorphy_migrator/test/fixtures/lean/live_class_consumer.dart
  • zorphy_migrator/test/fixtures/lean/local_use.dart
  • zorphy_migrator/test/fixtures/lean/remote_json_consumer.dart
  • zorphy_migrator/test/fixtures/lean/remote_json_model.dart
  • zorphy_migrator/test/lean_detector_test.dart
  • zorphy_migrator/test/smoke_e2e_test.dart
  • zorphy_migrator/tool/probe.dart

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

  • Autofix Β· Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

Share

@arrrrny arrrrny added the spec a feature β€” new capability or change to existing behavior label Nov 17, 2026

@zuraffa-review zuraffa-review Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

CodeRabbit-style review β€” feat(zorphy)!: 3.0.0 β€” shared parts, lean-flavor migrator

Reviewed 722cd2b9 (141 files, +1781/βˆ’547). I cloned the tree to /tmp, resolved it against the pinned toolchain (build 5.0.0, build_runner 2.17.1, source_gen 4.3.1, analyzer 14.x) and ran everything the description claims:

Claim Result
zorphy 366/366 tests βœ… dart test -j 2 β†’ +366: All tests passed!
dart analyze . clean βœ… zorphy, zorphy_migrator and zorphy/example all report No issues found!
example builds 178 outputs βœ… dart run build_runner build β†’ Built with build_runner/aot in 48s; wrote 178 outputs.
71 .zorphy.dart β†’ 71 shared parts βœ… 71 files under example/lib/_br_/**.part.dart, 0 *.zorphy.dart left
build_runner writes the part directive βœ… example/lib/various/preset_example.dart now carries part '../_br_/various/preset_example.part.dart';
zorphy_migrator 45/45 βœ… dart test -j 2 β†’ +45: All tests passed!
check_version_sync.sh βœ… OK: both packages at version 3.0.0

I also checked the shared-part plumbing against build_runner's own source rather than taking the comments at face value. It holds up: adds_to_library: true passes BuilderDefinition and BuildPhase validation (one factory, .dart-only inputs, build_to: source), LibrarySourceSink.add is the right sink call, and the generator emits no import / part of directives, so the sink's "source must not contain directives" contract is satisfied. Dropping zorphy2Builder leaves no dangling reference anywhere in the tree. This is a genuine improvement and the migration is in good shape.

Findings β€” 8 (1 🟠, 5 🟑, 2 πŸ”΅)

🟠

  1. zorphy_migrator/lib/src/cli.dart:322 β€” liveness only sees the scanned tree, so lean <pkg>/lib strips features that test/ consumes (reproduced), and a library package's public API is slimmed wholesale.

🟑

  1. zorphy_migrator/lib/src/cli.dart:344 β€” ^\s*part\s+of\s without multiLine; a leading comment or // @dart= line defeats it. Same block reads every file synchronously and can abort the run.
  2. zorphy_migrator/CHANGELOG.md:23 β€” "the migrator's own migrate subcommand is unchanged" is false; _collectDartFiles is shared.
  3. zorphy/lib/src/shared_part_builder.dart:55 β€” the documented sink fallback is unreachable (librarySourceSink returns non-null or throws UnsupportedError).
  4. zorphy/lib/src/shared_part_builder.dart:52 β€” the // ignore_for_file: type=lint header is gone; generated parts are now linted under the consumer's config, and only the example's new exclude hides it.
  5. README.md:1372 β€” --delete-conflicting-outputs was removed in build_runner 2.17.1 and is now ignored with a warning, so the upgrade step is a no-op.

πŸ”΅

  1. zorphy_migrator/test/smoke_e2e_test.dart:12 β€” test name still says "compiles against zorphy 2.0".
  2. zorphy/test/generation/zorphy2_alias_compat_test.dart:8 β€” doc comment still points at .zorphy.dart.

Two nits below the inline threshold: zorphy/build.yaml lost its trailing newline, and zorphy_migrator/test/smoke_e2e_test.dart still writes zorphy: ^2.0.0 into the fixture pubspec it generates.

mergeStateStatus is UNSTABLE only because the GitHub Actions check is billing-blocked on this repo β€” it ends in ~3s with zero steps executed, so the red check is not a signal about this diff. Everything above was run locally with dart test -j 2 / dart analyze / build_runner build.

Comment on lines +322 to +327
// A package root's tests and integration tests consume generated
// helpers too: a feature used only there still has to be generated, or
// the suite stops compiling. Anything else is scanned as given. The set
// keeps the root walk and the extra dirs from double-counting a file.
final roots = <String>{target};
if (File(p.join(target, 'pubspec.yaml')).existsSync()) {

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟠 Liveness is computed only from the scanned tree, so lean <dir> that is not a package root silently strips features its real consumers need β€” Effort: πŸ”¨

_collectDartFiles adds test/ and integration_test/ only when target itself contains a pubspec.yaml (line 327). Point the command at lib/ and the tests are never scanned, so a class whose only consumers live there comes out isLive: false β€” which makes _featureUsed drop every feature, the instance-level generateJson / generateCopyWithFn included, and rewrites the annotation to preset: ZorphyPreset.lean.

Reproduction (dry run, zorphy_migrator lean <pkg>/lib):

// lib/user.dart
@Zorphy(generateJson: true, generatePatch: true)
abstract class $User { String get id; }

// test/user_test.dart
UserPatch(id: 'x');
UserFields.id;
User(id: 'x').toJson();
Classes that can slim down: 1
| `User` | `user.dart` | generateJson, generatePatch |

Pointed at the package root instead, the same tree reports 0 annotation(s) would change. The second face of the same gap: a published library has no in-tree consumer at all, so lean . slims every class to preset: lean β€” a breaking change to that package's public API, which the detector has no way to see.

Two cheap guards would cover both: warn loudly when target has no pubspec.yaml of its own ("scanning <dir> in isolation β€” test/ and consumers outside this tree are invisible"), and say in the README that lean is meant for applications, not for a package whose generated code is public API.

Comment on lines +344 to +348
files.removeWhere((file) {
if (file.split(Platform.pathSeparator).contains('_br_')) return true;
final head = File(file).readAsStringSync();
return RegExp(r'^\s*part\s+of\s').hasMatch(head);
});

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟑 ^\s*part\s+of\s needs multiLine, and the readAsStringSync() beside it can abort the whole scan β€” Effort: ⚑

  1. Without multiLine: true, ^ anchors at the start of the file only. A part file that opens with a license header, a // @dart=3.13 language-version line or any comment before part of is not excluded β€” it is scanned, and a generated part names every class in its library, which is precisely the "makes every class look used" failure the comment above describes. RegExp(r'^\s*part\s+of\s', multiLine: true) closes it.
  2. File(file).readAsStringSync() throws on the first unreadable or vanished file and aborts _runLean before it prints anything β€” the opposite of the rule lean_detector.dart sets for itself ("one bad file must not abort a 150-class scan"). A try/catch that keeps the file (or an existsSync() guard) keeps the run going. It is also the third full read of every file, after collectSymbols and detect.

Comment thread zorphy_migrator/CHANGELOG.md Outdated
- A file that fails to parse is reported and skipped instead of aborting the
whole scan.
- Version aligned with the `zorphy` 3.0.0 major; the migrator's own `migrate`
subcommand is unchanged.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟑 "the migrator's own migrate subcommand is unchanged" is not accurate β€” Effort: ⚑

_collectDartFiles is shared by both subcommands, so migrate changes too: a package-root target now also walks test/ and integration_test/ (extra files it will try to migrate), and every file under a _br_ directory or beginning with part of is dropped from the collection. Both changes are very likely right β€” but they are behaviour changes to migrate, and the release note currently claims the opposite. Reword to something like: "migrate is otherwise unchanged; its file collection now also covers test//integration_test/ and skips generated shared parts."

Comment thread zorphy/lib/src/shared_part_builder.dart Outdated
Comment on lines +55 to +60
final sink = await buildStep.librarySourceSink;
if (sink != null) {
// Shared-part path: add to the library's single `.zorphy.part`.
sink.add(output);
return;
}

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟑 The "falls back to a standalone part file when the sink is unavailable" branch cannot be reached β€” Effort: ⚑

BuildStep.librarySourceSink (build 5.0.0, lib/src/build_step.dart:165) is Future<LibrarySourceSink?> whose contract is: null when the primary input is not a library, and throw UnsupportedError when the builder did not opt into adds_to_library. This builder already returned at line 46 for a non-library, so past line 55 sink is always non-null β€” the if (sink != null) guard is dead and lines 62-68 are unreachable.

"An older build runner" cannot degrade here either: the sink is a build 5.0.0 API and zorphy/pubspec.yaml pins build: ">=4.0.4 <6.0.0", so a runner old enough to lack the sink resolves against a build that has no librarySourceSink to call β€” it would be a compile error, not a null. Suggest deleting the branch, or making the doc honest ("throws UnsupportedError if the builder is applied without adds_to_library: true").

Related: the declared build_extensions: {".dart": [".zorphy.part"]} in build.yaml does not name anything on disk β€” build_runner names the shared part <library>.part.dart under lib/_br_/ (br_outputs.dart, sharedPartId), so a reader who greps for *.zorphy.part will not find them.

Comment on lines +52 to +53
final output = await _generator.generate(LibraryReader(library), buildStep);
if (output.isEmpty) return;

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟑 The // ignore_for_file header the PartBuilder used to prepend is gone, so generated parts are now linted under each consumer's own analysis_options.yaml β€” Effort: πŸ”¨

The old builder.dart passed header: '// ignore_for_file: UNNECESSARY_CAST\n// ignore_for_file: type=lint\n'; the sink path writes the generator's output verbatim. zorphy/example stays clean only because this PR adds example/analysis_options.yaml excluding lib/_br_/** β€” and downstream consumers are not told to copy it.

Verified: with that exclude removed, dart analyze lib on zorphy/example reports

warning - _br_/various/issue_148_list_map_cast_example.part.dart:356:21 - The receiver can't be 'null' because of short-circuiting, so the null-aware operator '?.' can't be used. - invalid_null_aware_operator

(four of those). A // ignore_for_file: comment is not a directive, so sink.add(output) would still accept it β€” prepending the two lines here keeps 2.x consumers warning-free. Otherwise the README's upgrade steps need to say "add lib/_br_/** to your analyzer excludes".

Comment thread README.md Outdated
`adds_to_library: true`, so `build_runner` emits a single
`<library>.part.dart` per annotated library and inserts the `part`
directive itself. Delete any hand-written `part '*.zorphy.dart';` line and
rebuild with `--delete-conflicting-outputs`. (2.x wrote one

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟑 --delete-conflicting-outputs no longer exists β€” this upgrade step is a no-op β€” Effort: ⚑

build_runner 2.17.1, the version this repo pins, lists it in removedOptions (lib/src/build_runner_command_line.dart:187-196, "Removed options, kept to not break old command lines") and warns:

W These options have been removed and were ignored: --delete-conflicting-outputs

Confirmed live: dart run build_runner build --delete-conflicting-outputs in zorphy/example prints exactly that. So the instruction added here and at line 1407, in zorphy/CHANGELOG.md:12, in zorphy_migrator/README.md:123, in the fixture hints of zorphy2_alias_compat_test.dart / issue_148 / issue_88, and β€” outside this diff but still shipped β€” in zorphy/lib/src/cli/services/doctor_service.dart:101 and project_validator.dart:322,350, does not delete the 2.x <file>.zorphy.dart files. A user who follows it keeps one stale generated file per source file (harmless β€” an unreferenced part of file analyzes clean, I checked β€” but litter that .gitignore already hides).

Suggest dropping the flag from the docs and saying plainly "delete the old *.zorphy.dart files yourself", or pointing at zorphy build --clean.

/// (shared parts) with build_runner + dart analyze.
void main() {
test(
'smoke fixture migrates end-to-end and compiles against zorphy 2.0',

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

πŸ”΅ Test name is stale β€” Effort: ⚑

'smoke fixture migrates end-to-end and compiles against zorphy 2.0' β€” the body now asserts zorphy 3.0 shared parts (lib/_br_/models.part.dart exists, models.zorphy.dart does not, build_runner inserts the directive). Renaming it to "…against zorphy 3.0" keeps the test log honest. The generated pubspec.yaml inside the test still pins zorphy: ^2.0.0 / zorphy_annotation: ^2.0.0 and is only saved by dependency_overrides; harmless, but worth bumping in the same pass.

@@ -7,7 +7,9 @@ import 'package:test/test.dart';
/// generate the same standard output as `@zorphy` classes, into the
/// `.zorphy.dart` part file.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

πŸ”΅ Stale doc comment β€” Effort: ⚑

"…generate the same standard output as @zorphy classes, into the .zorphy.dart part file." As of 3.0 the output is the library's shared part under lib/_br_/, and there is no per-file .zorphy.dart any more β€” the fixture path below already says so.

@zuraffa-review

Copy link
Copy Markdown
Contributor

Review walkthrough β€” 3.0.0 shared parts + lean

What I did. Cloned to /tmp, resolved against the pinned toolchain (build 5.0.0, build_runner 2.17.1, source_gen 4.3.1, analyzer 14.x), ran the full gate, then read build_runner's own adds_to_library / LibrarySourceSink implementation before judging the new builder. Everything the description claims reproduced locally:

  • zorphy: dart test -j 2 β†’ 366/366; dart analyze lib bin clean; scripts/check_version_sync.sh β†’ OK: both packages at version 3.0.0.
  • zorphy/example: build_runner build β†’ 178 outputs, 71 files under lib/_br_/**.part.dart, 0 *.zorphy.dart left, and build_runner itself inserted part '../_br_/various/preset_example.part.dart'; into the source. dart analyze . clean (only because of the new example/analysis_options.yaml exclude β€” see finding 5).
  • zorphy_migrator: dart test -j 2 β†’ 45/45, dart analyze . clean.

What is genuinely good here. The adds_to_library conversion is the right mechanism and it is plumbed correctly: the config passes BuilderDefinition/BuildPhase validation (single factory, .dart-only inputs, build_to: source), sink.add(output) is the correct sink call, and the generator emits no import/part of directives so the sink's "no directives" contract holds. Removing zorphy2Builder leaves no dangling reference in the tree. The update<Type>At cast fix is a real consumer-visible win. The lean detector's conservative posture (only class-attributed symbols count as proof of use, unparseable files are skipped rather than fatal) is the right default.

Where it needs another pass. One medium and five smaller items, all with reproductions in the inline threads. The one I would not merge without addressing is the lean scope gap (🟠): liveness is derived only from the scanned tree, so lean <pkg>/lib classifies a test-only consumer as absent and rewrites @Zorphy(generateJson: true, generatePatch: true) to @Zorphy(preset: ZorphyPreset.lean) β€” the test suite then stops compiling. The same blind spot makes lean . strip the generated API of a published library, since nothing inside the package references it. Both are cheap to guard: warn when the target is not a package root, and say in the README that lean targets applications.

Note on the red check. mergeStateStatus is UNSTABLE only because Actions is billing-blocked on this repo (every run ends in ~3s with zero steps). It says nothing about this diff.

Nits below the inline threshold. zorphy/build.yaml lost its trailing newline, and zorphy_migrator/test/smoke_e2e_test.dart still writes zorphy: ^2.0.0 into the fixture pubspec it generates (masked by dependency_overrides).

@arrrrny

arrrrny commented Nov 17, 2026

Copy link
Copy Markdown
Owner Author

Usage evidence behind the lean tool

Measured on the two real consumers, since the point of lean is "stop generating what nothing uses":

zik_zak dart_web_scraper
.changeToX call sites 24 0
.compareTo( call sites 53 15
Fields. references 144 9
Patch( / patchWith 139 / 21 0 / 0
$$Sealed references 22 8
generated .zorphy.dart 2.91 MB 1.24 MB

What the tool proposes: 40 annotations on zik_zak (all dropping an unused generateFilter, whose FooFields descriptor appears nowhere in lib or test), and 1 on dart_web_scraper. That is ~42 KB of filter descriptors on zik_zak, about 1.4% of its zorphy output.

The honest read: for these two apps the generated code is mostly not waste β€” patch, filter, compareTo and changeTo are all in real use. lean is deliberately conservative: a live class keeps its preset because toJson/copyWithFn/changeTo are instance calls whose receiver type a syntactic scan cannot resolve. Squeezing a live class further needs resolution-based evidence; that is a follow-up, not this PR.

Note: CodeRabbit skipped this PR (138 files, over its 100-file review limit; it also reported no available credits), so the automated review is this pool's own pass.

arrrrny and others added 4 commits November 17, 2026 11:56
`dart pub publish` refuses a package that carries `dependency_overrides`
in its pubspec, so 3.0.0 could not be published at all. The override now
lives in `pubspec_overrides.yaml` (gitignored? no β€” tracked, exactly like
zorphy's own), which pub treats as a development-only file and only warns
about.
- add the MIT LICENSE the package never had β€” `dart pub publish` refused
  the package outright without it.
- drop `tool/probe.dart`, a scratch script that hard-coded
  /tmp/mig_scratch and was shipping inside the archive.
- the local zorphy_annotation path override moved to
  pubspec_overrides.yaml (previous commit) so pubspec.yaml carries no
  dependency_overrides, which pub also refuses.

All three packages now pass `dart pub publish --dry-run`.
- zorphy_migrator: `lean` warns when the target is not a package root, so a
  scan with `test/` and outside consumers invisible no longer slims silently.
- zorphy_migrator: the shared-part filter's `part of` pattern is `multiLine`
  (a leading comment defeated it, making every class look used) and an
  unreadable file no longer aborts the scan before anything is printed.
- zorphy: drop the unreachable librarySourceSink fallback and make the doc
  honest; restore the `// ignore_for_file` header `PartBuilder` used to
  prepend, so generated parts are not linted under a consumer's config.
- docs: `--delete-conflicting-outputs` was removed in build_runner 2.17 and
  is ignored, so the 3.0 upgrade steps now say to delete the stale
  `*.zorphy.dart` files; correct the "migrate is unchanged" claim, the stale
  zorphy-2.0 smoke test name and the `.zorphy.dart` doc comments.
@arrrrny

arrrrny commented Nov 17, 2026

Copy link
Copy Markdown
Owner Author

Review-findings resolution

All 10 findings are addressed on 142-v3-0-0-refactor (fix commit 060d0fe, pushed on top of the two publishability commits that landed on the branch during this round).

Thread Verdict Notes
zorphy_migrator/lib/src/cli.dart:327 β€” lean liveness only sees the scanned tree applied _runLean now warns loudly when the target has no pubspec.yaml of its own, so lean <pkg>/lib says on stderr that test/, integration_test/ and any consumer outside the tree are invisible. zorphy_migrator/README.md gains a "lean targets applications" section covering the second face (a published library's API slimmed wholesale) β€” that one is not solvable syntactically, so it is documented rather than guessed at.
zorphy_migrator/lib/src/cli.dart:348 β€” ^\s*part\s+of\s needs multiLine; readAsStringSync can abort the scan applied The pattern is now _sharedPartPattern with multiLine: true, and the read is guarded so an unreadable file is kept in the scan and the failure surfaces through the caller's handled Analysis error: path instead of throwing before anything is printed. Proven by counterfactual on a fixture whose part of sits on line 2 under a license header: multiLine β†’ 1 class slimmed; reverting to the non-multiLine form β†’ "0 slimdowns", because the generated part's UserPatch symbol makes the class look used.
zorphy_migrator/CHANGELOG.md:23 β€” "the migrator's own migrate subcommand is unchanged" is false applied Now reads "otherwise unchanged β€” its file collection now also covers test//integration_test/ for a package-root target and skips generated shared parts."
zorphy/lib/src/shared_part_builder.dart:60 β€” the "falls back to a standalone part file when the sink is unavailable" branch is unreachable applied Branch deleted; the doc comment now states the contract plainly β€” librarySourceSink answers null only for a non-library input (already returned on) and throws UnsupportedError when the builder is applied without adds_to_library: true.
zorphy/lib/src/shared_part_builder.dart:53 β€” the // ignore_for_file header is gone applied, with a correction The two 2.x lines are restored via _withLintHeader. The suggested fix does not actually cover the reproduced warnings, though: type=lint only matches DiagnosticType.LINT, while invalid_null_aware_operator is a STATIC_WARNING (analyzer-14.7.0/lib/src/ignore_comments/ignore_info.dart:69). I verified this both ways on zorphy/example with its lib/_br_/** exclude removed β€” the 2.x header leaves the four invalid_null_aware_operator warnings, while a targeted // ignore_for_file: invalid_null_aware_operator silences them. So this is exact 2.x parity, not a new suppression policy; the ?.-in-generated-patch code is a pre-existing generator bug, not a regression of this PR. README.md now documents the lib/_br_/** analyzer exclude as the consumer-side option.
README.md:1372 β€” --delete-conflicting-outputs no longer exists applied Confirmed against the pinned source: build_runner-2.17.1/lib/src/build_runner_command_line.dart:188 declares it under "Removed options, kept to not break old command lines". Corrected in README.md (both the Generated Files and Troubleshooting steps), zorphy/CHANGELOG.md and zorphy_migrator/README.md:123 β€” all now say to delete the 2.x *.zorphy.dart files yourself, since the flag only warns. The no-op flag is also dropped from the smoke test's build call.
zorphy_migrator/test/smoke_e2e_test.dart:12 β€” test name says "against zorphy 2.0" applied Renamed to "…against zorphy 3.0".
zorphy/test/generation/zorphy2_alias_compat_test.dart:8 β€” stale .zorphy.dart doc comment applied Now points at the library's shared part under lib/_br_/; the fixture-missing hint in the same file no longer suggests the removed flag.
nit β€” zorphy/build.yaml lost its trailing newline applied Restored, and the builder comment no longer promises a sink fallback that cannot happen.
nit β€” smoke test's generated fixture pubspec pins zorphy: ^2.0.0 applied Bumped to ^3.0.0 (both zorphy and zorphy_annotation).
(adjacent, not in the review) β€” migrator README "After --apply" told users to add a zorphy part line applied Two steps now say 3.0 needs no zorphy directive: build_runner writes the shared-part line itself.
doctor_service.dart:101, project_validator.dart:322,350, doctor_result.dart:86 still advise the removed flag skipped Pre-existing 2.x-era advice strings β€” git diff origin/master...HEAD names no --delete-conflicting-outputs line in them, so this PR did not introduce them. The whole _checkGeneratedFiles path still probes $base.zorphy.dart, which 3.0 never writes; reworking doctor/validate for shared parts is a change of its own, not a fixes round.

One defect found while verifying, not fixed here (outside this PR's scope): MigratorCli._collectDartFiles's skip() treats any path segment starting with . as hidden, so a relative target beginning with .. (lean ../pkg/lib) silently collects no Dart files and reports "No Dart files found". Absolute paths are unaffected.

Verification

  • zorphy: dart pub get β†’ dart analyze . β†’ No issues found!; example rebuilt with build_runner build β†’ 178 outputs, 71 parts under lib/_br_/, 0 *.zorphy.dart; dart test -j 2 β†’ +366: All tests passed!
  • zorphy_migrator: dart analyze . β†’ No issues found!; dart test -j 2 β†’ +45: All tests passed! (the e2e smoke test builds a real package and asserts lib/_br_/models.part.dart exists, models.zorphy.dart does not, and dart analyze is clean)
  • dart format --set-exit-if-changed on every changed .dart file β†’ 0 changed
  • lean warning verified in all three shapes: non-package-root dir β†’ warns; package root β†’ silent; single file β†’ silent
  • scripts/check_version_sync.sh untouched (both packages still 3.0.0)

The format CI job failed on 17 files touched by this PR β€” the branch was
formatted with an older dart format invocation than the one the job runs.
Semantics-preserving; verified by `dart format --output=none
--set-exit-if-changed .` reporting 0 changed afterwards.

zuraffa-review-fixes: pool task 622ca9d8-0bb9-4305-968a-42d908316e55
@arrrrny
arrrrny merged commit 7c2b565 into master Nov 17, 2026
12 checks passed
@arrrrny

arrrrny commented Nov 17, 2026 •

Copy link
Copy Markdown
Owner Author

Merge task

merged as 7c2b565

The Β§4U CI gate was red on one job: format (dart format --output=none --set-exit-if-changed . in zorphy/, Dart 3.14.1) flagged 17 files. Local
Dart 3.14.0 reproduced the identical 17-file set, so this was genuine drift in
this PR's diff and not an SDK-version artifact; master's latest Dart CI run
was green, so the base was not red.

Fixed surgically on the branch β€” dart format . in zorphy/, whitespace and
call-chain wrapping only (git diff -w shows 82/111 lines vs 336/365 with
whitespace), pushed as f9e3644. Post-fix --set-exit-if-changed reports 0
changed; the full CI run then came back all-green (mergeStateStatus: CLEAN):
version_sync, format, prepare, analyze, test, build_runner_smoke, migrator,
analyzer_compat (13), analyzer_compat (14), build.

Readiness gate (Β§2) passed before the fix: 7 actionable reviewer findings, fixes
evidence (a zuraffa-review-fixes record at 2026-11-17T09:27:57Z plus 2 bot
commits) newer than the newest reviewer activity (2026-11-17T08:51:09Z).

Linked issue #142 is a real issue (not a PR) and was auto-closed by the merge
into the default branch.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

spec a feature β€” new capability or change to existing behavior

Projects

None yet

Development

Successfully merging this pull request may close these issues.

zorphy: generated sealed base cannot be implemented outside its library (multi-file hierarchies fail)

1 participant