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: 6a25a2f

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/

[pkg-svelte-dev]

Install the latest version of sv from 6a25a2f:

pnpm add https://pkg.svelte.dev/sv/c/6a25a2f6bf76e33cff72b7fd42c548aa77dea6a3

Open in pkg.svelte.dev: https://pkg.svelte.dev/repos/cli/pr/1138

[sacrosanctic]

Suggested change

	* Note: always adds excludes for `node_modules` and dot-prefixed directories
	* Note: `node_modules` and dot-prefixed directories are always excluded.

Should this also mention build and dist? Maybe link to the source for the curious? Should there be an option to override this?

[manuel3108]

Mhmm yeah, maybe it should. On the other hand it wouldn't cause any problems, because your next build is just going to override it. But in node_modules it could cause problems as this is sometimes treated as the source.

[sacrosanctic]

Suggested change

	const cmd = resolveCommand(options.packageManager, 'execute-local', [
	'prettier',
	'--write',
	'--ignore-unknown',
	...options.filesToFormat
	])!;
	await run(cmd.command, cmd.args, options.cwd, 'Formatting modified files');
	if (options.strategy === 'files-only') {
	const cmd = resolveCommand(options.packageManager, 'execute-local', [
	'prettier',
	'--write',
	'--ignore-unknown',
	...options.filesToFormat
	])!;
	await run(cmd.command, cmd.args, options.cwd, 'Formatting modified files');
	return;
	}
	void options.strategy satisfies never;

The second if is not an early return, we can make each enum explicit. And future enums will have less git diffs.

[manuel3108]

Typescript is not happy with that one

[sacrosanctic]

whoops, I missed that the previous check has a fall through logic. Ignore this.

[sacrosanctic]

I meant sv migrate vs svelte-migrate? How does a user decide when to use which?

[sacrosanctic]

Suggested change

	for (const dependency of dependencies) {
	if (dependency.dev && !data.devDependencies) data.devDependencies = {};
	if (!dependency.dev && !data.dependencies) data.dependencies = {};
	const dependencies = dependency.dev ? data.devDependencies! : data.dependencies!;
	if (!dependencies[dependency.pkg] || dependencies[dependency.pkg] !== dependency.version) {
	modified = true;
	dependencies[dependency.pkg] = dependency.version;
	}
	}
	for (const { dev, pkg, version } of dependencies) {
	const dependency = dev ? 'devDependencies' : 'dependencies';
	data[dependency] ??= {};
	if (data[dependency][pkg] !== version) {
	modified = true;
	data[dependency][pkg] = version;
	}
	}