Repository navigation
feat(zorphy)!: 3.0.0 β shared parts, lean-flavor migrator - #166
Conversation
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.
|
Important Review skippedToo 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.
|
There was a problem hiding this comment.
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 π΅)
π
zorphy_migrator/lib/src/cli.dart:322β liveness only sees the scanned tree, solean <pkg>/libstrips features thattest/consumes (reproduced), and a library package's public API is slimmed wholesale.
π‘
zorphy_migrator/lib/src/cli.dart:344β^\s*part\s+of\swithoutmultiLine; a leading comment or// @dart=line defeats it. Same block reads every file synchronously and can abort the run.zorphy_migrator/CHANGELOG.md:23β "the migrator's ownmigratesubcommand is unchanged" is false;_collectDartFilesis shared.zorphy/lib/src/shared_part_builder.dart:55β the documented sink fallback is unreachable (librarySourceSinkreturns non-null or throwsUnsupportedError).zorphy/lib/src/shared_part_builder.dart:52β the// ignore_for_file: type=lintheader is gone; generated parts are now linted under the consumer's config, and only the example's new exclude hides it.README.md:1372β--delete-conflicting-outputswas removed in build_runner 2.17.1 and is now ignored with a warning, so the upgrade step is a no-op.
π΅
zorphy_migrator/test/smoke_e2e_test.dart:12β test name still says "compiles against zorphy 2.0".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.
| // 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()) { |
There was a problem hiding this comment.
π 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.
| 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); | ||
| }); |
There was a problem hiding this comment.
π‘ ^\s*part\s+of\s needs multiLine, and the readAsStringSync() beside it can abort the whole scan β Effort: β‘
- Without
multiLine: true,^anchors at the start of the file only. A part file that opens with a license header, a// @dart=3.13language-version line or any comment beforepart ofis 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. File(file).readAsStringSync()throws on the first unreadable or vanished file and aborts_runLeanbefore it prints anything β the opposite of the rulelean_detector.dartsets for itself ("one bad file must not abort a 150-class scan"). Atry/catchthat keeps the file (or anexistsSync()guard) keeps the run going. It is also the third full read of every file, aftercollectSymbolsanddetect.
| - 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. |
There was a problem hiding this comment.
π‘ "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."
| final sink = await buildStep.librarySourceSink; | ||
| if (sink != null) { | ||
| // Shared-part path: add to the library's single `.zorphy.part`. | ||
| sink.add(output); | ||
| return; | ||
| } |
There was a problem hiding this comment.
π‘ 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.
| final output = await _generator.generate(LibraryReader(library), buildStep); | ||
| if (output.isEmpty) return; |
There was a problem hiding this comment.
π‘ 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".
| `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 |
There was a problem hiding this comment.
π‘ --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', |
There was a problem hiding this comment.
π΅ 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. | |||
There was a problem hiding this comment.
π΅ 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.
Review walkthrough β 3.0.0 shared parts +
|
Usage evidence behind the lean toolMeasured on the two real consumers, since the point of
What the tool proposes: 40 annotations on zik_zak (all dropping an unused The honest read: for these two apps the generated code is mostly not waste β patch, filter, 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. |
`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.
Review-findings resolutionAll 10 findings are addressed on
One defect found while verifying, not fixed here (outside this PR's scope): Verification
|
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
Merge taskmerged as 7c2b565 The Β§4U CI gate was red on one job: Fixed surgically on the branch β Readiness gate (Β§2) passed before the fix: 7 actionable reviewer findings, fixes Linked issue #142 is a real issue (not a PR) and was auto-closed by the merge |
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: trueand emits<library>.part.dartunderlib/_br_/(viaLibrarySourceSink), andbuild_runnerinserts thepartdirective itself. 2.x wrote a<file>.zorphy.dartbeside every source file. Onzorphy/examplethat is 71 generated files collapsed into 71 parts in one directory; consumers write no zorphypartline 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@Zorphyannotation to the smallest flavor that still covers real usage.Evidence is class-attributed and syntactic (no resolution), so a tree the size of
zik_zakscans in ~15s instead of minutes:FooPatch/FooFields/copyWithFooFnname their class β an absent name proves the helper dead, so the opt-in flag is dropped.toJson/copyWithFnare instance calls with no class in the name, so they are only dropped for a class nothing else references.lean.autoId,kind, β¦) are carried over verbatim; shared parts underlib/_br_/are excluded so generated code cannot make every class look used; a package-root target also scanstest/andintegration_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 analyzeclean.zorphy/example(deliberately uses every feature) β 0 changes.zik_zakβ 40 slims, allgenerateFilterflags whoseXFieldssymbol appears nowhere inlibortest.dart_web_scraperβ 1.Fix found on the way
update<Type>AtemittedapplyTo(updatedList[index] as Foo)where the receiver is alreadyList<Foo>, so every consumer shipped anunnecessary_castwarning. The example masked it by excludinglib/_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 13.3.0pinned,dart analyze libclean 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.shrunsversion_sync,formatandmigratorend to end. Thepreparejob's artifact archive step cannot write/prepared-workspace.tar.gzlocally, 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