Skip to content
Merged
Show file tree
Hide file tree
Changes from 3 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
33 changes: 33 additions & 0 deletions specs/141-v2-5-0-deps-sdk-align/contracts/published-contract.md
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.
45 changes: 45 additions & 0 deletions specs/141-v2-5-0-deps-sdk-align/data-model.md
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).
74 changes: 74 additions & 0 deletions specs/141-v2-5-0-deps-sdk-align/plan.md
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.
60 changes: 60 additions & 0 deletions specs/141-v2-5-0-deps-sdk-align/quickstart.md
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 ..
Comment thread
coderabbitai[bot] marked this conversation as resolved.
Resolved
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
Comment thread
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
Comment thread
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).
74 changes: 74 additions & 0 deletions specs/141-v2-5-0-deps-sdk-align/research.md
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).
Loading
Loading