feat(migrate): rework migrations and initial sveltekit-3 migration

[manuel3108]

Relates #1111
Closes #1124

Description

This PR lays the groundwork for making sv migrate the new home for Svelte migrations.

It does a few things:

• bumps svelte-migrate to a new major version so it can be deprecated in favor of sv migrate
• rewrites the migration system to re-use the tooling and utilities we have built for sv add over the last two years
• removes previous migrations from the source code
• keeps previous migrations available to users as legacy migrations by delegating to npx svelte-migrate@1
• introduces a new migration system that is closely aligned with the existing sv add architecture

Migration system

The new system is built around two concepts: migrations and migration tasks.

A migration is the top-level wrapper. It is similar to what we had before and will usually be added alongside a new version release, though not necessarily only for major releases.

A migration task is the actual execution unit responsible for applying part of a migration. Larger migrations can be split into multiple tasks. For example, sveltekit-3 currently consists of separate tasks for package.json, svelte.config.js, and environment variable changes.

Tasks can be required or optional. Optional tasks can be selected or deselected by the user, which has a few important benefits:

• users can migrate step by step
• users can split migration changes into multiple commits more easily
• each task can represent a clear testing surface

Each task receives almost the same parameters as an addon, with only minor differences. This allows migrations to re-use addon functionality directly. For example, the sveltekit-3 migration calls the experimental addon to update package.json and the relevant peer dependencies.

Multi-file migrations

To support migrations that need to edit multiple files, this PR introduces sv.files in addition to sv.file:

sv.files(
	{
		// glob expression evaluated with fs.globSync by sv
		include: '**/*.svelte',

		// early string-based content filter to avoid running expensive edit functions for unrelated files
		where: (content) => content.includes('$env/')
	},
	transforms.svelteScript({ language }, ({ ast }) => {
		return changeImports(ast.instance.content);
	})
);

Migrating

# basics (will prompt everything that is not explicitely provided)
pnpx sv migrate sveltekit-3

# with path
pnpx sv migrate sveltekit-3 --cwd ../your-work-dir 

# only required tasks (like package.json)
pnpx sv migrate sveltekit-3 --tasks required

# only required and selected optional task
pnpx sv migrate sveltekit-3 --tasks env-vars

# no prompt workflow
pnpx sv migrate sveltekit-3 --cwd ../your-work-dir --tasks all --confirm --install pnpm

Pending work

• Decide whether we want additional verification steps before running migrations
  • lint check We decided against this for now
  • svelte-check We decided against this for now
• Add docs and readmes
  • sv.files
  • sv migrate
• Implement the env-vars migration
• Fix and bump esrap
  • It currently generates a lot of new lines where the previous content did not have them.
  • This may be difficult and could potentially require a major bump for esrap.
  • This is not possible in esrap as it takes the ast as an argument and is unaware of the input. Therefore implemented based on a text diff library that does the job pretty good preserveOriginalNewlines
• Add tests for migrations
  • This should be fairly straightforward once a few migration testing helpers are in place.
• Add more command-line arguments
  • Currently not all prompts can be skipped through CLI arguments.
• allow users to pass a glob expression / directory / file and only migrate this one
• migration for $app/environment to $app/env
• check migration for app-state (legacy) and see if we can use that one or if we should rewrite it Should be fine, migration was published over 1.5 years ago
• expose an api for migrations, so that we can use it from the playground, vs code extension and whatever will be implemented at a later point

Checklist

• Update snapshots (if applicable)
• Add a changeset (if applicable)
• Allow maintainers to edit this PR
• I care about what I'm doing, no matter the tool I use (Notepad, Sublime, VSCode, AI...)

[changeset-bot]

🦋 Changeset detected

Latest commit: 85c1e75

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 3 packages

Name	Type
sv	Minor
@sveltejs/sv-utils	Patch
svelte-migrate	Major

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

[svelte-docs-bot]

Preview: https://svelte-dev-git-preview-cli-1138-svelte.vercel.app/