eslint-plugin-tailwind-canonical-classes 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Maisonnat Maxence
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,140 @@
+# eslint-plugin-tailwind-canonical-classes
+
+ESLint plugin to enforce canonical Tailwind CSS class names using Tailwind CSS v4's canonicalization API.
+
+## Overview
+
+This plugin helps maintain consistent Tailwind CSS class names across your codebase by automatically detecting and fixing non-canonical class names. It uses Tailwind CSS v4's `canonicalizeCandidates` API to ensure your classes follow the canonical format.
+
+For example, it can convert:
+- `p-4px` → `p-1` (if 4px equals 1rem at your root font size)
+- `m-2rem` → `m-8` (if 2rem equals 8 at your scale)
+
+## Installation
+
+```bash
+npm install --save-dev eslint-plugin-tailwind-canonical-classes @tailwindcss/node
+```
+
+## Requirements
+
+- Node.js >= 18.0.0
+- ESLint >= 8.0.0
+- Tailwind CSS v4
+- `@tailwindcss/node` package
+
+## Configuration
+
+Add the plugin to your ESLint configuration file (e.g., `eslint.config.mjs` or `.eslintrc.js`):
+
+### Flat Config (ESLint 9+)
+
+```javascript
+import tailwindCanonicalClasses from 'eslint-plugin-tailwind-canonical-classes';
+
+export default [
+  {
+    plugins: {
+      'tailwind-canonical-classes': tailwindCanonicalClasses,
+    },
+    rules: {
+      'tailwind-canonical-classes/tailwind-canonical-classes': [
+        'warn',
+        {
+          cssPath: './app/styles/globals.css', // Path to your Tailwind CSS file
+          rootFontSize: 16, // Optional: root font size in pixels (default: 16)
+        },
+      ],
+    },
+  },
+];
+```
+
+### Legacy Config (.eslintrc.js)
+
+```javascript
+module.exports = {
+  plugins: ['tailwind-canonical-classes'],
+  rules: {
+    'tailwind-canonical-classes/tailwind-canonical-classes': [
+      'warn',
+      {
+        cssPath: './app/styles/globals.css',
+        rootFontSize: 16,
+      },
+    ],
+  },
+};
+```
+
+## Options
+
+### `cssPath` (required)
+
+Type: `string`
+
+Path to your Tailwind CSS file. Can be:
+- **Relative path**: Resolved relative to your project root (where ESLint config is located)
+- **Absolute path**: Full filesystem path to your CSS file
+
+Example:
+```javascript
+cssPath: './app/styles/globals.css'  // Relative to project root
+cssPath: '/absolute/path/to/styles.css'  // Absolute path
+```
+
+### `rootFontSize` (optional)
+
+Type: `number`  
+Default: `16`
+
+Root font size in pixels for rem calculations. This should match your CSS root font size setting.
+
+## Usage
+
+Once configured, ESLint will automatically check your JSX `className` attributes and suggest canonical alternatives.
+
+### Example
+
+**Before:**
+```tsx
+<div className="p-4px m-2rem">Content</div>
+```
+
+**After auto-fix:**
+```tsx
+<div className="p-1 m-8">Content</div>
+```
+
+The plugin supports:
+- String literals: `className="p-4"`
+- Template literals (without expressions): `className={`p-4 ${someVar}`}` (only static parts are checked)
+- JSX expression containers with static values
+
+## How It Works
+
+1. The plugin loads your Tailwind CSS file using `@tailwindcss/node`'s `__unstable__loadDesignSystem` API
+2. It extracts class names from JSX `className` attributes
+3. For each class, it uses Tailwind's `canonicalizeCandidates` to find the canonical form
+4. If a non-canonical class is found, it reports an error/warning and can auto-fix it
+
+## Limitations
+
+- Only works with static class names (no dynamic expressions)
+- Requires Tailwind CSS v4
+- CSS file must be accessible from the ESLint process
+- Template literals with expressions are skipped
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.
+
+## License
+
+MIT
+
+## Related
+
+- [Tailwind CSS v4](https://tailwindcss.com/)
+- [ESLint](https://eslint.org/)
+

package/index.js

@@ -0,0 +1,7 @@
+import tailwindCanonicalClasses from './lib/tailwind-canonical-classes.js';
+
+export default {
+  rules: {
+    'tailwind-canonical-classes': tailwindCanonicalClasses,
+  },
+};

package/lib/tailwind-canonical-classes.js

@@ -0,0 +1,354 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { __unstable__loadDesignSystem } from '@tailwindcss/node';
+
+// Cache the design system to avoid reloading on every file
+let designSystemCache = null;
+let designSystemPromise = null;
+let designSystemError = null;
+let cssPathCache = null;
+
+function resolveCssPath(cssPath, context) {
+  if (!cssPath) {
+    return null;
+  }
+
+  // If absolute path, use as-is
+  if (path.isAbsolute(cssPath)) {
+    return cssPath;
+  }
+
+  // If relative path, resolve relative to the project root (where ESLint config is)
+  // Try to find the project root by looking for common config files
+  const filename = context.getFilename();
+  const fileDir = path.dirname(filename);
+  
+  // Try to resolve relative to the current file's directory first
+  const relativeToFile = path.resolve(fileDir, cssPath);
+  if (fs.existsSync(relativeToFile)) {
+    return relativeToFile;
+  }
+
+  // Try to resolve relative to the working directory (project root)
+  const relativeToCwd = path.resolve(process.cwd(), cssPath);
+  if (fs.existsSync(relativeToCwd)) {
+    return relativeToCwd;
+  }
+
+  return relativeToCwd; // Return even if doesn't exist, let error handling catch it
+}
+
+function getDesignSystemSync(cssPath, context) {
+  // Reset cache if CSS path changed
+  if (cssPathCache !== cssPath) {
+    designSystemCache = null;
+    designSystemPromise = null;
+    designSystemError = null;
+    cssPathCache = cssPath;
+  }
+
+  if (designSystemCache) {
+    return designSystemCache;
+  }
+
+  if (designSystemError) {
+    return null;
+  }
+
+  if (designSystemPromise && !designSystemCache) {
+    return null;
+  }
+
+  if (!designSystemPromise) {
+    try {
+      const resolvedPath = resolveCssPath(cssPath, context);
+      if (!resolvedPath || !fs.existsSync(resolvedPath)) {
+        designSystemError = new Error(`CSS file not found: ${cssPath}`);
+        return null;
+      }
+
+      const cssContent = fs.readFileSync(resolvedPath, 'utf-8');
+      const basePath = path.dirname(resolvedPath);
+
+      designSystemPromise = __unstable__loadDesignSystem(cssContent, {
+        base: basePath,
+      })
+        .then((ds) => {
+          designSystemCache = ds;
+          return ds;
+        })
+        .catch((error) => {
+          designSystemError = error;
+          return null;
+        });
+    } catch (error) {
+      designSystemError = error;
+      return null;
+    }
+  }
+
+  return null;
+}
+
+async function getDesignSystemAsync(cssPath, context) {
+  // Reset cache if CSS path changed
+  if (cssPathCache !== cssPath) {
+    designSystemCache = null;
+    designSystemPromise = null;
+    designSystemError = null;
+    cssPathCache = cssPath;
+  }
+
+  if (designSystemCache) {
+    return designSystemCache;
+  }
+
+  if (designSystemError) {
+    return null;
+  }
+
+  if (!designSystemPromise) {
+    getDesignSystemSync(cssPath, context);
+  }
+
+  if (designSystemPromise) {
+    try {
+      return await designSystemPromise;
+    } catch (error) {
+      designSystemError = error;
+      return null;
+    }
+  }
+
+  return null;
+}
+
+function extractClassNames(classNameValue, sourceCode) {
+  const classes = [];
+
+  if (!classNameValue) {
+    return classes;
+  }
+
+  if (classNameValue.type === 'Literal' && typeof classNameValue.value === 'string') {
+    const classString = classNameValue.value;
+    return classString.split(/\s+/).filter((cls) => cls.trim().length > 0);
+  }
+
+  if (classNameValue.type === 'TemplateLiteral') {
+    if (classNameValue.expressions && classNameValue.expressions.length > 0) {
+      return [];
+    }
+
+    const parts = [];
+    for (const quasi of classNameValue.quasis) {
+      const cooked = quasi.value?.cooked || '';
+      if (cooked.trim()) {
+        parts.push(cooked.trim());
+      }
+    }
+
+    const combined = parts.join(' ');
+    return combined.split(/\s+/).filter((cls) => cls.trim().length > 0);
+  }
+
+  if (classNameValue.type === 'JSXExpressionContainer') {
+    return extractClassNames(classNameValue.expression, sourceCode);
+  }
+
+  return classes;
+}
+
+export default {
+  meta: {
+    type: 'suggestion',
+    docs: {
+      description: 'Enforce canonical Tailwind CSS class names',
+      category: 'Best Practices',
+      recommended: false,
+    },
+    fixable: 'code',
+    schema: [
+      {
+        type: 'object',
+        properties: {
+          cssPath: {
+            type: 'string',
+            description: 'Path to your Tailwind CSS file (relative to project root or absolute)',
+          },
+          rootFontSize: {
+            type: 'number',
+            default: 16,
+            description: 'Root font size in pixels for rem calculations',
+          },
+        },
+        required: ['cssPath'],
+        additionalProperties: false,
+      },
+    ],
+    messages: {
+      nonCanonical: 'The class `{{original}}` can be written as `{{canonical}}`',
+      cssNotFound: 'CSS file not found: {{path}}. Please check your cssPath configuration.',
+    },
+  },
+
+  create(context) {
+    const options = context.options[0] || {};
+    const cssPath = options.cssPath;
+    const rootFontSize = options.rootFontSize || 16;
+    const sourceCode = context.getSourceCode();
+
+    if (!cssPath) {
+      context.report({
+        loc: { line: 1, column: 0 },
+        messageId: 'cssNotFound',
+        data: { path: 'not specified' },
+      });
+      return {};
+    }
+
+    return {
+      JSXAttribute(node) {
+        if (node.name.name !== 'className') {
+          return;
+        }
+
+        const value = node.value;
+        if (!value) {
+          return;
+        }
+
+        let classNameValue = value;
+        if (value.type === 'JSXExpressionContainer') {
+          classNameValue = value.expression;
+        }
+
+        if (
+          classNameValue.type !== 'Literal' &&
+          classNameValue.type !== 'TemplateLiteral' &&
+          classNameValue.type !== 'JSXExpressionContainer'
+        ) {
+          return;
+        }
+
+        const classNames = extractClassNames(classNameValue, sourceCode);
+        if (classNames.length === 0) {
+          return;
+        }
+
+        const designSystem = getDesignSystemSync(cssPath, context);
+
+        if (!designSystem) {
+          getDesignSystemAsync(cssPath, context).catch(() => {});
+          return;
+        }
+
+        if (designSystem && designSystem.canonicalizeCandidates) {
+          processClasses(
+            designSystem,
+            classNames,
+            classNameValue,
+            sourceCode,
+            rootFontSize,
+            context,
+          );
+        }
+      },
+    };
+  },
+};
+
+function processClasses(
+  designSystem,
+  classNames,
+  classNameValue,
+  sourceCode,
+  rootFontSize,
+  context,
+) {
+  const issues = [];
+
+  for (let i = 0; i < classNames.length; i++) {
+    const className = classNames[i];
+
+    try {
+      const canonicalized = designSystem.canonicalizeCandidates([className], {
+        rem: rootFontSize,
+      })[0];
+
+      if (canonicalized !== className) {
+        issues.push({
+          original: className,
+          canonical: canonicalized,
+          index: i,
+        });
+      }
+    } catch {
+      continue;
+    }
+  }
+
+  if (issues.length > 0) {
+    const originalText = sourceCode.getText(classNameValue);
+
+    const canonicalMap = new Map();
+    issues.forEach((issue) => {
+      canonicalMap.set(issue.original, issue.canonical);
+    });
+
+    const fixedClassNames = classNames.map((className) => {
+      return canonicalMap.get(className) || className;
+    });
+    const fixedClassString = fixedClassNames.join(' ');
+
+    let fixedText;
+
+    const quoteMatch = originalText.match(/^(["'`])(.*)\1$/);
+
+    if (quoteMatch) {
+      fixedText = `${quoteMatch[1]}${fixedClassString}${quoteMatch[1]}`;
+    } else if (classNameValue.type === 'TemplateLiteral') {
+      fixedText = `\`${fixedClassString}\``;
+    } else {
+      const startQuoteMatch = originalText.match(/^(["'`])/);
+      if (startQuoteMatch) {
+        const quote = startQuoteMatch[1];
+        const endQuoteIndex = originalText.lastIndexOf(quote);
+        if (endQuoteIndex > 0) {
+          fixedText = `${quote}${fixedClassString}${quote}`;
+        } else {
+          fixedText = fixedClassString;
+        }
+      } else {
+        fixedText = fixedClassString;
+      }
+    }
+
+    context.report({
+      node: classNameValue,
+      messageId: 'nonCanonical',
+      data: {
+        original: issues[0].original,
+        canonical: issues[0].canonical,
+      },
+      fix(fixer) {
+        if (fixedText !== originalText) {
+          return fixer.replaceText(classNameValue, fixedText);
+        }
+        return null;
+      },
+    });
+
+    for (let i = 1; i < issues.length; i++) {
+      context.report({
+        node: classNameValue,
+        messageId: 'nonCanonical',
+        data: {
+          original: issues[i].original,
+          canonical: issues[i].canonical,
+        },
+      });
+    }
+  }
+}
+

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "eslint-plugin-tailwind-canonical-classes",
+  "version": "1.0.0",
+  "description": "ESLint plugin to enforce canonical Tailwind CSS class names using Tailwind CSS v4's canonicalization API",
+  "type": "module",
+  "main": "index.js",
+  "exports": {
+    ".": "./index.js",
+    "./rule": "./lib/tailwind-canonical-classes.js"
+  },
+  "files": [
+    "index.js",
+    "lib"
+  ],
+  "keywords": [
+    "eslint",
+    "eslint-plugin",
+    "tailwind",
+    "tailwindcss",
+    "canonical",
+    "lint",
+    "css"
+  ],
+  "author": "Maisonnat Maxence <maisonnatmax@gmail.com>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/maxencemaisonnat/eslint-plugin-tailwind-canonical-classes.git"
+  },
+  "bugs": {
+    "url": "https://github.com/maxencemaisonnat/eslint-plugin-tailwind-canonical-classes/issues"
+  },
+  "homepage": "https://github.com/maxencemaisonnat/eslint-plugin-tailwind-canonical-classes#readme",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "peerDependencies": {
+    "eslint": ">=8.0.0"
+  },
+  "dependencies": {
+    "@tailwindcss/node": "^4.0.0"
+  },
+  "devDependencies": {
+    "eslint": "^9.0.0"
+  }
+}
+