Add @codama/upgrade - #1095
Draft
lorisleiva wants to merge 1 commit into
Draft
Conversation
This PR adds the `@codama/upgrade` package: an append-only chain of pure, hand-written functions, each upgrading a Codama document exactly one major to the next. `upgrade()` detects the source major from the document's `version`, refuses pre-1.0 or unparsable versions with the new `CODAMA_ERROR__UNSUPPORTED_VERSION` code, refuses future majors with the existing `CODAMA_ERROR__VERSION_MISMATCH` (whose message now covers both directions), runs the applicable upgrade functions as sequential `if (major <= N)` blocks, and restamps the result with the latest `CODAMA_VERSION`. The chain is empty while the latest spec major is 1, so upgrading is identity plus restamp; adding a future major means one new function and one new `if` block, and because the functions and frozen types are committed source with zero dependencies, every major back to 1.0.0 stays upgradable forever. The frozen v1 node types are generated as part of the default `generate` orchestrator from a new `@codama/spec-v1` aliased exact pin in `spec-generators`, so the CI freshness check guards the snapshot automatically and it only changes when that pin or the generator code deliberately changes; after the v2 transition, the living pin moves to 2.x while the alias keeps pointing at the last 1.x. The snapshot is committed under `src/v1` alongside frozen copies of the hand-written `brands`/`Docs`/`Version` siblings, is compile-time only, and is exposed as the type-only `v1` namespace, adding zero runtime bytes. `upgradeFromJson` covers the JSON path and `upgradeToLatestVisitor` provides the CLI-friendly preprocessing boundary. Tests cover detection, restamping, content preservation, all error paths, a compile-time guarantee that the frozen `v1` types describe current v1 documents, and upgraded fixtures passing `@codama/validators` as a smoke check. Upgrade functions are pure JSON-tree-in, JSON-tree-out transforms with no environment access, keeping the chain portable to `codama-rs`. This is Phase 2 of the v2 migration framework plan.
🦋 Changeset detectedLatest commit: ae200d2 The changes in this PR will be included in the next version bump. This PR includes changesets to release 17 packages
Not sure what this means? Click here to learn what changesets are. Click here if you're a maintainer who wants to add another changeset to this PR |
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
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
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.
This PR adds the
@codama/upgradepackage: an append-only chain of pure, hand-written functions, each upgrading a Codama document exactly one major to the next.upgrade()detects the source major from the document'sversion, refuses pre-1.0 or unparsable versions with the newCODAMA_ERROR__UNSUPPORTED_VERSIONcode, refuses future majors with the existingCODAMA_ERROR__VERSION_MISMATCH(whose message now covers both directions), runs the applicable upgrade functions as sequentialif (major <= N)blocks, and restamps the result with the latestCODAMA_VERSION. The chain is empty while the latest spec major is 1, so upgrading is identity plus restamp; adding a future major means one new function and one newifblock, and because the functions and frozen types are committed source with zero dependencies, every major back to 1.0.0 stays upgradable forever. The frozen v1 node types are generated as part of the defaultgenerateorchestrator from a new@codama/spec-v1aliased exact pin inspec-generators, so the CI freshness check guards the snapshot automatically and it only changes when that pin or the generator code deliberately changes; after the v2 transition, the living pin moves to 2.x while the alias keeps pointing at the last 1.x. The snapshot is committed undersrc/v1alongside frozen copies of the hand-writtenbrands/Docs/Versionsiblings, is compile-time only, and is exposed as the type-onlyv1namespace, adding zero runtime bytes.upgradeFromJsoncovers the JSON path andupgradeToLatestVisitorprovides the CLI-friendly preprocessing boundary. Tests cover detection, restamping, content preservation, all error paths, a compile-time guarantee that the frozenv1types describe current v1 documents, and upgraded fixtures passing@codama/validatorsas a smoke check. Upgrade functions are pure JSON-tree-in, JSON-tree-out transforms with no environment access, keeping the chain portable tocodama-rs. This is Phase 2 of the v2 migration framework plan.