tw-migrate 0.2.0 → 0.4.0

package/README.md

@@ -1,22 +1,22 @@
 # tw-migrate
 
-Preview and 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 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
@@ -47,6 +47,7 @@ node /path/to/tw-migrate/bin/tw-migrate.js --write
 - 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`)
 - the tier-1 property mapping families with shorthand/longhand normalization
@@ -68,7 +69,7 @@ Everything outside this subset is retained and reported with one of the warning
 | `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-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.                                         |

package/dist/bin.d.ts

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

package/dist/bin.js

@@ -0,0 +1,149 @@
+#!/usr/bin/env node
+import { styleText } from "node:util";
+//#endregion
+//#region src/bin.ts
+const { version } = {
+	name: "tw-migrate",
+	version: "0.4.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": "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",
+		"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" },
+	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.23.2" },
+	packageManager: "pnpm@11.20.0"
+};
+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) {
+		const location = warning.line ? `${warning.file}:${warning.line}:${warning.column}-${warning.endLine}:${warning.endColumn}` : warning.file;
+		console.warn(styleText("yellow", `warning[${warning.code}] ${location} ${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,33 +7,34 @@ 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. */
   start: number;
   end: number;
+  /** 1-based UTF-16 positions, omitted when no unique authored mapping exists. */
+  line?: number;
+  column?: number;
+  endLine?: number;
+  endColumn?: number;
   message: string;
 }
-
-export interface RuleReport {
+interface RuleReport {
   selector: string;
   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 +44,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 };