@weerachai06/tw-scanner 1.0.0

package/README.md

@@ -0,0 +1,88 @@
+# tw-scanner
+
+AST-based Tailwind v4 class validator for React projects.
+Detects invalid, renamed, or missing classes after design token / plugin migrations.
+
+## Usage
+
+Run directly without installing:
+
+```bash
+npx @weerachai06/tw-scanner --src ./src --css ./src/globals.css
+```
+
+Or install globally:
+
+```bash
+npm install -g @weerachai06/tw-scanner
+tw-scanner --src ./src --css ./src/globals.css
+```
+
+### Options
+
+| Flag | Description |
+|---|---|
+| `--src` | Directory to scan (default: `./src`) |
+| `--css` | Path to Tailwind v4 CSS entry file (with `@import tailwindcss` + `@theme`) |
+| `--verbose` | Show source context snippet for each error |
+| `--output report.json` | Save full JSON report to file |
+| `--json` | Print JSON report to stdout (for CI piping) |
+
+### Examples
+
+```bash
+# Basic scan
+npx @weerachai06/tw-scanner --src ./src --css ./src/globals.css
+
+# With verbose context + save report
+npx @weerachai06/tw-scanner --src ./src --css ./src/globals.css --verbose --output report.json
+
+# CI mode (exits with code 1 if invalid classes found)
+npx @weerachai06/tw-scanner --src ./src --css ./src/globals.css --json | jq '.invalid | length'
+```
+
+## What it detects
+
+| Type | Example | Action |
+|---|---|---|
+| ❌ Invalid class | `bg-old-token-500` | **Error** — invalid after migration |
+| ❌ Invalid in cva variants | `danger: 'bg-red-danger'` | **Error** — detected via AST |
+| ⚠️ Dynamic expression | `` `text-${color}` `` | **Warning** — cannot validate statically |
+
+## How it works
+
+### 1. AST Extraction
+
+Uses `@typescript-eslint/typescript-estree` to parse `.ts/.tsx/.js/.jsx` and traverse:
+- `className="..."` JSX props
+- `clsx(...)`, `cn(...)`, `cva(...)` call arguments
+- Nested `ObjectExpression` (cva variant maps)
+- `ConditionalExpression` and `LogicalExpression` inside class utilities
+- `TemplateLiteral` — static parts extracted, dynamic parts flagged as warnings
+
+### 2. Tailwind v4 Validation
+
+Uses `@tailwindcss/node`'s `compile()` API to load your actual CSS entry file (including all `@theme` tokens and plugins), then calls `build([candidate])` for each class. If the class generates no CSS rule in the output, it's invalid.
+
+Validation is **100% accurate against your real config** — custom tokens, plugins, and all.
+
+### 3. Batch validation
+
+All unique class values are validated in a single `build()` call per batch for performance.
+
+## Extending
+
+To add support for more class utilities (e.g. `tv` from `tailwind-variants`), add the function name to `CLASS_UTIL_NAMES` in `src/extractor.ts`:
+
+```ts
+const CLASS_UTIL_NAMES = new Set(['clsx', 'cn', 'cx', 'classnames', 'cva', 'tv'])
+```
+
+## Development
+
+```bash
+bun install        # install dependencies
+bun run build      # compile TypeScript → dist/
+bun test           # run tests
+bun run scan -- --src ./src --css ./src/globals.css  # run locally without building
+```

package/dist/cli.js

