tw-migrate 0.1.0 → 0.3.0

package/README.md

@@ -1,22 +1,22 @@
 # tw-migrate
 
-Preview and migrate static React/Next.js stylesheet references to Tailwind v4 utilities.
+Migrate static React/Next.js, Vue 3 SFC, and HTML stylesheet references to Tailwind v4 utilities.
 
 ## Usage
 
 Run it in the package you want to migrate — no install step:
 
 ```bash
-npx tw-migrate                                    # Preview the current package
-npx tw-migrate --write                            # Migrate the current package
-npx tw-migrate path/to/Button.module.scss         # Preview one stylesheet
-npx tw-migrate path/to/Button.module.scss --write # Migrate one stylesheet
-npx tw-migrate --workspaces --write               # Migrate every package
+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 previews changes by default. 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.
+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.
 
 ## Run from a clone
 
@@ -25,14 +25,14 @@ The migration planner is a native addon, so a clone needs one build before the C
 ```bash
 vp install                    # or: pnpm install
 vp run build:debug            # compiles the addon for your platform
-node bin/tw-migrate.js --help
+node src/bin.ts --help
 ```
 
-Then use `node bin/tw-migrate.js` 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:
+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:
 
 ```bash
 cd ../some-app
-node /path/to/tw-migrate/bin/tw-migrate.js --write
+node /path/to/tw-migrate/src/bin.ts
 ```
 
 ## Current support
@@ -41,6 +41,10 @@ node /path/to/tw-migrate/bin/tw-migrate.js --write
 - 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
 - multi-compound CSS Module selectors whose element relationships are proven from the JSX graph
@@ -60,23 +64,29 @@ Everything outside this subset is retained and reported with one of the warning
 | `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 conflict on the same JSX 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 is dynamic, so the element 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.                                         |
 | `inferred-preprocessor-source`       | A linked CSS file was matched to a uniquely named preprocessor source file.                                            |
 | `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-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.                                                         |
@@ -91,9 +101,11 @@ Everything outside this subset is retained and reported with one of the warning
 | `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.
 

package/dist/bin.d.ts

@@ -0,0 +1 @@
+export {}

package/dist/bin.js

