tailwind-canonical 0.8.0 → 0.10.0

package/README.md

@@ -94,19 +94,30 @@ npx tailwind-canonical --help
 npx tailwind-canonical --version
 ```
 
-An unmatched target exits `1` with `No files matched: <targets>`.
+If none of the targets match any supported files, the command exits `1` with `No files matched: <targets>`. A missing target does not fail a run when other targets match. Unreadable targets or subdirectories fail discovery before any file is changed.
+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
 
 | Flag | What it fixes | Example |
 |---|---|---|
-| `--fix` | Arbitrary values → canonical tokens | `text-[12px]` → `text-xs` |
+| `--fix` | Arbitrary values → canonical tokens | `p-[16px]` → `p-4` |
 | `--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` |
+| `--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 |
@@ -120,9 +131,9 @@ npx tailwind-canonical --reporter json ./src
 ```json
 {
   "files": 3,
-  "total": 2,
+  "total": 1,
   "findings": [
-    { "file": "src/Button.tsx", "line": 12, "col": 17, "original": "text-[14px]", "canonical": "text-sm", "isCustomToken": false }
+    { "file": "src/Button.tsx", "line": 12, "col": 17, "original": "p-[16px]", "canonical": "p-4", "isCustomToken": false }
   ]
 }
 ```
