eslint-plugin-tailwind-variants 2.0.3 → 2.1.1

package/src/rules/require-variants-call-styles-name.js

@@ -0,0 +1,195 @@
+export const MESSAGE_IDS = {
+  renameAllOccurrences: "renameAllOccurrences",
+  requireVariantsCallStylesName: "requireVariantsCallStylesName",
+};
+
+/** @typedef {typeof MESSAGE_IDS[keyof typeof MESSAGE_IDS]} MessageIds */
+
+/**
+ * @typedef {object} RuleOptions
+ * @property {string} [name="styles"] Name required for variables assigned from tv().
+ */
+
+/** @type {import("eslint").Rule.RuleModule} */
+export const rule = {
+  create: (context) => {
+    const [options = {}] = /** @type {[RuleOptions]} */ (context.options);
+    const requiredName = options.name ?? "styles";
+
+    // Tracks by name, not scope—shadowed identifiers may cause false positives
+    /** @type {Set<string>} */
+    const variantFunctions = new Set();
+
+    /**
+     * Check if expression is a tv() call and track the variable name if so.
+     * @param {import("estree").CallExpression} init
+     * @param {import("estree").Identifier} id
+     * @returns {boolean} `true` if expression is a tv() call and variable name is tracked.
+     */
+    const trackVariantFunction = (init, id) => {
+      if (init.callee.type === "Identifier" && init.callee.name === "tv") {
+        variantFunctions.add(id.name);
+        return true;
+      }
+      return false;
+    };
+
+    return {
+      VariableDeclarator(node) {
+        const { id, init } = node;
+
+        if (
+          !init ||
+          init.type !== "CallExpression" ||
+          init.callee.type !== "Identifier" ||
+          id.type !== "Identifier"
+        ) {
+          return;
+        }
+
+        if (trackVariantFunction(init, id)) {
+          return;
+        }
+
+        if (variantFunctions.has(init.callee.name)) {
+          detectVariantVariableNameViolation({
+            context,
+            declaratorNode: node,
+            id,
+            requiredName,
+          });
+        }
+      },
+    };
+  },
+
+  meta: {
+    defaultOptions: [
+      {
+        name: "styles",
+      },
+    ],
+    docs: {
+      description:
+        "Require variables assigned from calling a function returned by tv() to be named a specific name.",
+    },
+    hasSuggestions: true,
+    messages: {
+      renameAllOccurrences: "Rename all occurrences to {{name}}",
+      requireVariantsCallStylesName:
+        "Require variables assigned from calling a function returned by tv() to be named {{name}}.",
+    },
+    schema: [
+      {
+        additionalProperties: false,
+        properties: {
+          name: {
+            default: "styles",
+            description: "Name required for variables assigned from tv().",
+            type: "string",
+          },
+        },
+        type: "object",
+      },
+    ],
+    type: "suggestion",
+  },
+};
+
+/**
+ * Collect all references to a variable declaration, excluding the initial
+ * declaration.
+ * @param {object} options
+ * @param {import("eslint").SourceCode} options.sourceCode ESLint SourceCode instance.
+ * @param {import("estree").VariableDeclarator} options.declaratorNode VariableDeclarator node of the declaration.
+ * @param {import("estree").Identifier} options.id Identifier node of the variable being declared.
+ * @returns {import("estree").Identifier[]} Array of identifier nodes referencing the variable.
+ */
+const collectReferences = (options) => {
+  const declaredVariables = options.sourceCode.getDeclaredVariables(
+    options.declaratorNode,
+  );
+
+  /** @type {import("estree").Identifier[]} */
+  const references = [];
+
+  for (const variable of declaredVariables) {
+    if (variable.name === options.id.name) {
+      for (const reference of variable.references) {
+        if (
+          reference.identifier !== options.id &&
+          reference.identifier.type === "Identifier"
+        ) {
+          references.push(reference.identifier);
+        }
+      }
+      break;
+    }
+  }
+
+  return references;
+};
+
+/**
+ * Report incorrect variable name with autofix suggestion to rename all
+ * occurrences.
+ * @param {object} options
+ * @param {import("eslint").Rule.RuleContext} options.context
+ * @param {import("estree").Identifier} options.id Identifier node of the variable declaration.
+ * @param {import("estree").VariableDeclarator} options.declaratorNode
+ * @param {string} options.requiredName Required variable name.
+ */
+const reportIncorrectName = (options) => {
+  const { sourceCode } = options.context;
+  const references = collectReferences({
+    declaratorNode: options.declaratorNode,
+    id: options.id,
+    sourceCode,
+  });
+
+  options.context.report({
+    data: {
+      name: options.requiredName,
+    },
+    messageId: MESSAGE_IDS.requireVariantsCallStylesName,
+    node: options.id,
+    suggest: [
+      {
+        data: {
+          name: options.requiredName,
+        },
+        fix: (fixer) => {
+          const fixes = [fixer.replaceText(options.id, options.requiredName)];
+
+          for (const reference of references) {
+            fixes.push(fixer.replaceText(reference, options.requiredName));
+          }
+
+          return fixes;
+        },
+        messageId: MESSAGE_IDS.renameAllOccurrences,
+      },
+    ],
+  });
+};
+
+/**
+ * Detect variant variable name violations and report if found.
+ * @param {object} options
+ * @param {import("eslint").Rule.RuleContext} options.context
+ * @param {import("estree").Identifier} options.id Identifier node of the variable declaration.
+ * @param {import("estree").VariableDeclarator} options.declaratorNode
+ * @param {string} options.requiredName Required variable name.
+ */
+const detectVariantVariableNameViolation = (options) => {
+  const variableName = options.id.name;
+
+  if (variableName !== options.requiredName) {
+    reportIncorrectName({
+      context: options.context,
+      declaratorNode: options.declaratorNode,
+      id: options.id,
+      requiredName: options.requiredName,
+    });
+  }
+};

