tailwind-canonical 0.8.0 → 0.9.0

package/README.md

@@ -95,6 +95,17 @@ npx tailwind-canonical --version
 ```
 
 An unmatched target exits `1` with `No files matched: <targets>`.
+Directory and glob discovery skip symbolic links. An explicitly named file symlink remains supported and reads or changes its target.
+
+### Watch behavior
+
+Watch mode discovers new and recreated files, including targets from initially
+empty globs. It applies the same exclusions and symlink policy as single-pass
+runs. Configuration entry-file changes reload mappings, defaults and targets;
+invalid configuration pauses processing until it is corrected. Watch roots are
+collapsed to avoid overlapping recursive watchers. SIGINT/SIGTERM close watchers
+and pending timers; filesystem watcher failures are reported and stop the session
+with a nonzero exit code. Watch output is text only.
 
 ## What each flag does
 
@@ -106,7 +117,7 @@ An unmatched target exits `1` with `No files matched: <targets>`.
 | `--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` |
+| `--watch` | Re-run on every file save (debounced 50ms; text reporter only) | `[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 (findings in check/typos modes; transform mode emits an empty document unless `--typos` is chained) | GitHub Code Scanning / VS Code |
@@ -234,7 +245,7 @@ npx tailwind-canonical --analyze ./src
 #   - px-11: 3 uses in 1 file (608 px uses total); e.g. src/Dialog.tsx
 ```
 
-Three detectors:
+Four detectors:
 
 | Detector | What it flags |
 |---|---|
@@ -243,6 +254,11 @@ Three detectors:
 | 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 |
 
+Repeated patterns compare complete class strings, ignoring class order; they do not
+mine shared subsets inside larger strings. The programmatic `FileClasses` input
+can provide `classLists` to preserve those string boundaries. If omitted,
+`classes` is treated as one class string per file for backward compatibility.
+
 Pairs with `--reporter json` for machine-readable output. Exits `1` when any inconsistency is found.
 
 ```bash
@@ -459,6 +475,25 @@ 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.
 
+### Custom themes (`useDefaultTheme`)
+
+The default mappings assume Tailwind's stock theme and a 16px root font size for
+px/rem equivalences. If your theme changes these values, disable inferred mappings:
+
+```ts
+export default {
+  useDefaultTheme: false,
+  customTextTokens: { 12: 'tiny' },
+  customSpacingTokens: { 16: 'gutter' },
+}
+```
+
+Only explicitly configured pixel mappings are suggested in this mode:
+`text-[12px]` becomes `text-tiny`, `p-[16px]` becomes `p-gutter`, and other
+arbitrary values (including rem values) stay unchanged. The option is shared by
+the CLI, library and ESLint canonicalization rule. It does not load your Tailwind
+theme or customize the separate `tailwind-merge` conflict resolver.
+
 ## Config
 
 Create `tailwind-canonical.config.ts` at the root:
@@ -582,15 +617,27 @@ ESLint without schema errors:
 ```
 
 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.
+and `tailwindVersion` (all applied via `suggestCanonical`), plus
+`useDefaultTheme` to disable inferred mappings. It also uses
+`attributeNames` (default: `['className']`) and `functionNames` (default:
+`['cn', 'clsx', 'cva']`) to identify class strings. Other `Config` fields are
+accepted for shared configuration and have no effect on this rule.
+
+Both rules inspect class attributes and recognized utility calls, including
+arrays, object arguments and conditional branches. Unrelated strings and tagged
+templates are ignored. In interpolated templates, only complete tokens separated
+from an interpolation by whitespace are transformed; partial tokens such as
+`text-[12px]${suffix}` are preserved. `no-conflicting-classes` accepts the same
+shared configuration and uses its attribute/function names and custom text tokens. Enabling this rule without
+`tailwind-merge` installed raises an installation error. In `cn`/`clsx` object arguments,
+only keys contain classes; predicate values are preserved. For `cva`, base
+classes, variant classes and compound variant `class`/`className` values are checked.
 
 ## 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.
+- **Source extraction is not a complete JavaScript/JSX parser** — ambiguous regex/division expressions and some nested templates are left intact. Quoted JSX prose can hide nested markup from CLI/API extraction; use the ESLint plugin when complete JSX syntax coverage is needed.
+- **CLI and content APIs extract static class positions** — strings, arrays, conditional result branches, `cn`/`clsx` object keys, and `cva` variant classes are supported. Predicates, variant identifiers, `defaultVariants`, computed keys, spreads and nested calls to unconfigured functions are preserved. Dynamic values are not evaluated.
+- **Watch reloads the configuration entry file** — imported helper modules keep Node's normal module cache. Restart the watcher after changing a helper imported by your config.
 - **`--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`.
 
@@ -627,6 +674,26 @@ npx tailwind-canonical --fix --dedup --sort ./src ./app
 }
 ```
 
+## Compatibility and performance checks
+
+The supported ESLint range is `>=8.57.1 <11` (flat configuration), and the optional
+`tailwind-merge` range is `>=2.0.0 <4`. CI tests the built tarball in isolated
+consumer projects across ESLint 8/9/10 and tailwind-merge 2/3, including minimum
+versions. Imports, the installed binary, ESLint fixes and TypeScript consumers
+are exercised rather than relying only on source tests.
+
+```bash
+pnpm test:compat 8.57.1 2.0.0
+pnpm benchmark
+# Tune the fixed JSX/Vue/Svelte corpus and emit machine-readable measurements:
+pnpm benchmark --files 300 --lines 40 --runs 7 --json
+```
+
+The benchmark checks expected findings and transform idempotence, then measures
+file discovery, file analysis, fix/dedup/sort and cross-file consistency. Results
+include Node/CPU/platform, corpus size, median and p95 after warmup. Compare on the
+same machine; this synthetic corpus is not a promise about every project.
+
 ## Dead code detection (knip)
 
 ```bash
@@ -637,6 +704,11 @@ Detects unused exports, files, and dependencies. Config in `knip.json`. Enforced
 
 ## Programmatic API
 
+This package targets Node.js. Some exported functions are pure transformations,
+but the package entry and `core` re-exports also load Node I/O modules. They are
+not browser entry points. “Pure” describes the function's behavior, not the
+entire import graph.
+
 ```ts
 import {
   suggestCanonical,    // pure: class string → suggestion or null

package/dist/cli/cli.js

@@ -2,7 +2,7 @@ import { existsSync, readFileSync, writeFileSync } from 'node:fs';
 import { dirname, join, resolve } from 'node:path';
 import { analyzeFile } from '../core/analyzer.js';
 import { toClassStringOpts } from '../core/class-strings.js';
-import { CONFIG_FILENAMES, loadConfig, resolveInitFilename, } from '../core/config.js';
+import { CONFIG_FILENAMES, findConfigPath, loadConfig, resolveInitFilename, } from '../core/config.js';
 import { analyzeConsistencyFiles, toConsistencyOptions, } from '../core/consistency.js';
 import { dedupeContent } from '../core/deduplicator.js';
 import { fixContent } from '../core/fixer.js';
@@ -12,7 +12,7 @@ import { sortContent } from '../core/sorter.js';
 import { analyzeTyposFile } from '../core/typos.js';
 import { errMsg, pluralize, timestamp } from './format.js';
 import { analyzeSarifDocument, findingsSarifDocument, logAnalyzeText, logFindings, logTransformCounts, logTyposText, logWatchFindings, sarifDocument, typoSarifDocument, writeJson, } from './reporters.js';
-import { startWatch } from './watch.js';
+import { startWatch, watchRoots } from './watch.js';
 const USAGE = 'Usage: tailwind-canonical [--fix] [--merge] [--dedup] [--sort] [--check] [--analyze] [--typos] [--watch] [--reporter json|sarif] <dir|file> [dir|file...]\n       tailwind-canonical init';
 const INIT_CONFIG_BODY = [
     '  // Run `tailwind-canonical` with no flags using these defaults:',
@@ -49,7 +49,7 @@ const HELP_TEXT = [
     '  --check            Dry-run: report what transforms would change, write nothing (exit 1 on pending changes)',
     '  --analyze          Cross-file consistency analysis (read-only)',
     '  --typos            Flag likely misspelled color names (read-only)',
-    '  --watch            Re-run on every file save (transform/check mode; ignored with --typos)',
+    '  --watch            Re-run on every file save (text reporter only; ignored with --typos/--check)',
     '  --reporter <type>  Output format: text|json|sarif',
     '  --help, -h         Show this help message',
     '  --version, -V      Show the installed version',
@@ -439,6 +439,7 @@ export async function run(argv, cwd, sink = defaultSink) {
         sink.error(`tailwind-canonical: ${errMsg(err)}`);
         return { exitCode: 1 };
     }
+    const cliFlags = flags;
     flags = applyDefaultCommand(flags, config);
     if (flags.targets.length === 0) {
         sink.error(USAGE);
@@ -448,6 +449,14 @@ export async function run(argv, cwd, sink = defaultSink) {
         sink.error('--check requires at least one of --fix, --dedup, --merge, --sort');
         return { exitCode: 1 };
     }
+    if (flags.watch &&
+        !flags.analyze &&
+        !flags.typos &&
+        !flags.check &&
+        flags.reporter !== 'text') {
+        sink.error('--watch requires --reporter text; JSON and SARIF support single-pass runs only');
+        return { exitCode: 1 };
+    }
     let twMerge;
     if (flags.merge && !flags.analyze) {
         try {
@@ -463,7 +472,8 @@ export async function run(argv, cwd, sink = defaultSink) {
     }
     const targetPaths = flags.targets.map((target) => resolveTarget(cwd, target));
     const files = await resolveTargets(targetPaths);
-    if (files.length === 0) {
+    if (files.length === 0 &&
+        !(flags.watch && !flags.analyze && !flags.typos && !flags.check)) {
         sink.error(`No files matched: ${flags.targets.join(' ')}`);
         return { exitCode: 1 };
     }
@@ -476,10 +486,42 @@ export async function run(argv, cwd, sink = defaultSink) {
         return runTypos(files, config, flags.reporter, sink, sarif);
     }
     if (flags.watch && !flags.typos && !flags.check) {
+        const configDirectory = () => {
+            const path = findConfigPath(cwd);
+            return path ? dirname(path) : cwd;
+        };
         return startWatch({
             files,
+            roots: watchRoots(targetPaths, [cwd, configDirectory()]),
             sink,
-            processFile: (file) => transforming
+            refresh: async (changed) => {
+                const nextConfig = await loadConfig(cwd, { reload: true });
+                const nextFlags = applyDefaultCommand(cliFlags, nextConfig);
+                if (nextFlags.analyze ||
+                    nextFlags.typos ||
+                    nextFlags.check ||
+                    nextFlags.reporter !== 'text') {
+                    throw new Error('Watch configuration must use text output without --analyze, --typos or --check');
+                }
+                let nextMerge = twMerge;
+                if (nextFlags.merge && !nextMerge)
+                    ({ twMerge: nextMerge } = await import('tailwind-merge'));
+                const paths = nextFlags.targets.map((target) => resolveTarget(cwd, target));
+                const nextFiles = await resolveTargets(paths);
+                const nextRoots = watchRoots(paths, [cwd, configDirectory()]);
+                const configChanged = JSON.stringify(config, (_key, value) => value instanceof RegExp ? value.toString() : value) !==
+                    JSON.stringify(nextConfig, (_key, value) => value instanceof RegExp ? value.toString() : value);
+                config = nextConfig;
+                flags = nextFlags;
+                twMerge = nextMerge;
+                return {
+                    files: nextFiles,
+                    roots: nextRoots,
+                    reprocessAll: configChanged ||
+                        [...changed].some((file) => CONFIG_FILENAMES.some((name) => file.endsWith(`/${name}`) || file.endsWith(`\\${name}`))),
+                };
+            },
+            processFile: (file) => isTransforming(flags)
                 ? watchTransform(file, flags, config, sink, twMerge)
                 : logWatchFindings(file, analyzeFile(file, config), timestamp(), sink),
         });

package/dist/cli/index.js

@@ -2,4 +2,4 @@
 import { run } from './cli.js';
 const { exitCode, watching } = await run(process.argv.slice(2), process.cwd());
 if (!watching)
-    process.exit(exitCode);
+    process.exitCode = exitCode;

package/dist/cli/watch.d.ts

@@ -1,11 +1,21 @@
 import type { Sink } from './types.js';
+type WatchRefresh = {
+    files: string[];
+    roots: string[];
+    reprocessAll?: boolean;
+};
 type WatchOptions = {
     files: string[];
+    roots: string[];
     sink: Sink;
+    refresh: (changed: ReadonlySet<string>) => Promise<WatchRefresh>;
     processFile: (file: string) => void;
 };
-export declare function startWatch({ files, sink, processFile }: WatchOptions): {
+/** Watch the existing ancestor of each target, including currently empty globs. */
+export declare function watchRoots(targets: string[], configDirs: string[]): string[];
+export declare function startWatch({ files, roots, sink, refresh, processFile, }: WatchOptions): {
     exitCode: number;
-    watching: true;
+    watching: boolean;
+    close: () => void;
 };
 export {};

package/dist/cli/watch.js

@@ -1,33 +1,153 @@
-import { watch as fsWatch } from 'node:fs';
-import { dirname, resolve } from 'node:path';
+import { existsSync, watch as fsWatch, statSync, } from 'node:fs';
+import { dirname, isAbsolute, relative, resolve, sep } from 'node:path';
+import { DEFAULT_IGNORE } from '../core/scanner.js';
 import { errMsg, pluralize, timestamp } from './format.js';
-export function startWatch({ files, sink, processFile }) {
-    const fileSet = new Set(files);
-    const timers = new Map();
-    const dirs = new Set(files.map((file) => dirname(file)));
-    sink.log(`Watching ${pluralize(files.length, 'file')}... (Ctrl+C to stop)`);
-    for (const dir of dirs) {
-        fsWatch(dir, { recursive: true }, (_, filename) => {
-            if (!filename)
+function contains(root, path) {
+    const rel = relative(root, path);
+    return (rel === '' ||
+        (!isAbsolute(rel) && rel !== '..' && !rel.startsWith(`..${sep}`)));
+}
+/** Watch the existing ancestor of each target, including currently empty globs. */
+export function watchRoots(targets, configDirs) {
+    const dirs = [...configDirs];
+    for (const target of targets) {
+        if (target.startsWith('!'))
+            continue;
+        const magic = existsSync(target) ? -1 : target.search(/[*?{[(]/);
+        const prefix = target.slice(0, magic);
+        let dir = magic < 0 ? target : prefix.endsWith(sep) ? prefix : dirname(prefix);
+        if (existsSync(dir) && !statSync(dir).isDirectory())
+            dir = dirname(dir);
+        while (!existsSync(dir)) {
+            const parent = dirname(dir);
+            if (parent === dir)
+                break;
+            dir = parent;
+        }
+        dirs.push(dir);
+    }
+    const roots = [...new Set(dirs.map((dir) => resolve(dir)))];
+    return roots.filter((dir) => !roots.some((other) => other !== dir && contains(other, dir)));
+}
+export function startWatch({ files, roots, sink, refresh, processFile, }) {
+    let fileSet = new Set(files);
+    const watchers = new Map();
+    const changed = new Set();
+    let timer;
+    let running = false;
+    let closed = false;
+    function close() {
+        if (closed)
+            return;
+        closed = true;
+        clearTimeout(timer);
+        changed.clear();
+        for (const watcher of watchers.values())
+            watcher.close();
+        watchers.clear();
+        process.removeListener('SIGINT', stop);
+        process.removeListener('SIGTERM', stop);
+    }
+    function stop() {
+        close();
+        sink.log('\nWatcher stopped.');
+    }
+    function fail(path, error) {
+        sink.error(`${timestamp()} ${path} — error: ${errMsg(error)}`);
+    }
+    function schedule() {
+        if (closed || running)
+            return;
+        clearTimeout(timer);
+        timer = setTimeout(() => {
+            void flush();
+        }, 50);
+    }
+    function synchronize(nextRoots) {
+        // Install replacements before closing the old set, so no event gap is added.
+        for (const root of nextRoots) {
+            if (watchers.has(root))
+                continue;
+            try {
+                const watcher = fsWatch(root, { recursive: true }, (_, filename) => {
+                    if (closed)
+                        return;
+                    if (filename &&
+                        String(filename)
+                            .split(/[\\/]/)
+                            .some((part) => DEFAULT_IGNORE.includes(part)))
+                        return;
+                    changed.add(filename ? resolve(root, String(filename)) : root);
+                    schedule();
+                });
+                watchers.set(root, watcher);
+                watcher.on('error', (error) => {
+                    if (closed)
+                        return;
+                    fail(root, error);
+                    process.exitCode = 1;
+                    close();
+                });
+            }
+            catch (error) {
+                fail(root, error);
+                process.exitCode = 1;
+                close();
+                return;
+            }
+        }
+        for (const [root, watcher] of watchers) {
+            if (!nextRoots.includes(root)) {
+                watcher.close();
+                watchers.delete(root);
+            }
+        }
+    }
+    async function flush() {
+        if (closed || running)
+            return;
+        running = true;
+        const batch = new Set(changed);
+        changed.clear();
+        try {
+            const next = await refresh(batch);
+            if (closed)
                 return;
-            const full = resolve(dir, filename);
-            if (!fileSet.has(full))
+            synchronize(next.roots);
+            if (closed)
                 return;
-            clearTimeout(timers.get(full));
-            timers.set(full, setTimeout(() => {
-                timers.delete(full);
+            const nextFiles = new Set(next.files);
+            for (const file of nextFiles) {
+                if (closed)
+                    break;
+                if (!next.reprocessAll &&
+                    fileSet.has(file) &&
+                    ![...batch].some((path) => contains(path, file)))
+                    continue;
                 try {
-                    processFile(full);
+                    processFile(file);
                 }
                 catch (error) {
-                    sink.error(`${timestamp()} ${full} — error: ${errMsg(error)}`);
+                    fail(file, error);
                 }
-            }, 50));
-        });
+            }
+            fileSet = nextFiles;
+        }
+        catch (error) {
+            if (!closed)
+                fail('watch refresh', error);
+        }
+        finally {
+            running = false;
+            if (changed.size > 0)
+                schedule();
+        }
     }
-    process.once('SIGINT', () => {
-        sink.log('\nWatcher stopped.');
-        process.exit(0);
-    });
-    return { exitCode: 0, watching: true };
+    synchronize(roots);
+    if (!closed) {
+        process.once('SIGINT', stop);
+        process.once('SIGTERM', stop);
+        sink.log(`Watching ${pluralize(files.length, 'file')}... (Ctrl+C to stop)`);
+    }
+    return { exitCode: closed ? 1 : 0, watching: !closed, close };
 }