@@ -203,11 +214,11 @@ Skip specific lines or blocks from check and all transforms (`--fix`, `--dedup`,
 
 ```jsx
 {/* tailwind-canonical-disable-next-line */}
-<div className="text-[13px]" />        {/* left untouched */}
+<div className="p-[16px]" />        {/* left untouched */}
 
 {/* tailwind-canonical-disable */}
-<div className="text-[13px] p-[7px]" /> {/* whole block untouched */}
-<div className="m-[9px]" />
+<div className="p-[16px] h-[24px]" /> {/* whole block untouched */}
+<div className="m-[8px]" />
 {/* tailwind-canonical-enable */}
 ```
 
@@ -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
@@ -319,13 +335,17 @@ flex block             → block  (last wins)
 relative absolute      → absolute
 ```
 
+Conflict resolution follows the last-token convention, which can change the
+result of Tailwind's stylesheet precedence. Important and normal utilities keep
+separate priorities.
+
 ### Padding / margin shorthand collapse
 
 ```
 px-4 py-4  → p-4
 p-4 px-2   → py-4 px-2
-pt-2 pb-2  → py-2
-pl-4 pr-4  → px-4
+pt-2 pb-2  → py-2  (v3 only)
+pl-4 pr-4  → px-4  (v3 only)
 mx-4 my-4  → m-4
 ```
 
@@ -333,24 +353,31 @@ mx-4 my-4  → m-4
 
 ```
 border-t-2 border-b-2 border-l-2 border-r-2  → border-2
-border-t-2 border-b-2                          → border-y-2
-border-l-4 border-r-4                          → border-x-4
+border-t-2 border-b-2                          → border-y-2  (v3 only)
+border-l-4 border-r-4                          → border-x-4  (v3 only)
 ```
 
 ### Inset shorthand collapse
 
 ```
 top-4 right-4 bottom-4 left-4  → inset-4
-top-4 bottom-4                  → inset-y-4
-left-2 right-2                  → inset-x-2
+top-4 bottom-4                  → inset-y-4  (v3 only)
+left-2 right-2                  → inset-x-2  (v3 only)
 ```
 
+With Tailwind v4 (the default), axis utilities use logical inline/block properties.
+Physical sides such as `pl-*` and `pr-*` are therefore not collapsed into `px-*`,
+and mixed physical/logical groups are preserved. Equal values covering all four
+sides can still collapse to the global utility. Set `tailwindVersion: 3` to enable
+v3's physical-side to axis shorthand rules. The pure API also accepts this option:
+`deduplicateClasses(classes, { tailwindVersion: 3 })`.
+
 ## Arbitrary value detection (`--fix`)
 
 | Arbitrary | Canonical | Notes |
 |---|---|---|
-| `text-[12px]` | `text-xs` | Built-in |
-| `text-[0.75rem]` | `text-xs` | rem values |
+| `text-[12px]` | `text-xs` | Explicit `allowTextSizeLineHeightChanges: true` only |
+| `text-[0.75rem]` | `text-xs` | Explicit opt-in only; default leaves the class unchanged |
 | `h-[64px]` | `h-16` | Spacing scale ÷4 |
 | `p-[1px]` / `gap-[1px]` | `p-px` / `gap-px` | 1px spacing step |
 | `w-[50%]` | `w-1/2` | Percentage fractions |
@@ -377,16 +404,19 @@ left-2 right-2                  → inset-x-2
 | `order-[1]` / `order-[0]` | `order-1` / `order-none` | Any integer on v4 |
 | `grow-[1]` / `shrink-[0]` | `grow` / `shrink-0` | |
 | `line-clamp-[3]`, `columns-[3]` | `line-clamp-3`, `columns-3` | Any integer ≥ 1 on v4 |
-| `text-[11px]` | `text-2xs` | Requires `customTextTokens` |
-| `text-[8px]`–`text-[10px]` | `text-3xs` | Requires `customTextTokens` |
+| `text-[11px]` | `text-2xs` | Requires `customTextTokens` and explicit text-size opt-in |
+| `text-[8px]`–`text-[10px]` | `text-3xs` | Requires `customTextTokens` and explicit text-size opt-in |
 | `hover:p-[16px]` | `hover:p-4` | Variants are preserved |
 | `!p-[16px]` / `p-[16px]!` | `!p-4` / `p-4!` | Important modifier kept in place |
 | `-mt-[8px]` / `mt-[-8px]` | `-mt-2` | Negative margin / inset / translate / space / scale / rotate / z / order only |
 
-`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`:
+`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 only if the typography change is intended, using `customTextTokens` and the explicit opt-in:
 
 ```ts
-export default { customTextTokens: { 8: '3xs', 9: '3xs', 10: '3xs', 11: '2xs' } }
+export default {
+  allowTextSizeLineHeightChanges: true, // named sizes may also set line-height
+  customTextTokens: { 8: '3xs', 9: '3xs', 10: '3xs', 11: '2xs' },
+}
 ```
 
 Non-divisible values (`h-[22px]`, `px-[7px]`) are left untouched.
@@ -459,16 +489,63 @@ 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 considered in this mode:
+`p-[16px]` becomes `p-gutter`, while other arbitrary values (including rem values)
+stay unchanged. Text-size mappings are also subject to the separate opt-in below:
+`customTextTokens` alone never enables them. The options are shared by the CLI,
+library and ESLint canonicalization rule. They do not load your Tailwind theme
+or customize the separate `tailwind-merge` conflict resolver.
+
+### Preserve text line-height (default)
+
+`text-[12px]` sets only font-size; `text-xs` also sets line-height. Equal font sizes
+therefore do not guarantee the same rendering. By default, pixel and rem text-size
+conversions are neither reported nor applied, including custom text tokens.
+Variants, important modifiers and nearby `leading-*` utilities do not bypass this
+protection: without the complete stylesheet, their presence cannot prove that the
+conversion preserves the cascade. No `leading-[inherit]` utility is inserted.
+
+```ts
+suggestCanonical('text-[12px]') // null
+suggestCanonical('p-[16px]')    // { original: 'p-[16px]', canonical: 'p-4', ... }
+```
+
+To deliberately adopt the named typography token, including its line-height,
+opt in explicitly in shared configuration:
+
+```ts
+export default {
+  allowTextSizeLineHeightChanges: true, // default: false
+}
+```
+
+With this option, `text-[12px]` becomes `text-xs` and custom text mappings become
+active. This restores the earlier behavior and can change rendering. With the
+option absent or `false`, text classes stay unchanged in lint, `--fix`, `--check`,
+watch, the programmatic API and ESLint; other utility families remain enabled.
+
 ## Config
 
 Create `tailwind-canonical.config.ts` at the root:
 
 ```ts
 export default {
-  customTextTokens: {
-    10: '3xs',
-    11: '2xs',
-  },
+  // Text mappings are inactive unless the line-height change is intentional:
+  // allowTextSizeLineHeightChanges: true,
+  // customTextTokens: { 10: '3xs', 11: '2xs' },
   customSpacingTokens: {
     14: '3.5',
   },
@@ -502,7 +579,7 @@ export default {
 }
 ```
 
-`customTextTokens` merges with the built-in text size map. `customSpacingTokens` supplements the default ÷4 spacing logic. `ignorePatterns` makes `suggestCanonical` skip matching classes everywhere — CLI, analyzer, and the ESLint plugin.
+`customTextTokens` merges with the built-in text size map only when `allowTextSizeLineHeightChanges: true`; otherwise text-size suggestions stay disabled. `customSpacingTokens` supplements the default ÷4 spacing logic. `ignorePatterns` makes `suggestCanonical` skip matching classes everywhere — CLI, analyzer, and the ESLint plugin.
 
 `attributeNames` controls which HTML/JSX attributes are scanned (default: `['className']`). Use `['class']` for plain HTML/PHP/Jinja templates, `[':class']` for Vue, `['tw']` for styled-components.
 
@@ -577,20 +654,33 @@ ESLint without schema errors:
 ```js
 'tailwind-canonical/no-arbitrary-canonical': [
   'warn',
-  { customTextTokens: { 11: '2xs' }, ignorePatterns: [/^font-/] },
+  { customSpacingTokens: { 14: '3.5' }, 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.
+and `tailwindVersion` (all applied via `suggestCanonical`), plus
+`useDefaultTheme` to disable inferred mappings and
+`allowTextSizeLineHeightChanges` for the explicit typography opt-in. 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. To prevent renaming a key onto another property, objects with multiple properties, computed keys or spreads are left unchanged. 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, single-property `cn`/`clsx` object keys, and `cva` variant classes are supported. Objects with multiple properties, computed keys or spreads are kept unchanged to prevent key collisions. Vue `:class`/`v-bind:class` bindings are read as expressions; Svelte interpolations inside quoted attributes are kept intact. Predicates, variant identifiers, `defaultVariants` 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 +717,30 @@ 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
+# Compile regression cases against Tailwind v3 and v4 in temporary consumers:
+pnpm test:css
+pnpm benchmark
+# Tune the fixed JSX/Vue/Svelte corpus and emit machine-readable measurements:
+pnpm benchmark --files 300 --lines 40 --runs 7 --json
+# Helper-heavy corpus, including large files:
+pnpm benchmark --corpus helpers --files 1 --lines 8000 --runs 3 --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 +751,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,22 +2,24 @@ 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';
 import { mergeContent } from '../core/merger.js';
-import { resolveTargets } from '../core/scanner.js';
+import { isGlob, resolveTargets } from '../core/scanner.js';
 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:',
     "  // defaultCommand: { fix: true, dedup: true, sort: true, typos: true, targets: ['./src'] },",
     '  // px → token additions/overrides:',
+    '  // Text mappings can change line-height; enable only when intentional:',
+    '  // allowTextSizeLineHeightChanges: true,',
     "  // customTextTokens: { 11: '2xs' },",
     "  // customSpacingTokens: { 14: '3.5' },",
     '  // Never suggest replacements for classes matching:',
@@ -49,7 +51,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 +441,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 +451,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 {
@@ -462,8 +473,29 @@ export async function run(argv, cwd, sink = defaultSink) {
         sink.error(`Warning: ${warning}`);
     }
     const targetPaths = flags.targets.map((target) => resolveTarget(cwd, target));
-    const files = await resolveTargets(targetPaths);
-    if (files.length === 0) {
+    const targetKinds = new Map();
+    const rememberTargetKinds = (paths) => {
+        for (const path of paths) {
+            const target = path.startsWith('!') ? path.slice(1) : path;
+            const key = target.replace(/\\/g, '/');
+            if (!targetKinds.has(key))
+                targetKinds.set(key, existsSync(target) || !(path.startsWith('!') || isGlob(target))
+                    ? 'literal'
+                    : 'glob');
+        }
+        return targetKinds;
+    };
+    rememberTargetKinds(targetPaths);
+    let files;
+    try {
+        files = await resolveTargets(targetPaths, { targetKinds });
+    }
+    catch (error) {
+        sink.error(`tailwind-canonical: could not resolve targets: ${errMsg(error)}`);
+        return { exitCode: 1 };
+    }
+    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 +508,48 @@ 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;
+        };
+        const explicitTargets = (paths) => paths.filter((path) => !path.startsWith('!') &&
+            targetKinds.get(path.replace(/\\/g, '/')) === 'literal');
         return startWatch({
             files,
+            explicitTargets: explicitTargets(targetPaths),
+            roots: watchRoots(targetPaths, [cwd, configDirectory()], targetKinds),
             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, {
+                    targetKinds: rememberTargetKinds(paths),
+                });
+                const nextRoots = watchRoots(paths, [cwd, configDirectory()], targetKinds);
+                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,
+                    explicitTargets: explicitTargets(paths),
+                    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,23 @@
 import type { Sink } from './types.js';
+type WatchRefresh = {
+    files: string[];
+    roots: string[];
+    explicitTargets?: string[];
+    reprocessAll?: boolean;
+};
 type WatchOptions = {
     files: string[];
+    roots: string[];
+    explicitTargets?: 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[], targetKinds?: ReadonlyMap<string, 'literal' | 'glob'>): string[];
+export declare function startWatch({ files, roots, explicitTargets, sink, refresh, processFile, }: WatchOptions): {
     exitCode: number;
-    watching: true;
+    watching: boolean;
+    close: () => void;
 };
 export {};