@trackunit/eslint-plugin-trackunit 0.0.2

package/src/lib/utils/classname-utils.d.ts

@@ -0,0 +1,150 @@
+import { TSESTree } from "@typescript-eslint/utils";
+/**
+ * Utility functions for finding and analyzing Tailwind CSS classnames in ESLint rules.
+ *
+ * This module provides a centralized way to detect classname usage patterns across:
+ * - JSX `className` and `class` attributes
+ * - Variables named with `...Class` or `...ClassName` suffixes
+ * - Tailwind utility functions: `cvaMerge`, `twMerge`, `cva`, `tw`, `twx`, `tws`, `cn`, `clsx`, `classNames`, `twJoin`
+ *
+ * ## Core Concepts
+ *
+ * ### ClassnameLocation
+ * Represents a single location where a classname string value is found.
+ * Contains the string value, the AST node for reporting/fixing, and metadata.
+ *
+ * ### ClassnameContext
+ * Describes where a classname was found (JSX attribute, function call, variable, etc.)
+ *
+ * ## Usage in ESLint Rules
+ *
+ * ```typescript
+ * import { findClassnameStrings, TAILWIND_FUNCTIONS, isClassnameVariable } from "./classname-utils";
+ *
+ * // In a CallExpression handler:
+ * CallExpression(node) {
+ *   const locations = findClassnameStrings(node);
+ *   for (const location of locations) {
+ *     // Check location.value for banned patterns
+ *     // Report on location.reportNode
+ *     // Fix using location.fixNode
+ *   }
+ * }
+ * ```
+ */
+/**
+ * Context describing where a classname was found
+ */
+export type ClassnameContext = {
+    type: "jsx-attribute";
+    attributeName: string;
+} | {
+    type: "function-call";
+    functionName: string;
+    argumentIndex: number;
+} | {
+    type: "cva-variant";
+    functionName: string;
+    variantPath: Array<string>;
+} | {
+    type: "variable";
+    variableName: string;
+} | {
+    type: "array-element";
+    parentContext: ClassnameContext;
+    elementIndex: number;
+};
+/**
+ * Represents a location where a classname string value is found
+ */
+export type ClassnameLocation = {
+    /** The extracted string value (for template literals, only static parts) */
+    value: string;
+    /** The AST node to use when reporting errors */
+    reportNode: TSESTree.Node;
+    /** The AST node to use when creating fixes (string literal or template literal) */
+    fixNode: TSESTree.Literal | TSESTree.TemplateLiteral;
+    /** Context describing where this classname was found */
+    context: ClassnameContext;
+};
+/**
+ * Function names that accept Tailwind class strings as arguments.
+ * These are commonly used for class merging and conditional class application.
+ *
+ * Corresponds to the `tailwindFunctions` config in .prettierrc for Prettier's
+ * Tailwind CSS plugin.
+ */
+export declare const TAILWIND_FUNCTIONS: readonly ["cva", "cvaMerge", "tw", "twx", "tws", "twMerge", "twJoin", "cn", "clsx", "classNames"];
+export type TailwindFunction = (typeof TAILWIND_FUNCTIONS)[number];
+/**
+ * JSX attribute names that contain classname values
+ */
+export declare const CLASSNAME_ATTRIBUTES: readonly ["className", "class"];
+/**
+ * Check if a function name is a known Tailwind utility function
+ */
+export declare const isTailwindFunction: (name: string) => name is TailwindFunction;
+/**
+ * Check if a variable name indicates it contains classnames
+ */
+export declare const isClassnameVariable: (name: string) => boolean;
+/**
+ * Check if a JSX attribute name is a classname attribute
+ */
+export declare const isClassnameAttribute: (name: string) => boolean;
+/**
+ * Get the function name from a CallExpression callee
+ */
+export declare const getCalleeName: (callee: TSESTree.CallExpression["callee"]) => string | null;
+/**
+ * Find all classname string locations in a CallExpression node.
+ *
+ * Use this in your ESLint rule's CallExpression handler to process
+ * Tailwind utility function calls like twMerge, cvaMerge, etc.
+ *
+ * @example
+ * ```typescript
+ * CallExpression(node) {
+ *   const locations = findClassnameStringsInCall(node);
+ *   for (const location of locations) {
+ *     if (hasBannedPattern(location.value)) {
+ *       context.report({ node: location.reportNode, ... });
+ *     }
+ *   }
+ * }
+ * ```
+ */
+export declare const findClassnameStringsInCall: (node: TSESTree.CallExpression) => Array<ClassnameLocation>;
+/**
+ * Find all classname string locations in a JSXAttribute node.
+ *
+ * Use this in your ESLint rule's JSXAttribute handler to process
+ * className and class attributes.
+ *
+ * @example
+ * ```typescript
+ * JSXAttribute(node) {
+ *   const locations = findClassnameStringsInAttribute(node);
+ *   for (const location of locations) {
+ *     if (hasBannedPattern(location.value)) {
+ *       context.report({ node: location.reportNode, ... });
+ *     }
+ *   }
+ * }
+ * ```
+ */
+export declare const findClassnameStringsInAttribute: (node: TSESTree.JSXAttribute) => Array<ClassnameLocation>;
+/**
+ * Split a classname string into individual class names.
+ * Handles whitespace-separated classes.
+ */
+export declare const splitClasses: (value: string) => Array<string>;
+/**
+ * Join class names into a single string.
+ */
+export declare const joinClasses: (classes: Array<string>) => string;
+/**
+ * Create a JSON-formatted array string from an array of class names.
+ * Useful for auto-fix operations.
+ */
+export declare const formatAsArray: (classes: Array<string>) => string;

