@weerachai06/tw-scanner 1.0.4 → 1.1.1

package/README.md

@@ -47,7 +47,10 @@ npx @weerachai06/tw-scanner --src ./src --css ./src/globals.css --json | jq '.in
 |---|---|---|
 | ❌ Invalid class | `bg-old-token-500` | **Error** — invalid after migration |
 | ❌ Invalid in cva variants | `danger: 'bg-red-danger'` | **Error** — detected via AST |
+| ❌ Invalid `@apply` class | `@apply bg-fake-999;` in `.css` | **Error** — validated against your config |
+| ❌ Missing CSS Module class | `styles.nonExistent` | **Error** — class not defined in `.module.css` |
 | ⚠️ Dynamic expression | `` `text-${color}` `` | **Warning** — cannot validate statically |
+| ⚠️ Dynamic module access | `styles[variable]` | **Warning** — skipped, cannot resolve statically |
 
 ## How it works
 
@@ -60,13 +63,36 @@ Uses `@typescript-eslint/typescript-estree` to parse `.ts/.tsx/.js/.jsx` and tra
 - `ConditionalExpression` and `LogicalExpression` inside class utilities
 - `TemplateLiteral` — static parts extracted, dynamic parts flagged as warnings
 
-### 2. Tailwind v4 Validation
+### 2. CSS file scanning
+
+`.css` and `.module.css` files are also scanned. Classes inside `@apply` directives are extracted and validated against your Tailwind config.
+
+```css
+.btn {
+  @apply bg-blue-500 text-white px-4; /* ✓ valid */
+  @apply bg-fake-999;                 /* ✗ error */
+}
+```
+
+### 3. CSS Modules validation
+
+When a JS/TS file imports a `.module.css` file, all `styles.xxx` and `styles['xxx']` usages are checked against the class names actually defined in that file.
+
+```tsx
+import styles from './button.module.css'
+
+<button className={styles.btn}>...</button>          // ✓ defined
+<button className={styles.nonExistent}>...</button>  // ✗ error
+<button className={styles[variant]}>...</button>     // ⚠ skipped (dynamic)
+```
+
+### 4. 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
+### 5. Batch validation
 
 All unique class values are validated in a single `build()` call per batch for performance.
 

package/dist/cli.js

@@ -46,8 +46,7 @@ async function main() {
         if (outputArg) {
             writeJsonReport(result, path.resolve(outputArg));
         }
-        // Exit with error code if invalid classes found
-        process.exit(result.invalid.length > 0 ? 1 : 0);
+        process.exit(result.invalid.length > 0 || result.cssModuleViolations.length > 0 ? 1 : 0);
     }
     catch (err) {
         console.error('Fatal error:', err.message);

package/dist/extractor.js

@@ -1,5 +1,6 @@
 import { parse } from '@typescript-eslint/typescript-estree';
 import * as fs from 'fs';
+import * as path from 'path';
 // ─── Class utility function names to detect ──────────────────────────────────
 const CLASS_UTIL_NAMES = new Set(['clsx', 'cn', 'cx', 'classnames', 'cva', 'tv']);
 // JSX props that contain class strings
@@ -210,6 +211,93 @@ function walk(node, file, source, results, visited = new WeakSet()) {
         }
     }
 }