@@ -0,0 +1,146 @@
+#!/usr/bin/env node
+import { styleText } from "node:util";
+//#endregion
+//#region src/bin.ts
+const { version } = {
+	name: "tw-migrate",
+	version: "0.3.0",
+	description: "Preview and migrate React, Vue, and HTML CSS to Tailwind utilities",
+	keywords: [
+		"codemod",
+		"css",
+		"css-modules",
+		"migration",
+		"napi-rs",
+		"react",
+		"tailwind",
+		"tailwindcss",
+		"vue"
+	],
+	homepage: "https://github.com/jong-kyung/tw-migrate#readme",
+	bugs: { "url": "https://github.com/jong-kyung/tw-migrate/issues" },
+	license: "MIT",
+	author: "JongKyung Lee",
+	repository: {
+		"type": "git",
+		"url": "git+https://github.com/jong-kyung/tw-migrate.git"
+	},
+	bin: { "tw-migrate": "dist/bin.js" },
+	files: ["dist"],
+	type: "module",
+	main: "dist/index.js",
+	types: "dist/index.d.ts",
+	scripts: {
+		"build": "vp pack && napi build --manifest-path crates/tw_migrate/Cargo.toml --package-json-path package.json --output-dir . --platform --release --no-js --dts binding.d.ts",
+		"build:debug": "napi build --manifest-path crates/tw_migrate/Cargo.toml --package-json-path package.json --output-dir . --platform --no-js --dts binding.d.ts",
+		"artifacts": "napi artifacts --output-dir . --npm-dir npm",
+		"test": "cargo test && pnpm build:debug && vp test",
+		"test:ecosystem": "node ecosystem-ci/run.ts",
+		"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": "7.3.0" },
+	devDependencies: {
+		"@napi-rs/cli": "catalog:",
+		"@types/node": "catalog:",
+		"@vitest/browser-playwright": "catalog:",
+		"less": "catalog:",
+		"playwright": "catalog:",
+		"sass": "catalog:",
+		"tailwindcss": "catalog:",
+		"typescript": "catalog:",
+		"verdaccio": "catalog:",
+		"vite": "catalog:",
+		"vite-plus": "catalog:",
+		"vitest": "catalog:",
+		"vue": "catalog:"
+	},
+	optionalDependencies: {
+		"tw-migrate-darwin-arm64": "workspace:*",
+		"tw-migrate-darwin-x64": "workspace:*",
+		"tw-migrate-linux-arm64-gnu": "workspace:*",
+		"tw-migrate-linux-x64-gnu": "workspace:*",
+		"tw-migrate-win32-x64-msvc": "workspace:*"
+	},
+	napi: {
+		"binaryName": "tw-migrate",
+		"targets": [
+			"aarch64-apple-darwin",
+			"x86_64-apple-darwin",
+			"aarch64-unknown-linux-gnu",
+			"x86_64-unknown-linux-gnu",
+			"x86_64-pc-windows-msvc"
+		]
+	},
+	engines: { "node": ">=22.18.0" },
+	packageManager: "pnpm@11.15.1"
+};
+const usage = "Usage: tw-migrate [style-file] [options]";
+const help = `${usage}
+
+Arguments:
+  [style-file]               Migrate one stylesheet instead of the current package.
+                             Cannot be used with --workspaces.
+
+Options:
+  --tailwind-css <entry.css> Use this Tailwind CSS entry when the current package
+                             has multiple entries. Cannot be used with --workspaces.
+  --workspaces               Migrate every package in the workspace.
+  --force                    Skip packages with recoverable discovery or input errors.
+  --dry-run                  Preview changes without applying them.
+  -h, --help                 Show this help message.
+  -v, --version              Show the version number.
+
+Examples:
+  tw-migrate
+  tw-migrate --dry-run
+  tw-migrate path/to/Button.module.scss
+  tw-migrate --workspaces`;
+async function main() {
+	const args = process.argv.slice(2);
+	if (args.includes("--help") || args.includes("-h")) {
+		console.log(help);
+		return;
+	}
+	if (args.includes("--version") || args.includes("-v")) {
+		console.log(`tw-migrate ${version}`);
+		return;
+	}
+	let styleFile;
+	let tailwindCss;
+	let write = true;
+	let force = false;
+	let workspaces = false;
+	for (let index = 0; index < args.length; index += 1) {
+		const argument = args[index];
+		if (argument === "--dry-run") write = false;
+		else if (argument === "--force") force = true;
+		else if (argument === "--workspaces") workspaces = true;
+		else if (argument === "--tailwind-css") {
+			tailwindCss = args[++index];
+			if (!tailwindCss) throw new Error(`${usage}\n--tailwind-css requires a path.`);
+		} else if (argument.startsWith("-")) throw new Error(`Unknown option: ${argument}`);
+		else if (!styleFile) styleFile = argument;
+		else throw new Error(`Unexpected argument: ${argument}`);
+	}
+	const { migrate } = await import("./index.js");
+	const report = await migrate({
+		styleFile,
+		tailwindCss,
+		write,
+		force,
+		workspaces
+	});
+	if (report.diff) process.stdout.write(report.diff);
+	for (const warning of report.warnings) console.warn(styleText("yellow", `warning[${warning.code}] ${warning.file}:${warning.start}-${warning.end} ${warning.message}`, { stream: process.stderr }));
+	for (const failure of report.failures) console.warn(styleText("yellow", `skipped[${failure.package}] ${failure.message}`, { stream: process.stderr }));
+	console.log(`${write ? "Applied" : "Previewed"} ${report.changedFiles.length} file(s); ${report.convertedRules} rule(s) converted, ${report.retainedRules} retained.`);
+}
+main().catch((error) => {
+	console.error(styleText("red", `tw-migrate: ${error.message}`, { stream: process.stderr }));
+	process.exitCode = 1;
+});
+//#endregion
+export {};

package/{index.d.ts → dist/index.d.ts}

@@ -1,4 +1,5 @@
-export interface MigrateOptions {
+//#region src/types.d.ts
+interface MigrateOptions {
   styleFile?: string;
   cwd?: string;
   write?: boolean;
@@ -6,8 +7,7 @@ export interface MigrateOptions {
   workspaces?: boolean;
   force?: boolean;
 }
-
-export interface MigrationWarning {
+interface MigrationWarning {
   code: string;
   file: string;
   /** Byte offsets into the authored file, or (0, 0) when no unique mapping exists. */
@@ -15,24 +15,21 @@ export interface MigrationWarning {
   end: number;
   message: string;
 }
-
-export interface RuleReport {
+interface RuleReport {
   selector: string;
-  status: 'converted' | 'retained';
+  status: "converted" | "retained";
   candidates: string[];
   file: string;
   /** Rule span in the analysis source (compiled CSS for preprocessor stylesheets). */
-  ruleId: { start: number; end: number };
+  ruleId: RuleSpan;
   /** Rule span in the authored file, or (0, 0) when no unique mapping exists. */
-  authoredSpan: { start: number; end: number };
+  authoredSpan: RuleSpan;
 }
-
-export interface MigrationFailure {
+interface MigrationFailure {
   package: string;
   message: string;
 }
-
-export interface MigrationReport {
+interface MigrationReport {
   changedFiles: string[];
   diff: string;
   convertedRules: number;
@@ -42,5 +39,12 @@ export interface MigrationReport {
   warnings: MigrationWarning[];
   failures: MigrationFailure[];
 }
-
-export function migrate(options?: MigrateOptions): Promise<MigrationReport>;
+interface RuleSpan {
+  start: number;
+  end: number;
+}
+//#endregion
+//#region src/index.d.ts
+declare function migrate(options?: MigrateOptions): Promise<MigrationReport>;
+//#endregion
+export { type MigrateOptions, type MigrationFailure, type MigrationReport, type MigrationWarning, type RuleReport, migrate };