tailwind-canonical 0.4.2 → 0.6.0

package/README.md

@@ -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 tailwind-canonical.config.ts in the current directory
+npx tailwind-canonical init
+
 # Check for non-canonical arbitrary values
 npx tailwind-canonical ./src
 
@@ -38,17 +76,26 @@ 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
 
 # Watch mode: re-run on every file save
 npx tailwind-canonical --watch --fix --sort ./src
 
-# Structured output for CI (check mode only)
+# Structured output for CI (findings in check mode, summary in fix mode)
 npx tailwind-canonical --reporter json ./src
 npx tailwind-canonical --reporter sarif ./src
+
+# Help and version
+npx tailwind-canonical --help
+npx tailwind-canonical --version
 ```
 
+An unmatched target exits `1` with `No files matched: <targets>`.
+
 ## What each flag does
 
 | Flag | What it fixes | Example |
@@ -57,10 +104,12 @@ npx tailwind-canonical --reporter sarif ./src
 | `--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] |
 | `--reporter json` | JSON output (check mode) or fix summary | machine-readable for CI pipelines |
-| `--reporter sarif` | SARIF 2.1.0 output (check mode) | GitHub Code Scanning / VS Code |
+| `--reporter sarif` | SARIF 2.1.0 output (findings in check/typos modes; transform mode emits an empty document unless `--typos` is chained) | GitHub Code Scanning / VS Code |
 
 ## Structured output (`--reporter`)
 
@@ -91,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.
@@ -103,6 +161,37 @@ npx tailwind-canonical --typos ./src
 
 Only color-property classes (`text-`, `bg-`, `border-`, …) are checked. Valid colors, non-color utilities (`text-center`), custom colors (`bg-brand-500`), and arbitrary values are never flagged. Pairs with `--reporter json`; exits `1` on findings.
 
+### Chaining with transforms
+
+`--typos` combines with `--fix`/`--dedup`/`--merge`/`--sort`: the mutating pass runs first, then the typo scan — one command for lint-staged/CI:
+
+```bash
+npx tailwind-canonical --fix --dedup --sort --typos ./src
+#   fixed  src/Button.tsx (1 replacement)
+#   ✓ Fixed 1 replacement, 2 dedups, 3 sorted across 12 files
+#   src/Card.tsx:3:17  text-gry-500 → text-gray-500 [typo]
+#   ✖ Found 1 likely typo
+```
+
+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`):
@@ -290,6 +379,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
@@ -317,7 +407,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
@@ -333,6 +423,16 @@ new configs should prefer `analyze`.
 `tailwind-canonical.config.js` is still loaded as a fallback when no TypeScript
 config exists.
 
+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.
+
+On Node 22.6–23.5, loading a `.ts` config requires `--experimental-strip-types`;
+from Node 23.6 onward it works natively; the `.js` fallback works on every
+supported Node version.
+
 ## ESLint plugin
 
 ```js
