tailwind-canonical 0.3.0 → 0.4.1

package/README.md

@@ -2,6 +2,8 @@
 
 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.
+
 ## Install
 
 ```bash
@@ -89,6 +91,18 @@ npx tailwind-canonical --fix --reporter json ./src
 npx tailwind-canonical --reporter sarif ./src > results.sarif
 ```
 
+## Typo detection (`--typos`)
+
+Flags likely misspelled Tailwind color names (Levenshtein distance 1, low false-positive bias). Read-only.
+
+```bash
+npx tailwind-canonical --typos ./src
+#   src/Card.tsx:3:17  text-gry-500 → text-gray-500 [typo]
+#   src/Nav.tsx:8:12   bg-slte-100 → bg-slate-100 [typo]
+```
+
+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.
+
 ## Suppression comments
 
 Skip specific lines or blocks from check and all transforms (`--fix`, `--dedup`, `--merge`, `--sort`):
@@ -111,9 +125,19 @@ Detects semantic inconsistencies visible only at project scale — it never modi
 
 ```bash
 npx tailwind-canonical --analyze ./src
-# Warning: 3 red color variants used for text: text-red-500 (4), text-rose-500 (1), text-red-600 (2)
-# Warning: px inconsistency: px-4 (8 files) vs px-3 (2 files)
-# Warning: z inconsistency: z-[100] (3 files) vs z-[200] (1 file) vs z-[50] (2 files)
+# tailwind-canonical analyze
+# Files analyzed: 42
+# Issue groups: 3 (1 color, 2 scales, 0 patterns)
+#
+# Color variants
+#   - text/red: text-red-500 x4, text-rose-500 x1
+#
+# Scale inconsistency groups
+#   - px: 2 values, 10 uses, 10 files
+#     Top: px-4 (8 uses, 8 files), px-3 (2 uses, 2 files)
+#
+# Rare scale values
+#   - px-11: 3 uses in 1 file (608 px uses total); e.g. src/Dialog.tsx
 ```
 
 Three detectors:
@@ -122,6 +146,7 @@ Three detectors:
 |---|---|
 | Color variants | Multiple shades/colors of the same hue family used for one property (`text`, `bg`, `border`, …) |
 | Scale inconsistency | Competing values for the same spacing / `gap` / `z` property across files |
+| Rare scale values | Low-frequency scale values inside otherwise common properties (`ml-13`, `gap-24`, `px-11`, …) |
 | Repeated patterns | Identical class combinations recurring across 3+ files |
 
 Pairs with `--reporter json` for machine-readable output. Exits `1` when any inconsistency is found.
@@ -146,6 +171,10 @@ npx tailwind-canonical --analyze --reporter json ./src
         { "value": "3", "count": 2, "files": ["src/IconButton.tsx"] }
       ] }
   ],