+// ─── CSS Modules extractor ───────────────────────────────────────────────────
+export function extractCssModuleUsages(file) {
+    if (!fs.existsSync(file))
+        return [];
+    const source = fs.readFileSync(file, 'utf8');
+    const isJSX = /\.(tsx|jsx)$/.test(file);
+    let ast;
+    try {
+        ast = parse(source, { jsx: isJSX, loc: true, range: true, tolerant: true });
+    }
+    catch {
+        return [];
+    }
+    // Pass 1: collect `import styles from './foo.module.css'` → binding → resolved path
+    const imports = new Map();
+    for (const node of ast.body) {
+        if (node.type === 'ImportDeclaration' &&
+            typeof node.source.value === 'string' &&
+            node.source.value.endsWith('.module.css')) {
+            const resolvedPath = path.resolve(path.dirname(file), node.source.value);
+            for (const specifier of node.specifiers) {
+                if (specifier.type === 'ImportDefaultSpecifier') {
+                    imports.set(specifier.local.name, resolvedPath);
+                }
+            }
+        }
+    }
+    if (imports.size === 0)
+        return [];
+    // Pass 2: collect `styles.btn` / `styles['btn']` / `styles[expr]` usages
+    const results = [];
+    function walkForUsages(node) {
+        if (!node)
+            return;
+        if (node.type === 'MemberExpression') {
+            const obj = node.object;
+            if (obj.type === 'Identifier' && imports.has(obj.name)) {
+                const modulePath = imports.get(obj.name);
+                const prop = node.property;
+                const snippet = source.slice(Math.max(0, (node.range?.[0] ?? 0) - 20), Math.min(source.length, (node.range?.[1] ?? 0) + 20)).replace(/\n/g, ' ').trim();
+                if (!node.computed && prop.type === 'Identifier') {
+                    results.push({ file, line: node.loc.start.line, col: node.loc.start.column, className: prop.name, modulePath, context: snippet, isDynamic: false });
+                }
+                else if (node.computed && prop.type === 'Literal' && typeof prop.value === 'string') {
+                    results.push({ file, line: node.loc.start.line, col: node.loc.start.column, className: prop.value, modulePath, context: snippet, isDynamic: false });
+                }
+                else if (node.computed) {
+                    results.push({ file, line: node.loc.start.line, col: node.loc.start.column, className: source.slice(node.range?.[0] ?? 0, node.range?.[1] ?? 0), modulePath, context: snippet, isDynamic: true });
+                }
+            }
+        }
+        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)
+                        walkForUsages(c);
+                }
+            }
+            else if (child && typeof child === 'object' && 'type' in child) {
+                walkForUsages(child);
+            }
+        }
+    }
+    walkForUsages(ast);
+    return results;
+}
+export function extractDefinedCssModuleClasses(cssFile) {
+    if (!fs.existsSync(cssFile))
+        return new Set();
+    const source = fs.readFileSync(cssFile, 'utf8');
+    const classes = new Set();
+    const lines = source.split('\n');
+    for (const line of lines) {
+        // Skip @apply lines — those dots are Tailwind classes, not module class names
+        if (line.trimStart().startsWith('@apply'))
+            continue;
+        const regex = /\.([a-zA-Z_][a-zA-Z0-9_-]*)\b/g;
+        let m;
+        while ((m = regex.exec(line)) !== null) {
+            classes.add(m[1]);
+        }
+    }
+    return classes;
+}
 // ─── CSS @apply extractor ─────────────────────────────────────────────────────
 export function extractClassesFromCss(file) {
     if (!fs.existsSync(file))

package/dist/reporter.js

@@ -22,7 +22,7 @@ export function printReport(result, opts = {}) {
         console.log(JSON.stringify(result, null, 2));
         return;
     }
-    const { invalid, dynamic, totalClasses, totalFiles, durationMs } = result;
+    const { invalid, dynamic, cssModuleViolations, totalClasses, totalFiles, durationMs } = result;
     console.log('');
     console.log(pc.bold('─── Tailwind v4 Class Scanner ───────────────────────────────'));
     console.log(`  Scanned ${pc.cyan(pluralize(totalFiles, 'file'))} · ` +
@@ -67,11 +67,32 @@ export function printReport(result, opts = {}) {
             console.log('');
         }
     }
+    // ── CSS Module violations ──
+    if (cssModuleViolations.length > 0) {
+        console.log(pc.red(pc.bold(`  ✗ ${pluralize(cssModuleViolations.length, 'CSS Module class')} not found`)));
+        console.log('');
+        const byFile = groupByFile(cssModuleViolations);
+        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.className));
+                const mod = pc.dim(`(${relativePath(item.modulePath)})`);
+                console.log(`    ${loc}  ${cls}  ${mod}`);
+                if (opts.verbose) {
+                    console.log(`         ${pc.dim(`…${item.context}…`)}`);
+                }
+            }
+            console.log('');
+        }
+    }
     // ── Summary ──
     console.log('─────────────────────────────────────────────────────────────');
