@lunawerx/normwind

NormWind can rewrite class tokens that reference a Tailwind v4 @theme variable in their long form (border-(--color-ink-400), border-[var(--color-ink-400)]/40, rounded-[var(--radius-sm)]) into the equivalent named-utility form (border-ink-400, border-ink-400/40, rounded-sm).

Two @theme patterns are supported:

Direct pattern: the project authors the theme key itself:

@theme {
  --color-ink-400: var(--color-zinc-400);
  --radius-sm: 0.125rem;
}

border-(--color-ink-400)/40 → border-ink-400/40, rounded-[var(--radius-sm)] → rounded-sm.

Forwarder pattern: the project forwards a Tailwind-namespaced theme var to a foreign root variable:

@theme {
  --color-outline-variant: var(--md-sys-color-outline-variant);
}

border-(--md-sys-color-outline-variant) → border-outline-variant.

Both rewrites are gated by a per-token CSS rule-body equivalence check: NormWind asks Tailwind to compile both candidates and only emits the rewrite when the produced rule bodies are byte-equivalent (after substituting the forwarder, where applicable). Ambiguous forwarders, unknown variables, and prefix-mismatches (e.g. rounded-(--color-ink-400): rounded- is not a color utility) are silently skipped.

Audit (opt-in via flag):

npx @lunawerx/normwind \
  --suggest-named-theme-vars \
  --theme-css src/assets/css/theme.css \
  --json

Fix (auto-engaged when --theme-css is provided):

npx @lunawerx/normwind \
  --fixall \
  --theme-css src/assets/css/theme.css

The audit suggestion flag is intentionally still opt-in to preserve the existing public audit contract. During --fix/--fixall the safety gate is the per-token equivalence check, so passing --theme-css alone is enough. When neither --theme-css nor --suggest-named-theme-vars is passed, NormWind's output is identical to v3.0.0; existing CI pipelines are unaffected.

Inputs:

Outputs: version, finding-count, linted-files, result, exit-code, report-path, and sarif-path (set only when sarif-file was provided).

Run the full pre-push verification suite:

npm test          # alias: npm run prepush

The pre-push suite verifies package metadata, canonical-snapshot integrity, canonical drift, regression fixtures, the rewrite-precision gate, live-Tailwind-vs-snapshot parity, CLI audit/fix smoke behavior, and npm pack --dry-run contents.

Other useful scripts:

npm run test:regression          # run the regression fixtures
npm run test:regression:update   # update fixtures after an intentional change
                                 # (review each fixture's expected.golden.txt diff:
                                 #  the input with ~~~ under every finding, then the fixed output)
npm run test:compare             # live canonicalizer vs bundled snapshot
npm run test:precision           # score the rewrite rules against the labelled corpus
npm run canonical:extract        # regenerate canonical replacement files
npm run canonical:check          # verify canonical replacement files are current
npm run deps:sync                # after a dependency bump: refresh bun.lock and rebuild dist/

Rewrite precision gate

A false positive is a bug in a rewrite rule, so the rate is measured, not assumed. test/precision/corpus.json holds labelled class strings: rewrite cases name the exact result --fixall must produce, and keep cases must be neither reported nor rewritten. npm run test:precision runs the whole corpus through the real CLI twice (audit, then --fixall) and fails when either pass drops below precision 0.90, recall 0.85, or rises above a false-positive rate of 0.10. A wrong rewrite counts as a false positive, and a corpus with no cases on one side of the label fails rather than scoring as perfect. Every misclassified case is listed by id.

A new rewrite rule lands with at least one rewrite case and one keep case that pins where the rule must stop.

Updating dependencies

This repo commits three things that a dependency bump has to move together:

Dependabot only knows about the first row. It has no way to update the other two, and no Dependabot configuration can fix that: bun.lock and package-lock.json describe the same package.json, so adding a second package-ecosystem would just open a second, conflicting PR for every bump. Every Dependabot PR therefore arrives red on purpose, and finishing it is a manual step:

gh pr checkout <number>
npm run deps:sync
git add bun.lock dist/            # only if they actually changed
git commit -m "chore(deps): sync bun.lock and dist/ with the npm bump"
git push

deps:sync needs Bun on PATH for its first step; nothing else in the repo does, and CI never runs it. If you do not have Bun, ask someone who does to push the bun.lock half.

