tailwind-canonical 0.6.0 → 0.7.1

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
 
@@ -50,7 +50,7 @@ For pre-commit automation, see the [Pre-commit hook](#pre-commit-hook-husky--lef
 ## CLI
 
 ```bash
-# Scaffold a tailwind-canonical.config.ts in the current directory
+# Scaffold a config in the current directory (.ts, or .js/.mjs on older Node)
 npx tailwind-canonical init
 
 # Check for non-canonical arbitrary values
@@ -140,6 +140,11 @@ npx tailwind-canonical --fix --reporter json ./src
 npx tailwind-canonical --reporter sarif ./src > results.sarif
 ```
 
+Each result's `artifactLocation.uri` is relative to the git root (falling back to the working
+directory), with `uriBaseId: "%SRCROOT%"`, so Code Scanning maps it from any subdirectory.
+Results also carry `level`, a full `region` (start/end column) and line-independent
+`partialFingerprints`; `tool.driver.version` records the emitting version.
+
 **GitHub Actions integration:**
 ```yaml
 - run: npx tailwind-canonical --reporter sarif ./src > results.sarif
@@ -349,13 +354,63 @@ 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` | Built-in extra token |
-| `text-[8px]`–`text-[10px]` | `text-3xs` | Built-in extra token |
+| `text-[11px]` | `text-2xs` | Requires `customTextTokens` |
+| `text-[8px]`–`text-[10px]` | `text-3xs` | Requires `customTextTokens` |
 
-`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`.
+`text-2xs` and `text-3xs` are not stock Tailwind tokens, so they are not in the built-in text size map — without config, `text-[11px]` and `text-[8px]`–`text-[10px]` are left untouched. Enable them with `customTextTokens`:
+
+```ts
+export default { customTextTokens: { 8: '3xs', 9: '3xs', 10: '3xs', 11: '2xs' } }
+```
 
 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:
@@ -369,6 +424,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
@@ -420,8 +477,15 @@ 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
@@ -429,10 +493,6 @@ 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
@@ -531,15 +591,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

@@ -1,13 +1,5 @@
-export type Sink = {
-    log: (s: string) => void;
-    error: (s: string) => void;
-    write: (s: string) => void;
-};
-export type RunResult = {
-    exitCode: number;
-    watching?: boolean;
-};
-type Reporter = 'text' | 'json' | 'sarif';
+import type { Reporter, RunResult, Sink } from './types.js';
+export type { RunResult, Sink } from './types.js';
 type Flags = {
     fix: boolean;
     merge: boolean;
@@ -37,5 +29,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