@@ -351,6 +451,15 @@ export default [
 ]
 ```
 
+Or use the bundled flat-config shortcut:
+
+```js
+// eslint.config.js
+import tailwindCanonical from 'tailwind-canonical/eslint'
+
+export default [tailwindCanonical.configs.recommended]
+```
+
 ### Rule options
 
 `no-arbitrary-canonical` accepts the full tailwind-canonical `Config` object as
@@ -371,6 +480,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
@@ -393,6 +508,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

package/dist/cli/cli.d.ts

@@ -16,19 +16,24 @@ type Flags = {
     watch: boolean;
     analyze: boolean;
     typos: boolean;
+    check: boolean;
+    help: boolean;
+    version: boolean;
     reporter: Reporter;
     targets: string[];
     error?: string;
     hasExplicitMode: boolean;
     hasExplicitReporter: boolean;
     hasExplicitWatch: boolean;
+    hasExplicitCheck: boolean;
 };
 export declare function parseArgs(argv: string[]): Flags;
 /**
- * Modes are mutually exclusive with a fixed precedence: analyze > typos >
- * transform/check. `--watch` is only honored in transform/check mode. This
- * computes warnings for every flag that the active mode will ignore. Pure and
- * order-stable so it can be unit-tested via the injectable sink.
+ * `--analyze` is exclusive: it suppresses transforms, `--typos`, and
+ * `--watch`. `--typos` chains after transforms (fix → dedup → merge → sort →
+ * typo scan) but does not support `--watch`. This computes warnings for every
+ * flag the active mode will ignore. Pure and order-stable so it can be
+ * unit-tested via the injectable sink.
  */
 export declare function flagWarnings(flags: Flags): string[];
 export declare function run(argv: string[], cwd: string, sink?: Sink): Promise<RunResult>;

package/dist/cli/cli.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../../src/cli/cli.ts"],"names":[],"mappings":"AAwBA,MAAM,MAAM,IAAI,GAAG;IACjB,GAAG,EAAE,CAAC,CAAC,EAAE,MAAM,KAAK,IAAI,CAAC;IACzB,KAAK,EAAE,CAAC,CAAC,EAAE,MAAM,KAAK,IAAI,CAAC;IAC3B,KAAK,EAAE,CAAC,CAAC,EAAE,MAAM,KAAK,IAAI,CAAC;CAC5B,CAAC;AAQF,MAAM,MAAM,SAAS,GAAG;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,OAAO,CAAA;CAAE,CAAC;AAEjE,KAAK,QAAQ,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC;AAE1C,KAAK,KAAK,GAAG;IACX,GAAG,EAAE,OAAO,CAAC;IACb,KAAK,EAAE,OAAO,CAAC;IACf,KAAK,EAAE,OAAO,CAAC;IACf,IAAI,EAAE,OAAO,CAAC;IACd,KAAK,EAAE,OAAO,CAAC;IACf,OAAO,EAAE,OAAO,CAAC;IACjB,KAAK,EAAE,OAAO,CAAC;IACf,QAAQ,EAAE,QAAQ,CAAC;IACnB,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,eAAe,EAAE,OAAO,CAAC;IACzB,mBAAmB,EAAE,OAAO,CAAC;IAC7B,gBAAgB,EAAE,OAAO,CAAC;CAC3B,CAAC;AAmJF,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,KAAK,CAwD/C;AA6CD;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,KAAK,GAAG,MAAM,EAAE,CAwBnD;AAgbD,wBAAsB,GAAG,CACvB,IAAI,EAAE,MAAM,EAAE,EACd,GAAG,EAAE,MAAM,EACX,IAAI,GAAE,IAAkB,GACvB,OAAO,CAAC,SAAS,CAAC,CAwLpB"}
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../../src/cli/cli.ts"],"names":[],"mappings":"AAgEA,MAAM,MAAM,IAAI,GAAG;IACjB,GAAG,EAAE,CAAC,CAAC,EAAE,MAAM,KAAK,IAAI,CAAC;IACzB,KAAK,EAAE,CAAC,CAAC,EAAE,MAAM,KAAK,IAAI,CAAC;IAC3B,KAAK,EAAE,CAAC,CAAC,EAAE,MAAM,KAAK,IAAI,CAAC;CAC5B,CAAC;AAQF,MAAM,MAAM,SAAS,GAAG;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,OAAO,CAAA;CAAE,CAAC;AAEjE,KAAK,QAAQ,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC;AAE1C,KAAK,KAAK,GAAG;IACX,GAAG,EAAE,OAAO,CAAC;IACb,KAAK,EAAE,OAAO,CAAC;IACf,KAAK,EAAE,OAAO,CAAC;IACf,IAAI,EAAE,OAAO,CAAC;IACd,KAAK,EAAE,OAAO,CAAC;IACf,OAAO,EAAE,OAAO,CAAC;IACjB,KAAK,EAAE,OAAO,CAAC;IACf,KAAK,EAAE,OAAO,CAAC;IACf,IAAI,EAAE,OAAO,CAAC;IACd,OAAO,EAAE,OAAO,CAAC;IACjB,QAAQ,EAAE,QAAQ,CAAC;IACnB,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,eAAe,EAAE,OAAO,CAAC;IACzB,mBAAmB,EAAE,OAAO,CAAC;IAC7B,gBAAgB,EAAE,OAAO,CAAC;IAC1B,gBAAgB,EAAE,OAAO,CAAC;CAC3B,CAAC;AAyJF,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,KAAK,CAqE/C;AAgDD;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,KAAK,GAAG,MAAM,EAAE,CAyBnD;AAgfD,wBAAsB,GAAG,CACvB,IAAI,EAAE,MAAM,EAAE,EACd,GAAG,EAAE,MAAM,EACX,IAAI,GAAE,IAAkB,GACvB,OAAO,CAAC,SAAS,CAAC,CA0RpB"}