@@ -0,0 +1,57 @@
+#!/usr/bin/env node
+import * as path from 'path';
+import { scan } from './scanner.js';
+import { printReport, writeJsonReport } from './reporter.js';
+// ─── Minimal arg parser ───────────────────────────────────────────────────────
+function parseArgs(argv) {
+    const args = {};
+    for (let i = 0; i < argv.length; i++) {
+        const arg = argv[i];
+        if (arg.startsWith('--')) {
+            const key = arg.slice(2);
+            const next = argv[i + 1];
+            if (next && !next.startsWith('--')) {
+                args[key] = next;
+                i++;
+            }
+            else {
+                args[key] = true;
+            }
+        }
+    }
+    return args;
+}
+async function main() {
+    const args = parseArgs(process.argv.slice(2));
+    const srcArg = args['src'] ?? './src';
+    const cssArg = args['css'];
+    const outputArg = args['output'];
+    const jsonMode = Boolean(args['json']);
+    const verbose = Boolean(args['verbose']);
+    if (!cssArg) {
+        console.error('Usage: tw-scanner --src <dir> --css <tailwind-entry.css> [--output report.json] [--verbose] [--json]');
+        console.error('');
+        console.error('  --src      Directory to scan (default: ./src)');
+        console.error('  --css      Path to Tailwind CSS entry file with @import and @theme');
+        console.error('  --output   Write JSON report to file');
+        console.error('  --verbose  Show context snippets for each error');
+        console.error('  --json     Print full JSON report to stdout');
+        process.exit(1);
+    }
+    const src = path.resolve(srcArg);
+    const css = path.resolve(cssArg);
+    try {
+        const result = await scan({ src, css });
+        printReport(result, { json: jsonMode, verbose });
+        if (outputArg) {
+            writeJsonReport(result, path.resolve(outputArg));
+        }
+        // Exit with error code if invalid classes found
+        process.exit(result.invalid.length > 0 ? 1 : 0);
+    }
+    catch (err) {
+        console.error('Fatal error:', err.message);
+        process.exit(2);
+    }
+}
+main();

package/dist/extractor.js

