Skip to content
Merged
Show file tree
Hide file tree
Changes from all 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
26 changes: 22 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,19 @@ 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
the 2.x `<file>.zorphy.dart` files, then rebuild. (2.x wrote one
`<file>.zorphy.dart` beside every source file; that layout is gone, and
build_runner 2.17 removed `--delete-conflicting-outputs` — passing it is
ignored with a warning, so the stale files are yours to delete.) Each
generated part carries `// ignore_for_file:` headers, so a consumer's own
`analysis_options.yaml` does not lint code it cannot edit; exclude
`lib/_br_/**` as well if you prefer to keep generated code out of analysis
altogether.

### Generated Enums

Expand Down Expand Up @@ -1397,8 +1410,13 @@ 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` (or `zorphy build`) so the shared
part under `lib/_br_/` is regenerated — no `--delete-conflicting-outputs`:
build_runner 2.17 removed that flag and only warns about it
2. You removed any leftover `part 'filename.zorphy.dart';` line and any stale
`filename.zorphy.dart` from the 2.x layout — 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