eslint-plugin-tailwind-canonical-classes 1.0.10 → 1.2.0

package/README.md

@@ -28,6 +28,7 @@
 - 🔧 **Auto-fix Support**: Automatically fixes non-canonical classes using ESLint's auto-fix feature
 - 🎯 **Tailwind CSS v4 Integration**: Uses Tailwind CSS v4's official `canonicalizeCandidates` API
 - 📝 **Multiple Format Support**: Works with string literals, template literals, and JSX expressions
+- 🛠️ **Utility Function Support**: Detects and fixes classes in utility functions like `cn()`, `clsx()`, `classNames()`, `twMerge()`, and `cva()`
 - ⚡ **Zero Config**: Minimal configuration required to get started
 
 ## 📦 Installation
@@ -122,6 +123,7 @@ export default [
         {
           cssPath: './app/styles/globals.css', // Required
           rootFontSize: 16, // Optional, default: 16
+          calleeFunctions: ['cn', 'clsx'], // Optional, default: ['cn', 'clsx', 'classNames', 'twMerge', 'cva']
         },
       ],
     },
@@ -140,6 +142,7 @@ module.exports = {
       {
         cssPath: './app/styles/globals.css',
         rootFontSize: 16,
+        calleeFunctions: ['cn', 'clsx'],
       },
     ],
   },
@@ -175,6 +178,18 @@ rootFontSize: 16  // Default (16px = 1rem)
 rootFontSize: 14  // If your root font size is 14px
 ```
 
+### `calleeFunctions` (optional)
+
+- **Type**: `string[]`
+- **Default**: `['cn', 'clsx', 'classNames', 'twMerge', 'cva']`
+- **Description**: Array of utility function names to check for Tailwind classes. The plugin will detect and canonicalize classes passed as string arguments to these functions.
+
+**Example**:
+```javascript
+calleeFunctions: ['cn', 'clsx']  // Only check cn() and clsx()
+calleeFunctions: ['customFn']    // Check a custom utility function
+```
+
 ## 💡 Usage Examples
 
 ### Basic Example
@@ -209,6 +224,13 @@ The plugin supports various class name formats:
    <div className={"p-4px"}>Content</div>
    ```
 
+4. **Utility functions** (e.g., `cn()`, `clsx()`, `classNames()`, `twMerge()`, `cva()`):
+   ```tsx
+   <div className={cn("p-4px", "m-2rem")}>Content</div>
+   <div className={clsx("w-[16px]", condition && "hidden")}>Content</div>
+   // Only string literal arguments are checked; dynamic expressions are skipped
+   ```
+
 ### Real-world Example
 
 ```tsx
@@ -231,10 +253,38 @@ function Card({ children }) {
 }
 ```
 
+### Utility Function Example
+
+```tsx
+// Before
+import { cn } from '@/lib/utils';
+
+function Button({ variant, className }) {
+  return (
+    <button className={cn("w-[16px]", "h-[32px]", className)}>
+      Click me
+    </button>
+  );
+}
+
+// After auto-fix
+import { cn } from '@/lib/utils';
+
+function Button({ variant, className }) {
+  return (
+    <button className={cn("w-4", "h-8", className)}>
+      Click me
+    </button>
+  );
+}
+```
+
 ## 🔧 How It Works
 
-1. **Load Design System**: The plugin loads your Tailwind CSS file using `@tailwindcss/node`'s `__unstable__loadDesignSystem` API
-2. **Extract Classes**: It extracts class names from JSX `className` attributes in your code
+1. **Load Design System**: The plugin loads your Tailwind CSS file using `@tailwindcss/node`'s worker API
+2. **Extract Classes**: It extracts class names from:
+   - JSX `className` attributes (string literals, template literals, JSX expressions)
+   - Utility function calls (e.g., `cn()`, `clsx()`) - only string literal arguments are checked
 3. **Canonicalize**: For each class, it uses Tailwind's `canonicalizeCandidates` to find the canonical form
 4. **Report & Fix**: If a non-canonical class is found, it reports an error/warning and can auto-fix it
 
@@ -244,6 +294,7 @@ function Card({ children }) {
 - **Tailwind CSS v4 required**: Requires Tailwind CSS v4 (not compatible with v3)
 - **CSS file accessibility**: CSS file must be accessible from the ESLint process
 - **Template literals**: Template literals with expressions are partially supported (only static parts are checked)
+- **Utility functions**: Only string literal arguments are checked; dynamic expressions, variables, and conditional logic within utility functions are skipped
 
 ## 🐛 Troubleshooting
 

package/lib/rules/tailwind-canonical-classes.js

@@ -45,6 +45,61 @@ function getQuoteChar(source, start, end) {
     }
     return '"';
 }
