Duolith docs

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.1 and 0.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-run prints 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. --json lists them under problems, and ok is 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), takes export off the script block's top-level statements, as the parser sees them, so export in a string, a comment or a namespace is left alone. export const, export function and export default function shown() keep their declaration; export { a as b } goes; export { x } from "./y" and export * from "./y" become import "./y", keeping what loading the module does. export default of an unnamed value, export = and export as namespace are problems. examples/upgrade/edition-0.1 is a project written for 0.1 for it to run on.
  • **--json follows spec/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

OptionWhy not
An edition field in a project fileA second source of truth; files copied from elsewhere would claim the wrong edition
Printing the file again from the syntax treeThe tree drops formatting and comments; edits by span keep the author's text
Matching lines of text without parsingRewrote export inside template strings, comments and namespaces, and missed export default function and export { a as b }
Warn and leave the change to the authorEvery 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 an edition-* 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.