Repository navigation
feat(zorphy)!: 3.0.0 — shared parts, lean-flavor migrator #166
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Merged
Merged
Changes from 6 commits
Commits
Show all changes
11 commits
Select commit
Hold shift + click to select a range
f6f58ef
docs(spec): 3.0.0 spec bundle — shared parts + lean-flavor migration
arrrrny e21e3bf
feat(zorphy)!: shared-part generation via LibrarySourceSink (3.0.0 P1)
arrrrny 97dee08
test(zorphy): point fixture readers at shared parts (lib/_br_/*.part.…
arrrrny 6196a93
fix(zorphy): drop always-redundant cast in update<Type>At
arrrrny 0c696f3
feat(zorphy_migrator): lean subcommand — pick a flavor from real usage
arrrrny 722cd2b
chore(release): 3.0.0 — versions, CHANGELOGs, README for shared parts
arrrrny c0d899e
fix(zorphy_migrator): move the local path override out of pubspec.yaml
arrrrny ffcbcc0
chore(zorphy_migrator): make 3.0.0 publishable
arrrrny 060d0fe
fix: address review comments on #166
zuraffa-review[bot] 8dfa2c9
merge: bring in 3.0.0 publishability fixes landed during the review r…
zuraffa-review[bot] f9e3644
style(zorphy): apply dart format to the 3.0.0 diff
zuraffa-review[bot] File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,52 @@ | ||
| # Data Model: zorphy 3.0.0 | ||
|
|
||
| ## Entities | ||
|
|
||
| ### SharedPartBuilder (new, `zorphy/lib/src/shared_part_builder.dart`) | ||
| - `inputLibrary: LibraryElement` — the resolved input library. | ||
| - `sink: LibrarySourceSink?` — from `buildStep.librarySourceSink`. | ||
| - `generatedParts: List<String>` — per-entity source blocks (no directives). | ||
| - `build()`: | ||
| - resolve library; if no `@Zorphy`/`@Zorphy2` annotations → return (no output). | ||
| - for each generator output block: `sink?.add(block)` if sink != null; else legacy write. | ||
| - if sink == null and outputs non-empty → write legacy `.zorphy.dart` (defensive fallback + warning). | ||
|
|
||
| ### LeanFlavorProposal (new, `zorphy_migrator/lib/src/lean_detector.dart`) | ||
| - `className: String` — annotated class name. | ||
| - `currentPreset: ZorphyPreset` + `currentFlags: Map<String,bool>`. | ||
| - `referencedFeatures: Set<LeanFeature>` — {copyWith, patch, filter, copyWithFn, json, comparators} detected in package. | ||
| - `proposedPreset: ZorphyPreset` — `lean` unless a feature forces higher. | ||
| - `proposedFlags: Map<String,bool>` — explicit `generateX: true` for referenced features only. | ||
| - `estimatedLinesSaved: int`. | ||
|
|
||
| ### LeanFeature (enum) | ||
| `copyWith, patch, filter, copyWithFn, json, comparators` | ||
|
|
||
| ### LeanReport | ||
| - `proposals: List<LeanFlavorProposal>`. | ||
| - `totalLinesSaved: int`. | ||
| - `renderDiff()` → unified diff via `Rewriter`. | ||
|
|
||
| ## Preset → feature mapping | ||
|
|
||
| | Feature | lean | standard | full | | ||
| |---|---|---|---| | ||
| | copyWith | ✓ | ✓ | ✓ | | ||
| | equality/comparators | ✓ | ✓ | ✓ | | ||
| | patch | — | ✓ | ✓ | | ||
| | filter | — | ✓ | ✓ | | ||
| | json (toJson/fromJson) | opt-in | opt-in | opt-in | | ||
| | copyWithFn | — | — | ✓ | | ||
|
|
||
| ## Detection rules (conservative, FR-5) | ||
|
|
||
| For each feature F, F is "referenced" if any of: | ||
| - `copyWith`: `.copyWith(` appears on the class or its instances. | ||
| - `patch`: `.patch(` or `Patch` type usage. | ||
| - `filter`: `.filter(` or `Filter` type usage. | ||
| - `copyWithFn`: `copyWithFn` identifier or function-tearoff usage. | ||
| - `json`: `toJson`/`fromJson` invocation, or `json_serializable` annotation on the class. | ||
| - `comparators`: `compareTo`/`operator ==` reliance beyond identity. | ||
|
|
||
| If NO features beyond lean-default are referenced → `proposedPreset = lean`, no flags. | ||
| If features referenced → `proposedPreset = lean` + `generateX: true` for each (keeps output minimal but functional). |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,60 @@ | ||
| # Implementation Plan: zorphy 3.0.0 — Shared-Part Generation + Lean-Flavor Auto-Migration | ||
|
|
||
| **Branch**: `142-v3-0-0-refactor` | **Date**: 2026-11-16 | **Spec**: [spec.md](./spec.md) | ||
|
|
||
| **Input**: Feature specification from `/specs/142-v3-0-0-refactor/spec.md` | ||
|
|
||
| ## Summary | ||
|
|
||
| Major release with two coupled deliverables. **(1) Shared-part generation**: replace the per-class `.zorphy.dart` `source_gen.PartBuilder` output with a single shared `.zorphy.part` per library, written through `build`'s `LibrarySourceSink` (`BuildStep.librarySourceSink`) via a **custom `build.Builder`** (source_gen 4.3.1 `PartBuilder` does not consume the sink — verified in source). One part per library instead of N files; cross-entity polymorphic dispatch becomes a single compilation unit. **(2) Lean-flavor auto-migration**: a new `zorphy_migrator lean` command that scans a project's `@Zorphy` annotations + real usage of generated members, computes the minimal `ZorphyPreset`/feature-flag set per class, and emits a unified diff (dry-run default) or applies (`--apply`) — shrinking generated code without removing used functionality. Both are breaking; `builder2.dart`/`zorphy2Builder` deprecated alias removed; all tests upgraded. | ||
|
|
||
| ## Technical Context | ||
|
|
||
| **Language/Version**: Dart — floor `>=3.11.0 <4.0.0` (dev/CI on ≥3.13). | ||
|
|
||
| **Primary Dependencies**: `build` 5.0.0 (`LibrarySourceSink` in `lib/src/library_source_sink.dart`; `BuildStep.librarySourceSink` impl in `build_runner` 2.17.1 `build_step_impl.dart:68`). `source_gen` 4.3.1 (`PartBuilder` at `lib/src/builder.dart:277` — does NOT consume sink). `analyzer` ^14.0.0. | ||
|
|
||
| **Key API surface**: | ||
| - `LibrarySourceSink.add(String source)` — source must not contain directives. | ||
| - `LibrarySourceSink.addImport(uri, as:, show:, hide:)` — requires `enhanced-parts` experiment (StateError otherwise). | ||
| - `BuildStep.librarySourceSink` → `Future<LibrarySourceSink?>`; `partContribution`, `imports`, `languageVersion`. | ||
|
|
||
| **Storage**: source files + generated `.zorphy.part` + `build.yaml` + migrator detector. | ||
|
|
||
| **Testing**: `dart test -j 2`, `dart analyze`, `./scripts/local_ci.sh`, build_runner smoke on `zik_zak` + `dart_web_scraper`. | ||
|
|
||
| **Constraints**: shared-part output deterministic + `dart_style`-formatted; `enhanced-parts` experiment required; migration advisory by default; no regression on analyzer 13.x/14.x gates. | ||
|
|
||
| ## Phase 1 — Shared-part builder (breaking) | ||
|
|
||
| 1. New `lib/src/shared_part_builder.dart`: a `build.Builder` that, per input library, collects generator output and calls `buildStep.librarySourceSink?.add(...)`; falls back to legacy per-class output if sink is null (defensive). | ||
| 2. `lib/builder.dart`: `zorphyBuilder` returns the new builder (or composes it); `build.yaml` `build_extensions` updated to emit `.zorphy.part` and declare `required_experiments: [enhanced-parts]` if supported. | ||
| 3. Remove `lib/builder2.dart` (`zorphy2Builder`). | ||
| 4. Update `ZorphyGenerator` call site to write to the sink instead of `buildStep.writeAsString`. | ||
|
|
||
| ## Phase 2 — Lean-flavor migrator | ||
|
|
||
| 5. `zorphy_migrator/lib/src/lean_detector.dart`: parse `@Zorphy`/`@Zorphy2` annotations (via analyzer), walk the package for references to generated members (`copyWith`, `patch`, `filter`, `toJson`/`fromJson`, comparators), compute minimal preset per class. | ||
| 6. `zorphy_migrator/lib/src/cli.dart`: add `lean` subcommand — `--dry-run` (default) emits unified diff via `Rewriter`; `--apply` writes. | ||
| 7. `zorphy_migrator/lib/src/report.dart`: lean report (per-class current→proposed, lines saved estimate). | ||
|
|
||
| ## Phase 3 — Tests & release | ||
|
|
||
| 8. Upgrade `zorphy/test/` golden tests to `.zorphy.part` layout; add shared-part smoke test. | ||
| 9. New `zorphy_migrator/test/lean_detector_test.dart` + CLI integration test on a fixture. | ||
| 10. Bump `zorphy`/`zorphy_annotation`/`zorphy_migrator` to `3.0.0`; CHANGELOG ×3; `check_version_sync.sh`. | ||
| 11. Smoke: build `zik_zak` + `dart_web_scraper` with shared parts; run `zorphy_migrator lean --dry-run` on both. | ||
|
|
||
| ## Verification | ||
|
|
||
| - `dart test -j 2` green across all 3 packages. | ||
| - `dart analyze` clean on `zorphy`, `zorphy_annotation`, `zorphy_migrator`, and on built `zik_zak`/`dart_web_scraper`. | ||
| - `build_runner build` on `zik_zak` produces one `.zorphy.part` per library; `flutter analyze` clean. | ||
| - `zorphy_migrator lean --dry-run` on `zik_zak` proposes reductions; `--apply` reduces generated line count with all tests green. | ||
| - Release gate: `check_version_sync.sh` passes; version `3.0.0` in sync. | ||
|
|
||
| ## Risks | ||
|
|
||
| - `enhanced-parts` experiment stability — gate behind detection; if sink unavailable, fall back to legacy output with a clear error. | ||
| - Generated `.zorphy.part` may need `// ignore_for_file` headers matching legacy. | ||
| - Migrator false positives (removing a used feature) — dry-run default + conservative "referenced → keep" rule (FR-5). |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,44 @@ | ||
| # Quickstart: zorphy 3.0.0 | ||
|
|
||
| ## For consumers (shared parts) | ||
|
|
||
| 1. Upgrade `zorphy: ^3.0.0` and `zorphy_annotation: ^3.0.0`. | ||
| 2. Ensure `analysis_options.yaml` enables the experiment if your build uses imports in shared parts: | ||
| ```yaml | ||
| analyzer: | ||
| enable-experiment: | ||
| - enhanced-parts | ||
| ``` | ||
| 3. Run `dart run build_runner build --delete-conflicting-outputs`. | ||
| 4. Output: one `<library>.zorphy.part` per library (was many `.zorphy.dart` files). Add `**/*.zorphy.part` to `analysis_options.yaml` exclude if desired. | ||
|
|
||
| ## For consumers (lean migration) | ||
|
|
||
| 1. Preview reductions (no changes written): | ||
| ```bash | ||
| dart run zorphy_migrator lean --dry-run | ||
| ``` | ||
| Prints a unified diff: `@Zorphy(preset: standard, ...)` → `@Zorphy(preset: lean, generatePatch: true, ...)` for classes that use patch but not filter/json/comparators. | ||
| 2. Apply: | ||
| ```bash | ||
| dart run zorphy_migrator lean --apply | ||
| dart run build_runner build --delete-conflicting-outputs | ||
| dart test | ||
| ``` | ||
| 3. Report: per-class current→proposed preset, estimated lines saved. | ||
|
|
||
| ## For contributors | ||
|
|
||
| ```bash | ||
| cd zorphy && dart pub get && dart test -j 2 && dart analyze | ||
| cd ../zorphy_migrator && dart pub get && dart test -j 2 && dart analyze | ||
| ./scripts/local_ci.sh | ||
| ``` | ||
|
|
||
| ## Smoke against real consumers | ||
|
|
||
| ```bash | ||
| # zik_zak | ||
| cd ~/Developer/zik_zak && dart run build_runner build --delete-conflicting-outputs && dart analyze | ||
| dart run zorphy_migrator lean --dry-run | ||
| ``` |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,59 @@ | ||
| # Research: zorphy 3.0.0 — Shared Parts & Lean-Flavor Migration | ||
|
|
||
| ## R1. source_gen PartBuilder vs LibrarySourceSink (RESOLVED) | ||
|
|
||
| **Question**: Can `source_gen` 4.3.1 `PartBuilder` emit into a shared part via `LibrarySourceSink`? | ||
|
|
||
| **Finding**: **No.** `source_gen/lib/src/builder.dart` `_Builder` (line 20) writes its own `part of` file via `_generateForLibrary` (line ~120). `grep librarySourceSink` across `source_gen-4.3.1/lib/` returns **zero** matches. `PartBuilder` (line 277) is a thin wrapper over `_Builder` with a `generatedExtension`; it has no sink integration. | ||
|
|
||
| **Implication**: 3.0.0 shared parts require a **custom `build.Builder`**, not a `PartBuilder` flag. The builder must call `buildStep.librarySourceSink?.add(source)` itself. | ||
|
|
||
| ## R2. LibrarySourceSink API (build 5.0.0) | ||
|
|
||
| `build/lib/src/library_source_sink.dart`: | ||
| - `void add(String source)` — source must NOT contain directives; do not format (whitespace not preserved). | ||
| - `String get importPrefix` — reserved prefix for this sink. | ||
| - `void addImport(String uri, {required String as, Iterable<String>? show, Iterable<String>? hide})` — `as` must start with `importPrefix`; adds imports cause dependency on `enhanced-parts` feature (StateError if not enabled). | ||
|
|
||
| `build_runner` 2.17.1 `build_step_impl.dart:68`: `Future<LibrarySourceSink?> get librarySourceSink` — returns null if no sink; exposes `partContribution`, `imports`, `languageVersion`. | ||
|
|
||
| ## R3. enhanced-parts experiment | ||
|
|
||
| `addImport` throws `StateError` unless the `enhanced-parts` experiment is enabled. For 3.0.0: | ||
| - If the generator needs NO imports in the shared part (most Zorphy output is self-contained after the `part of` header), `addImport` is not required and the experiment is not triggered. | ||
| - If imports are needed (e.g. `package:zorphy_annotation/...`), the experiment must be enabled via `analysis_options.yaml` `analyzer: enable-experiment: [enhanced-parts]` or `build.yaml` `required_experiments` (verify support in plan phase). | ||
| - **Decision**: default shared-part output avoids imports (uses fully-qualified or `part of` library imports); `addImport` only when explicitly needed, with a clear error if experiment missing. | ||
|
|
||
| ## R4. Current builder wiring | ||
|
|
||
| - `zorphy/lib/builder.dart:28` `zorphyBuilder` → `source_gen.PartBuilder([...], '.zorphy.dart', header: ...)`. | ||
| - `zorphy/build.yaml`: `zorphy:zorphy` builder, `build_extensions: {".dart": [".zorphy.dart"]}`, `auto_apply: dependents`, `applies_builders: ["source_gen|combining_builder"]`. | ||
| - `zorphy/lib/builder2.dart`: `@Deprecated zorphy2Builder` alias (remove in 3.0.0). | ||
| - `zorphy/lib/src/zorphy_generator.dart:98`: emits `.zorphy.dart` / `.zorphy2.dart` via output extension. | ||
|
|
||
| ## R5. Preset system (lean flavor target) | ||
|
|
||
| `zorphy_annotation/lib/src/annotations.dart:23` `enum ZorphyPreset { lean, standard, full }`. | ||
| - `lean`: class, constructor, `copyWith`, equality. | ||
| - `standard`: lean + patch + filter + comparators + JSON opt-in. | ||
| - `full`: standard + function-based copyWith. | ||
| - Per-feature overrides: `generateJson` (bool, default false), `generatePatch?`, `generateFilter?`, `generateCopyWith?`, `generateCopyWithFn?` (null = inherit preset). | ||
|
|
||
| **Lean-flavor tool**: for each `@Zorphy` class, detect which of {patch, filter, copyWithFn, json, comparators} are actually referenced in the package; propose `preset: lean` + explicit `generateX: true` only for referenced features. Conservative rule (FR-5): never drop a feature referenced anywhere in `lib/` or `test/`. | ||
|
|
||
| ## R6. Usage evidence (from completed analysis — do not redo) | ||
|
|
||
| - `zik_zak`: 159 `@Zorphy` classes, ~95.4k generated lines, ~42% patch code. | ||
| - `dart_web_scraper`: 70 `@Zorphy` classes, ~38.5k generated lines, ~39% patch code. | ||
| - Majority of entities generate unused JSON/patch/filter/comparator plumbing under `standard`. | ||
|
|
||
| ## R7. zorphy_migrator extension point | ||
|
|
||
| `zorphy_migrator/lib/src/cli.dart` `MigratorCli.run()`: | ||
| - Parses args, selects detectors (`freezed_detector`, `exchangeable_detector`), builds replacements, `Rewriter().applySpans` + `unifiedDiff`. | ||
| - New `lean_detector.dart` implements the same detector interface: scan → replacements (annotation rewrites) → diff/apply. | ||
| - `Rewriter` (span-based) already supports unified diff + apply; lean detector only needs to produce the right spans. | ||
|
|
||
| ## R8. Output extension choice | ||
|
|
||
| `.zorphy.part` chosen (not `.g.dart`) to avoid collision with `source_gen|combining_builder` (`SharedPartBuilder`) outputs. `build.yaml` `build_extensions: {".dart": [".zorphy.part"]}`. |
Oops, something went wrong.
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
🟡
--delete-conflicting-outputsno 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:Confirmed live:
dart run build_runner build --delete-conflicting-outputsinzorphy/exampleprints exactly that. So the instruction added here and at line 1407, inzorphy/CHANGELOG.md:12, inzorphy_migrator/README.md:123, in the fixture hints ofzorphy2_alias_compat_test.dart/issue_148/issue_88, and — outside this diff but still shipped — inzorphy/lib/src/cli/services/doctor_service.dart:101andproject_validator.dart:322,350, does not delete the 2.x<file>.zorphy.dartfiles. A user who follows it keeps one stale generated file per source file (harmless — an unreferencedpart offile analyzes clean, I checked — but litter that.gitignorealready hides).Suggest dropping the flag from the docs and saying plainly "delete the old
*.zorphy.dartfiles yourself", or pointing atzorphy build --clean.