npm - tw-migrate - Versions diffs - 0.6.0 → 0.7.1 - Mend

tw-migrate 0.6.0 → 0.7.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (4) hide show

package/README.md CHANGED Viewed

@@ -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 CHANGED Viewed

@@ -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.1",
 	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 CHANGED Viewed

@@ -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",
@@ -282,6 +284,16 @@ async function rejectSymlinkTarget(path, root) {
 		if (current === root) break;
 	}
 }
+async function* readInBatches(paths) {
+	for (let offset = 0; offset < paths.length; offset += 32) {
+		const batch = paths.slice(offset, offset + 32);
+		const reads = await Promise.allSettled(batch.map((path) => readFile(path, "utf8")));
+		for (const [index, path] of batch.entries()) yield {
+			path,
+			read: reads[index]
+		};
+	}
+}
 async function snapshotFile(snapshots, path) {
 	return recordSnapshot(snapshots, path, await readFile(path, "utf8"));
 }
@@ -723,18 +735,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 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 hasTailwindImport(source) {
-	return cssDirectives(source)?.some((directive) => directive.kind === "import" && directive.specifier !== null && emitsUtilities(directive.specifier)) ?? false;
+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 +890,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 +1334,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 +1621,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 +1650,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 +1668,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 +1760,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 +2613,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();
@@ -2815,16 +2824,15 @@ async function preparePackageVue({ packageRoot, styleCompilers, sourceFiles, sty
 //#endregion
 //#region src/util/write.ts
 async function verifySnapshots(snapshots) {
-	const entries = [...snapshots].sort(([left], [right]) => left.localeCompare(right));
-	const reads = await Promise.allSettled(entries.map(([path]) => readFile(path, "utf8")));
-	for (const [index, [path, before]] of entries.entries()) {
-		const read = reads[index];
+	const expected = new Map(snapshots);
+	const paths = [...expected.keys()].sort((left, right) => left.localeCompare(right));
+	for await (const { path, read } of readInBatches(paths)) {
 		if (read.status === "rejected") {
 			const error = read.reason;
 			const detail = errorCode(error) ?? errorMessage(error);
 			throw new Error(`Source changed after planning: ${path} (${detail})`);
 		}
-		if (read.value !== before) throw new Error(`Source changed after planning: ${path}`);
+		if (read.value !== expected.get(path)) throw new Error(`Source changed after planning: ${path}`);
 	}
 }
 async function writeChanges(changes, deletions) {
@@ -2888,7 +2896,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);
@@ -2899,28 +2920,30 @@ async function migrate(options = {}) {
 		throw new Error(`Found leftover tw-migrate files from an interrupted run:\n${listed}\nRestore each ".<name>.tw-migrate-backup-*" file by renaming it back to "<name>", delete any remaining ".<name>.tw-migrate-*" staging files, then re-run.`);
 	}
 	const snapshots = /* @__PURE__ */ new Map();
-	const stylePaths = scope.scannedPaths.filter(isStylesheetPath);
-	const sourcePaths = scope.scannedPaths.filter((path) => SOURCE_EXTENSIONS.has(extname(path)));
-	const [styleSources, sourceCandidates] = await Promise.all([
-		Promise.all(stylePaths.map(async (path) => [path, await snapshotFile(snapshots, path)])).then((entries) => new Map(entries)),
-		Promise.all(sourcePaths.map(async (path) => {
-			const source = await readFile(path, "utf8");
-			const mayReferenceModule = extname(path) !== ".html" || (() => {
-				try {
-					return parseHtmlSource(path, source).links.length > 0;
-				} catch {
-					return /<link\b/i.test(source);
-				}
-			})();
-			if (!scope.targetable.has(path) && !mayReferenceModule) return void 0;
-			return {
-				path,
-				source: recordSnapshot(snapshots, path, source)
-			};
-		})),
-		...selectedPackages.map((packageRoot) => snapshotFile(snapshots, join(packageRoot, "package.json")))
-	]);
-	const sourceFiles = sourceCandidates.flatMap((file) => file ? [file] : []);
+	const styleSources = /* @__PURE__ */ new Map();
+	const sourceFiles = [];
+	const inputPaths = [...scope.scannedPaths.filter((path) => isStylesheetPath(path) || SOURCE_EXTENSIONS.has(extname(path))), ...selectedPackages.map((packageRoot) => join(packageRoot, "package.json"))];
+	for await (const { path, read } of readInBatches(inputPaths)) {
+		if (read.status === "rejected") throw read.reason;
+		const source = read.value;
+		if (!SOURCE_EXTENSIONS.has(extname(path))) {
+			recordSnapshot(snapshots, path, source);
+			if (isStylesheetPath(path)) styleSources.set(path, source);
+			continue;
+		}
+		const mayReferenceModule = extname(path) !== ".html" || (() => {
+			try {
+				return parseHtmlSource(path, source).links.length > 0;
+			} catch {
+				return /<link\b/i.test(source);
+			}
+		})();
+		if (!scope.targetable.has(path) && !mayReferenceModule) continue;
+		sourceFiles.push({
+			path,
+			source: recordSnapshot(snapshots, path, source)
+		});
+	}
 	if (explicitStyle && isStylesheetPath(explicitStyle) && !styleSources.has(explicitStyle)) styleSources.set(explicitStyle, await snapshotFile(snapshots, explicitStyle));
 	if (configuredEntry && !styleSources.has(configuredEntry)) styleSources.set(configuredEntry, await snapshotFile(snapshots, configuredEntry));
 	const vueStyleRanges = /* @__PURE__ */ new Map();
@@ -3104,10 +3127,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 CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "tw-migrate",
-  "version": "0.6.0",
+  "version": "0.7.1",
   "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.1",
+    "tw-migrate-darwin-x64": "0.7.1",
+    "tw-migrate-linux-arm64-gnu": "0.7.1",
+    "tw-migrate-linux-x64-gnu": "0.7.1",
+    "tw-migrate-win32-x64-msvc": "0.7.1"
   },
   "napi": {
     "binaryName": "tw-migrate",
@@ -81,5 +85,5 @@
   "engines": {
     "node": ">=22.23.2"
   },
-  "packageManager": "pnpm@11.20.0"
+  "packageManager": "pnpm@11.24.0"
 }