tw-migrate 0.1.0-alpha.1 → 0.2.0

package/README.md

@@ -1,6 +1,6 @@
 # tw-migrate
 
-Preview and migrate static React/Next.js stylesheet references to Tailwind v4 utilities.
+Preview and migrate static React/Next.js, Vue 3 SFC, and HTML stylesheet references to Tailwind v4 utilities.
 
 ## Usage
 
@@ -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/bin/tw-migrate.js

@@ -1,8 +1,9 @@
 #!/usr/bin/env node
 
-import { migrate } from '../index.js';
+import { migrate } from "../index.js";
 
-const usage = 'Usage: tw-migrate [style-file] [--tailwind-css <entry.css>] [--workspaces] [--force] [--write]';
+const usage =
+  "Usage: tw-migrate [style-file] [--tailwind-css <entry.css>] [--workspaces] [--force] [--write]";
 
 async function main() {
   const args = process.argv.slice(2);
@@ -14,16 +15,16 @@ async function main() {
 
   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') {
+    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') {
+    } else if (argument === "--help" || argument === "-h") {
       console.log(usage);
       return;
-    } else if (argument.startsWith('-')) {
+    } else if (argument.startsWith("-")) {
       throw new Error(`Unknown option: ${argument}`);
     } else if (!styleFile) styleFile = argument;
     else throw new Error(`Unexpected argument: ${argument}`);
@@ -32,12 +33,16 @@ async function main() {
   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}`);
+    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.`);
+  console.log(
+    `${write ? "Applied" : "Previewed"} ${report.changedFiles.length} file(s); ${report.convertedRules} rule(s) converted, ${report.retainedRules} retained.`,
+  );
 }
 
 main().catch((error) => {

package/html.js

@@ -1,6 +1,6 @@
-import { parse } from 'parse5';
+import { parse } from "parse5";
 
-const RECOVERABLE_PARSE_ERRORS = new Set(['missing-doctype']);
+const RECOVERABLE_PARSE_ERRORS = new Set(["missing-doctype"]);
 const TEMPLATE_MARKERS = /\{\{|\}\}|\$\{|<%|%>|<#|#>|\[%|%\]/;
 
 export function parseHtmlSource(path, source) {
@@ -12,7 +12,7 @@ export function parseHtmlSource(path, source) {
     },
   });
   if (errors.length > 0) {
-    throw new Error(`Failed to parse ${path}: ${errors.map((error) => error.code).join(', ')}`);
+    throw new Error(`Failed to parse ${path}: ${errors.map((error) => error.code).join(", ")}`);
   }
 
   const links = [];
@@ -22,25 +22,27 @@ export function parseHtmlSource(path, source) {
   const scriptTexts = [];
 
   function visit(node) {
-    if (node.tagName === 'script') {
+    if (node.tagName === "script") {
       for (const child of node.childNodes ?? []) {
-        if (child.nodeName === '#text' && child.value) scriptTexts.push(child.value);
+        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'));
+        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 ?? '',
+              media: media?.value ?? "",
               start: href.start,
               end: href.end,
               tagStart: tag.startOffset,
@@ -48,30 +50,40 @@ export function parseHtmlSource(path, source) {
             });
           }
         }
-        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 });
+        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'));
+        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);
+        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 };
+              classAttribute = { value: "", start: insertion, end: insertion, synthetic: true };
             }
           }
           elements.push({ classAttribute, idAttribute });
@@ -86,13 +98,39 @@ export function parseHtmlSource(path, source) {
   visit(document);
   return {
     ...toByteOffsets(source, { links, bases, elements, dynamicAttributes }),
-    scriptText: scriptTexts.join('\n'),
+    scriptText: scriptTexts.join("\n"),
   };
 }
 
+// Map UTF-16 string indices to UTF-8 byte offsets in one source pass, so
+// large documents stay linear instead of rescanning the prefix per site.
+export function utf8OffsetMap(source, indices) {
+  const sorted = [...new Set(indices)].sort((left, right) => left - right);
+  const map = new Map();
+  let lastIndex = 0;
+  let bytes = 0;
+  for (const index of sorted) {
+    bytes += Buffer.byteLength(source.slice(lastIndex, index));
+    lastIndex = index;
+    map.set(index, bytes);
+  }
+  return map;
+}
+
 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) };
+  const offsets = utf8OffsetMap(source, [
+    ...parsed.links.flatMap((link) => [link.start, link.end, link.tagStart, link.tagEnd]),
+    ...parsed.bases.flatMap((base) => [base.start, base.end]),
+    ...parsed.elements.flatMap((element) =>
+      [element.classAttribute, element.idAttribute]
+        .filter(Boolean)
+        .flatMap((value) => [value.start, value.end]),
+    ),
+    ...parsed.dynamicAttributes.flatMap((value) => [value.start, value.end]),
+  ]);
+  const offset = (index) => offsets.get(index);
+  const attribute = (value) =>
+    value && { ...value, start: offset(value.start), end: offset(value.end) };
   return {
     links: parsed.links.map((link) => ({
       ...link,
@@ -101,7 +139,7 @@ function toByteOffsets(source, parsed) {
       tagStart: offset(link.tagStart),
       tagEnd: offset(link.tagEnd),
     })),
-    bases: parsed.bases.map((base) => ({ ...base, start: offset(base.start), end: offset(base.end) })),
+    bases: parsed.bases.map(attribute),
     elements: parsed.elements.map((element) => ({
       classAttribute: attribute(element.classAttribute),
       idAttribute: attribute(element.idAttribute),
@@ -113,24 +151,24 @@ function toByteOffsets(source, parsed) {
 function classInsertionOffset(source, startTag) {
   if (!startTag) return undefined;
   let offset = startTag.endOffset - 1;
-  if (source[offset] !== '>') return undefined;
+  if (source[offset] !== ">") return undefined;
   while (offset > startTag.startOffset && /\s/.test(source[offset - 1])) offset -= 1;
-  if (source[offset - 1] === '/') offset -= 1;
+  if (source[offset - 1] === "/") offset -= 1;
   return offset;
 }
 
-function stylesheetRel(value = '') {
+function stylesheetRel(value = "") {
   const tokens = value.toLowerCase().split(/\s+/);
-  return tokens.includes('stylesheet') && !tokens.includes('alternate');
+  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('=');
+  const equals = raw.indexOf("=");
   if (equals < 0) return undefined;
   let start = equals + 1;
-  while (/\s/.test(raw[start] ?? '')) start += 1;
+  while (/\s/.test(raw[start] ?? "")) start += 1;
   const quote = raw[start];
   let end;
   const quoted = quote === '"' || quote === "'";
@@ -144,9 +182,9 @@ function locatedAttribute(source, location, parsedValue) {
   }
   const value = raw.slice(start, end);
   return {
-    value: value.includes('&') ? parsedValue : value,
+    value: value.includes("&") ? parsedValue : value,
     quoted,
-    writable: !value.includes('&'),
+    writable: !value.includes("&"),
     start: location.startOffset + start,
     end: location.startOffset + end,
   };

package/index.d.ts

@@ -18,7 +18,7 @@ export interface MigrationWarning {
 
 export 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). */