tw-migrate 0.1.0-alpha.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 JongKyung Lee 
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,121 @@
+# tw-migrate
+
+Preview and migrate static React/Next.js 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
+```
+
+`pnpm dlx tw-migrate` and `yarn dlx tw-migrate` take the same arguments.
+
+> **Not on npm yet.** Until the first release the commands above will 404 — build it from a clone instead (see [Run from a clone](#run-from-a-clone)).
+
+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.
+
+## 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 bin/tw-migrate.js --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:
+
+```bash
+cd ../some-app
+node /path/to/tw-migrate/bin/tw-migrate.js --write
+```
+
+## 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)
+- 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
+- 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
+- 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 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.                     |
+| `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.                          |
+| `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.                                 |
+| `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.                                                                             |
+| `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.                                               |
+| `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-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.                                                       |
+
+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
+```
+
+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.
+
+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.
+
+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.

package/bin/tw-migrate.js

@@ -0,0 +1,46 @@
+#!/usr/bin/env node
+
+import { migrate } from '../index.js';
+
+const usage = 'Usage: tw-migrate [style-file] [--tailwind-css <entry.css>] [--workspaces] [--force] [--write]';
+
+async function main() {
+  const args = process.argv.slice(2);
+  let styleFile;
+  let tailwindCss;
+  let write = false;
+  let force = false;
+  let workspaces = false;
+
+  for (let index = 0; index < args.length; index += 1) {
+    const argument = args[index];
+    if (argument === '--write') write = true;
+    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 === '--help' || argument === '-h') {
+      console.log(usage);
+      return;
+    } else if (argument.startsWith('-')) {
+      throw new Error(`Unknown option: ${argument}`);
+    } else if (!styleFile) styleFile = argument;
+    else throw new Error(`Unexpected argument: ${argument}`);
+  }
+
+  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(`warning[${warning.code}] ${warning.file}:${warning.start}-${warning.end} ${warning.message}`);
+  }
+  for (const failure of report.failures) {
+    console.warn(`skipped[${failure.package}] ${failure.message}`);
+  }
+  console.log(`${write ? 'Applied' : 'Previewed'} ${report.changedFiles.length} file(s); ${report.convertedRules} rule(s) converted, ${report.retainedRules} retained.`);
+}
+
+main().catch((error) => {
+  console.error(`tw-migrate: ${error.message}`);
+  process.exitCode = 1;
+});

package/html.js

@@ -0,0 +1,153 @@
+import { parse } from 'parse5';
+
+const RECOVERABLE_PARSE_ERRORS = new Set(['missing-doctype']);
+const TEMPLATE_MARKERS = /\{\{|\}\}|\$\{|<%|%>|<#|#>|\[%|%\]/;
+
+export function parseHtmlSource(path, source) {
+  const errors = [];
+  const document = parse(source, {
+    sourceCodeLocationInfo: true,
+    onParseError(error) {
+      if (!RECOVERABLE_PARSE_ERRORS.has(error.code)) errors.push(error);
+    },
+  });
+  if (errors.length > 0) {
+    throw new Error(`Failed to parse ${path}: ${errors.map((error) => error.code).join(', ')}`);
+  }
+
+  const links = [];
+  const bases = [];
+  const elements = [];
+  const dynamicAttributes = [];
+  const scriptTexts = [];
+
+  function visit(node) {
+    if (node.tagName === 'script') {
+      for (const child of node.childNodes ?? []) {
+        if (child.nodeName === '#text' && child.value) scriptTexts.push(child.value);
+      }
+    }
+    if (node.tagName) {
+      const attributes = new Map(node.attrs.map((attribute) => [attribute.name, attribute.value]));
+      const locations = node.sourceCodeLocation?.attrs;
+      if (locations) {
+        if (node.tagName === 'link'
+          && stylesheetRel(attributes.get('rel'))
+          && !attributes.has('disabled')) {
+          const href = locatedAttribute(source, locations.href, attributes.get('href'));
+          const media = locatedAttribute(source, locations.media, attributes.get('media'));
+          const tag = node.sourceCodeLocation?.startTag ?? node.sourceCodeLocation;
+          if (href && tag) {
+            links.push({
+              href: href.value,
+              media: media?.value ?? '',
+              start: href.start,
+              end: href.end,
+              tagStart: tag.startOffset,
+              tagEnd: tag.endOffset,
+            });
+          }
+        }
+        if (node.tagName === 'base' && bases.length === 0) {
+          const href = locatedAttribute(source, locations.href, attributes.get('href'));
+          if (href) bases.push({ href: href.value, writable: href.writable, start: href.start, end: href.end });
+        }
+
+        let classAttribute = locatedAttribute(source, locations.class, attributes.get('class'));
+        const idAttribute = locatedAttribute(source, locations.id, attributes.get('id'));
+        // A class attribute that exists but cannot be located as a writable
+        // value (e.g. valueless `<main class>`) must not look absent, or the
+        // id-only branch would synthesize a duplicate class attribute.
+        const unparsedClass = !classAttribute && idAttribute && locations.class
+          ? { start: locations.class.startOffset, end: locations.class.endOffset }
+          : undefined;
+        const dynamic = unparsedClass
+          ?? [classAttribute, idAttribute].find((attribute) =>
+            attribute && (!attribute.writable || TEMPLATE_MARKERS.test(attribute.value)),
+          ) ?? (classAttribute && !classAttribute.quoted ? classAttribute : undefined);
+        if (dynamic) {
+          dynamicAttributes.push({ start: dynamic.start, end: dynamic.end });
+        } else if (classAttribute || idAttribute) {
+          if (!classAttribute && idAttribute) {
+            const insertion = classInsertionOffset(source, node.sourceCodeLocation?.startTag);
+            if (insertion !== undefined) {
+              classAttribute = { value: '', start: insertion, end: insertion, synthetic: true };
+            }
+          }
+          elements.push({ classAttribute, idAttribute });
+        }
+      }
+    }
+
+    for (const child of node.childNodes ?? []) visit(child);
+    if (node.content) visit(node.content);
+  }
+
+  visit(document);
+  return {
+    ...toByteOffsets(source, { links, bases, elements, dynamicAttributes }),
+    scriptText: scriptTexts.join('\n'),
+  };
+}
+
+function toByteOffsets(source, parsed) {
+  const offset = (index) => Buffer.byteLength(source.slice(0, index));
+  const attribute = (value) => value && { ...value, start: offset(value.start), end: offset(value.end) };
+  return {
+    links: parsed.links.map((link) => ({
+      ...link,
+      start: offset(link.start),
+      end: offset(link.end),
+      tagStart: offset(link.tagStart),
+      tagEnd: offset(link.tagEnd),
+    })),
+    bases: parsed.bases.map((base) => ({ ...base, start: offset(base.start), end: offset(base.end) })),
+    elements: parsed.elements.map((element) => ({
+      classAttribute: attribute(element.classAttribute),
+      idAttribute: attribute(element.idAttribute),
+    })),
+    dynamicAttributes: parsed.dynamicAttributes.map(attribute),
+  };
+}
+
+function classInsertionOffset(source, startTag) {
+  if (!startTag) return undefined;
+  let offset = startTag.endOffset - 1;
+  if (source[offset] !== '>') return undefined;
+  while (offset > startTag.startOffset && /\s/.test(source[offset - 1])) offset -= 1;
+  if (source[offset - 1] === '/') offset -= 1;
+  return offset;
+}
+
+function stylesheetRel(value = '') {
+  const tokens = value.toLowerCase().split(/\s+/);
+  return tokens.includes('stylesheet') && !tokens.includes('alternate');
+}
+
+function locatedAttribute(source, location, parsedValue) {
+  if (!location || parsedValue === undefined) return undefined;
+  const raw = source.slice(location.startOffset, location.endOffset);
+  const equals = raw.indexOf('=');
+  if (equals < 0) return undefined;
+  let start = equals + 1;
+  while (/\s/.test(raw[start] ?? '')) start += 1;
+  const quote = raw[start];
+  let end;
+  const quoted = quote === '"' || quote === "'";
+  if (quoted) {
+    start += 1;
+    end = raw.lastIndexOf(quote);
+    if (end < start) return undefined;
+  } else {
+    end = start;
+    while (end < raw.length && !/\s/.test(raw[end])) end += 1;
+  }
+  const value = raw.slice(start, end);
+  return {
+    value: value.includes('&') ? parsedValue : value,
+    quoted,
+    writable: !value.includes('&'),
+    start: location.startOffset + start,
+    end: location.startOffset + end,
+  };
+}

package/index.d.ts

@@ -0,0 +1,46 @@
+export interface MigrateOptions {
+  styleFile?: string;
+  cwd?: string;
+  write?: boolean;
+  tailwindCss?: string;
+  workspaces?: boolean;
+  force?: boolean;
+}
+
+export interface MigrationWarning {
+  code: string;
+  file: string;
+  /** Byte offsets into the authored file, or (0, 0) when no unique mapping exists. */
+  start: number;
+  end: number;
+  message: string;
+}
+
+export 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 };
+  /** Rule span in the authored file, or (0, 0) when no unique mapping exists. */
+  authoredSpan: { start: number; end: number };
+}
+
+export interface MigrationFailure {
+  package: string;
+  message: string;
+}
+
+export interface MigrationReport {
+  changedFiles: string[];
+  diff: string;
+  convertedRules: number;
+  retainedRules: number;
+  rules: RuleReport[];
+  candidates: string[];
+  warnings: MigrationWarning[];
+  failures: MigrationFailure[];
+}
+
+export function migrate(options?: MigrateOptions): Promise<MigrationReport>;