-    const status = invalid.length === 0 ? pc.green('PASS') : pc.red('FAIL');
+    const hasErrors = invalid.length > 0 || cssModuleViolations.length > 0;
+    const status = hasErrors ? pc.red('FAIL') : pc.green('PASS');
     console.log(`  Status: ${status}  ·  ` +
         `${pc.red(String(invalid.length))} invalid  ·  ` +
+        `${pc.red(String(cssModuleViolations.length))} CSS module  ·  ` +
         `${pc.yellow(String(dynamicOnly.length))} dynamic warnings`);
     console.log('');
 }

package/dist/scanner.js

@@ -1,6 +1,6 @@
 import { globSync } from 'glob';
 import * as path from 'path';
-import { extractClassesFromFile, extractClassesFromCss } from './extractor.js';
+import { extractClassesFromFile, extractClassesFromCss, extractCssModuleUsages, extractDefinedCssModuleClasses } from './extractor.js';
 import { loadTailwindContext, validateBatch } from './validator.js';
 const DEFAULT_INCLUDE = ['**/*.{ts,tsx,js,jsx,css}'];
 const DEFAULT_EXCLUDE = [
@@ -50,9 +50,34 @@ export async function scan(opts) {
             invalid.push({ cls, valid });
         }
     }
+    // ── 7. CSS Module cross-reference ────────────────────────────────────────────
+    const cssModuleViolations = [];
+    const jsFiles = files.filter((f) => !f.endsWith('.css'));
+    // Collect all usages across JS/TS files
+    const allUsages = jsFiles.flatMap((f) => extractCssModuleUsages(f));
+    const staticUsages = allUsages.filter((u) => !u.isDynamic);
+    // Load defined classes per unique module path (cached)
+    const moduleClassesCache = new Map();
+    for (const usage of staticUsages) {
+        if (!moduleClassesCache.has(usage.modulePath)) {
+            moduleClassesCache.set(usage.modulePath, extractDefinedCssModuleClasses(usage.modulePath));
+        }
+        const defined = moduleClassesCache.get(usage.modulePath);
+        if (!defined.has(usage.className)) {
+            cssModuleViolations.push({
+                file: usage.file,
+                line: usage.line,
+                col: usage.col,
+                className: usage.className,
+                modulePath: usage.modulePath,
+                context: usage.context,
+            });
+        }
+    }
     return {
         invalid,
         dynamic: dynamicClasses,
+        cssModuleViolations,
         totalClasses: allExtracted.length,
         totalFiles: files.length,
         durationMs: Date.now() - start,

package/dist/validator.js

@@ -11,10 +11,23 @@ export async function loadTailwindContext(cssFile) {
         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: () => { },
-    });
+    let result;
+    try {
+        result = await compile(css, {
+            base: path.dirname(abs),
+            onDependency: () => { },
+        });
+    }
+    catch (err) {
+        const msg = err.message ?? '';
+        const match = msg.match(/Cannot apply unknown utility class [`']?([^\s`']+)[`']?/);
+        if (match) {
+            throw new Error(`Tailwind could not compile "${path.relative(process.cwd(), abs)}" — ` +
+                `unknown utility used in @apply: "${match[1]}".\n` +
+                `  Fix: add "@utility ${match[1]} {}" to your CSS entry file to register it as a custom utility.`);
+        }
+        throw err;
+    }
     compileCache.set(abs, result);
     return result;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@weerachai06/tw-scanner",
-  "version": "1.0.4",
+  "version": "1.1.1",
   "description": "AST-based Tailwind v4 class validator for React projects",
   "type": "module",
   "bin": {