package/src/rules/require-variants-call-styles-name.test.js

@@ -0,0 +1,105 @@
+import { RuleTester } from "eslint";
+
+import { MESSAGE_IDS, rule } from "./require-variants-call-styles-name";
+
+const tester = new RuleTester();
+
+/** @type {import("eslint").RuleTester.ValidTestCase[]} */
+const valid = [
+  {
+    code: `const buttonVariants = tv({})`,
+    name: "Direct tv() call - no enforcement",
+  },
+  {
+    code: `
+      const buttonVariants = tv({});
+      const styles = buttonVariants();
+    `,
+    name: "Variant function call named 'styles' (default)",
+  },
+  {
+    code: `
+      const cardVariants = tv({});
+      const variants = cardVariants();
+    `,
+    name: "Variable named custom 'variants'",
+    options: [{ name: "variants" }],
+  },
+];
+
+/** @type {import("eslint").RuleTester.InvalidTestCase[]} */
+const invalid = [
+  {
+    code: `
+      const buttonVariants = tv({});
+      const buttonStyles = buttonVariants();
+    `,
+    errors: [
+      {
+        messageId: MESSAGE_IDS.requireVariantsCallStylesName,
+        suggestions: [
+          {
+            messageId: MESSAGE_IDS.renameAllOccurrences,
+            output: `
+      const buttonVariants = tv({});
+      const styles = buttonVariants();
+    `,
+          },
+        ],
+      },
+    ],
+    name: "Variant function call not named 'styles' (default)",
+  },
+  {
+    code: `
+      const cardVariants = tv({});
+      const styles = cardVariants();
+    `,
+    errors: [
+      {
+        messageId: MESSAGE_IDS.requireVariantsCallStylesName,
+        suggestions: [
+          {
+            messageId: MESSAGE_IDS.renameAllOccurrences,
+            output: `
+      const cardVariants = tv({});
+      const variants = cardVariants();
+    `,
+          },
+        ],
+      },
+    ],
+    name: "Variant function call not named custom 'variants'",
+    options: [{ name: "variants" }],
+  },
+  {
+    code: `
+      const buttonVariants = tv({});
+      const buttonStyles = buttonVariants();
+      console.log(buttonStyles);
+      const result = buttonStyles();
+    `,
+    errors: [
+      {
+        messageId: MESSAGE_IDS.requireVariantsCallStylesName,
+        suggestions: [
+          {
+            messageId: MESSAGE_IDS.renameAllOccurrences,
+            output: `
+      const buttonVariants = tv({});
+      const styles = buttonVariants();
+      console.log(styles);
+      const result = styles();
+    `,
+          },
+        ],
+      },
+    ],
+    name: "Renames declaration and all references via suggestion",
+  },
+];
+
+tester.run("require-variants-call-styles-name", rule, {
+  invalid,
+  valid,
+});

package/src/rules/require-variants-suffix.js

