Skip to content
Merged
Show file tree
Hide file tree
Changes from 6 commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -23,6 +23,8 @@
*.morphy.dart
*.morphy2.dart
*.zorphy.dart
# zorphy 3.0.0 shared parts (build_runner `adds_to_library` output)
_br_/
*.zorphy2.dart
n# Allow golden reference files for v2 pipeline
!specs/
Expand Down
18 changes: 14 additions & 4 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -215,7 +215,8 @@ Or create classes manually:
```dart
import 'package:zorphy_annotation/zorphy_annotation.dart';

part 'user.zorphy.dart';
// zorphy 3.0 emits a shared part under lib/_br_/ and build_runner writes the
// `part` directive for you — there is nothing to declare here.

@Zorphy()
abstract class $User {
Expand Down Expand Up @@ -1363,7 +1364,13 @@ zorphy build --clean

### Generated Files

- **`*.zorphy.dart`** - Generated code from `@Zorphy` annotation
- **`lib/_br_/**.part.dart`** - Generated code from `@Zorphy` annotations,
one shared part per library. As of 3.0 the builder declares
`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.

`<file>.zorphy.dart` beside every source file; that layout is gone.)

### Generated Enums

Expand Down Expand Up @@ -1397,8 +1404,11 @@ Zorphy is designed for easy migration from Morphy:

If you get type not found errors, ensure:

1. You've added `part 'filename.zorphy.dart';` to your file
2. You've run `dart run build_runner build` or `zorphy build`
1. You've run `dart run build_runner build --delete-conflicting-outputs` (or
`zorphy build`) so the shared part under `lib/_br_/` is regenerated
2. You removed any leftover `part 'filename.zorphy.dart';` line — 3.0 no
longer writes per-file generated libraries, and `build_runner` adds the
shared-part directive itself
3. The import includes `package:zorphy_annotation/zorphy_annotation.dart`

### Generic Type Issues
Expand Down
52 changes: 52 additions & 0 deletions specs/142-v3-0-0-refactor/data-model.md
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).
60 changes: 60 additions & 0 deletions specs/142-v3-0-0-refactor/plan.md
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).
44 changes: 44 additions & 0 deletions specs/142-v3-0-0-refactor/quickstart.md
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
```
59 changes: 59 additions & 0 deletions specs/142-v3-0-0-refactor/research.md
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"]}`.
Loading
Loading