Note that npm test chains its three suites with &&, so a stale bun.lock short-circuits before the bundle check ever runs. If you fix only the lockfile, expect the dist/ failure to appear on the next push. npm run deps:sync does both at once for exactly this reason.

Security bumps on a transitive package need one extra step

deps:sync is enough for anything Dependabot touches, because those are dependencies declared in package.json. It is not enough for a transitive one, which is what most advisories are:

npm audit fix                     # moves package-lock.json only
bun update <name>                 # bun.lock needs to be told explicitly
npm ci && npm run build:action    # then resync the tree and the bundle

The bun install inside deps:sync will not move a pin that still satisfies its range. When nanoid was patched for GHSA-2v37-7h3g-55p8, 3.3.16 still satisfied its parent's ^3.3.16, so bun install left the vulnerable copy in place while npm ci installed the fixed one. The lockfiles agree on the whole resolved tree check exists to catch precisely that.

Resolving a dist/ conflict during a rebase

Rebuild the bundle. Never take either side.

npm run build:action && git add dist/

dist/ is generated, so neither side of a conflict is authoritative and a textual merge of two minified bundles is meaningless. Taking one side looks like it worked and then ships a stale bundle: the action: committed bundle is current check will fail, but only on the commit that carries the stale copy, which may not be the one that looked conflicted. That is precisely how it happened on 3fe92ad, which went red on all seven CI legs.