@@ -0,0 +1,146 @@
+export const MESSAGE_IDS = {
+  renameAllOccurrences: "renameAllOccurrences",
+  requireVariantsSuffix: "requireVariantsSuffix",
+};
+
+/** @typedef {typeof MESSAGE_IDS[keyof typeof MESSAGE_IDS]} MessageIds */
+
+/**
+ * @typedef {object} RuleOptions
+ * @property {string} [suffix="Variants"] Suffix required for variables assigned from tv().
+ */
+
+/** @type {import("eslint").Rule.RuleModule} */
+export const rule = {
+  create: (context) => {
+    const [options = {}] = /** @type {[RuleOptions]} */ (context.options);
+    const suffix = options.suffix ?? "Variants";
+
+    return {
+      VariableDeclarator(node) {
+        detectTvVariableNameViolation(node, context, suffix);
+      },
+    };
+  },
+  meta: {
+    defaultOptions: [
+      {
+        suffix: "Variants",
+      },
+    ],
+    docs: {
+      description:
+        "Require variables assigned from tv() to end with a given suffix.",
+    },
+    hasSuggestions: true,
+    messages: {
+      renameAllOccurrences: "Rename all occurrences to {{newName}}",
+      requireVariantsSuffix:
+        "Variable assigned from tv() must end with '{{suffix}}'.",
+    },
+    schema: [
+      {
+        additionalProperties: false,
+        properties: {
+          suffix: {
+            default: "Variants",
+            description: "Suffix required for variables assigned from tv().",
+            type: "string",
+          },
+        },
+        type: "object",
+      },
+    ],
+    type: "suggestion",
+  },
+};
+
+/**
+ * Check if expression is a tv() call.
+ * @param {import("estree").Expression} init
+ * @returns {boolean} `true` if expression is a tv() call.
+ */
+const isTvCallExpression = (init) =>
+  init.type === "CallExpression" &&
+  init.callee.type === "Identifier" &&
+  init.callee.name === "tv";
+
+/**
+ * Collect all references to a variable declaration, excluding the initial
+ * declaration.
+ * @param {object} options
+ * @param {import("eslint").SourceCode} options.sourceCode ESLint SourceCode instance.
+ * @param {import("estree").VariableDeclarator} options.declaratorNode VariableDeclarator node of the declaration.
+ * @param {import("estree").Identifier} options.id Identifier node of the variable being declared.
+ * @returns {import("estree").Identifier[]} Array of identifier nodes referencing the variable.
+ */
+const collectReferences = (options) => {
+  const declaredVariables = options.sourceCode.getDeclaredVariables(
+    options.declaratorNode,
+  );
+
+  /** @type {import("estree").Identifier[]} */
+  const references = [];
+
+  for (const variable of declaredVariables) {
+    if (variable.name === options.id.name) {
+      for (const reference of variable.references) {
+        if (
+          reference.identifier !== options.id &&
+          reference.identifier.type === "Identifier"
+        ) {
+          references.push(reference.identifier);
+        }
+      }
+      break;
+    }
+  }
+
+  return references;
+};
+
+/**
+ * Detect tv() variable naming violations and report with suggestion to rename all occurrences.
+ * @param {import("estree").VariableDeclarator} node
+ * @param {import("eslint").Rule.RuleContext} context
+ * @param {string} suffix Required variable name suffix.
+ */
+const detectTvVariableNameViolation = (node, context, suffix) => {
+  const { init, id } = node;
+
+  if (!init || !isTvCallExpression(init)) {
+    return;
+  }
+
+  if (id?.type !== "Identifier" || id.name.endsWith(suffix)) {
+    return;
+  }
+
+  const newName = `${id.name}${suffix}`;
+  const references = collectReferences({
+    declaratorNode: node,
+    id,
+    sourceCode: context.sourceCode,
+  });
+
+  context.report({
+    data: { suffix },
+    messageId: MESSAGE_IDS.requireVariantsSuffix,
+    node,
+    suggest: [
+      {
+        data: { newName },
+        fix: (fixer) => {
+          const fixes = [fixer.replaceText(id, newName)];
+
+          for (const reference of references) {
+            fixes.push(fixer.replaceText(reference, newName));
+          }
+
+          return fixes;
+        },
+        messageId: MESSAGE_IDS.renameAllOccurrences,
+      },
+    ],
+  });
+};

package/src/rules/require-variants-suffix.test.js

@@ -0,0 +1,81 @@
+import { RuleTester } from "eslint";
+
+import { MESSAGE_IDS, rule } from "./require-variants-suffix";
+
+const tester = new RuleTester();
+
+/** @type {import("eslint").RuleTester.ValidTestCase[]} */
+const valid = [
+  {
+    code: `const buttonVariants = tv({})`,
+    name: "Variable ends with 'Variants' suffix (default)",
+  },
+  {
+    code: `const buttonStyles = tv({})`,
+    name: "Variable ends with custom 'Styles' suffix",
+    options: [{ suffix: "Styles" }],
+  },
+];
+
+/** @type {import("eslint").RuleTester.InvalidTestCase[]} */
+const invalid = [
+  {
+    code: `const button = tv({})`,
+    errors: [
+      {
+        messageId: MESSAGE_IDS.requireVariantsSuffix,
+        suggestions: [
+          {
+            messageId: MESSAGE_IDS.renameAllOccurrences,
+            output: `const buttonVariants = tv({})`,
+          },
+        ],
+      },
+    ],
+    name: "Variable does not end with 'Variants' suffix (default)",
+  },
+  {
+    code: `const button = tv({})`,
+    errors: [
+      {
+        messageId: MESSAGE_IDS.requireVariantsSuffix,
+        suggestions: [
+          {
+            messageId: MESSAGE_IDS.renameAllOccurrences,
+            output: `const buttonStyles = tv({})`,
+          },
+        ],
+      },
+    ],
+    name: "Variable does not end with custom 'Styles' suffix",
+    options: [{ suffix: "Styles" }],
+  },
+  {
+    code: `
+      const button = tv({});
+      console.log(button);
+      const result = button;
+    `,
+    errors: [
+      {
+        messageId: MESSAGE_IDS.requireVariantsSuffix,
+        suggestions: [
+          {
+            messageId: MESSAGE_IDS.renameAllOccurrences,
+            output: `
+      const buttonVariants = tv({});
+      console.log(buttonVariants);
+      const result = buttonVariants;
+    `,
+          },
+        ],
+      },
+    ],
+    name: "Renames declaration and all references via suggestion",
+  },
+];
+
+tester.run("require-variants-suffix", rule, {
+  invalid,
+  valid,
+});