tailwind-canonical 0.5.0 → 0.7.0

package/README.md

@@ -2,7 +2,7 @@
 
 Lint and auto-fix Tailwind CSS classes: arbitrary values → canonical, deduplication, shorthand collapsing, and class sorting.
 
-> Compatible with Tailwind CSS v3.3+ and v4 — zero `tailwindcss` dependency (conventions are built in). Custom theme tokens are supported via config.
+> Compatible with Tailwind CSS v4 out of the box, and with v3.3+ via [`tailwindVersion: 3`](#tailwind-v3-vs-v4-tailwindversion) — the ÷4 spacing rule assumes v4's dynamic scale, so v3 projects must set it. Zero `tailwindcss` dependency (conventions are built in). Custom theme tokens are supported via config.
 
 ## Install
 
@@ -12,9 +12,47 @@ npm install -D tailwind-canonical
 yarn add -D tailwind-canonical
 ```
 
+## Quick start
+
+First scan to see what needs fixing:
+```bash
+npx tailwind-canonical ./src
+```
+
+Create a config file to make the full pipeline re-runnable:
+```ts
+// tailwind-canonical.config.ts
+export default {
+  defaultCommand: {
+    fix: true,
+    dedup: true,
+    sort: true,
+    typos: true,
+    targets: ['./src'],
+  },
+}
+```
+
+Now run the whole pipeline with a single command:
+```bash
+npx tailwind-canonical
+```
+
+For ESLint integration, add to your flat config:
+```js
+import tailwindCanonical from 'tailwind-canonical/eslint'
+
+export default [tailwindCanonical.configs.recommended]
+```
+
+For pre-commit automation, see the [Pre-commit hook](#pre-commit-hook-husky--lefthook) section below.
+
 ## CLI
 
 ```bash
+# Scaffold a config in the current directory (.ts, or .js/.mjs on older Node)
+npx tailwind-canonical init
+
 # Check for non-canonical arbitrary values
 npx tailwind-canonical ./src
 
@@ -38,6 +76,9 @@ npx tailwind-canonical --merge ./src
 # Combine: fix → dedup → merge → sort
 npx tailwind-canonical --fix --dedup --merge --sort ./src
 
+# Dry-run: report what the transforms would change, write nothing
+npx tailwind-canonical --check --fix --dedup --sort ./src
+
 # Cross-file consistency analysis
 npx tailwind-canonical --analyze ./src
 
@@ -63,6 +104,7 @@ An unmatched target exits `1` with `No files matched: <targets>`.
 | `--dedup` | Redundant classes, conflicts, shorthand collapse | `flex block` → `block`, `px-4 py-4` → `p-4`, `border-t-2 border-b-2` → `border-y-2` |
 | `--sort` | Canonical class order | `text-sm flex p-4` → `flex p-4 text-sm` |
 | `--merge` | tailwind-merge conflict resolution | `bg-red-500 bg-blue-500` → `bg-blue-500` |
+| `--check` | Dry-run: report what the combined transforms would change, write nothing (exit 1 on pending changes) | `would fix src/Button.tsx (1 replacement)` |
 | `--analyze` | Cross-file consistency (color variants, scale drift, repeated patterns) | `Warning: 3 red color variants used for text: text-red-500, text-rose-500, text-red-600` |
 | `--watch` | Re-run on every file save (debounced 50ms) | `[12:34:01] src/Button.tsx — 2 changes applied` |
 | `--typos` | Likely misspelled color names (read-only; chains after transforms) | `text-gry-500` → `text-gray-500` [typo] |
@@ -98,6 +140,15 @@ npx tailwind-canonical --fix --reporter json ./src
 npx tailwind-canonical --reporter sarif ./src > results.sarif
 ```
 
+**GitHub Actions integration:**
+```yaml
+- run: npx tailwind-canonical --reporter sarif ./src > results.sarif
+  continue-on-error: true
+- uses: github/codeql-action/upload-sarif@v3
+  with:
+    sarif_file: results.sarif
+```
+
 ## Typo detection (`--typos`)
 
 Flags likely misspelled Tailwind color names (Levenshtein distance 1, low false-positive bias). Read-only.
@@ -124,6 +175,23 @@ npx tailwind-canonical --fix --dedup --sort --typos ./src
 
 Exit code follows the typo scan (`1` on findings). With `--reporter json` the transform summary gains `typoTotal` and `typos` fields. `--analyze` remains exclusive: combining it with any other mode runs analyze only and warns. `--watch` is not supported with `--typos` (warned, single pass runs instead).
 
+## Dry-run mode (`--check`)
+
+Combine `--check` with any of `--fix`/`--dedup`/`--merge`/`--sort` to report what those transforms would change without writing anything to disk. Useful as a CI gate:
+
+```yaml
+# CI
+- run: npx tailwind-canonical --check --fix --dedup --sort ./src
+```
+
+```bash
+npx tailwind-canonical --check --fix --dedup --sort ./src
+#   would fix src/Button.tsx (1 replacement)
+#   ✖ 1 pending change across 1 file (run without --check to apply)
+```
+
+Exits `1` when any file would change (blocking the pipeline), `0` when the tree is already canonical. `--check` requires at least one transform flag; `--check` alone errors. `--analyze` takes priority over `--check` (warned, ignored). `--watch` is not supported with `--check` (warned, single pass runs instead). `--typos` still chains after the check pass since it's read-only. With `--reporter json` the transform report gains `"check": true`.
+
 ## Suppression comments
 
 Skip specific lines or blocks from check and all transforms (`--fix`, `--dedup`, `--merge`, `--sort`):
@@ -288,6 +356,52 @@ left-2 right-2                  → inset-x-2
 
 Non-divisible values (`h-[22px]`, `px-[7px]`) are left untouched.
 
+### Tailwind v3 vs v4 (`tailwindVersion`)
+
+The ÷4 spacing rule assumes the **v4** scale, where every step is derived from
+`calc(var(--spacing) * n)` and any integer works. v3 ships a discrete scale, so
+`p-[52px]` → `p-13` compiles to nothing at all on v3 and the padding silently
+disappears. Set `tailwindVersion: 3` on a v3 project:
+
+```ts
+export default {
+  tailwindVersion: 3, // default: 4
+}
+```
+
+In v3 mode, suggestions are restricted to what v3.3 actually generates — the
+scale differs per utility, not just per family:
+
+| Class | `tailwindVersion: 4` | `tailwindVersion: 3` |
+|---|---|---|
+| `p-[16px]` | `p-4` | `p-4` |
+| `p-[52px]` | `p-13` | untouched — not on the v3 scale |
+| `max-w-[16px]` | `max-w-4` | untouched — scale arrived after v3.3 |
+| `max-w-[0px]` | `max-w-0` | `max-w-0` — the zero step does exist |
+| `size-[16px]` | `size-4` | untouched — no scale at all in v3.3 |
+| `max-h-[16px]` | `max-h-4` | `max-h-4` |
+| `max-w-[50%]` | `max-w-1/2` | untouched — no fractions in v3.3 |
+| `top-[20%]` | `top-1/5` | untouched — v3.3 stops at quarters here |
+| `top-[25%]` | `top-1/4` | `top-1/4` |
+| `w-[8.333333%]` | `w-1/12` | `w-1/12` — `w` carries the full set |
+
+Spacing steps: `size-*` has no numeric scale in v3.3, and `min-w-*`, `max-w-*`
+and `min-h-*` only ship the zero step — they gained the scale afterwards.
+Fractions: `w` carries all thirteen, `h` stops at sixths, `inset`/`top`/`left`/
+`right`/`bottom`/`translate-x`/`translate-y` only have halves, thirds and
+quarters, and `min-w`/`max-w`/`min-h`/`max-h` have none.
+
+`text-*`, `rounded-*` and `opacity-*` are identical in both majors and are
+never gated. `customSpacingTokens` stays your decision and is applied in both
+modes. All of the above was measured against `tailwindcss@3.3.7`, the
+advertised floor.
+
+**On v3.4**, keep `tailwindVersion: 3`. v3.4 added the numeric scale to
+`size-*`, `min-w-*`, `max-w-*` and `min-h-*`, but its spacing scale is still
+discrete — `p-13` does not exist there either. So v3 mode is the safe setting
+and merely leaves a few v3.4-valid suggestions on the table; `tailwindVersion:
+4` would emit steps v3.4 cannot generate.
+
 ## Config
 
 Create `tailwind-canonical.config.ts` at the root:
@@ -301,6 +415,8 @@ export default {
   customSpacingTokens: {
     14: '3.5',
   },
+  // Target Tailwind major: 3 restricts suggestions to the v3 scale (default: 4)
+  tailwindVersion: 4,
   // Support non-React attribute patterns (default: ['className'])
   attributeNames: ['className', 'class', ':class', 'tw'],
   // Support utility function wrappers
@@ -311,6 +427,7 @@ export default {
     dedup: true,
     merge: true,
     sort: true,
+    check: false, // dry-run mode: report changes without writing (useful for CI)
     targets: ['./src'],
   },
   // Tune --analyze reporting
@@ -338,7 +455,7 @@ export default {
 above, running `tailwind-canonical` is equivalent to
 `tailwind-canonical --fix --dedup --merge --sort ./src`. Explicit CLI flags and
 targets still override the config, so `tailwind-canonical --typos ./app` runs
-only typo detection on `./app`.
+only typo detection on `./app`. Supported keys: `fix`, `dedup`, `merge`, `sort`, `check`, `analyze`, `typos`, `watch`, `reporter`, `targets`.
 
 `analyze` controls project-scale consistency reporting. `maxScaleGroups`,
 `maxScaleValues`, `maxRareValues`, and `maxPatterns` keep terminal output
@@ -351,8 +468,21 @@ files and at most 3 times.
 The older top-level rare-value keys are still accepted for compatibility, but
 new configs should prefer `analyze`.
 
-`tailwind-canonical.config.js` is still loaded as a fallback when no TypeScript
-config exists.
+Accepted filenames, in resolution order: `tailwind-canonical.config.ts`,
+`.mts`, `.js`, `.mjs`.
+
+A `.ts` or `.mts` config needs Node's type stripping, which is on by default
+from Node 22.18 and 23.6, and available behind `--experimental-strip-types`
+from 22.6. Short of that use `.mjs`, or `.js` when your nearest `package.json`
+declares `"type": "module"`; both load on every supported Node. `tailwind-
+canonical init` scaffolds a filename that loads on a bare `node` — it will not
+write `.ts` just because the process it runs in happens to carry the flag.
+
+The config is resolved upward from the current directory: if no config file is
+found in `cwd`, tailwind-canonical checks each parent directory in turn, until
+it finds one, reaches a `.git` directory, or reaches the filesystem root. This
+makes the CLI monorepo-friendly — a single config at the repo root applies to
+every package.
 
 ## ESLint plugin
 
@@ -401,6 +531,12 @@ It **accepts but ignores**: `functionNames`, `attributeNames`, `sortOrder`.
 These are CLI-only options, allowed in the schema purely so a single shared
 config object can be passed without errors.
 
+## Known limits
+
+- **`--watch` does not pick up files created after start** — the watcher initializes a file list once and monitors only existing files for changes. New files in the target directories are not detected until the watcher is restarted.
+- **`--typos` covers Tailwind color names only** — color-name detection uses Levenshtein distance 1 against the built-in Tailwind color palette. Custom colors from your config are supported via `extraColors` in the config, but typo detection does not extend to properties, function names, or arbitrary modifiers.
+- **`--merge` requires `tailwind-merge` as a peer dependency** — the plugin is optional, so the CLI will error if you use `--merge` without installing `tailwind-merge`. Install with `pnpm add -D tailwind-merge`.
+
 ## Pre-commit hook (Husky / Lefthook)
 
 ```yaml
@@ -423,6 +559,17 @@ pre-commit:
 npx tailwind-canonical --fix --dedup --sort ./src ./app
 ```
 
+### lint-staged
+
+```jsonc
+// package.json
+{
+  "lint-staged": {
+    "*.{jsx,tsx}": ["tailwind-canonical --fix --dedup --sort --typos"]
+  }
+}
+```
+
 ## Dead code detection (knip)
 
 ```bash
@@ -435,15 +582,37 @@ Detects unused exports, files, and dependencies. Config in `knip.json`. Enforced
 
 ```ts
 import {
-  suggestCanonical,   // pure: class string → suggestion or null
-  analyzeFile,        // find non-canonical classes in a file
-  fixFile,            // apply --fix in-place
-  deduplicateClasses, // pure: deduplicate a class string
-  dedupeFile,         // apply --dedup in-place
-  sortClasses,        // pure: sort a class string
-  sortFile,           // apply --sort in-place
-  mergeFile,          // apply --merge in-place (requires tailwind-merge)
-  scanFiles,          // recursive file scanner (sync, dir/file targets)
-  resolveTargets,     // async glob resolver with negation + brace expansion
+  suggestCanonical,    // pure: class string → suggestion or null
+  analyzeFile,         // find non-canonical classes in a file
+  fixFile,             // apply --fix in-place
+  deduplicateClasses,  // pure: deduplicate a class string
+  dedupeFile,          // apply --dedup in-place
+  sortClasses,         // pure: sort a class string
+  sortFile,            // apply --sort in-place
+  DEFAULT_SORT_ORDER,  // default sort category order (override via config sortOrder)
+  mergeFile,           // apply --merge in-place (requires tailwind-merge)
+  scanFiles,           // recursive file scanner (sync, dir/file targets)
+  resolveTargets,      // async glob resolver with negation + brace expansion
+  loadConfig,          // load + validate tailwind-canonical.config.{ts,mts,js,mjs} for a cwd
+  analyzeConsistency,  // pure: cross-file consistency analysis (--analyze)
+  analyzeTyposFile,    // find likely color-name typos in a file
+  detectTypo,          // pure: check one class for a likely color-name typo
+} from 'tailwind-canonical'
+
+import type {
+  Config,             // shared config object accepted across the API
+  Suggestion,         // suggestCanonical's non-null return shape
+  Finding,            // one entry returned by analyzeFile
+  ScanOptions,        // extensions/ignore options for scanFiles/resolveTargets
+  SortCategory,       // one entry of DEFAULT_SORT_ORDER / config.sortOrder
+  TypoFinding,        // one entry returned by analyzeTyposFile
+  ConsistencyOptions, // options accepted by analyzeConsistency
+  ConsistencyReport,  // analyzeConsistency's return shape
+  FileClasses,        // per-file input shape for analyzeConsistency
+  ColorVariant,       // one variant inside a ConsistencyReport color group
+  ColorVariantGroup,  // one color-family group in ConsistencyReport.colorVariants
+  ScaleInconsistency, // one entry in ConsistencyReport.scaleInconsistencies
+  ScaleValue,         // one value inside a ScaleInconsistency
+  ClassCombination,   // one repeated-pattern entry in ConsistencyReport.combinations
 } from 'tailwind-canonical'
 ```

package/dist/cli/cli.d.ts

@@ -16,6 +16,7 @@ type Flags = {
     watch: boolean;
     analyze: boolean;
     typos: boolean;
+    check: boolean;
     help: boolean;
     version: boolean;
     reporter: Reporter;
@@ -24,6 +25,7 @@ type Flags = {
     hasExplicitMode: boolean;
     hasExplicitReporter: boolean;
     hasExplicitWatch: boolean;
+    hasExplicitCheck: boolean;
 };
 export declare function parseArgs(argv: string[]): Flags;
 /**
@@ -36,4 +38,3 @@ export declare function parseArgs(argv: string[]): Flags;
 export declare function flagWarnings(flags: Flags): string[];
 export declare function run(argv: string[], cwd: string, sink?: Sink): Promise<RunResult>;
 export {};
-//# sourceMappingURL=cli.d.ts.map