You should not have to remember this. .gitattributes marks dist/** as -merge, so git refuses to invent a merge result there: it conflicts, leaves the current branch's copy in place, and writes no conflict markers, so there is no half-merged bundle to commit by accident. The full rule lives in .gitattributes next to that line, and every staleness error from build:action repeats it.

Note that the bundle can change even when the source edit appears to have no effect on it: removing a dead helper still changed the output, because it was the second user of a name and the minifier stopped emitting that name once it had one user left. Do not skip the rebuild because the diff looks irrelevant.

NormWind deliberately uses eslint-plugin-tailwindcss's static group data instead of invoking the plugin's enforces-shorthand rule directly. Under Tailwind v4, the plugin's config path can return only separator and prefix, which prevents the rule from resolving many utility families. NormWind keeps the useful upstream group data while using its own Tailwind v4-compatible matcher and Tailwind's own v4 canonicalization engine, so you get the plugin's knowledge without its v4 blind spots.

As of eslint-plugin-tailwindcss 4.x, that group table lives in NormWind's own tree (lib/vendor/tailwind-classname-groups.mjs, MIT-licensed, full notice in THIRD-PARTY-NOTICES.md) rather than being imported from the package at run time: v4 rewrote shorthand classification to query a live Tailwind engine through an internal worker and no longer ships or exports the static table, so this is a one-time snapshot of the last version (3.18.3) that had it. eslint-plugin-tailwindcss itself stays a declared dependency, bumped alongside the rest.

• Breaking: Node 22 is now the minimum (^22.18.0 || >=24.11.0). Node 20 reached end of life on 2026-04-30 and gets no security patches; an install on Node 20 now warns, and fails outright under engine-strict. Nothing else about how NormWind scans, reports or fixes depends on this, so if you are already on Node 22 or 24 the upgrade is a drop-in.

• Gate on changed lines only: --diff-base <ref> (CLI) and changed-lines-only / diff-base (Action) report, annotate, write SARIF for, and fail on only the findings on lines a change adds or edits, relative to the merge base with <ref>. Turning the audit on in an existing codebase no longer floods the first pull request with findings nobody touched; the CLI counts the rest on stderr and the Action's JSON report still lists every finding. With changed-lines gating on, the Action's finding-count and exit-code outputs describe the gated findings.

• Per-file count baseline (--baseline, --update-baseline, Action baseline input): adopt NormWind in CI on a codebase that already has findings. A file may keep the findings it had when the baseline was recorded; a new one fails, and a count that drops fails until the baseline is lowered, so the debt only goes down. --update-baseline creates the file once and afterwards refuses to raise any count. See Adopting on an existing codebase.

• Rewrite-precision gate (development gate): a labelled corpus of must-rewrite and must-not-rewrite class strings now runs through the CLI on every npm test, and the suite fails when aggregate precision, recall, or false-positive rate crosses a fixed floor (npm run test:precision). Nothing about scanning or --fix changes.

• Tailwind's own collapse engine adds shorthand merges the group table misses. When the resolved Tailwind supports canonicalizeCandidates(..., { collapse: true }), each variant/important group of a class list is also collapsed by Tailwind, which only swaps a set for a utility whose compiled CSS matches it. That reaches merges the vendored v3-era group table never listed and follows each Tailwind release. The table's findings always stand: an engine merge is added only when it shares no class with a table finding and its classes are not all in one table family, so nothing the table reports is lost. NormWind's render-safety proof still checks every added merge against the rest of the class list. Answers are cached with the other canonicalization results. NORMWIND_DISABLE_ENGINE_COLLAPSE=1 uses the table alone.

Nothing in this release changes what NormWind reports or how --fix behaves. It is repository housekeeping, published so the packaged README matches the source. If you are on v3.8.0 there is no functional reason to upgrade.

• Dependency bump: nanoid 3.3.18 (GHSA-2v37-7h3g-55p8), reached through eslint-plugin-tailwindcss → postcss. This is not a fix you were exposed to: the advisory affects a package resolved on a ^3.3.x range, so a fresh install of any recent NormWind already picked up the patched version, and the bundled Marketplace Action does not contain nanoid at all. The bump pins it in this repository's own lockfiles.
• Lockfile drift is now caught on transitive packages, not just declared ones (development gate). This project keeps both an npm and a Bun lockfile, and the previous check only compared the dependencies named in package.json, where most advisories never land. The nanoid bump above is the worked example: npm audit fix moved one lockfile while the other stayed on the vulnerable version, silently, because the old pin still satisfied its range. The check now compares the full resolved set of both files.
• A merge conflict in the committed Action bundle must be resolved by rebuilding it, never by taking either side. Both are stale by definition, since each was generated from a different source tree than the merged one. .gitattributes now marks dist/** as unmergeable so Git stops attempting a meaningless three-way merge of two single-line minified files, the build script repeats the rule in its staleness error, and the README documents it. A rebase that resolved this file in favour of the upstream copy is what turned CI red across all seven legs before v3.8.0.

• Merge-safety gate for shorthand merges (correctness fix): a merge such as ml-2 mr-2 → mx-2 is now applied only when Tailwind's own engine confirms the before and after class lists render identical CSS. Tailwind emits utilities in its own order, not authoring order, so a merge sharing a group with another utility at a different value (a pre-existing mx-8 alongside ml-2 mr-2) could previously hand that other utility the win and silently change the rendered layout. --fix/--fixall now skip any merge that isn't provably safe instead of applying it blind; this closes a real path to a silent visual regression from --fix.
• New flags: --reporter <text|json|sarif> (sarif emits SARIF 2.1.0 for GitHub code scanning; --json remains an alias for --reporter json), --ignore <glob> (repeatable), --allow-empty (exit 0 instead of 2 when a pattern matches nothing), and -- to end flag parsing so a target can start with a dash.
• .normwindignore: a project-local ignore file (one glob per line, # comments, a bare directory name means everything under it) is now read automatically from the scanned directory. It is deliberately not read in GitHub Action mode, since the file is checkout-controlled and a pull request could otherwise silence the audit on the very files it changed; --ignore flags are always honored in both modes.
• Broader file matching: .svelte, .astro (frontmatter skipped, markup scanned), and plain .html/.htm join the default scan alongside Vue/JS/TS. The generated-folder ignore list dropped project-specific paths and now covers .next, .nuxt, .output, .svelte-kit, .turbo, and storybook-static at any depth, plus root-only build folders such as build, coverage, out, and vendor.
• Class-string builders are scanned: clsx, cx, cn, classnames, classNames, cva, tv, twMerge, and twJoin calls, including strings nested in cva/tv variant objects, arrays, ternaries, and cond && "...", with locally-aliased imports resolved.
• --fix covers every markup format: .svelte, .astro, and .html/.htm join .vue in the safe default fixer, not just --fixall.
• Composite equivalences are now fixable: truncate, place-content-*, place-items-*, and place-self-* findings are applied by --fix/--fixall instead of being audit-only, so a fix-then-audit CI loop can actually reach exit 0.
• Stricter exit codes: a pattern matching no lintable files now exits 2 instead of 0 (--allow-empty restores the old behavior), and --fix/--fixall/--dry-run combined with a canonical-maintenance flag, or --dry-run without --fix/--fixall, now exits 2 instead of silently doing nothing.

• Native GitHub review feedback: the new NormWind Tailwind Audit Action emits file-and-line annotations, a complete job summary, stable outputs, and a machine-readable JSON report. Findings can fail the job or run in advisory mode; incomplete scans always fail closed.
• Self-contained and least privilege: the JavaScript Action bundles NormWind, Tailwind, Babel, and its reporting runtime; it installs nothing on the runner, requires no secret or write permission, strips inherited secrets from its scanner process, never executes checkout-provided dependencies/tools, and confines source/theme reads to the checked-out workspace.
• Reproducible Action releases: deterministic bundle generation, committed third-party license inventories, bundle-drift tests, and a pre-install local-Action smoke step now gate CI and releases. Moving Action tags no longer trigger duplicate npm publications.
• Dependency hardening: the transitive PostCSS version is refreshed past its source-map path-traversal advisory, leaving npm audit clean.

• Project Tailwind wins: canonicalization now uses the Tailwind v4 installation resolved from the scanned project's working directory, with bundled Tailwind 4.3.3 retained as the zero-config fallback.
• Older v4 projects stay semantically stable: Tailwind 4.1/4.2 projects no longer receive 4.3-only rewrites such as the new system-font stack collapsing to their older font-sans value. Snapshot and disk-cache entries are accepted only when their Tailwind version matches the active engine.
• Safe Tailwind 4.0 behavior: shorthand auditing remains available, while arbitrary-value canonicalization becomes a no-op because Tailwind 4.0 does not expose the required canonicalization API.
• Compatibility regression coverage: the pre-push suite now proves both project-local engine selection and the Tailwind 4.0 no-op fallback without requiring network access.

• Tailwind CSS 4.3.3 support: NormWind now bundles and validates against the current Tailwind 4.3 patch while retaining Node 20 compatibility.
• Canonical snapshot regenerated: the bundled reference now contains 12,438 replacements generated by Tailwind 4.3.3. Its new case-insensitive arbitrary hex-color canonicalization (bg-[#FFF] → bg-white) is covered by an end-to-end regression.
• Dependency automation fixed: routine minor/patch updates remain grouped, Tailwind updates get dedicated compatibility PRs, and the incompatible Babel 8 / eslint-plugin-tailwindcss 4 majors are deferred while Node 20 and the current group-data integration remain supported.
• GitHub Actions update: actions/setup-node v7 is adopted at a full commit SHA after passing the complete Ubuntu/Windows and Node 20/22 matrix.

• Syntax-aware extraction: JavaScript, TypeScript, JSX, and TSX are parsed before class strings are collected, while Vue SFC template/script boundaries are tracked structurally. Comments, serialized markup, regex literals, interpolations outside class props, and unrelated { class: "..." } data objects are no longer audit/fix candidates. Render-prop objects remain supported for recognized h/createElement/JSX-runtime calls and imported aliases.
• Fail-closed autofix: unparseable source, oversized files, read/stat failures, symlinks, concurrent editor saves, and per-file transform/write failures are surfaced with exit 2; unsafe files are left untouched while independent files continue. Atomic rewrites preserve Unix mode bits.
• Bounded canonicalization and cache validation: live Tailwind canonicalization is capped, on-disk cache data is type/size validated, stale snapshot entries are compacted away, and cache replacement is atomic. Generated canonical data now encodes candidate spaces correctly and includes an arbitrary-color regression.
• Audit/fix parity: reverse size shorthands, arbitrary variants, equal width/height values, and named theme-variable import ordering now follow the same matching rules in audit and fix paths.
• Target and output correctness: explicit directories and glob patterns are unioned, lintedFiles reflects successfully scanned files, skipped/failed work is summarized, and --dry-run --json keeps stdout machine-readable.
• Release and CI hardening: GitHub Actions are commit-SHA pinned with least-privilege permissions and timeouts, Dependabot covers npm and Actions, the release helper validates strict SemVer, stages/pushes exact release refs atomically, keeps GitHub credentials out of remotes/arguments, rolls back failed bumps, and uses network timeouts.

• Fault-isolated --fix/--fixall: a per-file try/catch means one EBUSY/EPERM/transform throw no longer aborts the whole batch; a fixed/skipped/failed summary prints, with a distinct exit code when anything failed.
• Unified audit/fix classifiers: isLikelyTailwindUtility/isLikelyFixUtility and matchUtilityToBody/matchFixBodyValue now share matching logic (bracket-variant and bare-body parity), closing gaps where --fix missed findings the audit reported.
• --dry-run: pair with --fix/--fixall to see which files would be rewritten without touching disk.
• Scanner guards: the fallback walker now skips oversized files and detects symlink loops instead of hanging or erroring.
• Corner and four-sides family merger rewritten: the fixer now uses the same family-table clustering the audit uses, so corner pairs (rounded-tl + rounded-tr → rounded-t), border side pairs (border-t + border-b → border-y), and complete four-sides sets (rounded-t/r/b/l → rounded, border-t/r/b/l → border) converge instead of persisting as unfixable findings.

• New brand: NormWind logo, wordmarks, and share card (assets/), plus a redesigned README.
• MIT LICENSE file added (the package always declared MIT; now the text ships too).
• Brand assets live in the repo only: the npm tarball stays lean (bin, canonical snapshot, README, LICENSE).

• npm publishing moved to GitHub Actions with provenance. Pushing a v* tag triggers the Release workflow, which re-runs the full test suite and then npm publish --provenance: packages now carry a verified build attestation linking them to this repo, commit, and workflow. scripts/release.py still drives the release locally (tests, bump, tag, GitHub release) but now waits for the Actions publish and verifies the version is live on the registry; --publish-locally remains as a fallback. Local releases no longer need an npm token.
• Line-ending hardening in the shipped binary. The --check-canonical drift check is tolerant of CRLF checkouts (git autocrlf on fresh Windows clones previously failed it), and .gitattributes pins the generated artifacts to LF. The v3.4.0 npm tarball already contained this fix; the tag now does too.
• release.py pre-flight hardening: validates GitHub credentials (with gh CLI token fallback) before any mutation, runs the npm dry-run at the new version, never echoes tokens, and always restores the clean git remote URL.

• Anchored class-string extraction: audit and fix now only inspect class=, className=, :class=, and v-bind:class= attribute values (quoted or JSX-brace form, including nested quoted strings inside bindings and static template-literal chunks) plus the object-property form { class: "..." } / { className: "..." }. The previous behavior (scanning every quoted string in a file) is gone; it could rewrite unrelated code such as SQL strings, title="..." text, or data-class attributes. Attribute names that merely end in -class are excluded.
• One shared extractor: audit and fix now use the same extraction path, so "audit clean" guarantees "--fix is a no-op." Class strings containing a bare * outside [...]/(...) brackets are conservatively skipped by both.
• Atomic writes: --fix/--fixall now write through a temp file + rename, so a crash mid-write can no longer truncate a source file.
• Order-independent padding merge: pt-4 pb-4 pl-4 pr-4 now fully merges to p-4 regardless of declaration order (previously order-dependent).
• Template literals: ${...} interpolations no longer disqualify the whole literal; static chunks are still audited/fixed, and partial tokens straddling an interpolation boundary (e.g. h-${size}) are never touched.
• New flags: -v/--version prints the version and exits 0. Unknown flags now error with exit 2 instead of being silently ignored. A --theme-css with a missing value errors; a --theme-css path that can't be read now fails loud (exit 2) instead of silently disabling the feature. Patterns that match no files print a warning.
• -h now works: previously only --help was recognized.
• Documented exit codes: 0 no findings, 1 findings, 2 usage/runtime error.
• Version banner fixed: the CLI now reads its version from package.json at runtime instead of a hardcoded string (the banner had been stuck on v3.1.1 for two releases).
• Portable canonical artifacts: docs/reference/canonical-replacements.* no longer embed an absolute machine path or the tool version, so npm test/--check-canonical passes on any machine.
• File discovery fixes: ripgrep returning "no matches" is no longer misread as "ripgrep is missing"; the no-rg fallback now applies glob patterns properly, and its ignore list matches ripgrep's (.venv and .git added).
• Trailer text: the text report's trailer no longer references npm run lint (a project-specific script); it now suggests --fix/--fixall.

• Direct-theme-key resolver: --suggest-named-theme-vars now collapses utilities that reference a registered @theme variable directly (e.g. border-(--color-ink-400)/40, text-(--color-ink-700), rounded-[var(--radius-sm)]) to the named form (border-ink-400/40, text-ink-700, rounded-sm). Previously the resolver only handled the forwarder pattern; it now also handles the direct pattern where the project authors the theme key itself. The CSS rule-body equivalence check still gates every emitted suggestion, so safety is unchanged.
• Modifier-aware: opacity-style modifiers such as /40 and ! important markers now flow through the named-theme-var resolver: border-(--color-ink-400)/40 round-trips to border-ink-400/40 instead of being silently skipped.
• Bracket-form audit coverage: the audit's arbitrary-token regex now matches an optional trailing /<modifier> suffix, so tokens like border-[var(--color-ink-400)]/40 reach the canonicalizer. The audit also chains Tailwind's canonicalizer into the named-theme resolver, so a single finding emits the most specific safe rewrite.
• Theme CSS auto-engages the resolver during fix: --fix/--fixall now apply named-theme-var rewrites whenever --theme-css is provided; the explicit --suggest-named-theme-vars flag is no longer required at fix time.
• Order-agnostic w/h → size shorthand: height-first authoring (h-5 w-5, hover:h-8 hover:w-8) now collapses to size-5, hover:size-8 alongside the width-first form.
• Multi-line class strings with data-[state=…]: variants are no longer skipped: the operator-character heuristic now ignores characters inside Tailwind's […] and (…) brackets, so attribute-style variants such as data-[state=open]:text-(--color-ink-1000) and aria-[expanded=true]:rotate-180 no longer suppress fixes.
• New regression fixtures: reverse-size-shorthand, multiline-with-data-attr, and named-theme-var-direct. The regression harness now auto-supplies --theme-css/--suggest-named-theme-vars for any fixture that ships a sibling theme.css, and the prepush gate counts fixtures dynamically.

• Vue dynamic bindings: the class-attribute extractor now matches :class="…" and v-bind:class="…" in addition to plain class="…", so utilities embedded in Vue ternaries and object/array bindings are audited and fixed alongside their static siblings.
• Multi-line class attributes: the extractor no longer terminates at the first newline, so class lists wrapped across multiple lines (common in templates and JSX) are picked up in full.
• Internal refactor: class-string extraction was split into focused helpers for readability; no behavior change beyond the two items above.
• Packaging hygiene: the files whitelist lists bin/normwind.mjs explicitly, and the prepush gate fails the publish if any *.bak/*.orig/*.swp/*.tmp straggler lands in the tarball.
• Single source of truth: the parent/repo-clone wrapper layout collapsed into a single flat repo; bin/normwind.mjs is the only CLI source.

• --suggest-named-theme-vars flag (opt-in): detects utility-(--var-name) classes and, when the project's @theme defines a single-step forwarder, suggests (or rewrites with --fixall) the equivalent named-theme class.
• --theme-css <path> flag: points NormWind at your Tailwind entry CSS; it recursively inlines local @import directives so a re-exporting style.css is fully resolved. Package imports like @import "tailwindcss" are skipped.
• Hash-namespaced resolver cache: the on-disk cache key is themevar:<sha1(resolvedCss)>:<rawToken>, so two projects with disagreeing forwarders never poison each other's cache.
• Fail-loud on missing @theme: a one-line diagnostic instead of silently producing zero suggestions.
• Runtime-equivalence gating: suggestions are emitted only when both candidates compile to byte-equivalent CSS rule bodies.
• Single-token paren-form support in .vue files, and zero default change when the flag is omitted.

• Bundled canonical snapshot: ships docs/reference/canonical-replacements.json (12,069 entries) generated from Tailwind's own designSystem.canonicalizeCandidates engine; no cold boot on first run.
• --check-canonical flag: exits 1 when the bundled snapshot is missing or stale; CI-suitable.
• canonical:extract / canonical:check scripts: the maintainer workflow for regenerating and verifying the snapshot.
• 7-fixture regression harness, live-vs-snapshot parity test, and a 7-check pre-push suite.
• Tailwind v4 note: documents why the eslint-plugin-tailwindcss rule is bypassed under v4.

Initial public release. Shorthand auditor and autofixer for Tailwind CSS utility classes.