0067. Editions, and duolith upgrade moves a project to one with migrations
- Status: Accepted (Mik, 17 Nov 2026)
- Date: 2026-11-14
- Decided by: toolchain work package (WP15), pending Mik's approval
- Planning item: WP15 (toolchain), goal 2
Context
The language will change in ways that break existing pages. Authors need a tool that rewrites their project, shows what it will change first, and can be run twice safely. The first such change already happened: a page's script used to be able to export, and now cannot (E0147, E0118).
Decision
- An edition is a named version of the language, such as
0.1and0.2. Each migration belongs to the edition that needs it and moves source written for the edition before.duolith upgrade [project] [--to edition] [--dry-run] [--json]runs every migration up to--to(default: the newest edition). - Migrations are idempotent and keep the author's text. Each is a function from a file's text to its new text and the problems it could not solve; running it on a file that is already up to date changes nothing. A migration may parse to find what to change (the first one parses the script block with oxc), but it edits the text by span, so formatting and comments stay. No project file records the edition, so a project is never stamped as upgraded while a file was missed.
- **
--dry-runprints a unified diff** for each file that would change and writes nothing. Without it the files are written and the same diff is shown. - What a migration cannot move fails the upgrade. Each such statement is reported with its file and line, the rest is still written, and the command exits 1, so a project is never said to be on an edition it is not on.
--jsonlists them underproblems, andokis false. - Symbolic links are not followed, so an upgrade never writes outside the project or loops.
- **The first migration,
scripts-do-not-export** (edition 0.2), takesexportoff the script block's top-level statements, as the parser sees them, soexportin a string, a comment or a namespace is left alone.export const,export functionandexport default function shown()keep their declaration;export { a as b }goes;export { x } from "./y"andexport * from "./y"becomeimport "./y", keeping what loading the module does.export defaultof an unnamed value,export =andexport as namespaceare problems.examples/upgrade/edition-0.1is a project written for 0.1 for it to run on. - **
--jsonfollowsspec/schemas/cli/upgrade.schema.json**:{ ok, project, edition, dryRun, migrations: [{ id, edition, description }], changes: [{ file, migrations, diff }], problems: [{ file, migration, message }] }. An unknown edition exits 2 and names the editions there are.
Alternatives considered
| Option | Why not |
|---|---|
An edition field in a project file | A second source of truth; files copied from elsewhere would claim the wrong edition |
| Printing the file again from the syntax tree | The tree drops formatting and comments; edits by span keep the author's text |
| Matching lines of text without parsing | Rewrote export inside template strings, comments and namespaces, and missed export default function and export { a as b } |
| Warn and leave the change to the author | Every breaking change would cost every app an afternoon |
Consequences
- A breaking language change ships with its migration, its tests, and a before-and-after pair under
examples/upgrade/: the old project in anedition-*folder, and the upgraded app, which CI builds and a test compares with the migration's output. - The
edition-*folder does not build, on purpose. The language server's example test allows exactly the codes the migration fixes there, and nowhere else.