@@ -0,0 +1,244 @@
+import { parse } from '@typescript-eslint/typescript-estree';
+import * as fs from 'fs';
+// ─── Class utility function names to detect ──────────────────────────────────
+const CLASS_UTIL_NAMES = new Set(['clsx', 'cn', 'cx', 'classnames', 'cva', 'tv']);
+// JSX props that contain class strings
+const CLASS_PROPS = new Set(['className', 'class']);
+// ─── Helpers ─────────────────────────────────────────────────────────────────
+function makeExtracted(value, node, file, source, isDynamic = false) {
+    const classes = isDynamic
+        ? [value] // keep raw template for dynamic
+        : value.split(/\s+/).filter(Boolean);
+    return classes.map((cls) => ({
+        value: cls,
+        file,
+        line: node.loc.start.line,
+        col: node.loc.start.column,
+        isDynamic,
+        context: source.slice(Math.max(0, (node.range?.[0] ?? 0) - 30), Math.min(source.length, (node.range?.[1] ?? 0) + 30)).replace(/\n/g, ' ').trim(),
+    }));
+}
+// Escape regex special chars
+function escapeRegex(s) {
+    return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+// ─── Node visitors ────────────────────────────────────────────────────────────
+/**
+ * Extract classes from a Literal (plain string)
+ */
+function visitLiteral(node, file, source) {
+    if (typeof node.value !== 'string' || !node.value.trim())
+        return [];
+    return makeExtracted(node.value, node, file, source, false);
+}
+/**
+ * Extract classes from a TemplateLiteral.
+ * Quasis (static parts) are extracted normally.
+ * If there are expressions, we flag the whole thing as dynamic.
+ */
+function visitTemplateLiteral(node, file, source) {
+    const results = [];
+    const hasDynamic = node.expressions.length > 0;
+    if (hasDynamic) {
+        // Extract static quasis individually — they may be valid standalone classes
+        for (const quasi of node.quasis) {
+            const raw = quasi.value.cooked ?? quasi.value.raw;
+            const staticParts = raw.split(/\s+/).filter(Boolean);
+            for (const part of staticParts) {
+                // Skip parts that look like incomplete prefixes (e.g. "text-", "bg-")
+                // These are the left/right edges of a dynamic expression: `text-${x}`
+                if (part && !part.endsWith('-') && !part.endsWith(':')) {
+                    results.push({
+                        value: part,
+                        file,
+                        line: quasi.loc.start.line,
+                        col: quasi.loc.start.column,
+                        isDynamic: false,
+                        context: source.slice(Math.max(0, (node.range?.[0] ?? 0) - 20), Math.min(source.length, (node.range?.[1] ?? 0) + 20)).replace(/\n/g, ' ').trim(),
+                    });
+                }
+            }
+        }
+        // Also record the whole template as dynamic for the warning report
+        const rawTemplate = source.slice(node.range?.[0] ?? 0, node.range?.[1] ?? 0);
+        results.push({
+            value: rawTemplate,
+            file,
+            line: node.loc.start.line,
+            col: node.loc.start.column,
+            isDynamic: true,
+            context: rawTemplate.replace(/\n/g, ' ').trim(),
+        });
+    }
+    else {
+        // Fully static template — treat like a plain string
+        const cooked = node.quasis.map((q) => q.value.cooked ?? q.value.raw).join('');
+        results.push(...makeExtracted(cooked, node, file, source, false));
+    }
+    return results;
+}
+/**
+ * Extract classes from an ArrayExpression (clsx(['a', 'b', cond && 'c']))
+ */
+function visitExpression(node, file, source) {
+    const results = [];
+    switch (node.type) {
+        case 'Literal':
+            results.push(...visitLiteral(node, file, source));
+            break;
+        case 'TemplateLiteral':
+            results.push(...visitTemplateLiteral(node, file, source));
+            break;
+        case 'ArrayExpression':
+            for (const el of node.elements) {
+                if (el)
+                    results.push(...visitExpression(el, file, source));
+            }
+            break;
+        case 'ObjectExpression':
+            for (const prop of node.properties) {
+                if (prop.type === 'Property') {
+                    const key = prop.key;
+                    const val = prop.value;
+                    // Pattern 1: { 'bg-red-500': condition } — key is the class name
+                    if (key.type === 'Literal' && typeof key.value === 'string') {
+                        results.push(...makeExtracted(key.value, key, file, source, false));
+                    }
+                    // Pattern 2: cva({ variants: { size: { sm: 'text-sm', lg: 'text-lg' } } })
+                    // Key is an Identifier (e.g. "sm", "danger") and VALUE is the class string
+                    if (key.type === 'Identifier') {
+                        // Skip cva's `defaultVariants` key — values are variant names, not class strings
+                        // e.g. defaultVariants: { variant: 'default', size: 'md' }
+                        if (key.name === 'defaultVariants')
+                            continue;
+                        // Recurse into the value — it could be a string, nested object, etc.
+                        results.push(...visitExpression(val, file, source));
+                    }
+                }
+                else if (prop.type === 'SpreadElement') {
+                    results.push(...visitExpression(prop.argument, file, source));
+                }
+            }
+            break;
+        case 'ConditionalExpression':
+            // cond ? 'a' : 'b'
+            results.push(...visitExpression(node.consequent, file, source));
+            results.push(...visitExpression(node.alternate, file, source));
+            break;
+        case 'LogicalExpression':
+            // cond && 'a'  |  cond || 'b'  |  cond ?? 'c'
+            results.push(...visitExpression(node.left, file, source));
+            results.push(...visitExpression(node.right, file, source));
+            break;
+        case 'CallExpression': {
+            // nested clsx / cn / cva calls
+            const callee = node.callee;
+            const name = callee.type === 'Identifier'
+                ? callee.name
+                : callee.type === 'MemberExpression' && callee.property.type === 'Identifier'
+                    ? callee.property.name
+                    : null;
+            if (name && CLASS_UTIL_NAMES.has(name)) {
+                for (const arg of node.arguments) {
+                    results.push(...visitExpression(arg, file, source));
+                }
+            }
+            break;
+        }
+        case 'SpreadElement':
+            results.push(...visitExpression(node.argument, file, source));
+            break;
+    }
+    return results;
+}
+// ─── Walk entire AST ──────────────────────────────────────────────────────────
+function walk(node, file, source, results, visited = new WeakSet()) {
+    if (!node || visited.has(node))
+        return;
+    visited.add(node);
+    // ── JSX className="..." ──
+    if (node.type === 'JSXAttribute') {
+        const nameNode = node.name;
+        const attrName = nameNode.type === 'JSXIdentifier'
+            ? nameNode.name
+            : nameNode.type === 'JSXNamespacedName'
+                ? nameNode.name.name
+                : '';
+        if (CLASS_PROPS.has(attrName) && node.value) {
+            const val = node.value;
+            if (val.type === 'Literal') {
+                results.push(...visitLiteral(val, file, source));
+            }
+            else if (val.type === 'JSXExpressionContainer') {
+                const expr = val.expression;
+                if (expr.type !== 'JSXEmptyExpression') {
+                    results.push(...visitExpression(expr, file, source));
+                }
+            }
+        }
+    }
+    // ── clsx(...) / cn(...) / cva(...) calls ──
+    if (node.type === 'CallExpression') {
+        const callee = node.callee;
+        const calleeName = callee.type === 'Identifier'
+            ? callee.name
+            : callee.type === 'MemberExpression' && callee.property.type === 'Identifier'
+                ? callee.property.name
+                : null;
+        if (calleeName && CLASS_UTIL_NAMES.has(calleeName)) {
+            for (const arg of node.arguments) {
+                results.push(...visitExpression(arg, file, source));
+            }
+        }
+        // cva('base', { variants: { size: { sm: 'text-sm' } } })
+        // Already handled by nested visitExpression calls above
+    }
+    // ── Recurse into children ──
+    for (const key of Object.keys(node)) {
+        if (key === 'parent' || key === 'tokens' || key === 'comments')
+            continue;
+        const child = node[key];
+        if (Array.isArray(child)) {
+            for (const c of child) {
+                if (c && typeof c === 'object' && 'type' in c) {
+                    walk(c, file, source, results, visited);
+                }
+            }
+        }
+        else if (child && typeof child === 'object' && 'type' in child) {
+            walk(child, file, source, results, visited);
+        }
+    }
+}
+// ─── Public API ───────────────────────────────────────────────────────────────
+export function extractClassesFromFile(file) {
+    if (!fs.existsSync(file))
+        return [];
+    const source = fs.readFileSync(file, 'utf8');
+    const isTS = /\.(ts|tsx)$/.test(file);
+    let ast;
+    try {
+        ast = parse(source, {
+            jsx: true,
+            loc: true,
+            range: true,
+            tolerant: true,
+            ...(isTS ? {} : {}),
+        });
+    }
+    catch (err) {
+        console.warn(`⚠  Parse error in ${file}: ${err.message}`);
+        return [];
+    }
+    const results = [];
+    walk(ast, file, source, results);
+    // Deduplicate by value+line+col
+    const seen = new Set();
+    return results.filter((r) => {
+        const key = `${r.value}:${r.line}:${r.col}`;
+        if (seen.has(key))
+            return false;
+        seen.add(key);
+        return true;
+    });
+}

package/dist/reporter.js

@@ -0,0 +1,81 @@
+import pc from 'picocolors';
+import * as fs from 'fs';
+import * as path from 'path';
+function relativePath(file, cwd = process.cwd()) {
+    return path.relative(cwd, file);
+}
+function pluralize(n, word) {
+    return `${n} ${word}${n === 1 ? '' : 's'}`;
+}
+// Group by file
+function groupByFile(items) {
+    const map = new Map();
+    for (const item of items) {
+        const list = map.get(item.file) ?? [];
+        list.push(item);
+        map.set(item.file, list);
+    }
+    return map;
+}
+export function printReport(result, opts = {}) {
+    if (opts.json) {
+        console.log(JSON.stringify(result, null, 2));
+        return;
+    }
+    const { invalid, dynamic, totalClasses, totalFiles, durationMs } = result;
+    console.log('');
+    console.log(pc.bold('─── Tailwind v4 Class Scanner ───────────────────────────────'));
+    console.log(`  Scanned ${pc.cyan(pluralize(totalFiles, 'file'))} · ` +
+        `${pc.cyan(String(totalClasses))} classes found · ` +
+        `${pc.dim(`${durationMs}ms`)}`);
+    console.log('');
+    // ── Invalid classes ──
+    if (invalid.length === 0) {
+        console.log(pc.green('  ✓ No invalid Tailwind classes found'));
+    }
+    else {
+        console.log(pc.red(pc.bold(`  ✗ ${pluralize(invalid.length, 'invalid class')} found`)));
+        console.log('');
+        const byFile = groupByFile(invalid.map((v) => ({ ...v.cls, _result: v })));
+        for (const [file, items] of byFile) {
+            console.log(`  ${pc.underline(relativePath(file))}`);
+            for (const item of items) {
+                const loc = pc.dim(`${item.line}:${item.col}`);
+                const cls = pc.red(pc.bold(item.value));
+                const ctx = pc.dim(`…${item.context}…`);
+                console.log(`    ${loc}  ${cls}`);
+                if (opts.verbose) {
+                    console.log(`         ${ctx}`);
+                }
+            }
+            console.log('');
+        }
+    }
+    // ── Dynamic (warnings) ──
+    const dynamicOnly = dynamic.filter((d) => d.isDynamic);
+    if (dynamicOnly.length > 0) {
+        console.log(pc.yellow(pc.bold(`  ⚠  ${pluralize(dynamicOnly.length, 'dynamic class expression')} (cannot validate)`)));
+        console.log('');
+        const byFile = groupByFile(dynamicOnly);
+        for (const [file, items] of byFile) {
+            console.log(`  ${pc.underline(relativePath(file))}`);
+            for (const item of items) {
+                const loc = pc.dim(`${item.line}:${item.col}`);
+                const val = pc.yellow(item.value.length > 60 ? item.value.slice(0, 60) + '…' : item.value);
+                console.log(`    ${loc}  ${val}`);
+            }
+            console.log('');
+        }
+    }
+    // ── Summary ──
+    console.log('─────────────────────────────────────────────────────────────');
+    const status = invalid.length === 0 ? pc.green('PASS') : pc.red('FAIL');
+    console.log(`  Status: ${status}  ·  ` +
+        `${pc.red(String(invalid.length))} invalid  ·  ` +
+        `${pc.yellow(String(dynamicOnly.length))} dynamic warnings`);
+    console.log('');
+}
+export function writeJsonReport(result, outputPath) {
+    fs.writeFileSync(outputPath, JSON.stringify(result, null, 2));
+    console.log(pc.dim(`  Report saved → ${outputPath}`));
+}

package/dist/scanner.js

@@ -0,0 +1,58 @@
+import { globSync } from 'glob';
+import * as path from 'path';
+import { extractClassesFromFile } from './extractor.js';
+import { loadTailwindContext, validateBatch } from './validator.js';
+const DEFAULT_INCLUDE = ['**/*.{ts,tsx,js,jsx}'];
+const DEFAULT_EXCLUDE = [
+    '**/node_modules/**',
+    '**/dist/**',
+    '**/.next/**',
+    '**/build/**',
+    '**/coverage/**',
+    '**/*.min.js',
+    '**/*.d.ts',
+];
+export async function scan(opts) {
+    const start = Date.now();
+    // ── 1. Find files ──────────────────────────────────────────────────────────
+    const include = opts.include ?? DEFAULT_INCLUDE;
+    const exclude = opts.exclude ?? DEFAULT_EXCLUDE;
+    const files = include.flatMap((pattern) => globSync(pattern, {
+        cwd: path.resolve(opts.src),
+        absolute: true,
+        ignore: exclude,
+        nodir: true,
+    }));
+    if (files.length === 0) {
+        console.warn(`⚠  No files found in: ${opts.src}`);
+    }
+    // ── 2. Load Tailwind context ───────────────────────────────────────────────
+    const twContext = await loadTailwindContext(opts.css);
+    // ── 3. Extract classes from all files ─────────────────────────────────────
+    const allExtracted = [];
+    for (const file of files) {
+        const extracted = extractClassesFromFile(file);
+        allExtracted.push(...extracted);
+    }
+    // ── 4. Separate static vs dynamic ─────────────────────────────────────────
+    const staticClasses = allExtracted.filter((c) => !c.isDynamic);
+    const dynamicClasses = allExtracted.filter((c) => c.isDynamic);
+    // ── 5. Batch validate static classes ──────────────────────────────────────
+    const uniqueValues = [...new Set(staticClasses.map((c) => c.value))];
+    const validityMap = validateBatch(uniqueValues, twContext);
+    // ── 6. Build results ───────────────────────────────────────────────────────
+    const invalid = [];
+    for (const cls of staticClasses) {
+        const valid = validityMap.get(cls.value) ?? false;
+        if (!valid) {
+            invalid.push({ cls, valid });
+        }
+    }
+    return {
+        invalid,
+        dynamic: dynamicClasses,
+        totalClasses: allExtracted.length,
+        totalFiles: files.length,
+        durationMs: Date.now() - start,
+    };
+}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/dist/validator.js

@@ -0,0 +1,82 @@
+import * as fs from 'fs';
+import * as path from 'path';
+import { compile } from '@tailwindcss/node';
+// ─── Cache: compile result per CSS file ──────────────────────────────────────
+const compileCache = new Map();
+export async function loadTailwindContext(cssFile) {
+    const abs = path.resolve(cssFile);
+    if (compileCache.has(abs))
+        return compileCache.get(abs);
+    if (!fs.existsSync(abs)) {
+        throw new Error(`Tailwind CSS file not found: ${abs}`);
+    }
+    const css = fs.readFileSync(abs, 'utf8');
+    const result = await compile(css, {
+        base: path.dirname(abs),
+        onDependency: () => { },
+    });
+    compileCache.set(abs, result);
+    return result;
+}
+// ─── Build escape for CSS selector matching ───────────────────────────────────
+function cssEscape(cls) {
+    // Matches what Tailwind outputs in CSS selectors
+    return cls
+        .replace(/\//g, '\\/') // p-1/2 → p-1\/2
+        .replace(/\./g, '\\.') // . → \.
+        .replace(/:/g, '\\:') // md: → md\:
+        .replace(/\[/g, '\\[')
+        .replace(/\]/g, '\\]')
+        .replace(/\(/g, '\\(')
+        .replace(/\)/g, '\\)')
+        .replace(/#/g, '\\#')
+        .replace(/%/g, '\\%')
+        .replace(/!/g, '\\!');
+}
+// ─── Validation cache: per-context ───────────────────────────────────────────
+const validityCache = new Map();
+export function isValidClass(cls, context) {
+    if (!validityCache.has(context))
+        validityCache.set(context, new Map());
+    const cache = validityCache.get(context);
+    if (cache.has(cls))
+        return cache.get(cls);
+    // Build CSS with this single candidate
+    const output = context.build([cls]);
+    // A valid class generates a selector in the utilities/components layer
+    const escaped = cssEscape(cls);
+    // Look for .classname{ or .classname  { or .classname:hover{
+    const pattern = new RegExp(`\\.${escaped.replace(/\\/g, '\\\\')}[\\s{\\[:]`);
+    const valid = pattern.test(output);
+    cache.set(cls, valid);
+    return valid;
+}
+// ─── Batch validate (more efficient: one build call per batch) ────────────────
+export function validateBatch(classes, context) {
+    const result = new Map();
+    const toCheck = [];
+    const cache = validityCache.get(context) ?? new Map();
+    if (!validityCache.has(context))
+        validityCache.set(context, cache);
+    // Use cache first
+    for (const cls of classes) {
+        if (cache.has(cls)) {
+            result.set(cls, cache.get(cls));
+        }
+        else {
+            toCheck.push(cls);
+        }
+    }
+    if (toCheck.length === 0)
+        return result;
+    // Build all candidates at once
+    const output = context.build(toCheck);
+    for (const cls of toCheck) {
+        const escaped = cssEscape(cls);
+        const pattern = new RegExp(`\\.${escaped.replace(/\\/g, '\\\\')}[\\s{\\[:]`);
+        const valid = pattern.test(output);
+        result.set(cls, valid);
+        cache.set(cls, valid);
+    }
+    return result;
+}

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "@weerachai06/tw-scanner",
+  "version": "1.0.0",
+  "description": "AST-based Tailwind v4 class validator for React projects",
+  "type": "module",
+  "bin": {
+    "tw-scanner": "./dist/cli.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "scan": "bun src/cli.ts",
+    "test": "bun test"
+  },
+  "dependencies": {
+    "@tailwindcss/node": "^4.3.1",
+    "@typescript-eslint/typescript-estree": "^8.61.1",
+    "glob": "^11.0.0",
+    "picocolors": "^1.1.1"
+  },
+  "devDependencies": {
+    "@types/node": "^26.0.0",
+    "tailwindcss": "^4.3.1",
+    "typescript": "^5.8.3"
+  }
+}