Repository navigation
chore(release): zorphy 2.5.0 — SDK floor 3.11 alignment + analyze-clean gate #160
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 3 commits
Commits
Show all changes
14 commits
Select commit
Hold shift + click to select a range
cf3339a
docs(141): zorphy 2.5.0 spec + plan
arrrrny ed252e6
docs(141): zorphy 2.5.0 tasks
arrrrny 78e0ab2
chore(release): zorphy 2.5.0 — SDK floor 3.11 alignment + analyze-cle…
arrrrny 5a42670
fix(ci): resolve formatting and analyzer 13.x/14.x gate compatibility
arrrrny cf1b7aa
fix(ci): format bare checkout and move local path override to pubspec…
arrrrny f523a9c
fix(ci): preserve 58f07bc language-3.0 formatting for bare-checkout d…
arrrrny e987699
fix(ci): format new release test files at language-3.0 canonical style
arrrrny f1ae4ed
fix(test): support analyzer 13.x diagnostic message text in analyze_c…
arrrrny 7b342dc
fix(review): address CodeRabbit findings on PR #160 (sdk floor dep ch…
arrrrny d2a01bf
fix(review): address zuraffa-review findings on PR #160 (to_path.sh, …
arrrrny bc3284e
fix(review): remove inert pubspec_overrides.yaml exclude from analysi…
arrrrny e790c4d
fix(review): address review comments on #160
zuraffa-review[bot] 5a20999
Merge remote-tracking branch 'origin/141-v2-5-0-deps-sdk-align' into …
zuraffa-review[bot] c9273a1
fix(format): canonical dart format for dependency_constraints_unchang…
arrrrny 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
33 changes: 33 additions & 0 deletions
33
specs/141-v2-5-0-deps-sdk-align/contracts/published-contract.md
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,33 @@ | ||
| # Phase 1 — Contracts: zorphy 2.5.0 Published Contract | ||
|
|
||
| zorphy is a published library; its "interfaces" are (1) the package metadata consumers resolve against and (2) the stability of the code it generates. These are the contracts this release must honor. Each contract lists the observable, testable assertion. | ||
|
|
||
| ## Contract 1 — SDK-floor contract | ||
|
|
||
| **Statement**: `zorphy` and `zorphy_migrator` declare `environment: sdk` admitting `>=3.11.0 <4.0.0`, and no declared dependency requires an SDK floor above 3.11.0. | ||
|
|
||
| **Assertion**: Parse both pubspecs; assert the sdk constraint admits 3.11.0 and rejects 3.10.9; assert `max(dependency sdk floors) <= 3.11.0`. | ||
|
|
||
| ## Contract 2 — Output-stability contract | ||
|
|
||
| **Statement**: For every standard fixture, generated `.zorphy.dart` is byte-identical to the 2.4.6 golden. | ||
|
|
||
| **Assertion**: Existing golden/characterization tests pass with zero diff (goldens not regenerated). | ||
|
|
||
| ## Contract 3 — Analyze-clean contract | ||
|
|
||
| **Statement**: Generated `.zorphy.dart` for the standard fixtures produces zero `dart analyze` diagnostics under the pinned analyzer. | ||
|
|
||
| **Assertion**: The analyze-clean gate test generates the fixtures, runs `dart analyze` on the output, and asserts an empty diagnostics list. Runs in the default fast tier. | ||
|
|
||
| ## Contract 4 — Version-sync contract | ||
|
|
||
| **Statement**: `zorphy` and `zorphy_annotation` are both version `2.5.0`. | ||
|
|
||
| **Assertion**: `scripts/check_version_sync.sh` exits 0; a test reads both pubspec versions and asserts equality to `2.5.0`. | ||
|
|
||
| ## Contract 5 — Dependency-freshness contract | ||
|
|
||
| **Statement**: `dart pub outdated` reports all direct dependencies up-to-date; `dart pub get --no-example` produces zero lockfile drift. | ||
|
|
||
| **Assertion**: Documented in quickstart.md as release-gate commands (executed in CI/local_ci), not a unit test. |
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,45 @@ | ||
| # Phase 1 — Data Model: zorphy 2.5.0 | ||
|
|
||
| This release changes configuration and tests only. The "entities" are the artifacts under configuration management, each with invariants that the test suite enforces. | ||
|
|
||
| ## Entity: PubspecManifest | ||
|
|
||
| Represents a package's `pubspec.yaml` (`zorphy`, `zorphy_annotation`, `zorphy_migrator`). | ||
|
|
||
| **Fields** | ||
| - `name` — package name. | ||
| - `version` — semantic version string. | ||
| - `environment.sdk` — SDK constraint (e.g. `">=3.11.0 <4.0.0"`). | ||
| - `dependencies.*` — name → constraint map (unchanged this release). | ||
|
|
||
| **Invariants** | ||
| - `zorphy.environment.sdk` admits `>=3.11.0` and excludes `<3.11.0`. | ||
| - `zorphy_migrator.environment.sdk` admits `>=3.11.0`. | ||
| - `zorphy.version == zorphy_annotation.version` (parity). | ||
| - For every declared dependency, `dependency.sdkFloor <= 3.11.0` (the package floor is sufficient). | ||
|
|
||
| **State transitions**: `zorphy`/`zorphy_annotation` version `2.4.6 → 2.5.0`; `zorphy`/`zorphy_migrator` `environment.sdk` `">=3.8.0 <4.0.0" → ">=3.11.0 <4.0.0"`. No dependency-constraint transitions. | ||
|
|
||
| ## Entity: Lockfile (`pubspec.lock`) | ||
|
|
||
| The committed resolved baseline per package. | ||
|
|
||
| **Invariants** | ||
| - `dart pub get --no-example` leaves the lock byte-identical (zero drift). | ||
| - Resolved versions remain analyzer 14.7.0 / build 5.0.0 / source_gen 4.3.1 / code_builder 4.13.0 / dart_style 3.1.14 (unchanged). | ||
|
|
||
| ## Entity: GeneratedOutputFixture | ||
|
|
||
| An input entity file paired with its expected `.zorphy.dart` golden. | ||
|
|
||
| **Invariants** | ||
| - Generated bytes equal the 2.4.6 golden (byte-identical). | ||
| - `dart analyze` on the generated output yields **zero** diagnostics under the pinned analyzer (the analyze-clean gate). | ||
|
|
||
| ## Entity: ReleaseMetadata | ||
|
|
||
| Per-package `CHANGELOG.md` plus the version-sync check. | ||
|
|
||
| **Invariants** | ||
| - `zorphy/CHANGELOG.md` and `zorphy_annotation/CHANGELOG.md` each contain a `2.5.0` entry. | ||
| - `scripts/check_version_sync.sh` exits 0 (zorphy == zorphy_annotation == 2.5.0). |
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,74 @@ | ||
| # Implementation Plan: zorphy 2.5.0 — Dependency & SDK-Floor Alignment Release | ||
|
|
||
| **Branch**: `141-v2-5-0-deps-sdk-align` | **Date**: 2026-11-16 | **Spec**: [spec.md](./spec.md) | ||
|
|
||
| **Input**: Feature specification from `/specs/141-v2-5-0-deps-sdk-align/spec.md` | ||
|
|
||
| ## Summary | ||
|
|
||
| Non-breaking metadata + test + release-notes release. The resolved dependency graph already sits on the latest analyzer/build/source_gen majors (committed `pubspec.lock`; `dart pub outdated` all up-to-date; `dart analyze lib` clean on core and migrator). The single functional defect is the unsatisfiable `environment: sdk: ">=3.8.0 <4.0.0"`. This plan raises the published SDK floor to `>=3.11.0` in `zorphy` and `zorphy_migrator`, preserves every dependency constraint (dependency-bump-rule), keeps `pubspec.lock` pinned and drift-free, adds a permanent analyze-clean regression gate over generated output, bumps `zorphy` + `zorphy_annotation` to `2.5.0` in sync, writes CHANGELOG entries, and upgrades every affected test. There are **no `lib/` or emitted-output changes** — generated code stays byte-identical. | ||
|
|
||
| ## Technical Context | ||
|
|
||
| **Language/Version**: Dart — published floor `>=3.11.0 <4.0.0` (dev/CI run on ≥3.13 to honor the locked analyzer 14.7.0). | ||
|
|
||
| **Primary Dependencies**: analyzer `^14.0.0` (lock 14.7.0), build `>=4.0.4 <6.0.0` (lock 5.0.0), source_gen `^4.3.1`, code_builder `^4.10.0` (lock 4.13.0), dart_style `^3.1.1` (lock 3.1.14), build_runner `^2.17.1` (dev). Constraints unchanged. | ||
|
|
||
| **Storage**: N/A (files: `pubspec.yaml` ×3, `pubspec.lock` ×3, `CHANGELOG.md` ×2). | ||
|
|
||
| **Testing**: `dart test` at concurrency 2 (default fast tier), `dart analyze`, `./scripts/local_ci.sh`, `scripts/check_version_sync.sh`. | ||
|
|
||
| **Target Platform**: pub.dev package consumed by Dart VM and Flutter apps. | ||
|
|
||
| **Project Type**: library + CLI (monorepo: `zorphy`, `zorphy_annotation`, `zorphy_migrator`). | ||
|
|
||
| **Performance Goals**: N/A (no runtime change). | ||
|
|
||
| **Constraints**: byte-identical generated output; no dependency-constraint changes; zero lockfile drift; zorphy/annotation version parity. | ||
|
|
||
| **Scale/Scope**: 3 packages, ~6 manifest files, CHANGELOG ×2, test suite (new analyze-clean gate + floor/version assertions). | ||
|
|
||
| ## Constitution Check | ||
|
|
||
| *GATE: Must pass before Phase 0 research. Re-check after Phase 1 design.* | ||
|
|
||
| The repository `.specify/memory/constitution.md` is the **unfilled template** (placeholder tokens such as `[PRINCIPLE_1_NAME]`; no ratified principles, version, or dates). There are therefore no enforceable gates to evaluate — Constitution Check is **N/A**. No violations. Post-design re-check: still N/A (constitution remains an unfilled template). Logged as a known gap; not a blocker for this release. | ||
|
|
||
| ## Project Structure | ||
|
|
||
| ### Documentation (this feature) | ||
|
|
||
| ```text | ||
| specs/141-v2-5-0-deps-sdk-align/ | ||
| ├── spec.md # Feature specification | ||
| ├── plan.md # This file | ||
| ├── research.md # Phase 0 — decisions & rationale | ||
| ├── data-model.md # Phase 1 — manifest/lock/fixture/release entities | ||
| ├── quickstart.md # Phase 1 — validation guide | ||
| ├── contracts/ # Phase 1 — published metadata & output-stability contracts | ||
| └── tasks.md # Phase 2 (speckit-tasks — NOT created here) | ||
| ``` | ||
|
|
||
| ### Source Code (repository root) | ||
|
|
||
| ```text | ||
| zorphy/ | ||
| ├── pubspec.yaml # environment: sdk -> >=3.11.0 ; version -> 2.5.0 | ||
| ├── pubspec.lock # verify: zero drift after dart pub get --no-example | ||
| ├── CHANGELOG.md # add 2.5.0 entry | ||
| └── test/** # add analyze-clean gate; update floor/version assertions | ||
| zorphy_migrator/ | ||
| ├── pubspec.yaml # environment: sdk -> >=3.11.0 | ||
| └── pubspec.lock # verify: zero drift | ||
| zorphy_annotation/ | ||
| ├── pubspec.yaml # version -> 2.5.0 (sync) | ||
| ├── pubspec.lock # verify: zero drift | ||
| └── CHANGELOG.md # add 2.5.0 entry | ||
| scripts/check_version_sync.sh # run: must pass (zorphy == zorphy_annotation) | ||
| ``` | ||
|
|
||
| **Structure Decision**: Existing monorepo layout; no new directories. The change is confined to manifests, lockfiles (verify-only), CHANGELOGs, and the test tree. | ||
|
|
||
| ## Complexity Tracking | ||
|
|
||
| No Constitution violations (constitution is an unfilled template — N/A). No complexity justifications required. |
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 @@ | ||
| # Phase 1 — Quickstart: validating zorphy 2.5.0 | ||
|
|
||
| Run from the repository root (`/Users/arrrrny/Developer/zorphy`) unless noted. These are the end-to-end checks that prove the release is correct and non-breaking. All must pass before opening the PR. | ||
|
|
||
| ## Prerequisites | ||
|
|
||
| - Dart SDK ≥ 3.13 on the dev/CI machine (to honor the committed lock's analyzer 14.7.0). The *published* floor is 3.11.0. | ||
| - `--no-example` for resolution: the `example/` packages depend on the Flutter SDK. | ||
|
|
||
| ## 1. Lockfile is the tested baseline (zero drift) | ||
|
|
||
| ```bash | ||
| cd zorphy && dart pub get --no-example && cd .. | ||
| git diff --exit-code -- zorphy/pubspec.lock zorphy_annotation/pubspec.lock zorphy_migrator/pubspec.lock | ||
| ``` | ||
| **Expected**: no diff (exit 0). | ||
|
|
||
| ## 2. Direct dependencies are current | ||
|
|
||
| ```bash | ||
| cd zorphy && dart pub outdated | ||
|
coderabbitai[bot] marked this conversation as resolved.
Resolved
|
||
| ``` | ||
| **Expected**: "direct dependencies: all up-to-date." | ||
|
|
||
| ## 3. Core + migrator analyze clean | ||
|
|
||
| ```bash | ||
| cd zorphy && dart analyze lib | ||
| cd ../zorphy_migrator && dart analyze lib | ||
| ``` | ||
| **Expected**: "No issues found!" for both. | ||
|
|
||
| ## 4. Full suite green (includes the new analyze-clean gate) | ||
|
|
||
| ```bash | ||
| cd zorphy && dart test | ||
|
coderabbitai[bot] marked this conversation as resolved.
Resolved
|
||
| ``` | ||
| **Expected**: all tests pass. The analyze-clean gate generates `.zorphy.dart` for the standard fixtures, analyzes the output, and asserts zero diagnostics. | ||
|
|
||
| ## 5. Version sync | ||
|
|
||
| ```bash | ||
| ./scripts/check_version_sync.sh | ||
| ``` | ||
| **Expected**: "OK: both packages at version 2.5.0". | ||
|
|
||
| ## 6. Generated output is byte-identical to 2.4.6 | ||
|
|
||
| Covered by the golden/characterization tests in step 4 (they must pass with no golden regeneration). If a dedicated diff check exists, run it; otherwise the unchanged goldens are the proof. | ||
|
|
||
| ## 7. Local CI gate | ||
|
|
||
| ```bash | ||
| ./scripts/local_ci.sh | ||
| ``` | ||
| **Expected**: exit 0 (every executed step passes). | ||
|
|
||
| ## Notes / deferred | ||
|
|
||
| See [research.md](./research.md) D1–D8 for the decisions behind these checks. Shared parts, primary constructors, migrator AST rework, and the lean-flavor migration tool are **out of scope** for 2.5.0 (3.0.0). | ||
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,74 @@ | ||
| # Phase 0 — Research: zorphy 2.5.0 SDK-Floor & Dependency Alignment | ||
|
|
||
| All NEEDS CLARIFICATION items from the plan's Technical Context are resolved here. | ||
|
|
||
| ## D1 — Published SDK floor = `>=3.11.0` (not `^3.13.0`, not `>=3.8.0`) | ||
|
|
||
| **Decision**: Set `environment: sdk` to `">=3.11.0 <4.0.0"` in `zorphy` and `zorphy_migrator`. | ||
|
|
||
| **Rationale**: Verified from the pub.dev API (`/api/packages/<pkg>` → `pubspec.environment.sdk`): | ||
| - analyzer `14.0.0` → `^3.11.0` (14.1–14.5 also `^3.11.0`); only the **locked** `14.7.0` → `^3.13.0`. | ||
| - source_gen `4.3.1` → `^3.11.0`; build `5.0.0` → `^3.11.0`; dart_style `3.1.14` → `^3.11.0`; code_builder `4.13.0` → `^3.10.0`. | ||
| - A Dart 3.11 consumer can resolve the whole declared set (picking analyzer 14.0.0–14.5.x inside `^14.0.0`). The binding minimum is therefore 3.11.0. This matches the sibling `zuraffa` pubspec policy (its floor stays `^3.11.0` for the same reason). | ||
|
|
||
| **Alternatives considered**: | ||
| - `^3.13.0` — rejected: that is only the locked analyzer 14.7.0's floor; it would break Dart 3.11/3.12 consumers who legitimately resolve an older analyzer within `^14.0.0`. | ||
| - Keep `>=3.8.0` — rejected: unsatisfiable (no declared dependency supports 3.8–3.10) and misleading. | ||
|
|
||
| ## D2 — Do NOT tighten dependency constraints | ||
|
|
||
| **Decision**: Leave `analyzer`, `build`, `source_gen`, `code_builder`, `dart_style`, `build_runner` constraints exactly as in 2.4.6. Only `environment: sdk` and `version` change. | ||
|
|
||
| **Rationale**: Repository `dependency-bump-rule` — "Do not raise every constraint to the locked version… preserve the supported lower bound otherwise." The declared constraints already resolve to the latest majors (`dart pub outdated` = up-to-date). Tightening (e.g. `^14.0.0` → `^14.7.0`) would narrow consumer compatibility for no benefit. | ||
|
|
||
| **Alternatives considered**: align constraints to locked majors — rejected per the rule. | ||
|
|
||
| ## D3 — Lockfile stays committed and drift-free | ||
|
|
||
| **Decision**: Keep `pubspec.lock` committed; verify `dart pub get --no-example` produces zero lockfile changes (use `--no-example` because `example/` depends on the Flutter SDK). | ||
|
|
||
| **Rationale**: CI resolves with `--enforce-lockfile`; a drifted lock must fail loudly (repo policy). The lock is the tested baseline. | ||
|
|
||
| **Alternatives considered**: delete/ignore lock — rejected (repo commits locks intentionally). | ||
|
|
||
| ## D4 — Analyze-clean regression gate design | ||
|
|
||
| **Decision**: Add a test in the **default fast tier** that (a) generates `.zorphy.dart` for the standard fixture entities into a temp dir, (b) runs `dart analyze` on the generated files using the pinned analyzer (spawned child process, matching existing `spawn`-tagged suites), and (c) asserts zero diagnostics. Reuse the repo's existing "generate then analyze" test pattern if one exists; otherwise spawn `dart analyze` on the generated temp package. | ||
|
|
||
| **Rationale**: analyzer 14.6 replaced `undefined_getter` with the `undefined_*_read`/`undefined_*_write` family — the exact breakage that hit `zuraffa` (#1980). Goldens alone do not re-analyze output under the new diagnostics; a live analyze gate is the durable guard that keeps 2.5.0 "aligned to latest". | ||
|
|
||
| **Alternatives considered**: | ||
| - Rely on downstream consumer builds — rejected (reactive). | ||
| - Golden-file comparison only — rejected (does not exercise the new diagnostics). | ||
|
|
||
| ## D5 — Byte-identical output verification | ||
|
|
||
| **Decision**: Prove no output change by running the existing golden/characterization tests unchanged and asserting zero diffs. Do NOT regenerate goldens. | ||
|
|
||
| **Rationale**: 2.5.0 must be non-breaking; regenerating goldens would mask accidental drift. | ||
|
|
||
| **Alternatives considered**: regenerate goldens — rejected. | ||
|
|
||
| ## D6 — Version bump scope | ||
|
|
||
| **Decision**: `zorphy` 2.4.6 → 2.5.0 **and** `zorphy_annotation` 2.4.6 → 2.5.0 (parity enforced by `scripts/check_version_sync.sh`). `zorphy_migrator` stays on its own 2.0.0 line but receives the same SDK-floor fix. | ||
|
|
||
| **Rationale**: `check_version_sync.sh` compares only zorphy vs zorphy_annotation. The migrator is independently versioned. | ||
|
|
||
| **Alternatives considered**: bump migrator to 2.5.0 — rejected (separate line, not required, would be misleading). | ||
|
|
||
| ## D7 — Semver treatment of the floor change | ||
|
|
||
| **Decision**: Treat `>=3.8.0 → >=3.11.0` as a non-breaking correctness fix and ship as **2.5.0 (MINOR)**; document clearly in the CHANGELOG. | ||
|
|
||
| **Rationale**: Dart 3.8–3.10 consumers could not resolve zorphy 2.4.6 anyway (no declared dependency supports those SDKs), so raising the floor breaks no working consumer. This matches the user's two-part release intent (2.5.0 non-breaking, 3.0.0 breaking). | ||
|
|
||
| **Alternatives considered**: classify as MAJOR — rejected (no practical breakage; user's explicit intent). | ||
|
|
||
| ## D8 — No `writeDescriptions` / output-affecting API adoption in 2.5.0 | ||
|
|
||
| **Decision**: Do not adopt `PartBuilder(writeDescriptions: false)` or any API that alters emitted headers/bytes. Deferred to 3.0.0. | ||
|
|
||
| **Rationale**: Such changes would violate the byte-identical requirement (FR-006). | ||
|
|
||
| **Alternatives considered**: adopt now — rejected (output drift). |
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.
Uh oh!
There was an error while loading. Please reload this page.