@trackunit/css-classname-utils 0.0.2

package/README.md

@@ -0,0 +1,19 @@
+# Trackunit css-classname-utils
+
+The `@trackunit/css-classname-utils` package is the home of Trackunit's Tailwind/classname detection utilities.
+It has no dependency on `eslint` or `@typescript-eslint/utils`, so it can be consumed by any TypeScript project,
+not just ESLint plugins.
+
+For more info and a full guide on Iris App SDK Development, please visit our [Developer Hub](https://developers.trackunit.com/).
+
+## Development
+
+At this point this library is only developed by Trackunit Employees.  
+For development related information see the [development readme](https://github.com/Trackunit/manager/blob/master/libs/react/components/DEVELOPMENT.md).
+
+## Trackunit
+
+This package was developed by Trackunit ApS.
+Trackunit is the leading SaaS-based IoT solution for the construction industry, offering an ecosystem of hardware, fleet management software & telematics.
+
+![The Trackunit logo](https://trackunit.com/wp-content/uploads/2022/03/top-logo.svg)

package/index.cjs.js

@@ -0,0 +1,554 @@
+'use strict';
+
+var types = require('@typescript-eslint/types');
+
+// =============================================================================
+// Constants
+// =============================================================================
+/**
+ * Function names that accept Tailwind class strings as arguments.
+ * These are commonly used for class merging and conditional class application.
+ *
+ * Kept in sync with Prettier's Tailwind CSS plugin config by
+ * `classname-config-sync.spec.ts`.
+ */
+const TAILWIND_FUNCTIONS = [
+    "cva",
+    "cvaMerge",
+    "tw",
+    "twx",
+    "tws",
+    "twMerge",
+    "twJoin",
+    "cn",
+    "clsx",
+    "classNames",
+];
+/**
+ * Variable name suffixes that indicate a classname value.
+ * Matches variables like: containerClass, buttonClassName, rootClasses
+ *
+ * Kept in sync with the VS Code `tailwindCSS.experimental.classRegex` setting by
+ * `classname-config-sync.spec.ts`, since Prettier has no equivalent option to check against.
+ */
+const CLASSNAME_VARIABLE_SUFFIXES = ["Class", "ClassName", "Classes"];
+/**
+ * Variable name patterns that indicate a classname value, derived from CLASSNAME_VARIABLE_SUFFIXES.
+ */
+const CLASSNAME_VARIABLE_PATTERNS = CLASSNAME_VARIABLE_SUFFIXES.map(suffix => new RegExp(`${suffix}$`));
+/**
+ * JSX attribute names that contain classname values
+ */
+const CLASSNAME_ATTRIBUTES = ["className", "class"];
+// =============================================================================
+// Detection Helpers
+// =============================================================================
+/**
+ * Check if a function name is a known Tailwind utility function
+ */
+const isTailwindFunction = (name) => {
+    return TAILWIND_FUNCTIONS.some(fn => fn === name);
+};
+/**
+ * Check if a variable name indicates it contains classnames
+ */
+const isClassnameVariable = (name) => {
+    return CLASSNAME_VARIABLE_PATTERNS.some(pattern => pattern.test(name));
+};
+/**
+ * Check if a JSX attribute name is a classname attribute
+ */
+const isClassnameAttribute = (name) => {
+    return CLASSNAME_ATTRIBUTES.some(attr => attr === name);
+};
+/**
+ * Get the function name from a CallExpression callee
+ */
+const getCalleeName = (callee) => {
+    if (callee.type === types.AST_NODE_TYPES.Identifier) {
+        return callee.name;
+    }
+    if (callee.type === types.AST_NODE_TYPES.MemberExpression && callee.property.type === types.AST_NODE_TYPES.Identifier) {
+        return callee.property.name;
+    }
+    return null;
+};
+// =============================================================================
+// 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 types.AST_NODE_TYPES.Literal:
+            return extractFromLiteral(node);
+        case types.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 === types.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 !== types.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 === types.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 === types.AST_NODE_TYPES.ArrayExpression) {
+            // Check if this is an array of objects (like compoundVariants)
+            const hasObjectElements = property.value.elements.some(el => el?.type === types.AST_NODE_TYPES.ObjectExpression);
+            if (hasObjectElements) {
+                // Recurse into each object in the array
+                property.value.elements.forEach((element, index) => {
+                    if (element?.type === types.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 === types.AST_NODE_TYPES.Identifier) {
+        return key.name;
+    }
+    if (key.type === types.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 = getCalleeName(node.callee);
+    if (!calleeName || !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 === types.AST_NODE_TYPES.ArrayExpression) {
+            locations.push(...extractFromArray(arg, baseContext));
+            return;
+        }
+        // Handle CVA options object (typically second argument)
+        if (isCvaStyle && arg.type === types.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 !== types.AST_NODE_TYPES.JSXIdentifier) {
+        return [];
+    }
+    const attrName = node.name.name;
+    if (!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 === types.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 === types.AST_NODE_TYPES.JSXExpressionContainer) {
+        const expression = attrValue.expression;
+        // Skip empty expressions
+        if (expression.type === types.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 !== types.AST_NODE_TYPES.Identifier) {
+        return [];
+    }
+    const varName = node.id.name;
+    if (!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 === types.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);
+};
+/**
+ * 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);
+};
+/**
+ * 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);
+};
+/**
+ * Join class names into a single string.
+ */
+const joinClasses = (classes) => {
+    return classes.join(" ");
+};
+/**
+ * Create a JSON-formatted array string from an array of class names.
+ * Useful for auto-fix operations.
+ */
+const formatAsArray = (classes) => {
+    return JSON.stringify(classes);
+};
+/**
+ * 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}`;
+};
+
+/**
+ * Matches zero or more chained Tailwind variant prefixes (e.g. `hover:`, `sm:`,
+ * `dark:hover:`) that may precede a class token. Kept generic (word chars/hyphens
+ * followed by a colon) rather than an enumerated variant list, so it stays in sync
+ * with any variant Tailwind supports without needing updates here.
+ */
+const VARIANT_PREFIX = "(?:[\\w-]+:)*";
+/**
+ * Replace a class token in a whitespace-separated classname string, word-boundary safe.
+ *
+ * Handles both prefix-based patterns (e.g., `bg-red-500` -> `bg-danger-500`) and exact
+ * token matches (e.g., `red` -> `blue`).
+ *
+ * When `replacement` is the empty string, the whole matched token is deleted and the
+ * surrounding whitespace is collapsed so no double space (or leading/trailing space) is
+ * left behind.
+ */
+function replaceClassToken(value, pattern, replacement, options) {
+    const prefixes = options?.prefixes;
+    const hasPrefixes = prefixes !== undefined && prefixes.length > 0;
+    if (replacement === "") {
+        return deleteToken(value, pattern, hasPrefixes ? prefixes : undefined);
+    }
+    if (hasPrefixes) {
+        // With prefixes, replace -pattern- with -replacement-. Any variant prefix (e.g.
+        // "hover:bg-") is untouched since we only match starting from the hyphen.
+        const prefixRegex = new RegExp(`-${pattern}(-|$|/)`, "g");
+        return value.replace(prefixRegex, `-${replacement}$1`);
+    }
+    // Without prefixes, replace exact word boundaries, preserving any variant prefix
+    // chain (e.g. "sm:red" keeps "sm:" and only swaps "red" for the replacement).
+    const exactRegex = new RegExp(`(^|\\s)(${VARIANT_PREFIX})${pattern}($|\\s)`, "g");
+    return value.replace(exactRegex, `$1$2${replacement}$3`);
+}
+/**
+ * Remove a class token entirely, collapsing surrounding whitespace.
+ *
+ * - Token flanked by whitespace on both sides: one side of whitespace is kept as the
+ *   separator between its neighbors.
+ * - Token at the very start or end of the string: the single boundary whitespace is
+ *   removed along with the token.
+ */
+function deleteToken(value, pattern, prefixes) {
+    const regex = prefixes !== undefined
+        ? new RegExp(`(^|\\s)${VARIANT_PREFIX}(?:${prefixes.join("|")})-${pattern}(?:-[a-zA-Z0-9]+)?(?:/\\d+)?($|\\s)`, "g")
+        : new RegExp(`(^|\\s)${VARIANT_PREFIX}${pattern}($|\\s)`, "g");
+    return value.replace(regex, (_fullMatch, before, after) => (before && after ? before : ""));
+}
+
+exports.CLASSNAME_ATTRIBUTES = CLASSNAME_ATTRIBUTES;
+exports.CLASSNAME_VARIABLE_SUFFIXES = CLASSNAME_VARIABLE_SUFFIXES;
+exports.TAILWIND_FUNCTIONS = TAILWIND_FUNCTIONS;
+exports.findClassnameStringsInAttribute = findClassnameStringsInAttribute;
+exports.findClassnameStringsInCall = findClassnameStringsInCall;
+exports.findClassnameStringsInVariable = findClassnameStringsInVariable;
+exports.formatAsArray = formatAsArray;
+exports.getCalleeName = getCalleeName;
+exports.isClassnameAttribute = isClassnameAttribute;
+exports.isClassnameVariable = isClassnameVariable;
+exports.isTailwindFunction = isTailwindFunction;
+exports.joinClasses = joinClasses;
+exports.quoteString = quoteString;
+exports.replaceClassToken = replaceClassToken;
+exports.splitClasses = splitClasses;

package/index.d.ts

@@ -0,0 +1 @@
+export * from "./src/index";

package/index.esm.js

@@ -0,0 +1,538 @@
+import { AST_NODE_TYPES } from '@typescript-eslint/types';
+
+// =============================================================================
+// Constants
+// =============================================================================
+/**
+ * Function names that accept Tailwind class strings as arguments.
+ * These are commonly used for class merging and conditional class application.
+ *
+ * Kept in sync with Prettier's Tailwind CSS plugin config by
+ * `classname-config-sync.spec.ts`.
+ */
+const TAILWIND_FUNCTIONS = [
+    "cva",
+    "cvaMerge",
+    "tw",
+    "twx",
+    "tws",
+    "twMerge",
+    "twJoin",
+    "cn",
+    "clsx",
+    "classNames",
+];
+/**
+ * Variable name suffixes that indicate a classname value.
+ * Matches variables like: containerClass, buttonClassName, rootClasses
+ *
+ * Kept in sync with the VS Code `tailwindCSS.experimental.classRegex` setting by
+ * `classname-config-sync.spec.ts`, since Prettier has no equivalent option to check against.
+ */
+const CLASSNAME_VARIABLE_SUFFIXES = ["Class", "ClassName", "Classes"];
+/**
+ * Variable name patterns that indicate a classname value, derived from CLASSNAME_VARIABLE_SUFFIXES.
+ */
+const CLASSNAME_VARIABLE_PATTERNS = CLASSNAME_VARIABLE_SUFFIXES.map(suffix => new RegExp(`${suffix}$`));
+/**
+ * JSX attribute names that contain classname values
+ */
+const CLASSNAME_ATTRIBUTES = ["className", "class"];
+// =============================================================================
+// Detection Helpers
+// =============================================================================
+/**
+ * Check if a function name is a known Tailwind utility function
+ */
+const isTailwindFunction = (name) => {
+    return TAILWIND_FUNCTIONS.some(fn => fn === name);
+};
+/**
+ * Check if a variable name indicates it contains classnames
+ */
+const isClassnameVariable = (name) => {
+    return CLASSNAME_VARIABLE_PATTERNS.some(pattern => pattern.test(name));
+};
+/**
+ * Check if a JSX attribute name is a classname attribute
+ */
+const isClassnameAttribute = (name) => {
+    return CLASSNAME_ATTRIBUTES.some(attr => attr === name);
+};
+/**
+ * Get the function name from a CallExpression callee
+ */
+const getCalleeName = (callee) => {
+    if (callee.type === AST_NODE_TYPES.Identifier) {
+        return callee.name;
+    }
+    if (callee.type === AST_NODE_TYPES.MemberExpression && callee.property.type === AST_NODE_TYPES.Identifier) {
+        return callee.property.name;
+    }
+    return null;
+};
+// =============================================================================
+// 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 AST_NODE_TYPES.Literal:
+            return extractFromLiteral(node);
+        case 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 === 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 !== 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 === 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 === AST_NODE_TYPES.ArrayExpression) {
+            // Check if this is an array of objects (like compoundVariants)
+            const hasObjectElements = property.value.elements.some(el => el?.type === AST_NODE_TYPES.ObjectExpression);
+            if (hasObjectElements) {
+                // Recurse into each object in the array
+                property.value.elements.forEach((element, index) => {
+                    if (element?.type === 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 === AST_NODE_TYPES.Identifier) {
+        return key.name;
+    }
+    if (key.type === 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 = getCalleeName(node.callee);
+    if (!calleeName || !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 === AST_NODE_TYPES.ArrayExpression) {
+            locations.push(...extractFromArray(arg, baseContext));
+            return;
+        }
+        // Handle CVA options object (typically second argument)
+        if (isCvaStyle && arg.type === 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 !== AST_NODE_TYPES.JSXIdentifier) {
+        return [];
+    }
+    const attrName = node.name.name;
+    if (!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 === 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 === AST_NODE_TYPES.JSXExpressionContainer) {
+        const expression = attrValue.expression;
+        // Skip empty expressions
+        if (expression.type === 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 !== AST_NODE_TYPES.Identifier) {
+        return [];
+    }
+    const varName = node.id.name;
+    if (!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 === 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);
+};
+/**
+ * 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);
+};
+/**
+ * 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);
+};
+/**
+ * Join class names into a single string.
+ */
+const joinClasses = (classes) => {
+    return classes.join(" ");
+};
+/**
+ * Create a JSON-formatted array string from an array of class names.
+ * Useful for auto-fix operations.
+ */
+const formatAsArray = (classes) => {
+    return JSON.stringify(classes);
+};
+/**
+ * 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}`;
+};
+
+/**
+ * Matches zero or more chained Tailwind variant prefixes (e.g. `hover:`, `sm:`,
+ * `dark:hover:`) that may precede a class token. Kept generic (word chars/hyphens
+ * followed by a colon) rather than an enumerated variant list, so it stays in sync
+ * with any variant Tailwind supports without needing updates here.
+ */
+const VARIANT_PREFIX = "(?:[\\w-]+:)*";
+/**
+ * Replace a class token in a whitespace-separated classname string, word-boundary safe.
+ *
+ * Handles both prefix-based patterns (e.g., `bg-red-500` -> `bg-danger-500`) and exact
+ * token matches (e.g., `red` -> `blue`).
+ *
+ * When `replacement` is the empty string, the whole matched token is deleted and the
+ * surrounding whitespace is collapsed so no double space (or leading/trailing space) is
+ * left behind.
+ */
+function replaceClassToken(value, pattern, replacement, options) {
+    const prefixes = options?.prefixes;
+    const hasPrefixes = prefixes !== undefined && prefixes.length > 0;
+    if (replacement === "") {
+        return deleteToken(value, pattern, hasPrefixes ? prefixes : undefined);
+    }
+    if (hasPrefixes) {
+        // With prefixes, replace -pattern- with -replacement-. Any variant prefix (e.g.
+        // "hover:bg-") is untouched since we only match starting from the hyphen.
+        const prefixRegex = new RegExp(`-${pattern}(-|$|/)`, "g");
+        return value.replace(prefixRegex, `-${replacement}$1`);
+    }
+    // Without prefixes, replace exact word boundaries, preserving any variant prefix
+    // chain (e.g. "sm:red" keeps "sm:" and only swaps "red" for the replacement).
+    const exactRegex = new RegExp(`(^|\\s)(${VARIANT_PREFIX})${pattern}($|\\s)`, "g");
+    return value.replace(exactRegex, `$1$2${replacement}$3`);
+}
+/**
+ * Remove a class token entirely, collapsing surrounding whitespace.
+ *
+ * - Token flanked by whitespace on both sides: one side of whitespace is kept as the
+ *   separator between its neighbors.
+ * - Token at the very start or end of the string: the single boundary whitespace is
+ *   removed along with the token.
+ */
+function deleteToken(value, pattern, prefixes) {
+    const regex = prefixes !== undefined
+        ? new RegExp(`(^|\\s)${VARIANT_PREFIX}(?:${prefixes.join("|")})-${pattern}(?:-[a-zA-Z0-9]+)?(?:/\\d+)?($|\\s)`, "g")
+        : new RegExp(`(^|\\s)${VARIANT_PREFIX}${pattern}($|\\s)`, "g");
+    return value.replace(regex, (_fullMatch, before, after) => (before && after ? before : ""));
+}
+
+export { CLASSNAME_ATTRIBUTES, CLASSNAME_VARIABLE_SUFFIXES, TAILWIND_FUNCTIONS, findClassnameStringsInAttribute, findClassnameStringsInCall, findClassnameStringsInVariable, formatAsArray, getCalleeName, isClassnameAttribute, isClassnameVariable, isTailwindFunction, joinClasses, quoteString, replaceClassToken, splitClasses };

package/migrations/entry.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=entry.js.map

package/migrations.json

@@ -0,0 +1,3 @@
+{
+  "generators": {}
+}

package/package.json

@@ -0,0 +1,16 @@
+{
+  "name": "@trackunit/css-classname-utils",
+  "version": "0.0.2",
+  "repository": "https://github.com/Trackunit/manager",
+  "license": "SEE LICENSE IN LICENSE.txt",
+  "engines": {
+    "node": ">=24.x"
+  },
+  "dependencies": {
+    "@typescript-eslint/types": "8.58.1"
+  },
+  "migrations": "./migrations.json",
+  "module": "./index.esm.js",
+  "main": "./index.cjs.js",
+  "types": "./index.d.ts"
+}

package/src/classname-utils.d.ts

@@ -0,0 +1,192 @@
+import { TSESTree } from "@typescript-eslint/types";
+/**
+ * Utility functions for finding and analyzing Tailwind CSS classnames.
+ *
+ * This module lives in `@trackunit/css-classname-utils`, a dependency-light package
+ * (its only dependency is `@typescript-eslint/types`, with no runtime dependency on
+ * `eslint` or `@typescript-eslint/utils`) so it can be imported by any TypeScript
+ * project, not just ESLint plugins. It has two consumer categories:
+ *
+ * - **ESLint rules** in `plugin-trackunit` use these helpers to find and report on
+ *   classname usage (see "Usage in ESLint Rules" below).
+ * - **Nx migrations/codemods** import this package directly, with no ESLint context
+ *   needed, to detect and rewrite classnames across the codebase (e.g. via
+ *   `replaceClassToken` from `./replace-class-token`).
+ *
+ * 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.
+ *
+ * Kept in sync with Prettier's Tailwind CSS plugin config by
+ * `classname-config-sync.spec.ts`.
+ */
+export declare const TAILWIND_FUNCTIONS: readonly ["cva", "cvaMerge", "tw", "twx", "tws", "twMerge", "twJoin", "cn", "clsx", "classNames"];
+export type TailwindFunction = (typeof TAILWIND_FUNCTIONS)[number];
+/**
+ * Variable name suffixes that indicate a classname value.
+ * Matches variables like: containerClass, buttonClassName, rootClasses
+ *
+ * Kept in sync with the VS Code `tailwindCSS.experimental.classRegex` setting by
+ * `classname-config-sync.spec.ts`, since Prettier has no equivalent option to check against.
+ */
+export declare const CLASSNAME_VARIABLE_SUFFIXES: readonly ["Class", "ClassName", "Classes"];
+/**
+ * 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>;
+/**
+ * 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, ... });
+ *     }
+ *   }
+ * }
+ * ```
+ */
+export declare const findClassnameStringsInVariable: (node: TSESTree.VariableDeclarator) => 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;
+/**
+ * Create a quoted string with the same quote style as the original.
+ */
+export declare const quoteString: (value: string, originalNode: TSESTree.Literal) => string;

package/src/index.d.ts

@@ -0,0 +1,2 @@
+export * from "./classname-utils";
+export * from "./replace-class-token";

package/src/replace-class-token.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Options for {@link replaceClassToken}.
+ */
+export type ReplaceClassTokenOptions = {
+    /**
+     * Optional prefixes to match (e.g., "bg", "text", "border"). If not provided,
+     * `pattern` is matched as an exact, standalone class token.
+     */
+    prefixes?: Array<string>;
+};
+/**
+ * Replace a class token in a whitespace-separated classname string, word-boundary safe.
+ *
+ * Handles both prefix-based patterns (e.g., `bg-red-500` -> `bg-danger-500`) and exact
+ * token matches (e.g., `red` -> `blue`).
+ *
+ * When `replacement` is the empty string, the whole matched token is deleted and the
+ * surrounding whitespace is collapsed so no double space (or leading/trailing space) is
+ * left behind.
+ */
+export declare function replaceClassToken(value: string, pattern: string, replacement: string, options?: ReplaceClassTokenOptions): string;