package/src/lib/utils/classname-utils.js

@@ -0,0 +1,492 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.formatAsArray = exports.joinClasses = exports.splitClasses = exports.findClassnameStringsInAttribute = exports.findClassnameStringsInCall = exports.getCalleeName = exports.isClassnameAttribute = exports.isClassnameVariable = exports.isTailwindFunction = exports.CLASSNAME_ATTRIBUTES = exports.TAILWIND_FUNCTIONS = void 0;
+const utils_1 = require("@typescript-eslint/utils");
+// =============================================================================
+// Constants
+// =============================================================================
+/**
+ * Function names that accept Tailwind class strings as arguments.
+ * These are commonly used for class merging and conditional class application.
+ *
+ * Corresponds to the `tailwindFunctions` config in .prettierrc for Prettier's
+ * Tailwind CSS plugin.
+ */
+exports.TAILWIND_FUNCTIONS = [
+    "cva",
+    "cvaMerge",
+    "tw",
+    "twx",
+    "tws",
+    "twMerge",
+    "twJoin",
+    "cn",
+    "clsx",
+    "classNames",
+];
+/**
+ * Variable name patterns that indicate a classname value.
+ * Matches variables like: containerClass, buttonClassName, rootClasses
+ */
+const CLASSNAME_VARIABLE_PATTERNS = [/Class$/, /ClassName$/, /Classes$/];
+/**
+ * JSX attribute names that contain classname values
+ */
+exports.CLASSNAME_ATTRIBUTES = ["className", "class"];
+// =============================================================================
+// Detection Helpers
+// =============================================================================
+/**
+ * Check if a function name is a known Tailwind utility function
+ */
+const isTailwindFunction = (name) => {
+    return exports.TAILWIND_FUNCTIONS.some(fn => fn === name);
+};
+exports.isTailwindFunction = isTailwindFunction;
+/**
+ * Check if a variable name indicates it contains classnames
+ */
+const isClassnameVariable = (name) => {
+    return CLASSNAME_VARIABLE_PATTERNS.some(pattern => pattern.test(name));
+};
+exports.isClassnameVariable = isClassnameVariable;
+/**
+ * Check if a JSX attribute name is a classname attribute
+ */
+const isClassnameAttribute = (name) => {
+    return exports.CLASSNAME_ATTRIBUTES.some(attr => attr === name);
+};
+exports.isClassnameAttribute = isClassnameAttribute;
+/**
+ * Get the function name from a CallExpression callee
+ */
+const getCalleeName = (callee) => {
+    if (callee.type === utils_1.AST_NODE_TYPES.Identifier) {
+        return callee.name;
+    }
+    if (callee.type === utils_1.AST_NODE_TYPES.MemberExpression && callee.property.type === utils_1.AST_NODE_TYPES.Identifier) {
+        return callee.property.name;
+    }
+    return null;
+};
+exports.getCalleeName = getCalleeName;
+// =============================================================================
+// String Extraction
+// =============================================================================
+/**
+ * Extract a string value from a Literal node
+ */
+const extractFromLiteral = (node) => {
+    if (typeof node.value === "string") {
+        return { value: node.value, node };
+    }
+    return null;
+};
+/**
+ * Extract the static parts of a TemplateLiteral as a single string.
+ * Template expressions are replaced with a single space to preserve word boundaries.
+ */
+const extractFromTemplateLiteral = (node) => {
+    // Join static parts with spaces (representing where expressions would be)
+    const value = node.quasis.map(quasi => quasi.value.raw).join(" ");
+    return { value, node };
+};
+/**
+ * Extract string value from a node that might contain a classname string.
+ * Handles Literal and TemplateLiteral nodes.
+ */
+const extractStringValue = (node) => {
+    switch (node.type) {
+        case utils_1.AST_NODE_TYPES.Literal:
+            return extractFromLiteral(node);
+        case utils_1.AST_NODE_TYPES.TemplateLiteral:
+            return extractFromTemplateLiteral(node);
+        default:
+            return null;
+    }
+};
+// =============================================================================
+// Array Traversal
+// =============================================================================
+/**
+ * Extract classname locations from an ArrayExpression.
+ * Handles arrays like: ["flex", "items-center", "bg-primary-500"]
+ */
+const extractFromArray = (node, parentContext) => {
+    const locations = [];
+    node.elements.forEach((element, index) => {
+        if (!element || element.type === utils_1.AST_NODE_TYPES.SpreadElement) {
+            return;
+        }
+        const extracted = extractStringValue(element);
+        if (extracted) {
+            locations.push({
+                value: extracted.value,
+                reportNode: element,
+                fixNode: extracted.node,
+                context: { type: "array-element", parentContext, elementIndex: index },
+            });
+        }
+    });
+    return locations;
+};
+// =============================================================================
+// CVA/CVAMerge Object Traversal
+// =============================================================================
+/**
+ * Recursively extract classname locations from a CVA options object.
+ *
+ * CVA structure:
+ * ```
+ * cva(baseClasses, {
+ *   variants: {
+ *     variantName: {
+ *       variantValue: "classnames here",
+ *     }
+ *   },
+ *   compoundVariants: [
+ *     { variantName: "value", className: "classnames" }
+ *   ],
+ *   defaultVariants: { ... }
+ * })
+ * ```
+ */
+const extractFromCvaObject = (node, functionName, currentPath = []) => {
+    const locations = [];
+    for (const property of node.properties) {
+        if (property.type !== utils_1.AST_NODE_TYPES.Property) {
+            continue;
+        }
+        const keyName = getPropertyKeyName(property.key);
+        if (!keyName) {
+            continue;
+        }
+        const propertyPath = [...currentPath, keyName];
+        // Skip defaultVariants as it doesn't contain classnames
+        if (keyName === "defaultVariants") {
+            continue;
+        }
+        // Recurse into nested objects (variants, compoundVariants entries, etc.)
+        if (property.value.type === utils_1.AST_NODE_TYPES.ObjectExpression) {
+            locations.push(...extractFromCvaObject(property.value, functionName, propertyPath));
+            continue;
+        }
+        // Handle arrays (compoundVariants array, or array of class strings)
+        if (property.value.type === utils_1.AST_NODE_TYPES.ArrayExpression) {
+            // Check if this is an array of objects (like compoundVariants)
+            const hasObjectElements = property.value.elements.some(el => el?.type === utils_1.AST_NODE_TYPES.ObjectExpression);
+            if (hasObjectElements) {
+                // Recurse into each object in the array
+                property.value.elements.forEach((element, index) => {
+                    if (element?.type === utils_1.AST_NODE_TYPES.ObjectExpression) {
+                        locations.push(...extractFromCvaObject(element, functionName, [...propertyPath, `[${index}]`]));
+                    }
+                });
+            }
+            else {
+                // This is an array of class strings
+                const arrayContext = {
+                    type: "cva-variant",
+                    functionName,
+                    variantPath: propertyPath,
+                };
+                locations.push(...extractFromArray(property.value, arrayContext));
+            }
+            continue;
+        }
+        // Extract string values at leaf nodes
+        const extracted = extractStringValue(property.value);
+        if (extracted) {
+            locations.push({
+                value: extracted.value,
+                reportNode: property.value,
+                fixNode: extracted.node,
+                context: {
+                    type: "cva-variant",
+                    functionName,
+                    variantPath: propertyPath,
+                },
+            });
+        }
+    }
+    return locations;
+};
+/**
+ * Get the name of an object property key
+ */
+const getPropertyKeyName = (key) => {
+    if (key.type === utils_1.AST_NODE_TYPES.Identifier) {
+        return key.name;
+    }
+    if (key.type === utils_1.AST_NODE_TYPES.Literal && typeof key.value === "string") {
+        return key.value;
+    }
+    return null;
+};
+// =============================================================================
+// Function Call Extraction
+// =============================================================================
+/**
+ * Extract classname locations from a Tailwind function call.
+ *
+ * Handles various argument patterns:
+ * - String literals: twMerge("flex items-center")
+ * - Template literals: twMerge(`flex ${condition && "hidden"}`)
+ * - Arrays: cvaMerge(["flex", "items-center"], options)
+ * - CVA options objects: cva(base, { variants: { ... } })
+ */
+const extractFromFunctionCall = (node) => {
+    const calleeName = (0, exports.getCalleeName)(node.callee);
+    if (!calleeName || !(0, exports.isTailwindFunction)(calleeName)) {
+        return [];
+    }
+    const locations = [];
+    const isCvaStyle = calleeName === "cva" || calleeName === "cvaMerge";
+    node.arguments.forEach((arg, argIndex) => {
+        const baseContext = {
+            type: "function-call",
+            functionName: calleeName,
+            argumentIndex: argIndex,
+        };
+        // Handle string literals
+        const extracted = extractStringValue(arg);
+        if (extracted) {
+            locations.push({
+                value: extracted.value,
+                reportNode: arg,
+                fixNode: extracted.node,
+                context: baseContext,
+            });
+            return;
+        }
+        // Handle array arguments
+        if (arg.type === utils_1.AST_NODE_TYPES.ArrayExpression) {
+            locations.push(...extractFromArray(arg, baseContext));
+            return;
+        }
+        // Handle CVA options object (typically second argument)
+        if (isCvaStyle && arg.type === utils_1.AST_NODE_TYPES.ObjectExpression) {
+            locations.push(...extractFromCvaObject(arg, calleeName));
+        }
+    });
+    return locations;
+};
+// =============================================================================
+// JSX Attribute Extraction
+// =============================================================================
+/**
+ * Extract classname locations from a JSX attribute (className or class).
+ *
+ * Handles various value patterns:
+ * - String literals: className="flex items-center"
+ * - Expression with string: className={"flex items-center"}
+ * - Template literals: className={`flex ${condition && "hidden"}`}
+ */
+const extractFromJsxAttribute = (node) => {
+    if (node.name.type !== utils_1.AST_NODE_TYPES.JSXIdentifier) {
+        return [];
+    }
+    const attrName = node.name.name;
+    if (!(0, exports.isClassnameAttribute)(attrName)) {
+        return [];
+    }
+    const attrValue = node.value;
+    if (!attrValue) {
+        return [];
+    }
+    const context = {
+        type: "jsx-attribute",
+        attributeName: attrName,
+    };
+    // Direct string literal: className="flex items-center"
+    if (attrValue.type === utils_1.AST_NODE_TYPES.Literal) {
+        const extracted = extractFromLiteral(attrValue);
+        if (extracted) {
+            return [
+                {
+                    value: extracted.value,
+                    reportNode: node,
+                    fixNode: extracted.node,
+                    context,
+                },
+            ];
+        }
+    }
+    // JSX Expression: className={...}
+    if (attrValue.type === utils_1.AST_NODE_TYPES.JSXExpressionContainer) {
+        const expression = attrValue.expression;
+        // Skip empty expressions
+        if (expression.type === utils_1.AST_NODE_TYPES.JSXEmptyExpression) {
+            return [];
+        }
+        // String literal in expression: className={"flex items-center"}
+        const extracted = extractStringValue(expression);
+        if (extracted) {
+            return [
+                {
+                    value: extracted.value,
+                    reportNode: node,
+                    fixNode: extracted.node,
+                    context,
+                },
+            ];
+        }
+        // Note: We don't recurse into function calls here as they're handled
+        // separately by the CallExpression handler in the rule
+    }
+    return [];
+};
+// =============================================================================
+// Variable Declaration Extraction
+// =============================================================================
+/**
+ * Extract classname locations from a variable declaration with a classname-like name.
+ *
+ * Example: const buttonClass = "flex items-center";
+ */
+const extractFromVariableDeclarator = (node) => {
+    if (node.id.type !== utils_1.AST_NODE_TYPES.Identifier) {
+        return [];
+    }
+    const varName = node.id.name;
+    if (!(0, exports.isClassnameVariable)(varName)) {
+        return [];
+    }
+    if (!node.init) {
+        return [];
+    }
+    const context = {
+        type: "variable",
+        variableName: varName,
+    };
+    // Handle string literal
+    const extracted = extractStringValue(node.init);
+    if (extracted) {
+        return [
+            {
+                value: extracted.value,
+                reportNode: node.init,
+                fixNode: extracted.node,
+                context,
+            },
+        ];
+    }
+    // Handle array of strings
+    if (node.init.type === utils_1.AST_NODE_TYPES.ArrayExpression) {
+        return extractFromArray(node.init, context);
+    }
+    // Note: Function calls in variable initializers are handled separately
+    // by the CallExpression handler
+    return [];
+};
+// =============================================================================
+// Unified Entry Points
+// =============================================================================
+/**
+ * Find all classname string locations in a CallExpression node.
+ *
+ * Use this in your ESLint rule's CallExpression handler to process
+ * Tailwind utility function calls like twMerge, cvaMerge, etc.
+ *
+ * @example
+ * ```typescript
+ * CallExpression(node) {
+ *   const locations = findClassnameStringsInCall(node);
+ *   for (const location of locations) {
+ *     if (hasBannedPattern(location.value)) {
+ *       context.report({ node: location.reportNode, ... });
+ *     }
+ *   }
+ * }
+ * ```
+ */
+const findClassnameStringsInCall = (node) => {
+    return extractFromFunctionCall(node);
+};
+exports.findClassnameStringsInCall = findClassnameStringsInCall;
+/**
+ * Find all classname string locations in a JSXAttribute node.
+ *
+ * Use this in your ESLint rule's JSXAttribute handler to process
+ * className and class attributes.
+ *
+ * @example
+ * ```typescript
+ * JSXAttribute(node) {
+ *   const locations = findClassnameStringsInAttribute(node);
+ *   for (const location of locations) {
+ *     if (hasBannedPattern(location.value)) {
+ *       context.report({ node: location.reportNode, ... });
+ *     }
+ *   }
+ * }
+ * ```
+ */
+const findClassnameStringsInAttribute = (node) => {
+    return extractFromJsxAttribute(node);
+};
+exports.findClassnameStringsInAttribute = findClassnameStringsInAttribute;
+/**
+ * Find all classname string locations in a VariableDeclarator node.
+ *
+ * Use this in your ESLint rule's VariableDeclarator handler to process
+ * variables with classname-like names.
+ *
+ * @example
+ * ```typescript
+ * VariableDeclarator(node) {
+ *   const locations = findClassnameStringsInVariable(node);
+ *   for (const location of locations) {
+ *     if (hasBannedPattern(location.value)) {
+ *       context.report({ node: location.reportNode, ... });
+ *     }
+ *   }
+ * }
+ * ```
+ */
+const findClassnameStringsInVariable = (node) => {
+    return extractFromVariableDeclarator(node);
+};
+// =============================================================================
+// Utility Helpers for Fixing
+// =============================================================================
+/**
+ * Split a classname string into individual class names.
+ * Handles whitespace-separated classes.
+ */
+const splitClasses = (value) => {
+    return value.split(/\s+/).filter(Boolean);
+};
+exports.splitClasses = splitClasses;
+/**
+ * Join class names into a single string.
+ */
+const joinClasses = (classes) => {
+    return classes.join(" ");
+};
+exports.joinClasses = joinClasses;
+/**
+ * Create a JSON-formatted array string from an array of class names.
+ * Useful for auto-fix operations.
+ */
+const formatAsArray = (classes) => {
+    return JSON.stringify(classes);
+};
+exports.formatAsArray = formatAsArray;
+/**
+ * Get the quote character used in a string literal.
+ */
+const getQuoteChar = (node) => {
+    if (typeof node.value === "string" && node.raw) {
+        return node.raw.charAt(0);
+    }
+    return '"';
+};
+/**
+ * Create a quoted string with the same quote style as the original.
+ */
+const quoteString = (value, originalNode) => {
+    const quote = getQuoteChar(originalNode);
+    return `${quote}${value}${quote}`;
+};
+//# sourceMappingURL=classname-utils.js.map