+  "rareScaleValues": [
+    { "property": "px", "value": "11", "className": "px-11",
+      "count": 3, "files": ["src/Dialog.tsx"], "propertyCount": 608 }
+  ],
   "combinations": []
 }
 ```
@@ -168,8 +197,8 @@ Variants (`hover:`, `sm:`, `focus:`) are sorted after base classes, with respons
 
 Override the category order via config. Categories you omit (and unknown classes) sort to the end, preserving their original relative order. Variants are always sorted after base classes regardless of order.
 
-```js
-// tailwind-canonical.config.js
+```ts
+// tailwind-canonical.config.ts
 export default {
   sortOrder: [
     'display',
@@ -231,15 +260,18 @@ left-2 right-2                  → inset-x-2
 | `h-[64px]` | `h-16` | Spacing scale ÷4 |
 | `w-[50%]` | `w-1/2` | Percentage fractions |
 | `opacity-[0.5]` | `opacity-50` | Opacity scale |
-| `text-[11px]` | `text-2xs` | Custom token |
+| `text-[11px]` | `text-2xs` | Built-in extra token |
+| `text-[8px]`–`text-[10px]` | `text-3xs` | Built-in extra token |
+
+`text-2xs` (11px) and `text-3xs` (8–10px) are part of the built-in text size map — they convert with no config. Override or extend the map via `customTextTokens`.
 
 Non-divisible values (`h-[22px]`, `px-[7px]`) are left untouched.
 
 ## Config
 
-Create `tailwind-canonical.config.js` at the root:
+Create `tailwind-canonical.config.ts` at the root:
 
-```js
+```ts
 export default {
   customTextTokens: {
     10: '3xs',
@@ -252,6 +284,16 @@ export default {
   attributeNames: ['className', 'class', ':class', 'tw'],
   // Support utility function wrappers
   functionNames: ['cn', 'clsx', 'cva'],
+  // Tune --analyze reporting
+  analyze: {
+    maxScaleGroups: 8,
+    maxScaleValues: 5,
+    maxRareValues: 12,
+    maxPatterns: 10,
+    minRareScalePropertyOccurrences: 10,
+    rareScaleMaxFiles: 2,
+    rareScaleMaxCount: 3,
+  },
   // Never suggest replacements for classes matching these patterns
   ignorePatterns: [/^font-/, /-\[var\(/],
 }
@@ -263,6 +305,20 @@ export default {
 
 `functionNames` enables scanning inside utility function calls like `cn(...)` and `clsx(...)`.
 
+`analyze` controls project-scale consistency reporting. `maxScaleGroups`,
+`maxScaleValues`, `maxRareValues`, and `maxPatterns` keep terminal output
+compact. `minRareScalePropertyOccurrences`, `rareScaleMaxFiles`, and
+`rareScaleMaxCount` control which low-frequency values are surfaced as rare
+scale values. Defaults are conservative: only properties with 10+ total
+occurrences are considered, and a value is rare when it appears in at most 2
+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.
+
 ## ESLint plugin
 
 ```js
@@ -281,6 +337,26 @@ export default [
 ]
 ```
 
+### Rule options
+
+`no-arbitrary-canonical` accepts the full tailwind-canonical `Config` object as
+its rule options, so the same shared config can be reused for both the CLI and
+ESLint without schema errors:
+
+```js
+'tailwind-canonical/no-arbitrary-canonical': [
+  'warn',
+  { customTextTokens: { 11: '2xs' }, ignorePatterns: [/^font-/] },
+],
+```
+
+The rule **honors**: `customTextTokens`, `customSpacingTokens`, `ignorePatterns`
+(all applied via `suggestCanonical`).
+
+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.
+
 ## Pre-commit hook (Husky / Lefthook)
 
 ```yaml
@@ -309,7 +385,7 @@ npx tailwind-canonical --fix --dedup --sort ./src ./app
 pnpm knip
 ```
 
-Detects unused exports, files, and dependencies. Config in `knip.json`.
+Detects unused exports, files, and dependencies. Config in `knip.json`. Enforced in CI and in the `pre-push` git hook.
 
 ## Programmatic API
 

package/dist/cli/cli.d.ts

@@ -3,7 +3,6 @@ export type Sink = {
     error: (s: string) => void;
     write: (s: string) => void;
 };
-export declare const defaultSink: Sink;
 export type RunResult = {
     exitCode: number;
     watching?: boolean;
@@ -16,10 +15,19 @@ type Flags = {
     sort: boolean;
     watch: boolean;
     analyze: boolean;
+    typos: boolean;
     reporter: Reporter;
     targets: string[];
+    error?: string;
 };
 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.
+ */
+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

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

@@ -1 +1 @@
-{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../../src/cli/cli.ts"],"names":[],"mappings":"AAmBA,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;AAEF,eAAO,MAAM,WAAW,EAAE,IAIzB,CAAC;AAEF,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,QAAQ,EAAE,QAAQ,CAAC;IACnB,OAAO,EAAE,MAAM,EAAE,CAAC;CACnB,CAAC;AAuBF,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,KAAK,CA2B/C;AAmJD,wBAAsB,GAAG,CACvB,IAAI,EAAE,MAAM,EAAE,EACd,GAAG,EAAE,MAAM,EACX,IAAI,GAAE,IAAkB,GACvB,OAAO,CAAC,SAAS,CAAC,CAgMpB"}
+{"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;CAChB,CAAC;AA2IF,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,KAAK,CAqD/C;AASD;;;;;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,CAqLpB"}