alpha/v4-settings (#416)

* refactor

* playing with settings

* settings

Author: francoismassart

docs/rules/my-rule.md

@@ -16,9 +16,14 @@ Examples would normally go here.
 
 <!-- begin auto-generated rule options list -->
 
-| Name       | Description           | Type    | Choices           | Default  |
-| :--------- | :-------------------- | :------ | :---------------- | :------- |
-| `someBool` | someBool description. | Boolean |                   | `true`   |
-| `someEnum` | someEnum description. | String  | `always`, `never` | `always` |
+| Name                 | Description                                                          | Type     | Choices           | Default                |
+| :------------------- | :------------------------------------------------------------------- | :------- | :---------------- | :--------------------- |
+| `callees`            | List of function names to validate classnames                        | String[] |                   | [`ctl`]                |
+| `cssConfigPath`      | Path to the Tailwind CSS configuration file (*.css)                  | String   |                   | `default-path/app.css` |
+| `removeDuplicates`   | Remove duplicated classnames                                         | Boolean  |                   | `true`                 |
+| `skipClassAttribute` | If you only want to lint the classnames inside one of the `callees`. | Boolean  |                   | `false`                |
+| `someBool`           | someBool description.                                                | Boolean  |                   | `false`                |
+| `someEnum`           | someEnum description.                                                | String   | `always`, `never` | `always`               |
+| `tags`               | List of tags to be detected in template literals                     | String[] |                   | [`tw`]                 |
 
 <!-- end auto-generated rule options list -->

jest.config.js

@@ -6,5 +6,5 @@ module.exports = {
   testMatch: ["**/*.spec.ts"],
   // Jest running with imported vitest utils causes errors like:
   // Vitest cannot be imported in a CommonJS module using require(). Please use "import" instead.
-  modulePathIgnorePatterns: ["<rootDir>/src/util/tailwindcss-api/worker/"],
+  modulePathIgnorePatterns: ["<rootDir>/src/utils/tailwindcss-api/worker/"],
 };

src/index.ts

@@ -1,30 +1,38 @@
-import { RuleModule } from "@typescript-eslint/utils/ts-eslint";
-import { ESLint } from "eslint";
+import * as parserBase from "@typescript-eslint/parser";
+import { TSESLint } from "@typescript-eslint/utils";
+import { Linter } from "@typescript-eslint/utils/ts-eslint";
 
 import { rules } from "./rules";
 
-type RuleKey = keyof typeof rules;
-
-interface Plugin extends Omit<ESLint.Plugin, "rules"> {
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  rules: Record<RuleKey, RuleModule<any, any, any>>;
-}
+export const parser: TSESLint.FlatConfig.Parser = {
+  meta: parserBase.meta,
+  parseForESLint: parserBase.parseForESLint,
+};
 
 const { name, version } =
   // `import`ing here would bypass the TSConfig's `"rootDir": "src"`
+  // Also an import statement will make TSC copy the package.json to the dist folder
   // eslint-disable-next-line @typescript-eslint/no-require-imports
-  require("../package.json") as typeof import("../package.json");
+  require("../package.json") as {
+    name: string;
+    version: string;
+  };
+
+/**
+ * TODO: Add configs (recommended, etc.)
+ * @see https://github.com/typescript-eslint/examples/blob/main/packages/eslint-plugin-example-typed-linting/src/index.ts
+ */
 
-const plugin: Plugin = {
-  /**
-   * TODO: Add configs (recommended, etc.)
-   * @see https://github.com/typescript-eslint/examples/blob/main/packages/eslint-plugin-example-typed-linting/src/index.ts
-   */
+// Plugin not fully initialized yet.
+// See https://eslint.org/docs/latest/extend/plugins#configs-in-plugins
+const plugin = {
+  // `configs`, assigned later
+  configs: {},
+  rules,
   meta: {
     name,
     version,
   },
-  rules,
-};
+} satisfies Linter.Plugin;
 
-export = plugin;
+export default plugin;

src/rules/my-rule.spec.ts

@@ -19,13 +19,30 @@ ruleTester.run(RULE_NAME, myRule, {
     {
       // a code snippet that should pass the linter
       code: `const x = 5;`,
+      options: [
+        {
+          callees: ["ctl2"],
+          someBool: true,
+          someEnum: "always",
+        },
+      ],
     },
     {
       code: `let y = 'abc123';`,
     },
     {
       code: `<button onClick={() => { const name = 'John'; alert(name); }}>JSX</button>`,
     },
+    {
+      // a code snippet that should pass the linter
+      code: `var x = 5;`,
+      options: [
+        {
+          someBool: true,
+          someEnum: "always",
+        },
+      ],
+    },
   ],
   invalid: [
     {

src/rules/my-rule.ts

@@ -2,6 +2,12 @@ import { RuleCreator } from "@typescript-eslint/utils/eslint-utils";
 
 import { PluginSharedSettings } from "../types";
 import urlCreator from "../url-creator";
+import {
+  DEFAULTS,
+  parsePluginSettings,
+  type PluginSettings,
+  sharedSettingsSchema,
+} from "../utils/parse-plugin-settings";
 
 export { ESLintUtils } from "@typescript-eslint/utils";
 
@@ -10,13 +16,28 @@ export const RULE_NAME = "my-rule";
 // Message IDs don't need to be prefixed, I just find it easier to keep track of them this way
 type MessageIds = "issue:var" | "fix:let" | "fix:const";
 
-// The options that the rule can take
-type Options = [
-  {
-    someBool: boolean;
-    someEnum: string;
-  }
-];
+/**
+ * The extra options that the rule can accept.
+ * These options get merged with the shared settings.
+ * The typing is not used by `eslint-doc-generator` which uses the `schema` property in the rule's metadata.
+ * Yet, it is useful for the IDE to provide autocompletion and type checking.
+ */
+type RuleOptions = {
+  someBool: boolean;
+  someEnum: string;
+};
+
+export type MergedOptions = RuleOptions & PluginSettings;
+
+const RULE_DEFAULT: RuleOptions = {
+  someBool: false,
+  someEnum: "always",
+};
+
+// TODO which one ?
+// - type Options = [RuleOptions];
+// - type Options = [MergedOptions];
+type Options = [MergedOptions];
 
 // The Rule creator returns a function that is used to create a well-typed ESLint rule
 // The parameter passed into RuleCreator is a URL generator function.
@@ -34,20 +55,22 @@ export const myRule = createRule<Options, MessageIds>({
       "fix:let": "Replace this `var` declaration with `let`",
       "fix:const": "Replace this `var` declaration with `const`",
     },
+    // Schema is also parsed by `eslint-doc-generator`
     schema: [
       {
         type: "object",
         properties: {
+          ...sharedSettingsSchema,
           someBool: {
             description: "someBool description.",
             type: "boolean",
-            default: true,
+            default: RULE_DEFAULT.someBool,
           },
           someEnum: {
             description: "someEnum description.",
             type: "string",
             enum: ["always", "never"],
-            default: "always",
+            default: RULE_DEFAULT.someEnum,
           },
         },
         additionalProperties: false,
@@ -62,21 +85,37 @@ export const myRule = createRule<Options, MessageIds>({
    * - If some configuration is provided as the second argument, it is ignored, not merged
    * - In other words, the `defaultOptions` is only used when the rule is used without configuration
    */
-  defaultOptions: [{ someBool: false, someEnum: "always" }],
+  defaultOptions: [
+    {
+      ...DEFAULTS,
+      someBool: false,
+      someEnum: "always",
+    },
+  ],
   create: (context, options) => {
+    // Reading inline configuration
+    console.log("\n", new Date(), "\n", "Options (rule):", "\n", options[0]);
+
+    // Shared settings
+    const sharedSettings = (context.settings?.tailwindcss ||
+      DEFAULTS) as PluginSharedSettings;
+    console.log("\n", "sharedSettings (rule):", "\n", sharedSettings);
+
+    // Merged settings
+    // const merged = parsePluginSettings(options[0]) as RuleOptions;
+    const merged = parsePluginSettings<RuleOptions>({
+      tailwindcss: options[0],
+    }) as RuleOptions;
+    console.log("\n", "merged (rule):", "\n", merged);
+
     return {
       VariableDeclaration: (node) => {
+        console.log("\n", "merged.someBool:", "\n", merged.someBool);
+        if (merged.someBool === true) {
+          console.log("someBool is true, processing VariableDeclaration");
+          return;
+        }
         if (node.kind === "var") {
-          // Reading inline configuration
-          console.log("\n", "Options:", "\n", options[0]);
-
-          // Shared settings
-          const sharedSettings = (context.settings?.tailwindcss || {
-            stylesheet: "",
-            functions: [],
-          }) as PluginSharedSettings;
-          console.log("\n", "sharedSettings:", "\n", sharedSettings);
-
           const rangeStart = node.range[0];
           const range: readonly [number, number] = [
             rangeStart,

src/utils/parse-plugin-settings.ts

@@ -0,0 +1,82 @@
+// Inspired by https://github.com/vitest-dev/eslint-plugin-vitest/blob/7fb864c28f91a92891c7a4fa025ca9d2a9780d49/src/utils/parse-plugin-settings.ts
+
+import { JSONSchema4 } from "@typescript-eslint/utils/json-schema";
+import type { SharedConfigurationSettings } from "@typescript-eslint/utils/ts-eslint";
+
+/**
+ * Typing of the shared settings of the eslint-plugin-tailwindcss.
+ */
+export type PluginSettings = {
+  callees?: Array<string>; // TODO can we use a {Set<string>} instead ?
+  cssConfigPath?: string;
+  removeDuplicates?: boolean;
+  skipClassAttribute?: boolean;
+  tags?: Array<string>; // TODO can we use a {Set<string>} instead ?
+};
+
+/**
+ * The default values for the shared settings.
+ */
+export const DEFAULTS: PluginSettings = {
+  callees: ["ctl"],
+  cssConfigPath: "default-path/app.css",
+  removeDuplicates: true,
+  skipClassAttribute: false,
+  tags: ["tw"],
+};
+
+/**
+ * The JSON schema for the shared settings to be reused in many of the rule's configuration.
+ */
+export const sharedSettingsSchema: Record<keyof PluginSettings, JSONSchema4> = {
+  callees: {
+    description: "List of function names to validate classnames",
+    type: "array",
+    items: { type: "string", minLength: 0 },
+    uniqueItems: true,
+    default: DEFAULTS.callees,
+  },
+  cssConfigPath: {
+    description: "Path to the Tailwind CSS configuration file (*.css)",
+    type: "string",
+    default: DEFAULTS.cssConfigPath,
+  },
+  removeDuplicates: {
+    description: "Remove duplicated classnames",
+    type: "boolean",
+    default: DEFAULTS.removeDuplicates,
+  },
+  skipClassAttribute: {
+    description:
+      "If you only want to lint the classnames inside one of the `callees`.",
+    type: "boolean",
+    default: DEFAULTS.skipClassAttribute,
+  },
+  tags: {
+    description: "List of tags to be detected in template literals",
+    type: "array",
+    items: { type: "string", minLength: 0 },
+    uniqueItems: true,
+    default: DEFAULTS.tags,
+  },
+};
+
+/**
+ * @description Parses the global eslint settings and merge.
+ * @param settings The shared settings from the ESLint configuration.
+ * @returns The parsed plugin settings.
+ */
+export function parsePluginSettings<RuleOptions>(
+  settings: SharedConfigurationSettings
+): PluginSettings & RuleOptions {
+  const tailwindcssSettings = (
+    typeof settings.tailwindcss !== "object" || settings.tailwindcss === null
+      ? {}
+      : settings.tailwindcss
+  ) as PluginSettings & RuleOptions;
+
+  return {
+    ...DEFAULTS,
+    ...tailwindcssSettings,
+  };
+}