tw-migrate 0.6.0 → 0.7.0

package/README.md

@@ -1,144 +1,26 @@
 # tw-migrate
 
-Migrate static React/Next.js, Vue 3 SFC, and HTML stylesheet references to Tailwind v4 utilities.
+Migrate static React/Next.js, Vue 3 SFC, and HTML stylesheet usage to Tailwind CSS v4 utilities. Supports CSS, SCSS, Sass, Less, and CSS Modules.
 
-## Prerequisites
-
-Install and configure Tailwind CSS v4 in the package you want to migrate by following the [official installation guide](https://tailwindcss.com/docs/installation/). The package must have a CSS entry that loads Tailwind CSS, usually with `@import "tailwindcss";`, so `tw-migrate` can validate generated utilities against the project's Tailwind configuration.
+Requires Node.js 22.23.2+ and [Tailwind CSS v4 configured in your project](https://tailwindcss.com/docs/installation/) with a CSS entry such as `@import "tailwindcss";`. For Sass or Less, install the compiler in the project you are migrating.
 
 ## Usage
 
-Run it in the package you want to migrate — no separate `tw-migrate` install step:
-
-```bash
-npx tw-migrate                                      # Migrate the current package
-npx tw-migrate --dry-run                            # Preview the current package
-npx tw-migrate path/to/Button.module.scss           # Migrate one stylesheet
-npx tw-migrate path/to/Button.module.scss --dry-run # Preview one stylesheet
-npx tw-migrate --workspaces                         # Migrate every package
-```
-
-`pnpm dlx tw-migrate` and `yarn dlx tw-migrate` take the same arguments.
-
-The CLI applies changes by default; `--dry-run` prints the diff without touching files. Pass `--tailwind-css path/to/globals.css` when the current package has multiple Tailwind entries. `--force` skips package groups that fail discovery or input parsing; plan-integrity and write failures always stop the run.
-
-Unmatched media conditions are extracted into named `@custom-variant` definitions in the Tailwind entry and consumers receive stacked variants such as `screen:width-lte-700px:m-0`; verified built-ins and existing breakpoints are reused instead of redefined, and a second run recognizes the first run's definitions. Pass `--no-extract-media-queries` to keep the arbitrary-variant form instead.
-
-## Run from a clone
-
-The migration planner is a native addon, so a clone needs one build before the CLI runs:
-
-```bash
-vp install                    # or: pnpm install
-vp run build:debug            # compiles the addon for your platform
-node src/bin.ts --help
-```
-
-Then use `node src/bin.ts` wherever the commands above use `npx tw-migrate`. The CLI always migrates the package it is run from, so to migrate a different project, run the built entrypoint by absolute path from that project's directory:
+Run from the package you want to migrate:
 
 ```bash
-cd ../some-app
-node /path/to/tw-migrate/src/bin.ts
+npx tw-migrate --dry-run                  # Preview changes
+npx tw-migrate                            # Apply changes
+npx tw-migrate path/to/Button.module.scss # Migrate one stylesheet
+npx tw-migrate --workspaces               # Migrate all packages
+npx tw-migrate --help                     # See all options
 ```
 
-## Current support
-
-- `.css`, `.scss`, `.sass`, and `.less` stylesheets
-- SCSS/Sass/Less values evaluated with the target project's installed compiler; ambiguous mixin and partial origins are retained
-- `.js`, `.jsx`, `.ts`, and `.tsx` source files
-- static `.html` literal `class`/`id` attributes scoped by local external stylesheet links (link-level `print` media supported; other link media conditions are retained)
-- Vue 3 `.vue` files: literal template `class`/`id` attributes and static string/template `:class` bindings matched against inline CSS, SCSS, Sass, and Less `<style scoped>` blocks plus statically imported stylesheets, parsed and compiled with the target project's dependencies
-- direct `<script setup>` component imports can prove child-root and caller class surfaces across SFCs; unresolved components, exported roots, non-static bindings, and callers outside that graph retain scoped rules
-- unscoped Vue styles migrate only in private single-source packages where their global usage is closed; broader unscoped surfaces retain with warnings
-- Vue `<style module>` blocks migrate against direct `:class="$style.x"` member bindings; any other `$style`/`useCssModule` appearance or a named module retains the block
-- direct CSS Module members, static template literals, and static expression literals
-- global `className` and `id` literals
-- React/Next.js `className` logical (`&&`, `||`, `??`) and conditional (`?:`) expressions: string and direct CSS Module member result leaves migrate without evaluating their conditions, `null`/`undefined`/`false`/empty-string results are warning-free, and unsupported result leaves retain with a warning while supported siblings still migrate
-- multi-compound CSS Module selectors whose element relationships are proven from the JSX graph
-- common state pseudo-classes, global arbitrary descendant variants, and conditional at-rules (`@media`, `@supports`, `@container`, `@starting-style`)
-- `and`-joined media conditions decompose into stacked named variants with definitions extracted into the Tailwind entry; ordering-sensitive conflicts between overlapping conditions are retained unless the original winner is provable
-- in `--workspaces` mode a package without its own Tailwind entry may reuse a proven ancestor entry, packages sharing one entry plan as a single group with one composed entry edit, and cross-package consumers must provably load the shared entry
-- the tier-1 property mapping families with shorthand/longhand normalization
-- exact Tailwind theme tokens and breakpoints with arbitrary-value fallback
-- generated candidates are compiled against the project's Tailwind entry; failures retain the source rule
-- batch migration of every stylesheet in a package, and `--workspaces` runs across packages
-- CSS Module cleanup when every reference is safely migrated
-
-Everything outside this subset is retained and reported with one of the warning codes below.
-
-## Warning codes
-
-| Code                                 | Meaning                                                                                                                                                                             |
-| ------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `aliased-css-module-reference`       | A CSS Module class is aliased to a local binding, so the module is retained.                                                                                                        |
-| `batch-stylesheet-conflict`          | Utilities generated from different stylesheets, or under overlapping media conditions with an unprovable order, conflict on the same element, so the contributing rule is retained. |
-| `candidate-compilation-failure`      | A generated candidate did not compile under the project's Tailwind entry, so its rule is retained.                                                                                  |
-| `component-class-target`             | A child component's root element can carry classes a Vue scoped rule matches, so the rule is retained.                                                                              |
-| `computed-css-module-reference`      | A computed CSS Module access cannot be verified, so the module is retained.                                                                                                         |
-| `cross-package-stylesheet-link`      | A linked stylesheet is owned by another package, so it is not analyzed outside workspace mode.                                                                                      |
-| `css-module-composes`                | The rule uses or is targeted by `composes`, so it is retained.                                                                                                                      |
-| `dynamic-class-name`                 | A `className` value or expression result is dynamic, so that class site cannot be migrated.                                                                                         |
-| `dynamic-html-attribute`             | An HTML attribute is not a safely writable quoted literal, so the element cannot be migrated.                                                                                       |
-| `dynamic-template-class`             | A dynamic class binding makes a Vue template's class set unprovable, so its scoped rules are retained.                                                                              |
-| `existing-tailwind-conflict`         | A generated utility may conflict with a Tailwind class already on the element.                                                                                                      |
-| `font-theme-registration-failed`     | A safe Tailwind font theme token could not be registered, so the rule is retained.                                                                                                  |
-| `font-theme-registration-required`   | The font family requires a Tailwind theme token, but the Tailwind entry cannot be edited, so the rule is retained.                                                                  |
-| `inferred-preprocessor-source`       | A linked CSS file was matched to a uniquely named preprocessor source file.                                                                                                         |
-| `media-query-definition-fallback`    | The Tailwind entry could not be edited safely, so media behavior was preserved with arbitrary variants.                                                                             |
-| `module-utilities-conflict`          | Utilities generated from different module classes on one element overlap, so their rules are retained.                                                                              |
-| `non-classname-css-module-reference` | A CSS Module class is used outside a supported `className`, so the module is retained.                                                                                              |
-| `open-root-fallthrough`              | A parent component can merge classes onto a Vue SFC's single root element, so its scoped rules are retained.                                                                        |
-| `preprocessor-style-block`           | A Vue `<style>` block uses a preprocessor language outside the supported SCSS, Sass, and Less set.                                                                                  |
-| `rebuild-required`                   | A preprocessor entry was migrated; rebuild it to refresh its generated CSS.                                                                                                         |
-| `reference-only-css-module-consumer` | A reference-only (non-writable) source uses the CSS Module, so it is retained.                                                                                                      |
-| `retained-global-rule`               | Global CSS is never deleted automatically.                                                                                                                                          |
-| `shadowed-scoped-rule`               | Other package CSS also targets a class a Vue scoped rule matches, so the rule is retained to preserve the cascade.                                                                  |
-| `shared-preprocessor-source`         | A Sass partial must be analyzed through every consuming entry, so it is retained.                                                                                                   |
-| `unproven-css-module-relationship`   | A compound selector's element relationship could not be proven for every usage.                                                                                                     |
-| `unproven-script-reference`          | An inline script names a CSS Module class, so the module is retained.                                                                                                               |
-| `unproven-shared-entry-flow`         | A consumer flow could not be proven to load the shared Tailwind entry, so the stylesheet is retained.                                                                               |
-| `unproven-source-map`                | A generated rule does not map uniquely to one authored source rule, so it is retained.                                                                                              |
-| `unresolved-selector-target`         | No exclusively supported `className` references were found for the rule.                                                                                                            |
-| `unscoped-style-block`               | An unscoped Vue style does not have a closed private single-source usage surface, so it is retained.                                                                                |
-| `unsupported-animation`              | The animation references keyframes that cannot be converted.                                                                                                                        |
-| `unsupported-at-rule`                | The rule contains or sits inside an at-rule outside the supported set.                                                                                                              |
-| `unsupported-container-query`        | The `@container` condition has no Tailwind variant equivalent.                                                                                                                      |
-| `unsupported-css-module-reference`   | The CSS Module has an import or reference that cannot be migrated safely.                                                                                                           |
-| `unsupported-declaration`            | A declaration is outside the supported property subset.                                                                                                                             |
-| `unsupported-html-base`              | A remote or unrepresentable base URL prevents safe stylesheet link resolution.                                                                                                      |
-| `unsupported-html-stylesheet-link`   | Only local package stylesheet links are analyzed.                                                                                                                                   |
-| `unsupported-important`              | `!important` declarations are not migrated.                                                                                                                                         |
-| `unsupported-link-media`             | A stylesheet link or `@import` media condition cannot be represented safely.                                                                                                        |
-| `unsupported-media-query`            | The `@media` condition has no Tailwind variant equivalent.                                                                                                                          |
-| `unsupported-nested-at-rule`         | A nested conditional at-rule could not be fully converted.                                                                                                                          |
-| `unsupported-overlap`                | Shorthand and longhand declarations overlap in a way that cannot be normalized.                                                                                                     |
-| `unsupported-rule-content`           | The rule contains non-declaration content that cannot be converted.                                                                                                                 |
-| `unsupported-selector`               | The selector is outside the supported subset.                                                                                                                                       |
-| `unsupported-sfc-block`              | A Vue SFC or one of its blocks cannot be analyzed safely, so it is retained.                                                                                                        |
-| `unsupported-starting-style`         | The `@starting-style` condition could not be converted.                                                                                                                             |
-| `unsupported-supports-query`         | The `@supports` condition has no Tailwind variant equivalent.                                                                                                                       |
-| `unsupported-value`                  | A declaration value cannot be represented as a Tailwind utility.                                                                                                                    |
-| `unsupported-vue-version`            | The project's Vue version is not Vue 3, so its SFCs are retained.                                                                                                                   |
-
-See the [core RFC](./rfcs/css-to-tailwind-migration-cli.md) and [preprocessor/HTML RFC](./rfcs/preprocessor-and-html-migration.md) for the complete design and remaining scope.
-
-## Testing the packaged CLI
-
-Run `vp run test:snapshots` to build, pack, install, and test the published CLI shape against the cross-platform snapshot corpus. The command uses the npm registry and performs one shared install per test process. See [`crates/snapshots/README.md`](./crates/snapshots/README.md) for targeted runs and snapshot review commands.
-
-## Testing browser ecosystem compatibility
-
-Build the current-platform package and install Chromium before a focused browser run:
-
-```bash
-vp run build
-vp run artifacts
-vp exec playwright install chromium
-vp run test:ecosystem --case react-vite-css
-```
+`pnpm dlx tw-migrate` and `yarn dlx tw-migrate` accept the same arguments.
 
-Use `--case production-react-vite-css` for the installed CLI production-build smoke, or `--all` for all twelve controlled runtime/stylesheet cells. The default `vp run test` and packaged snapshots remain browser-free.
+**The CLI writes files by default.** Review the preview before applying. Unsupported or ambiguous rules stay in place with [warnings](https://github.com/jong-kyung/tw-migrate/blob/main/docs/warnings.md). Use `--tailwind-css path/to/globals.css` to select an entry when discovery is ambiguous.
 
-Pinned external projects run only in the **Ecosystem browser** GitHub Actions workflow on `main`, manual dispatch, or a pull request carrying the `test:e2e` label. The workflow checks them out under the runner's temporary directory without credentials or secrets; there is intentionally no contributor-facing local external command.
+## More
 
-On failure, each OS/case job uploads only its bounded phase ledger, computed-style captures, screenshots, migration output, source diff, and registry/install/build/server logs. See the [browser ecosystem RFC](./rfcs/browser-ecosystem-e2e.md) for immutable external evidence and the manifest, isolation, and oracle contracts.
+- [Supported behavior and design](https://github.com/jong-kyung/tw-migrate/tree/main/rfcs/)
+- [Contributing and local development](https://github.com/jong-kyung/tw-migrate/blob/main/CONTRIBUTING.md)

package/dist/bin.js

@@ -4,7 +4,7 @@ import { styleText } from "node:util";
 //#region src/bin.ts
 const { version } = {
 	name: "tw-migrate",
-	version: "0.6.0",
+	version: "0.7.0",
 	description: "Preview and migrate React, Vue, and HTML CSS to Tailwind utilities",
 	keywords: [
 		"codemod",
@@ -36,16 +36,22 @@ const { version } = {
 		"artifacts": "node -e \"const fs=require('node:fs'); const files=fs.readdirSync('.').filter((file)=>file.startsWith('tw-migrate.')&&file.endsWith('.node')); if(files.length===0) throw new Error('no tw-migrate.*.node artifact in the package root; run build first'); for(const file of files) fs.copyFileSync(file, 'npm/'+file.slice('tw-migrate.'.length, -'.node'.length)+'/'+file)\"",
 		"test": "cargo test && pnpm build:debug && vp test",
 		"test:ecosystem": "node ecosystem-ci/run.ts",
+		"knip": "knip",
 		"typecheck": "tsc --noEmit",
 		"snapshots:prepare": "node -e \"const fs=require('node:fs'); for(const dir of fs.readdirSync('npm')) for(const file of fs.readdirSync('npm/'+dir)) if(file.endsWith('.node')) fs.rmSync('npm/'+dir+'/'+file)\" && pnpm build && pnpm artifacts",
 		"test:snapshots": "pnpm snapshots:prepare && cargo test -p tw-migrate-snapshots",
 		"prepare": "vp config"
 	},
-	dependencies: { "parse5": "8.0.1" },
+	dependencies: {
+		"diff": "9.0.0",
+		"parse5": "8.0.1",
+		"zod": "4.5.4"
+	},
 	devDependencies: {
 		"@napi-rs/cli": "catalog:",
 		"@types/node": "catalog:",
 		"@vitest/browser-playwright": "catalog:",
+		"knip": "catalog:",
 		"less": "catalog:",
 		"playwright": "catalog:",
 		"sass": "catalog:",
@@ -75,7 +81,7 @@ const { version } = {
 		]
 	},
 	engines: { "node": ">=22.23.2" },
-	packageManager: "pnpm@11.20.0"
+	packageManager: "pnpm@11.24.0"
 };
 const usage = "Usage: tw-migrate [style-file] [options]";
 const help = `${usage}

package/dist/index.js

@@ -2,20 +2,18 @@ import { createRequire } from "node:module";
 import { promisify } from "node:util";
 import { chmod, lstat, readFile, readdir, realpath, rename, rm, stat, writeFile } from "node:fs/promises";
 import { basename, dirname, extname, isAbsolute, join, relative, resolve, sep } from "node:path";
+import * as z from "zod/mini";
+import { FILE_HEADERS_ONLY, createTwoFilesPatch } from "diff";
 import { execFile } from "node:child_process";
 import { fileURLToPath, pathToFileURL } from "node:url";
 import { parse } from "parse5";
 //#region src/util/diff.ts
 function unifiedDiff(path, before, after) {
-	const oldLines = before.split("\n");
-	const newLines = after.split("\n");
-	return [
-		`--- a/${path}\n`,
-		`+++ b/${path}\n`,
-		`@@ -1,${oldLines.length} +1,${newLines.length} @@\n`,
-		...oldLines.map((line, index) => `${index === oldLines.length - 1 && line === "" ? " " : "-"}${line}\n`),
-		...newLines.map((line, index) => `${index === newLines.length - 1 && line === "" ? " " : "+"}${line}\n`)
-	].join("");
+	if (before === after) return "";
+	return createTwoFilesPatch(`a/${path}`, `b/${path}`, before, after, void 0, void 0, {
+		context: 3,
+		headerOptions: FILE_HEADERS_ONLY
+	});
 }
 //#endregion
 //#region src/native.ts
@@ -231,6 +229,10 @@ function sourcePathFromMap(source, sourceBase) {
 }
 //#endregion
 //#region src/util/shared.ts
+const projectPackageSchema = z.looseObject({
+	name: z.optional(z.string()),
+	private: z.optional(z.boolean())
+});
 const SOURCE_EXTENSIONS = /* @__PURE__ */ new Set([
 	".html",
 	".vue",
@@ -723,18 +725,129 @@ function locatedAttribute(source, location, parsedValue) {
 	};
 }
 //#endregion
-//#region src/plan/entry.ts
-function emitsUtilities(specifier) {
-	return specifier === "tailwindcss" || specifier === "tailwindcss/utilities" || specifier === "tailwindcss/utilities.css";
+//#region src/tailwind.ts
+function findTailwindEntries(stylePaths, styleSources) {
+	return stylePaths.filter((path) => extname(path) === ".css" && importEntries(styleSources.get(path) ?? "").some(({ specifier }) => specifier === "tailwindcss" || specifier === "tailwindcss/index" || specifier === "tailwindcss/index.css" || specifier === "tailwindcss/utilities" || specifier === "tailwindcss/utilities.css"));
+}
+const externalStylesheetUrl = z.url({ protocol: /^(https?|data)$/ });
+const tailwindPackageSchema = z.object({ version: z.string() });
+function isExternalStylesheet(specifier) {
+	return specifier.startsWith("//") || /^(?:https?:\/\/|data:)/i.test(specifier) && externalStylesheetUrl.safeParse(specifier).success;
 }
-function hasTailwindImport(source) {
-	return cssDirectives(source)?.some((directive) => directive.kind === "import" && directive.specifier !== null && emitsUtilities(directive.specifier)) ?? false;
+function selectTailwindEntry(entries, configuredPath) {
+	if (configuredPath) return configuredPath;
+	if (entries.length === 0) throw new Error("No Tailwind v4 CSS entry was found. Pass --tailwind-css.");
+	if (entries.length > 1) throw new Error("Multiple Tailwind CSS entries were found. Pass --tailwind-css.");
+	return entries[0];
 }
+async function loadTailwind(packageRoot, tailwindCss, snapshots, workspaceRoot) {
+	const projectRequire = createRequire(join(packageRoot, "package.json"));
+	let packagePath;
+	try {
+		packagePath = projectRequire.resolve("tailwindcss/package.json");
+	} catch {
+		throw new Error("Tailwind v4 must be installed in the target project.");
+	}
+	const packageJson = tailwindPackageSchema.parse(JSON.parse(await readFile(packagePath, "utf8")));
+	if (!packageJson.version.startsWith("4.")) throw new Error(`Tailwind v4 is required; found ${packageJson.version}.`);
+	const { __unstable__loadDesignSystem: loadDesignSystem } = await loadProjectModule(packageRoot, "tailwindcss", "Tailwind v4 must be installed in the target project.");
+	const css = await snapshotFile(snapshots, tailwindCss);
+	const base = dirname(tailwindCss);
+	const tailwindRoot = dirname(packagePath);
+	const loadModule = async (id, moduleBase) => {
+		const path = createRequire(join(moduleBase, "package.json")).resolve(id);
+		if (isProjectInput(workspaceRoot, path)) await snapshotFile(snapshots, path);
+		const imported = await import(pathToFileURL(path).href);
+		return {
+			path,
+			base: dirname(path),
+			module: imported.default ?? imported
+		};
+	};
+	const loadStylesheet = async (id, sheetBase) => {
+		if (isExternalStylesheet(id)) return {
+			content: "",
+			base: sheetBase
+		};
+		let path;
+		if (id === "tailwindcss") path = join(tailwindRoot, "index.css");
+		else if (id.startsWith("tailwindcss/")) {
+			const subpath = id.slice(12);
+			path = join(tailwindRoot, subpath.endsWith(".css") ? subpath : `${subpath}.css`);
+		} else if (id.startsWith(".") || isAbsolute(id)) path = resolve(sheetBase, id);
+		else path = projectRequire.resolve(id);
+		return {
+			content: isProjectInput(workspaceRoot, path) ? await snapshotFile(snapshots, path) : await readFile(path, "utf8"),
+			base: dirname(path)
+		};
+	};
+	const defaultTheme = await readFile(join(dirname(packagePath), "theme.css"), "utf8");
+	const graphSources = [];
+	const referenceTokens = /* @__PURE__ */ new Set();
+	const themeTokens = {
+		...extractThemeTokens("tailwind-default.theme.css", defaultTheme),
+		...await extractThemeTokensFromGraph(tailwindCss, css, base, loadStylesheet, graphSources, referenceTokens)
+	};
+	graphSources.push({
+		path: tailwindCss,
+		source: css
+	});
+	const designSystem = await loadDesignSystem(css, {
+		base,
+		loadModule,
+		loadStylesheet
+	});
+	const loadWith = (replacement) => loadDesignSystem(replacement, {
+		base,
+		loadModule,
+		loadStylesheet
+	});
+	return {
+		designSystem,
+		css,
+		path: tailwindCss,
+		themeTokens,
+		referenceTokens,
+		graphSources,
+		loadWith
+	};
+}
+function extractThemeTokens(key, css) {
+	return stylesheetAnalysis(key, css).themeTokens;
+}
+function importEntries(css) {
+	return (cssDirectives$1(css) ?? []).flatMap((directive) => directive !== null && typeof directive === "object" && "kind" in directive && directive.kind === "import" && "specifier" in directive && typeof directive.specifier === "string" ? [{
+		specifier: directive.specifier,
+		reference: "reference" in directive && directive.reference === true
+	}] : []);
+}
+async function extractThemeTokensFromGraph(identity, css, base, loadStylesheet, graphSources, referenceTokens, inReference = false, seen = /* @__PURE__ */ new Set()) {
+	const tokens = {};
+	for (const { specifier: spec, reference } of importEntries(css)) {
+		if (isExternalStylesheet(spec)) continue;
+		const key = `${base}\0${spec}`;
+		if (seen.has(key)) continue;
+		seen.add(key);
+		const loaded = await loadStylesheet(spec, base);
+		if (spec !== "tailwindcss" && !spec.startsWith("tailwindcss/")) graphSources.push({
+			path: key,
+			source: loaded.content
+		});
+		Object.assign(tokens, await extractThemeTokensFromGraph(key, loaded.content, loaded.base, loadStylesheet, graphSources, referenceTokens, inReference || reference, seen));
+	}
+	const own = extractThemeTokens(`${identity}.theme.css`, css);
+	if (inReference) for (const token of Object.keys(own)) referenceTokens.add(token);
+	return Object.assign(tokens, own);
+}
+function invalidCandidates(system, candidates) {
+	const generated = system.candidatesToCss(candidates);
+	return candidates.filter((_, index) => generated[index] === null);
+}
+//#endregion
+//#region src/plan/entry.ts
 function tailwindEntryCatalog(styleSources, pathOwners) {
 	const catalog = /* @__PURE__ */ new Map();
-	for (const [path, source] of styleSources) {
-		if (extname(path) !== ".css") continue;
-		if (!hasTailwindImport(source)) continue;
+	for (const path of findTailwindEntries([...styleSources.keys()], styleSources)) {
 		const owner = pathOwners.get(path);
 		if (owner === void 0) continue;
 		const entries = catalog.get(owner) ?? [];
@@ -767,7 +880,7 @@ function entryGraphSheets(entry, styleSources) {
 			if (directive.kind !== "import") continue;
 			if (directive.specifier === null) return null;
 			const spec = directive.specifier;
-			if (directive.tailwind) continue;
+			if (directive.tailwind || isExternalStylesheet(spec)) continue;
 			if (!spec.startsWith(".") && !spec.startsWith("/")) {
 				let resolved;
 				try {
@@ -1211,115 +1324,6 @@ function htmlWarning(code, file, start, end, message) {
 	};
 }
 //#endregion
-//#region src/tailwind.ts
-function findTailwindEntries(stylePaths, styleSources) {
-	return stylePaths.filter((path) => extname(path) === ".css" && importEntries(styleSources.get(path) ?? "").some(({ specifier }) => specifier === "tailwindcss" || specifier.startsWith("tailwindcss/")));
-}
-function selectTailwindEntry(entries, configuredPath) {
-	if (configuredPath) return configuredPath;
-	if (entries.length === 0) throw new Error("No Tailwind v4 CSS entry was found. Pass --tailwind-css.");
-	if (entries.length > 1) throw new Error("Multiple Tailwind CSS entries were found. Pass --tailwind-css.");
-	return entries[0];
-}
-async function loadTailwind(packageRoot, tailwindCss, snapshots, workspaceRoot) {
-	const projectRequire = createRequire(join(packageRoot, "package.json"));
-	let packagePath;
-	try {
-		packagePath = projectRequire.resolve("tailwindcss/package.json");
-	} catch {
-		throw new Error("Tailwind v4 must be installed in the target project.");
-	}
-	const packageJson = JSON.parse(await readFile(packagePath, "utf8"));
-	if (!String(packageJson.version).startsWith("4.")) throw new Error(`Tailwind v4 is required; found ${packageJson.version}.`);
-	const { __unstable__loadDesignSystem: loadDesignSystem } = await loadProjectModule(packageRoot, "tailwindcss", "Tailwind v4 must be installed in the target project.");
-	const css = await snapshotFile(snapshots, tailwindCss);
-	const base = dirname(tailwindCss);
-	const tailwindRoot = dirname(packagePath);
-	const loadModule = async (id, moduleBase) => {
-		const path = createRequire(join(moduleBase, "package.json")).resolve(id);
-		if (isProjectInput(workspaceRoot, path)) await snapshotFile(snapshots, path);
-		const imported = await import(pathToFileURL(path).href);
-		return {
-			path,
-			base: dirname(path),
-			module: imported.default ?? imported
-		};
-	};
-	const loadStylesheet = async (id, sheetBase) => {
-		let path;
-		if (id === "tailwindcss") path = join(tailwindRoot, "index.css");
-		else if (id.startsWith("tailwindcss/")) {
-			const subpath = id.slice(12);
-			path = join(tailwindRoot, subpath.endsWith(".css") ? subpath : `${subpath}.css`);
-		} else if (id.startsWith(".") || isAbsolute(id)) path = resolve(sheetBase, id);
-		else path = projectRequire.resolve(id);
-		return {
-			content: isProjectInput(workspaceRoot, path) ? await snapshotFile(snapshots, path) : await readFile(path, "utf8"),
-			base: dirname(path)
-		};
-	};
-	const defaultTheme = await readFile(join(dirname(packagePath), "theme.css"), "utf8");
-	const graphSources = [];
-	const referenceTokens = /* @__PURE__ */ new Set();
-	const themeTokens = {
-		...extractThemeTokens("tailwind-default.theme.css", defaultTheme),
-		...await extractThemeTokensFromGraph(tailwindCss, css, base, loadStylesheet, graphSources, referenceTokens)
-	};
-	graphSources.push({
-		path: tailwindCss,
-		source: css
-	});
-	const designSystem = await loadDesignSystem(css, {
-		base,
-		loadModule,
-		loadStylesheet
-	});
-	const loadWith = (replacement) => loadDesignSystem(replacement, {
-		base,
-		loadModule,
-		loadStylesheet
-	});
-	return {
-		designSystem,
-		css,
-		path: tailwindCss,
-		themeTokens,
-		referenceTokens,
-		graphSources,
-		loadWith
-	};
-}
-function extractThemeTokens(key, css) {
-	return stylesheetAnalysis(key, css).themeTokens;
-}
-function importEntries(css) {
-	return (cssDirectives$1(css) ?? []).flatMap((directive) => directive !== null && typeof directive === "object" && "kind" in directive && directive.kind === "import" && "specifier" in directive && typeof directive.specifier === "string" ? [{
-		specifier: directive.specifier,
-		reference: "reference" in directive && directive.reference === true
-	}] : []);
-}
-async function extractThemeTokensFromGraph(identity, css, base, loadStylesheet, graphSources, referenceTokens, inReference = false, seen = /* @__PURE__ */ new Set()) {
-	const tokens = {};
-	for (const { specifier: spec, reference } of importEntries(css)) {
-		const key = `${base}\0${spec}`;
-		if (seen.has(key)) continue;
-		seen.add(key);
-		const loaded = await loadStylesheet(spec, base);
-		if (spec !== "tailwindcss" && !spec.startsWith("tailwindcss/")) graphSources.push({
-			path: key,
-			source: loaded.content
-		});
-		Object.assign(tokens, await extractThemeTokensFromGraph(key, loaded.content, loaded.base, loadStylesheet, graphSources, referenceTokens, inReference || reference, seen));
-	}
-	const own = extractThemeTokens(`${identity}.theme.css`, css);
-	if (inReference) for (const token of Object.keys(own)) referenceTokens.add(token);
-	return Object.assign(tokens, own);
-}
-function invalidCandidates(system, candidates) {
-	const generated = system.candidatesToCss(candidates);
-	return candidates.filter((_, index) => generated[index] === null);
-}
-//#endregion
 //#region src/plan/canonicalize.ts
 const caches = /* @__PURE__ */ new WeakMap();
 function canonicalCandidate(system, candidate) {
@@ -1607,7 +1611,10 @@ function matchingFontTokens(stacks, normalizedStack) {
 //#region src/plan/media.ts
 const GENERATED_NAMESPACE = "twm-media";
 /**
-* Resolve one fixed name per key across a complete entry group.
+* Resolve one fixed name per key across a complete entry group: key to
+* resolved name, in sorted key order. Only `generated` entries emit a
+* definition; a key absent from the map could not escape existing owners
+* and keeps the arbitrary-variant fallback.
 *
 * Resolution follows the RFC order: a built-in candidate with a verified
 * effective expansion, an existing breakpoint matched by exact value and
@@ -1633,7 +1640,6 @@ function resolveMediaNames(collections, themeTokens, probes, reservedNames = [])
 	};
 	const taken = (name) => claimed.has(name) || reserved.has(name) || authoredKeysByName.has(name) || probes.resolves(name);
 	const names = /* @__PURE__ */ new Map();
-	const fallbacks = /* @__PURE__ */ new Set();
 	for (const component of components) {
 		const resolved = (name, kind) => {
 			claimed.add(name);
@@ -1652,25 +1658,18 @@ function resolveMediaNames(collections, themeTokens, probes, reservedNames = [])
 		}
 		const digestName = `${GENERATED_NAMESPACE}-${component.digest}`;
 		const candidates = component.readableName === null ? [digestName] : [component.readableName, digestName];
-		let done = false;
 		for (const candidate of candidates) {
 			if (adoptableKey(candidate) === component.key && !claimed.has(candidate) && probes.expansionMatches(candidate, component.key)) {
 				resolved(candidate, "adopted");
-				done = true;
 				break;
 			}
 			if (!taken(candidate)) {
 				resolved(candidate, "generated");
-				done = true;
 				break;
 			}
 		}
-		if (!done) fallbacks.add(component.key);
 	}
-	return {
-		names,
-		fallbacks
-	};
+	return names;
 }
 function mergeComponents(collections) {
 	const byKey = /* @__PURE__ */ new Map();
@@ -1751,7 +1750,7 @@ function planMediaExtraction(options) {
 	const resolution = resolveMediaNames(options.collections, options.tailwind.themeTokens, buildMediaProbes(options.tailwind), scannedVariantReservations([...options.scannedSources, ...options.tailwind.graphSources.map((graphSource) => graphSource.source)]));
 	const names = {};
 	const generated = [];
-	for (const [key, resolved] of resolution.names) {
+	for (const [key, resolved] of resolution) {
 		names[key] = resolved.name;
 		if (resolved.kind === "generated") generated.push({
 			key,
@@ -2604,7 +2603,7 @@ async function preparePackageVue({ packageRoot, styleCompilers, sourceFiles, sty
 		})));
 		vueShadowModuleCss.push(...analysis.shadowModuleCssTexts, ...analysis.moduleBlocks.map((block) => block.analysisSource ?? block.content));
 	}
-	const packageIsPrivate = JSON.parse(await snapshotFile(snapshots, join(packageRoot, "package.json"))).private === true;
+	const packageIsPrivate = projectPackageSchema.parse(JSON.parse(await snapshotFile(snapshots, join(packageRoot, "package.json")))).private === true;
 	const files = /* @__PURE__ */ new Map();
 	const stylesheets = [];
 	const stylePaths = /* @__PURE__ */ new Set();
@@ -2888,7 +2887,20 @@ function indexWarningPositions(source, offsets, unicodeSeparatorsAreNewlines, fo
 	}
 	return positions;
 }
+const optionPath = z.string().check(z.minLength(1), z.refine((path) => !path.includes("\0")));
+const migrateOptionsSchema = z.strictObject({
+	styleFile: z.optional(optionPath),
+	cwd: z.optional(optionPath),
+	write: z.optional(z.boolean()),
+	tailwindCss: z.optional(optionPath),
+	workspaces: z.optional(z.boolean()),
+	force: z.optional(z.boolean()),
+	extractMediaQueries: z.optional(z.boolean())
+});
 async function migrate(options = {}) {
+	const parsedOptions = migrateOptionsSchema.safeParse(options);
+	if (!parsedOptions.success) throw new TypeError(`Invalid migrate options: ${parsedOptions.error.message}`);
+	options = parsedOptions.data;
 	if (options.styleFile && options.workspaces) throw new TypeError("styleFile cannot be combined with workspaces");
 	if (options.tailwindCss && options.workspaces) throw new TypeError("tailwindCss cannot be combined with workspaces");
 	const scope = await resolveScope(options);
@@ -3104,10 +3116,7 @@ async function preparePackage(context, packageRoot) {
 		let packageJson = {};
 		try {
 			const rawPackageJson = snapshots.get(join(packageRoot, "package.json"));
-			if (rawPackageJson !== void 0) {
-				const parsed = JSON.parse(rawPackageJson);
-				if (parsed !== null && typeof parsed === "object" && !Array.isArray(parsed)) packageJson = { ...parsed };
-			}
+			if (rawPackageJson !== void 0) packageJson = projectPackageSchema.parse(JSON.parse(rawPackageJson));
 		} catch (error) {
 			return recover(error);
 		}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tw-migrate",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "Preview and migrate React, Vue, and HTML CSS to Tailwind utilities",
   "keywords": [
     "codemod",
@@ -38,18 +38,22 @@
     "artifacts": "node -e \"const fs=require('node:fs'); const files=fs.readdirSync('.').filter((file)=>file.startsWith('tw-migrate.')&&file.endsWith('.node')); if(files.length===0) throw new Error('no tw-migrate.*.node artifact in the package root; run build first'); for(const file of files) fs.copyFileSync(file, 'npm/'+file.slice('tw-migrate.'.length, -'.node'.length)+'/'+file)\"",
     "test": "cargo test && pnpm build:debug && vp test",
     "test:ecosystem": "node ecosystem-ci/run.ts",
+    "knip": "knip",
     "typecheck": "tsc --noEmit",
     "snapshots:prepare": "node -e \"const fs=require('node:fs'); for(const dir of fs.readdirSync('npm')) for(const file of fs.readdirSync('npm/'+dir)) if(file.endsWith('.node')) fs.rmSync('npm/'+dir+'/'+file)\" && pnpm build && pnpm artifacts",
     "test:snapshots": "pnpm snapshots:prepare && cargo test -p tw-migrate-snapshots",
     "prepare": "vp config"
   },
   "dependencies": {
-    "parse5": "8.0.1"
+    "diff": "9.0.0",
+    "parse5": "8.0.1",
+    "zod": "4.5.4"
   },
   "devDependencies": {
     "@napi-rs/cli": "catalog:",
     "@types/node": "catalog:",
     "@vitest/browser-playwright": "catalog:",
+    "knip": "catalog:",
     "less": "catalog:",
     "playwright": "catalog:",
     "sass": "catalog:",
@@ -62,11 +66,11 @@
     "vue": "catalog:"
   },
   "optionalDependencies": {
-    "tw-migrate-darwin-arm64": "0.6.0",
-    "tw-migrate-darwin-x64": "0.6.0",
-    "tw-migrate-linux-arm64-gnu": "0.6.0",
-    "tw-migrate-linux-x64-gnu": "0.6.0",
-    "tw-migrate-win32-x64-msvc": "0.6.0"
+    "tw-migrate-darwin-arm64": "0.7.0",
+    "tw-migrate-darwin-x64": "0.7.0",
+    "tw-migrate-linux-arm64-gnu": "0.7.0",
+    "tw-migrate-linux-x64-gnu": "0.7.0",
+    "tw-migrate-win32-x64-msvc": "0.7.0"
   },
   "napi": {
     "binaryName": "tw-migrate",
@@ -81,5 +85,5 @@
   "engines": {
     "node": ">=22.23.2"
   },
-  "packageManager": "pnpm@11.20.0"
+  "packageManager": "pnpm@11.24.0"
 }