tw-canonicalize 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Matthias Helbich
+
+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

@@ -1,3 +1,89 @@
-# Temporary Holding Version
+# tw-canonicalize
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Rewrites Tailwind CSS **v4** class names in your templates to their canonical form, in bulk. These are the fixes the
+Tailwind IntelliSense extension offers one by one as `suggestCanonicalClasses` (`min-h-[100px]` → `min-h-25`,
+`gap-[10px]` → `gap-2.5`, `max-w-[600px]` → `max-w-150`, …). `npx @tailwindcss/upgrade` only covers a small part of them.
+
+It uses the canonicalizer that ships with Tailwind itself (`canonicalizeCandidates` of the design system loaded via
+`@tailwindcss/node`), with the Tailwind version and theme of the project you run it in.
+Every rewrite is checked to generate the same CSS before it is applied. It does only this one job: no class sorting, deduplication or linting.
+
+## Usage
+
+```bash
+# dry run in the current project (nothing is written)
+npx tw-canonicalize
+
+# write the changes
+npx tw-canonicalize --apply
+
+# CI: exit code 1 if anything is not canonical
+npx tw-canonicalize --check
+```
+
+Run it in a project that has Tailwind CSS v4 installed and a clean git tree, then review the diff.
+
+| Option         | Default                         | Description                                                                                 |
+| -------------- | ------------------------------- | ------------------------------------------------------------------------------------------- |
+| `--css <file>` | auto-detected                   | Entry stylesheet with `@import "tailwindcss"`. Required when several files match (or none). |
+| `--root <dir>` | current directory               | Project root.                                                                               |
+| `--ext <list>` | `html,vue,svelte,astro,jsx,tsx` | File extensions to process. Add e.g. `ts` (Angular inline templates), `mdx`, `php`, `erb`.  |
+| `--rem <px>`   | `16`                            | Root font size for the `px` ↔ `rem` equivalence check.                                      |
+| `--apply`      | off (dry run)                   | Write the changes.                                                                          |
+| `--check`      | off                             | Exit with code 1 when changes are found. Cannot be combined with `--apply`.                 |
+| `--no-verify`  | verification on                 | Also apply rewrites whose generated CSS differs from the original.                          |
+
+Exit codes: `0` ok, `1` changes found under `--check`, `2` error.
+
+## What it does (and does not do)
+
+- Processes **static** `class="…"`, `class='…'` and `className="…"` attributes, in any file with a configured extension.
+  The match ignores context, so it also finds them inside JS strings and comments (this is what makes `--ext ts` work for
+  Angular inline templates). Files come from `git ls-files` (so `.gitignore` is respected), or a directory walk outside a git repository.
+- Never touches dynamic bindings (`:class`, `v-bind:class`, `[ngClass]`, `[class]`, `className={…}`) or values with
+  interpolation (`{{ }}`, `${ }`, `{ }`). They are counted and reported as skipped.
+- Does not look at class helper calls (`cn(…)`, `clsx(…)`, `cva(…)`, `twMerge(…)`). Their strings are neither rewritten nor counted.
+- Does not touch `@apply` or `<style>` blocks.
+- **Verifies every rewrite**: the generated CSS declarations of the old and the new class are compared (theme variables
+  resolved, `calc(<n> * <n>)` evaluated, `rem` converted to `px`). A rewrite that generates different CSS is reported and
+  left alone. Selectors are not compared, only declarations.
+- Idempotent: a second run finds nothing.
+
+## Caveats
+
+- It relies on `__unstable__loadDesignSystem` and `canonicalizeCandidates` from `@tailwindcss/node`, which are not a public API.
+  Needs **tailwindcss >= 4.1.18**; tested up to 4.3.3. Older versions either fail with a clear message (<= 4.1.14: no
+  `canonicalizeCandidates`) or rewrite only part of the classes (4.1.15 - 4.1.17: spacing utilities such as `gap-`/`px-`/`py-`,
+  but not e.g. `w-`, `min-h-`, `mt-`, `max-w-`).
+- Pixel values become spacing-scale classes (`gap-[10px]` → `gap-2.5` = `0.625rem`). They are identical at the default 16px root
+  font size but scale with a changed browser font size, unlike the fixed pixel value.
+- One stylesheet (one theme) is used for the whole run. In a monorepo with different themes, run it once per package:
+  `--root packages/a --css src/app.css`.
+- Tailwind CSS v3 projects are not supported (migrate to v4 first).
+- With strict `node_modules` layouts (pnpm) `@tailwindcss/node` is looked up through `@tailwindcss/vite`, `@tailwindcss/postcss`
+  and `@tailwindcss/cli`.
+
+## Development
+
+```bash
+npm install
+npm run typecheck && npm run lint && npm run format:check && npm test
+npm run build
+```
+
+Run a local checkout against a project:
+
+```bash
+npx tsx src/cli.ts --root /path/to/project   # from source
+node dist/cli.js --root /path/to/project     # after npm run build
+```
+
+To try the packaged tarball: `npm pack`, then `npx --package=./tw-canonicalize-0.1.0.tgz tw-canonicalize` (plain `npx ./file.tgz` treats the path as a command).
+
+Tests run the CLI against `test/fixtures/basic` (copied to the git-ignored `test/.tmp`, so Node resolves this repo's Tailwind).
+
+## Release
+
+1. `npm version patch|minor|major` (runs lint, typecheck and tests, bumps the version, creates the tag), then `git push --follow-tags`.
+2. The `Publish` workflow stages the version (`npm stage publish`, stage-only token in the `NPM_TOKEN` secret).
+3. Approve it with 2FA: `npm stage list`, then `npm stage approve <stage-id>` (or on npmjs.com).

package/dist/canonicalize.js

@@ -0,0 +1,50 @@
+/**
+ * Canonicalizes every class in a `class="…"` value. Whitespace between the classes is preserved.
+ * Returns `null` if Tailwind throws, so the caller can skip the attribute.
+ */
+export function canonicalizeValue(ds, value, rem, accept = () => true) {
+    const parts = value.split(/(\s+)/);
+    const tokens = parts.filter((part) => part.trim() !== "");
+    if (tokens.length === 0)
+        return { value, changes: [] };
+    const canonical = canonicalizeTokens(ds, tokens, rem);
+    if (canonical === null)
+        return null;
+    const changes = [];
+    let index = 0;
+    const rebuilt = parts.map((part) => {
+        if (part.trim() === "")
+            return part;
+        const to = canonical[index++] ?? part;
+        if (to === part)
+            return part;
+        const change = { from: part, to };
+        if (!accept(change))
+            return part;
+        changes.push(change);
+        return to;
+    });
+    return { value: rebuilt.join(""), changes };
+}
+/**
+ * Tailwind drops duplicates from its result (`["a", "a"]` gives `["a"]`), so the output of one batch call cannot be
+ * matched to the input by position. In that case fall back to one call per class, which always returns one class.
+ */
+function canonicalizeTokens(ds, tokens, rem) {
+    try {
+        const batch = ds.canonicalizeCandidates(tokens, { rem });
+        if (batch.length === tokens.length)
+            return batch;
+        const single = [];
+        for (const token of tokens) {
+            const [canonical, ...rest] = ds.canonicalizeCandidates([token], { rem });
+            if (canonical === undefined || rest.length > 0)
+                return null;
+            single.push(canonical);
+        }
+        return single;
+    }
+    catch {
+        return null;
+    }
+}

package/dist/cli.js

@@ -0,0 +1,78 @@
+#!/usr/bin/env node
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+import { parseArgs } from "node:util";
+import { formatReport } from "./report.js";
+import { run } from "./run.js";
+const DEFAULT_EXTENSIONS = ["html", "vue", "svelte", "astro", "jsx", "tsx"];
+const HELP = `tw-canonicalize [options]
+
+Rewrites Tailwind CSS v4 class names in templates to their canonical form (the "suggestCanonicalClasses"
+fixes of the Tailwind IntelliSense extension, in bulk). Dry run by default.
+
+Options:
+  --css <file>       Entry stylesheet importing Tailwind (auto-detected when exactly one file has @import "tailwindcss")
+  --root <dir>       Project root, default: current directory
+  --ext <list>       Comma-separated file extensions, default: ${DEFAULT_EXTENSIONS.join(",")}
+  --rem <px>         Root font size used for rem conversions, default: 16
+  --apply            Write the changes to disk
+  --check            Exit with code 1 when changes are found (for CI)
+  --no-verify        Also apply rewrites whose generated CSS differs from the original
+  -h, --help         Show this help
+  -v, --version      Show the version
+
+Only static class="…" / className="…" attributes are rewritten. Dynamic bindings are never touched.`;
+async function main() {
+    const { values } = parseArgs({
+        options: {
+            css: { type: "string" },
+            root: { type: "string" },
+            ext: { type: "string" },
+            rem: { type: "string" },
+            apply: { type: "boolean", default: false },
+            check: { type: "boolean", default: false },
+            "no-verify": { type: "boolean", default: false },
+            help: { type: "boolean", short: "h", default: false },
+            version: { type: "boolean", short: "v", default: false },
+        },
+        allowPositionals: false,
+    });
+    if (values.help) {
+        console.log(HELP);
+        return 0;
+    }
+    if (values.version) {
+        console.log(await readVersion());
+        return 0;
+    }
+    const rem = values.rem === undefined ? 16 : Number(values.rem);
+    if (!Number.isFinite(rem) || rem <= 0)
+        throw new Error(`Invalid --rem value: ${values.rem}`);
+    if (values.apply && values.check)
+        throw new Error("--apply and --check cannot be combined.");
+    const root = path.resolve(values.root ?? process.cwd());
+    const extensions = (values.ext ?? DEFAULT_EXTENSIONS.join(","))
+        .split(",")
+        .map((extension) => extension.trim().replace(/^\./, "").toLowerCase())
+        .filter(Boolean);
+    const result = await run({
+        root,
+        css: values.css,
+        extensions,
+        rem,
+        apply: values.apply,
+        verify: !values["no-verify"],
+    });
+    console.log(formatReport(result, root));
+    return values.check && result.changes.length > 0 ? 1 : 0;
+}
+async function readVersion() {
+    const manifest = new URL("../package.json", import.meta.url);
+    return JSON.parse(await readFile(manifest, "utf8")).version;
+}
+main().then((code) => {
+    process.exitCode = code;
+}, (error) => {
+    console.error(`tw-canonicalize: ${error instanceof Error ? error.message : String(error)}`);
+    process.exitCode = 2;
+});

package/dist/design-system.js

@@ -0,0 +1,63 @@
+import fs from "node:fs";
+import { createRequire } from "node:module";
+import path from "node:path";
+// Packages that depend on @tailwindcss/node. With strict layouts (pnpm) it is not resolvable from the project root directly.
+const NODE_PROVIDERS = ["@tailwindcss/vite", "@tailwindcss/postcss", "@tailwindcss/cli"];
+/** Resolves `@tailwindcss/node` from the target project, so each repo is processed with its own Tailwind version. */
+export function resolveTailwindNode(root) {
+    const projectRequire = createRequire(path.join(root, "package.json"));
+    try {
+        return projectRequire.resolve("@tailwindcss/node");
+    }
+    catch {
+        // fall through to the packages that bring it in
+    }
+    for (const provider of NODE_PROVIDERS) {
+        try {
+            return createRequire(projectRequire.resolve(provider)).resolve("@tailwindcss/node");
+        }
+        catch {
+            // try the next one
+        }
+    }
+    throw new Error(`Could not resolve @tailwindcss/node from ${root}. Run the package manager install in the project first, and make sure it uses Tailwind CSS v4 (tailwindcss with @tailwindcss/vite, @tailwindcss/postcss or @tailwindcss/cli).`);
+}
+/** First Tailwind release whose canonicalizer covers the full set of utilities (4.1.15 - 4.1.17 only handle some). */
+export const MIN_TAILWIND_VERSION = "4.1.18";
+/** True when `version` is a plain `major.minor.patch` older than {@link MIN_TAILWIND_VERSION}. Unknown formats are not flagged. */
+export function isBelowMinimumVersion(version) {
+    const parse = (value) => /^(\d+)\.(\d+)\.(\d+)/.exec(value)?.slice(1).map(Number);
+    const actual = version === undefined ? undefined : parse(version);
+    const minimum = parse(MIN_TAILWIND_VERSION);
+    if (!actual || !minimum)
+        return false;
+    for (let index = 0; index < 3; index++) {
+        const difference = (actual[index] ?? 0) - (minimum[index] ?? 0);
+        if (difference !== 0)
+            return difference < 0;
+    }
+    return false;
+}
+export function readTailwindVersion(root) {
+    try {
+        const manifest = createRequire(path.join(root, "package.json")).resolve("tailwindcss/package.json");
+        return JSON.parse(fs.readFileSync(manifest, "utf8")).version;
+    }
+    catch {
+        return undefined;
+    }
+}
+export async function loadDesignSystem(root, entryCss) {
+    const tailwindVersion = readTailwindVersion(root);
+    const nodePath = resolveTailwindNode(root);
+    const tailwindNode = createRequire(nodePath)(nodePath);
+    const load = tailwindNode.__unstable__loadDesignSystem;
+    if (typeof load !== "function") {
+        throw new Error(`@tailwindcss/node (tailwindcss ${tailwindVersion ?? "unknown"}) has no __unstable__loadDesignSystem. This tool needs Tailwind CSS v4.`);
+    }
+    const ds = await load(fs.readFileSync(entryCss, "utf8"), { base: path.dirname(entryCss) });
+    if (typeof ds.canonicalizeCandidates !== "function") {
+        throw new Error(`tailwindcss ${tailwindVersion ?? "unknown"} has no canonicalizeCandidates. Upgrade to a newer Tailwind CSS 4.x release.`);
+    }
+    return { ds, tailwindVersion };
+}

package/dist/entry.js

@@ -0,0 +1,25 @@
+import fs from "node:fs";
+import path from "node:path";
+// Matches `@import "tailwindcss"`, `@import "tailwindcss/theme.css" layer(theme)` and `@import url("tailwindcss")`.
+const TAILWIND_IMPORT = /@import\s+(?:url\(\s*)?["']tailwindcss(?:\/[^"']*)?["']/;
+/** CSS files that import Tailwind CSS v4 (`@import "tailwindcss"`), i.e. candidates for the entry stylesheet. */
+export function findEntryCandidates(files) {
+    return files.filter((file) => file.endsWith(".css") && TAILWIND_IMPORT.test(fs.readFileSync(file, "utf8")));
+}
+/** Returns the absolute path of the entry stylesheet: `css` if given, else the only candidate among `files`. */
+export function resolveEntryCss(root, css, files) {
+    if (css) {
+        const resolved = path.resolve(root, css);
+        if (!fs.existsSync(resolved))
+            throw new Error(`Entry stylesheet not found: ${resolved}`);
+        return resolved;
+    }
+    const candidates = findEntryCandidates(files);
+    if (candidates.length === 1 && candidates[0])
+        return candidates[0];
+    if (candidates.length === 0) {
+        throw new Error(`No stylesheet with @import "tailwindcss" found below ${root}. Pass it with --css <file>. (Tailwind CSS v3 projects are not supported.)`);
+    }
+    const list = candidates.map((candidate) => `  ${path.relative(root, candidate)}`).join("\n");
+    throw new Error(`Several stylesheets import Tailwind CSS, pass one with --css <file>:\n${list}`);
+}

package/dist/extract.js

@@ -0,0 +1,33 @@
+// Static class attributes only. The lookbehind rejects `:class`, `v-bind:class`, `[class]`, `data-class`, `.class` and identifiers ending in "class".
+const STATIC_CLASS = /(?<![\w:.\-@#$[])(?:class|className)\s*=\s*(["'])([\s\S]*?)\1/g;
+const DYNAMIC_CLASS = /(?:(?<![\w.\-@#$])(?::class|v-bind:class|\[ngClass\]|\[class(?:\.[\w.-]+)?\])\s*=|(?<![\w:.\-@#$[])className\s*=\s*\{)/g;
+export function extractClassAttributes(source) {
+    const lineStarts = [0];
+    for (let index = source.indexOf("\n"); index !== -1; index = source.indexOf("\n", index + 1)) {
+        lineStarts.push(index + 1);
+    }
+    const attributes = [];
+    let interpolated = 0;
+    for (const match of source.matchAll(STATIC_CLASS)) {
+        const value = match[2] ?? "";
+        if (/[{}]/.test(value)) {
+            interpolated++;
+            continue;
+        }
+        const start = match.index + match[0].indexOf(value, match[0].indexOf("=") + 1);
+        attributes.push({ start, end: start + value.length, value, line: lineOf(lineStarts, start) });
+    }
+    return { attributes, interpolated, dynamic: [...source.matchAll(DYNAMIC_CLASS)].length };
+}
+function lineOf(lineStarts, offset) {
+    let low = 0;
+    let high = lineStarts.length - 1;
+    while (low < high) {
+        const middle = Math.ceil((low + high) / 2);
+        if ((lineStarts[middle] ?? 0) <= offset)
+            low = middle;
+        else
+            high = middle - 1;
+    }
+    return low + 1;
+}

package/dist/files.js

@@ -0,0 +1,56 @@
+import { execFileSync } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+const IGNORED_DIRS = new Set([
+    "node_modules",
+    "dist",
+    "build",
+    "coverage",
+    ".git",
+    ".nuxt",
+    ".output",
+    ".next",
+    ".angular",
+    ".svelte-kit",
+    ".turbo",
+    ".cache",
+]);
+/** Lists the files below `root` as absolute paths. Prefers git (honours .gitignore), falls back to a directory walk. */
+export function listFiles(root) {
+    const fromGit = listGitFiles(root);
+    return (fromGit.length > 0 ? fromGit : walk(root)).sort();
+}
+function listGitFiles(root) {
+    try {
+        const output = execFileSync("git", ["ls-files", "-z", "--cached", "--others", "--exclude-standard"], {
+            cwd: root,
+            encoding: "utf8",
+            maxBuffer: 256 * 1024 * 1024,
+            stdio: ["ignore", "pipe", "ignore"],
+        });
+        return output
+            .split("\0")
+            .filter(Boolean)
+            .map((relative) => path.join(root, relative))
+            .filter((absolute) => fs.existsSync(absolute));
+    }
+    catch {
+        // not a git repository, or git is unavailable
+        return [];
+    }
+}
+function walk(directory, found = []) {
+    for (const entry of fs.readdirSync(directory, { withFileTypes: true })) {
+        if (entry.isDirectory()) {
+            if (!IGNORED_DIRS.has(entry.name))
+                walk(path.join(directory, entry.name), found);
+        }
+        else if (entry.isFile()) {
+            found.push(path.join(directory, entry.name));
+        }
+    }
+    return found;
+}
+export function hasExtension(file, extensions) {
+    return extensions.includes(path.extname(file).slice(1).toLowerCase());
+}

package/dist/report.js

@@ -0,0 +1,56 @@
+import path from "node:path";
+import { isBelowMinimumVersion, MIN_TAILWIND_VERSION } from "./design-system.js";
+/** Formats a run for the terminal: per-change locations, a summary of distinct rewrites and what was skipped. */
+export function formatReport(result, root) {
+    const lines = [];
+    lines.push(`Entry stylesheet: ${path.relative(root, result.entryCss)} (tailwindcss ${result.tailwindVersion ?? "unknown"})`);
+    if (isBelowMinimumVersion(result.tailwindVersion)) {
+        lines.push(`Warning: tailwindcss < ${MIN_TAILWIND_VERSION} only canonicalizes part of the classes. Upgrade for complete results.`);
+    }
+    lines.push(`Scanned ${result.scannedFiles} files, ${result.attributes} static class attributes`);
+    if (result.changes.length > 0) {
+        lines.push("");
+        for (const change of result.changes) {
+            lines.push(`${change.file}:${change.line}  ${change.from} -> ${change.to}`);
+        }
+        const counts = new Map();
+        for (const change of result.changes) {
+            const key = `${change.from} -> ${change.to}`;
+            counts.set(key, (counts.get(key) ?? 0) + 1);
+        }
+        lines.push("");
+        lines.push(`${result.changes.length} rewrites (${counts.size} distinct) in ${result.changedFiles.length} files:`);
+        for (const [key, count] of [...counts].sort(([a], [b]) => a.localeCompare(b))) {
+            lines.push(`  ${count}x  ${key}`);
+        }
+    }
+    else {
+        lines.push("");
+        lines.push("Nothing to change, all class names are already canonical.");
+    }
+    if (result.unverified.length > 0) {
+        lines.push("");
+        lines.push(`${result.unverified.length} suggested rewrites generate different CSS and were left alone (use --no-verify to force):`);
+        for (const change of result.unverified) {
+            lines.push(`  ${change.file}:${change.line}  ${change.from} -> ${change.to}`);
+        }
+    }
+    const skipped = [];
+    if (result.skippedDynamic > 0)
+        skipped.push(`${result.skippedDynamic} dynamic class bindings`);
+    if (result.skippedInterpolated > 0)
+        skipped.push(`${result.skippedInterpolated} class attributes with interpolation`);
+    if (result.skippedErrors > 0)
+        skipped.push(`${result.skippedErrors} class attributes Tailwind could not process`);
+    if (skipped.length > 0) {
+        lines.push("");
+        lines.push(`Skipped: ${skipped.join(", ")}`);
+    }
+    if (result.changes.length > 0) {
+        lines.push("");
+        lines.push(result.applied
+            ? `Applied to ${result.changedFiles.length} files.`
+            : "Dry run, nothing written. Re-run with --apply to write the changes.");
+    }
+    return lines.join("\n");
+}

package/dist/rewrite.js

@@ -0,0 +1,42 @@
+import { canonicalizeValue } from "./canonicalize.js";
+import { extractClassAttributes } from "./extract.js";
+import { isEquivalent } from "./verify.js";
+/** Canonicalizes the static class attributes of one file's source. Pure: reads and writes nothing. */
+export function rewriteSource(ds, source, options) {
+    const extraction = extractClassAttributes(source);
+    const result = {
+        source: null,
+        attributes: extraction.attributes.length,
+        changes: [],
+        unverified: [],
+        skippedInterpolated: extraction.interpolated,
+        skippedDynamic: extraction.dynamic,
+        skippedErrors: 0,
+    };
+    const replacements = [];
+    for (const attribute of extraction.attributes) {
+        const canonical = canonicalizeValue(ds, attribute.value, options.rem, (change) => {
+            if (!options.verify || isEquivalent(ds, change.from, change.to, options.rem))
+                return true;
+            result.unverified.push({ line: attribute.line, ...change });
+            return false;
+        });
+        if (canonical === null) {
+            result.skippedErrors++;
+            continue;
+        }
+        if (canonical.changes.length === 0)
+            continue;
+        result.changes.push(...canonical.changes.map((change) => ({ line: attribute.line, ...change })));
+        replacements.push({ start: attribute.start, end: attribute.end, value: canonical.value });
+    }
+    if (replacements.length > 0) {
+        // Apply from the end so earlier offsets stay valid.
+        let rewritten = source;
+        for (const { start, end, value } of replacements.reverse()) {
+            rewritten = rewritten.slice(0, start) + value + rewritten.slice(end);
+        }
+        result.source = rewritten;
+    }
+    return result;
+}

package/dist/run.js

@@ -0,0 +1,44 @@
+import fs from "node:fs";
+import path from "node:path";
+import { loadDesignSystem } from "./design-system.js";
+import { resolveEntryCss } from "./entry.js";
+import { hasExtension, listFiles } from "./files.js";
+import { rewriteSource } from "./rewrite.js";
+export async function run(options) {
+    const root = path.resolve(options.root);
+    const files = listFiles(root);
+    const entryCss = resolveEntryCss(root, options.css, files);
+    const { ds, tailwindVersion } = await loadDesignSystem(root, entryCss);
+    const result = {
+        entryCss,
+        tailwindVersion,
+        scannedFiles: 0,
+        attributes: 0,
+        changes: [],
+        unverified: [],
+        skippedInterpolated: 0,
+        skippedDynamic: 0,
+        skippedErrors: 0,
+        changedFiles: [],
+        applied: options.apply,
+    };
+    for (const file of files) {
+        if (!hasExtension(file, options.extensions))
+            continue;
+        const relative = path.relative(root, file);
+        const rewrite = rewriteSource(ds, fs.readFileSync(file, "utf8"), options);
+        result.scannedFiles++;
+        result.attributes += rewrite.attributes;
+        result.skippedInterpolated += rewrite.skippedInterpolated;
+        result.skippedDynamic += rewrite.skippedDynamic;
+        result.skippedErrors += rewrite.skippedErrors;
+        result.changes.push(...rewrite.changes.map((change) => ({ file: relative, ...change })));
+        result.unverified.push(...rewrite.unverified.map((change) => ({ file: relative, ...change })));
+        if (rewrite.source !== null) {
+            result.changedFiles.push(relative);
+            if (options.apply)
+                fs.writeFileSync(file, rewrite.source);
+        }
+    }
+    return result;
+}

package/dist/verify.js

@@ -0,0 +1,41 @@
+/**
+ * Checks that two class names generate the same CSS declarations.
+ *
+ * Selectors and wrapping at-rules are ignored. Theme variables are resolved, simple `calc(<n> * <n>)` expressions are
+ * evaluated and `rem` is converted to `px`, so `gap-[10px]` and `gap-2.5` compare equal at the given root font size.
+ */
+export function isEquivalent(ds, from, to, rem) {
+    const [fromCss, toCss] = ds.candidatesToCss([from, to]);
+    if (fromCss == null || toCss == null)
+        return false;
+    const left = declarations(ds, fromCss, rem);
+    const right = declarations(ds, toCss, rem);
+    return (left.length > 0 && left.length === right.length && left.every((declaration, index) => declaration === right[index]));
+}
+function declarations(ds, css, rem) {
+    // Dropping everything in front of an opening brace removes selectors and at-rule preludes, leaving `{ prop: value; }` blocks.
+    const body = css.replace(/[^{};]*\{/g, "{");
+    const found = [];
+    for (const match of body.matchAll(/([\w-]+)\s*:\s*([^;{}]+)/g)) {
+        found.push(`${match[1] ?? ""}:${normalizeValue(ds, match[2] ?? "", rem)}`);
+    }
+    return found.sort();
+}
+function normalizeValue(ds, raw, rem) {
+    let value = raw.trim().toLowerCase();
+    // Resolve theme variables (`var(--spacing)`), a few passes for variables that reference other variables.
+    for (let pass = 0; pass < 5; pass++) {
+        const next = value.replace(/var\((--[\w-]+)\)/g, (whole, name) => ds.resolveThemeValue(name)?.toLowerCase() ?? whole);
+        if (next === value)
+            break;
+        value = next;
+    }
+    value = value.replace(/calc\(\s*(-?[\d.]+)(rem|px)?\s*\*\s*(-?[\d.]+)\s*\)/g, (_whole, a, unit, b) => {
+        return `${format(Number(a) * Number(b))}${unit ?? ""}`;
+    });
+    value = value.replace(/(-?[\d.]+)rem\b/g, (_whole, amount) => `${format(Number(amount) * rem)}px`);
+    return value.replace(/\s+/g, "");
+}
+function format(amount) {
+    return String(Number(amount.toFixed(4)));
+}

package/package.json

@@ -1,6 +1,60 @@
 {
   "name": "tw-canonicalize",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Rewrite Tailwind CSS v4 class names in templates to their canonical form (the suggestCanonicalClasses fixes, in bulk)",
+  "homepage": "https://github.com/mhelbich/tw-canonicalize#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mhelbich/tw-canonicalize.git"
+  },
+  "bugs": {
+    "url": "https://github.com/mhelbich/tw-canonicalize/issues"
+  },
+  "type": "module",
+  "engines": {
+    "node": ">=22"
+  },
+  "bin": {
+    "tw-canonicalize": "dist/cli.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "node -e \"fs.rmSync('dist',{recursive:true,force:true})\" && tsc -p tsconfig.build.json",
+    "prepare": "npm run build",
+    "preversion": "npm run lint && npm run typecheck && npm test",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "node --import tsx --test 'test/**/*.test.ts'",
+    "lint": "eslint .",
+    "lint:fix": "eslint . --fix",
+    "format": "prettier --write .",
+    "format:check": "prettier --check ."
+  },
+  "keywords": [
+    "tailwind",
+    "tailwindcss",
+    "canonical",
+    "codemod",
+    "cli"
+  ],
+  "author": {
+    "name": "mhelbich",
+    "email": "helbichmatthias@live.com",
+    "url": "https://mhelbich.de"
+  },
+  "license": "MIT",
+  "devDependencies": {
+    "@eslint/js": "^10.0.1",
+    "@tailwindcss/node": "^4.3.3",
+    "@types/node": "^22.0.0",
+    "eslint": "^10.8.1",
+    "eslint-config-prettier": "^10.1.8",
+    "globals": "^17.11.0",
+    "prettier": "^3.9.6",
+    "tailwindcss": "^4.3.3",
+    "tsx": "^4.19.2",
+    "typescript": "^6.0.3",
+    "typescript-eslint": "^8.67.0"
+  }
+}