docs: add docs for eslint-plugin

There is a technically “breaking change” in here, but I know no-one is using the undocumented preferredAlias options yet.

.gitignore

@@ -9,7 +9,7 @@ node_modules
 build
 cache
 public/static
-docs
+./docs
 lib
 dist
 config/local.*

nx.json

@@ -14,6 +14,11 @@
       "inputs": ["default", "^default", "baseTypescript"],
       "outputs": ["{projectRoot}/dist"]
     },
+    "docs": {
+      "dependsOn": ["build"],
+      "inputs": ["default", "^default", "baseTypescript"],
+      "outputs": ["{projectRoot}/docs"]
+    },
     "test": {
       "dependsOn": ["^test"],
       "inputs": ["default", "^default", "testConfig"]

package.json

@@ -11,7 +11,7 @@
   "scripts": {
     "audit": "tablecheck-frontend-audit",
     "audit:ci": "npx tablecheck-frontend-audit --ci",
-    "lint": "nx affected --target=quality && prettier -c .",
+    "lint": "nx affected --target=quality && nx affected --target=quality:docs && prettier -c .",
     "format": "nx affected --target=quality:format && prettier -w --loglevel warn .",
     "test": "nx affected --target=test",
     "test:watch": "nx run-many --target=test:watch",
@@ -59,6 +59,7 @@
     "auditjs": "4.0.41",
     "auto": "11.0.4",
     "eslint": "^8",
+    "eslint-plugin-eslint-plugin": "5.1.1",
     "file-loader": "^6.2.0",
     "fs-extra": "^11.1.1",
     "husky": "8.0.3",

packages/eslint-plugin/.eslint-doc-generatorrc.js

@@ -0,0 +1,11 @@
+const prettier = require('prettier');
+
+/** @type {import('eslint-doc-generator').GenerateOptions} */
+const config = {
+  postprocess: async (content, path) => {
+    const prettierRC = await prettier.resolveConfig(path);
+    return prettier.format(content, { ...prettierRC, parser: 'markdown' });
+  },
+};
+
+module.exports = config;

packages/eslint-plugin/.eslintrc.json

@@ -1,18 +1,12 @@
 {
-  "extends": ["../../.eslintrc.js"],
   "ignorePatterns": ["!**/*"],
-  "overrides": [
-    {
-      "files": ["*.ts", "*.tsx", "*.js", "*.jsx"],
-      "rules": {}
-    },
-    {
-      "files": ["*.ts", "*.tsx"],
-      "rules": {}
-    },
-    {
-      "files": ["*.js", "*.jsx"],
-      "rules": {}
-    }
-  ]
+  "parserOptions": {
+    "sourceType": "script"
+  },
+  "extends": ["../../.eslintrc.js", "plugin:eslint-plugin/recommended"],
+  "rules": {
+    "eslint-plugin/require-meta-docs-url": "error",
+    "eslint-plugin/require-meta-docs-description": "error",
+    "eslint-plugin/require-meta-schema": "error"
+  }
 }

packages/eslint-plugin/README.md

@@ -1,3 +1,30 @@
-This eslint-plugin is used internally in the eslint-config.
+# @tablecheck/eslint-plugins
 
-Custom rules must be done in a plugin and cannot be done in an eslint-config by default, plugins must be separate packages.
+This repository contains custom eslint plugins that can be used to enforce coding standards and best practices in your JavaScript projects.
+
+These rules were written for code consistency in our Frontend Team at [TableCheck](https://www.tablecheck.com/en/join/).
+
+Learn more about [TableCheck](https://www.tablecheck.com/en/join/) and check out our [Careers page](https://careers.tablecheck.com).
+
+## Installation
+
+To install the plugins, run the following command:
+
+```sh
+npm install --save-dev @tablecheck/eslint-plugin
+```
+
+## Rules
+
+<!-- begin auto-generated rules list -->
+
+🔧 Automatically fixable by the [`--fix` CLI option](https://eslint.org/docs/user-guide/command-line-interface#--fix).\
+💭 Requires type information.
+
+| Name                                                             | Description                                                                                 | 🔧  | 💭  |
+| :--------------------------------------------------------------- | :------------------------------------------------------------------------------------------ | :-- | :-- |
+| [consistent-react-import](docs/rules/consistent-react-import.md) | Ensure that react is always imported and used consistently                                  | 🔧  |     |
+| [forbidden-imports](docs/rules/forbidden-imports.md)             | Ensure that certain packages are using specific imports instead of using the default import | 🔧  |     |
+| [prefer-shortest-import](docs/rules/prefer-shortest-import.md)   | Enforce the consistent use of preferred import paths                                        | 🔧  | 💭  |
+
+<!-- end auto-generated rules list -->

packages/eslint-plugin/__tests__/shortestImport.test.ts

@@ -179,12 +179,12 @@ typescriptSetups.forEach((config) => {
         {
           path: '~/feature1/index',
           filename: './test_src/feature1/slice1/index.ts',
-          options: [['~/feature1', 'feature1']],
+          options: [{ preferredAlias: ['~/feature1', 'feature1'] }],
         },
         {
           path: '~/feature1/slice1',
           filename: './test_src/feature1/index.ts',
-          options: [['~/feature1', 'feature1']],
+          options: [{ preferredAlias: ['~/feature1', 'feature1'] }],
         },
         {
           path: '@node/module',
@@ -272,7 +272,7 @@ typescriptSetups.forEach((config) => {
           fixedPath: '~/feature1/index',
           filename: './test_src/feature1/slice1/index.ts',
           errors: [{ messageId }],
-          options: [['~/feature1', 'feature1']],
+          options: [{ preferredAlias: ['~/feature1', 'feature1'] }],
         },
       ]
         .filter((c) => !c.skipConfigs || !c.skipConfigs.includes(config.name))

packages/eslint-plugin/docs/rules/consistent-react-import.md

@@ -0,0 +1,5 @@
+# Ensure that react is always imported and used consistently (`@tablecheck/consistent-react-import`)
+
+🔧 This rule is automatically fixable by the [`--fix` CLI option](https://eslint.org/docs/latest/user-guide/command-line-interface#--fix).
+
+<!-- end auto-generated rule header -->

packages/eslint-plugin/docs/rules/forbidden-imports.md

@@ -0,0 +1,5 @@
+# Ensure that certain packages are using specific imports instead of using the default import (`@tablecheck/forbidden-imports`)
+
+🔧 This rule is automatically fixable by the [`--fix` CLI option](https://eslint.org/docs/latest/user-guide/command-line-interface#--fix).
+
+<!-- end auto-generated rule header -->

packages/eslint-plugin/docs/rules/prefer-shortest-import.md

@@ -0,0 +1,17 @@
+# Enforce the consistent use of preferred import paths (`@tablecheck/prefer-shortest-import`)
+
+🔧 This rule is automatically fixable by the [`--fix` CLI option](https://eslint.org/docs/latest/user-guide/command-line-interface#--fix).
+
+💭 This rule requires type information.
+
+<!-- end auto-generated rule header -->
+
+## Options
+
+<!-- begin auto-generated rule options list -->
+
+| Name             | Description                                                                                                                                                             | Type     |
+| :--------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------- |
+| `preferredAlias` | A list of alias paths to prefer over relative paths, for example, providing `["~/utils"]` will prefer `~/utils/useSomething` over `../useSomething` or `./useSomething` | String[] |
+
+<!-- end auto-generated rule options list -->

packages/eslint-plugin/package.json

@@ -33,7 +33,9 @@
     "@typescript-eslint/types": "^6.2.0",
     "@typescript-eslint/typescript-estree": "^6.2.0",
     "@typescript-eslint/utils": "^6.2.0",
+    "eslint-doc-generator": "1.5.3",
     "fs-extra": "11.1.1",
+    "prettier": "3.0.3",
     "type-fest": "4.4.0",
     "typescript": "5.1.6",
     "vite": "4.4.1",