+function getCalleeName(node) {
+    if (node.type === 'Identifier') {
+        return node.name;
+    }
+    if (node.type === 'MemberExpression' && node.property.type === 'Identifier') {
+        return node.property.name;
+    }
+    return null;
+}
+function collectStringLiterals(node, result) {
+    if (node.type === 'Literal' && typeof node.value === 'string') {
+        const classes = splitClasses(node.value);
+        if (classes.length > 0) {
+            result.push({ value: node.value, node, classes });
+        }
+    }
+    else if (node.type === 'ConditionalExpression') {
+        collectStringLiterals(node.consequent, result);
+        collectStringLiterals(node.alternate, result);
+    }
+    else if (node.type === 'LogicalExpression') {
+        collectStringLiterals(node.left, result);
+        collectStringLiterals(node.right, result);
+    }
+    else if (node.type === 'TemplateLiteral' && !hasTemplateExpressions(node)) {
+        const value = node.quasis.map((q) => q.value.cooked).join('');
+        const classes = splitClasses(value);
+        if (classes.length > 0) {
+            result.push({ value, node, classes });
+        }
+    }
+}
+function extractStringArgsFromCallExpression(node, calleeFunctions) {
+    if (node.type !== 'CallExpression') {
+        return null;
+    }
+    const calleeName = getCalleeName(node.callee);
+    if (!calleeName || !calleeFunctions.includes(calleeName)) {
+        return null;
+    }
+    const args = [];
+    node.arguments.forEach((arg, index) => {
+        const literals = [];
+        collectStringLiterals(arg, literals);
+        literals.forEach((lit) => {
+            args.push({
+                value: lit.value,
+                index,
+                node: lit.node,
+                classes: lit.classes,
+            });
+        });
+    });
+    return args.length > 0 ? { calleeName, args } : null;
+}
 const rule = {
     meta: {
         type: 'suggestion',
@@ -66,6 +121,12 @@ const rule = {
                     rootFontSize: {
                         type: 'number',
                     },
+                    calleeFunctions: {
+                        type: 'array',
+                        items: {
+                            type: 'string',
+                        },
+                    },
                 },
                 required: ['cssPath'],
                 additionalProperties: false,
@@ -92,6 +153,13 @@ const rule = {
             cssPath = path.normalize(path.resolve(process.cwd(), options.cssPath));
         }
         const rootFontSize = options.rootFontSize ?? 16;
+        const calleeFunctions = options.calleeFunctions ?? [
+            'cn',
+            'clsx',
+            'classNames',
+            'twMerge',
+            'cva',
+        ];
         if (!fs.existsSync(cssPath)) {
             context.report({
                 node: context.getSourceCode().ast,
@@ -108,94 +176,146 @@ const rule = {
                     node.name.name !== 'className') {
                     return;
                 }
-                const staticValue = extractStaticValue(node.value);
-                if (staticValue === null) {
-                    return;
-                }
-                const classes = splitClasses(staticValue);
-                if (classes.length === 0) {
-                    return;
-                }
                 const sourceCode = context.getSourceCode();
                 const sourceText = sourceCode.getText();
-                const errors = [];
-                try {
-                    const canonicalized = canonicalizeClasses(cssPath, classes, rootFontSize);
-                    if (canonicalized === null) {
-                        context.report({
-                            node,
-                            messageId: 'cssNotFound',
-                            data: {
-                                path: cssPath,
-                            },
-                        });
+                const staticValue = extractStaticValue(node.value);
+                if (staticValue !== null) {
+                    const classes = splitClasses(staticValue);
+                    if (classes.length === 0) {
                         return;
                     }
-                    classes.forEach((className, index) => {
-                        const canonical = canonicalized[index];
-                        if (canonical && canonical !== className) {
-                            errors.push({
+                    const errors = [];
+                    try {
+                        const canonicalized = canonicalizeClasses(cssPath, classes, rootFontSize);
+                        if (canonicalized === null) {
+                            context.report({
                                 node,
-                                original: className,
-                                canonical,
-                                index,
+                                messageId: 'cssNotFound',
+                                data: {
+                                    path: cssPath,
+                                },
                             });
+                            return;
                         }
-                    });
-                }
-                catch (error) {
-                    return;
-                }
-                if (errors.length > 0) {
-                    const valueNode = node.value;
-                    let fullRangeStart;
-                    let fullRangeEnd;
-                    let replacementText;
-                    if (valueNode.type === 'Literal') {
-                        fullRangeStart = valueNode.range[0];
-                        fullRangeEnd = valueNode.range[1];
-                        const quoteChar = getQuoteChar(sourceText, valueNode.range[0], valueNode.range[1]);
-                        const fixedClasses = [...classes];
-                        errors.forEach((error) => {
-                            fixedClasses[error.index] = error.canonical;
+                        classes.forEach((className, index) => {
+                            const canonical = canonicalized[index];
+                            if (canonical && canonical !== className) {
+                                errors.push({
+                                    node,
+                                    original: className,
+                                    canonical,
+                                    index,
+                                });
+                            }
                         });
-                        const fixedValue = joinClasses(fixedClasses);
-                        replacementText = `${quoteChar}${fixedValue}${quoteChar}`;
                     }
-                    else if (valueNode.type === 'JSXExpressionContainer') {
-                        const expr = valueNode.expression;
-                        if (expr.type === 'TemplateLiteral') {
+                    catch (error) {
+                        return;
+                    }
+                    if (errors.length > 0) {
+                        const valueNode = node.value;
+                        let fullRangeStart;
+                        let fullRangeEnd;
+                        let replacementText;
+                        if (valueNode.type === 'Literal') {
                             fullRangeStart = valueNode.range[0];
                             fullRangeEnd = valueNode.range[1];
+                            const quoteChar = getQuoteChar(sourceText, valueNode.range[0], valueNode.range[1]);
                             const fixedClasses = [...classes];
                             errors.forEach((error) => {
                                 fixedClasses[error.index] = error.canonical;
                             });
                             const fixedValue = joinClasses(fixedClasses);
-                            replacementText = `{\`${fixedValue}\`}`;
+                            replacementText = `${quoteChar}${fixedValue}${quoteChar}`;
+                        }
+                        else if (valueNode.type === 'JSXExpressionContainer') {
+                            const expr = valueNode.expression;
+                            if (expr.type === 'TemplateLiteral') {
+                                fullRangeStart = valueNode.range[0];
+                                fullRangeEnd = valueNode.range[1];
+                                const fixedClasses = [...classes];
+                                errors.forEach((error) => {
+                                    fixedClasses[error.index] = error.canonical;
+                                });
+                                const fixedValue = joinClasses(fixedClasses);
+                                replacementText = `{\`${fixedValue}\`}`;
+                            }
+                            else {
+                                return;
+                            }
                         }
                         else {
                             return;
                         }
+                        errors.forEach((error, errorIndex) => {
+                            context.report({
+                                node: error.node,
+                                messageId: 'nonCanonical',
+                                data: {
+                                    original: error.original,
+                                    canonical: error.canonical,
+                                },
+                                fix: errorIndex === 0
+                                    ? (fixer) => {
+                                        return fixer.replaceTextRange([fullRangeStart, fullRangeEnd], replacementText);
+                                    }
+                                    : undefined,
+                            });
+                        });
                     }
-                    else {
+                    return;
+                }
+                if (node.value?.type === 'JSXExpressionContainer') {
+                    const expr = node.value.expression;
+                    const callExprData = extractStringArgsFromCallExpression(expr, calleeFunctions);
+                    if (!callExprData) {
                         return;
                     }
-                    errors.forEach((error, errorIndex) => {
-                        context.report({
-                            node: error.node,
-                            messageId: 'nonCanonical',
-                            data: {
-                                original: error.original,
-                                canonical: error.canonical,
-                            },
-                            fix: errorIndex === 0
-                                ? (fixer) => {
-                                    return fixer.replaceTextRange([fullRangeStart, fullRangeEnd], replacementText);
+                    const { args } = callExprData;
+                    try {
+                        for (const arg of args) {
+                            const canonicalized = canonicalizeClasses(cssPath, arg.classes, rootFontSize);
+                            if (canonicalized === null) {
+                                context.report({
+                                    node,
+                                    messageId: 'cssNotFound',
+                                    data: { path: cssPath },
+                                });
+                                return;
+                            }
+                            const errors = [];
+                            arg.classes.forEach((className, idx) => {
+                                const canonical = canonicalized[idx];
+                                if (canonical && canonical !== className) {
+                                    errors.push({ original: className, canonical, idx });
                                 }
-                                : undefined,
-                        });
-                    });
+                            });
+                            if (errors.length === 0)
+                                continue;
+                            const fixedClasses = [...arg.classes];
+                            errors.forEach((e) => { fixedClasses[e.idx] = e.canonical; });
+                            const fixedValue = joinClasses(fixedClasses);
+                            const quoteChar = getQuoteChar(sourceText, arg.node.range[0], arg.node.range[1]);
+                            errors.forEach((error, errorIndex) => {
+                                context.report({
+                                    node: arg.node,
+                                    messageId: 'nonCanonical',
+                                    data: {
+                                        original: error.original,
+                                        canonical: error.canonical,
+                                    },
+                                    fix: errorIndex === 0
+                                        ? (fixer) => {
+                                            return fixer.replaceTextRange([arg.node.range[0], arg.node.range[1]], `${quoteChar}${fixedValue}${quoteChar}`);
+                                        }
+                                        : undefined,
+                                });
+                            });
+                        }
+                    }
+                    catch (error) {
+                        return;
+                    }
                 }
             },
         };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "eslint-plugin-tailwind-canonical-classes",
-  "version": "1.0.10",
+  "version": "1.2.0",
   "description": "ESLint plugin to enforce canonical Tailwind CSS class names using Tailwind CSS v4's canonicalization API",
   "type": "module",
   "main": "lib/index.js",