typescript-eslint · JoshuaKGoldberg · Oct 18, 2023 · Sep 17, 2023 · Sep 17, 2023 · Sep 17, 2023
diff --git a/packages/eslint-plugin/docs/rules/README.md b/packages/eslint-plugin/docs/rules/README.md
@@ -6,18 +6,55 @@ pagination_prev: null
 slug: /
 ---
 
-`@typescript-eslint/eslint-plugin` includes over 100 rules that detect best practice violations, bugs, and/or stylistic issues specifically for TypeScript code.
-See [Configs](/linting/configs) for how to enable recommended rules using configs.
+`@typescript-eslint/eslint-plugin` includes over 100 rules that detect best practice violations, bugs, and/or stylistic issues specifically for TypeScript code. All of our rules are listed below.
 
-## Supported Rules
+:::tip
+Instead of enabling rules one by one, we recommend using one of [our pre-defined configs](/linting/configs) to enable a large set of recommended rules.
+:::
+
+## Rules
+
+The rules are listed in alphabetical order. You can optionally filter them based on these categories:
 
 import RulesTable from "@site/src/components/RulesTable";
 
-<RulesTable ruleset="supported-rules" />
+<RulesTable />
+
+## Filtering
+
+### Config Group (⚙️)
+
+"Config Group" refers to the [pre-defined config](/linting/configs) that includes the rule. Extending from a configuration preset allow for enabling a large set of recommended rules all at once.
+
+### Metadata
+
+- `🔧 fixable` refers to whether the rule contains an [ESLint `--fix` auto-fixer](https://eslint.org/docs/latest/use/command-line-interface#--fix).
+- `💡 has suggestions` refers to whether the rule contains an ESLint suggestion fixer.
+  - Sometimes, it is not safe to automatically fix the code with an auto-fixer. But in these cases, we often have a good guess of what the correct fix should be, and we can provide it as a suggestion to the developer.
+- `💭 requires type information` refers to whether the rule requires [typed linting](/linting/typed-linting).
+- `🧱 extension rule` means that the rule is an extension of an [core ESLint rule](https://eslint.org/docs/latest/rules) (see [Extension Rules](#extension-rules)).
+- `📐 formatting rule` means that the rule has to do with formatting.
+  - We [strongly recommend against using ESLint for formatting](/linting/troubleshooting/formatting).
+  - Soon, formatting rules will be moved to the [ESLint stylistic plugin](https://eslint.style).
+- `💀 deprecated rule` means that the rule should no longer be used and will be removed from the plugin in a future version.
 
 ## Extension Rules
 
-In some cases, ESLint provides a rule itself, but it doesn't support TypeScript syntax; either it crashes, or it ignores the syntax, or it falsely reports against it.
-In these cases, we create what we call an extension rule; a rule within our plugin that has the same functionality, but also supports TypeScript.
+Some core ESLint rules do not support TypeScript syntax: either they crash, ignore the syntax, or falsely report against it.
+In these cases, we create what we call an "extension rule": a rule within our plugin that has the same functionality, but also supports TypeScript.
+
+Extension rules generally completely replace the base rule from ESLint core.
+If the base rule is enabled in a config you extend from, you'll need to disable the base rule:
+
+```js
+module.exports = {
+  extends: ['eslint:recommended'],
+  rules: {
+    // Note: you must disable the base rule as it can report incorrect errors
+    'no-unused-vars': 'off',
+    '@typescript-eslint/no-unused-vars': 'error',
+  },
+};
+```
 
-<RulesTable ruleset="extension-rules" />
+[Search for `🧱 extension rule`s](?=extension#rules) in this page to see all extension rules.
diff --git a/packages/eslint-plugin/docs/rules/camelcase.md b/packages/eslint-plugin/docs/rules/camelcase.md
@@ -5,6 +5,9 @@ This rule has been deprecated in favour of the [`naming-convention`](./naming-co
 :::
 
 <!--
-This doc file has been left on purpose because `camelcase` is a core ESLint rule.
-This exists to help direct people to the replacement rule.
+This doc file has been left on purpose because `camelcase` is a core ESLint
+rule. This exists to help direct people to the replacement rule.
+
+Note that there is no actual way to get to this page in the normal navigation,
+so end-users will only be able to get to this page from the search bar.
 -->
diff --git a/packages/eslint-plugin/docs/rules/no-duplicate-imports.md b/packages/eslint-plugin/docs/rules/no-duplicate-imports.md
@@ -5,6 +5,9 @@ This rule has been deprecated in favour of the [`import/no-duplicates`](https://
 :::
 
 <!--
-This doc file has been left on purpose because `import/no-duplicates` is commonly requested.
-This exists to help direct people to the replacement rule.
+This doc file has been left on purpose because `import/no-duplicates` is
+commonly requested. This exists to help direct people to the replacement rule.
+
+Note that there is no actual way to get to this page in the normal navigation,
+so end-users will only be able to get to this page from the search bar.
 -->
diff --git a/packages/eslint-plugin/tests/docs.test.ts b/packages/eslint-plugin/tests/docs.test.ts
@@ -42,7 +42,8 @@ describe('Validating rule docs', () => {
   const ignoredFiles = new Set([
     'README.md',
     'TEMPLATE.md',
-    // these rule docs were left behind on purpose for legacy reasons
+    // These rule docs were left behind on purpose for legacy reasons. See the
+    // comments in the files for more information.
     'camelcase.md',
     'no-duplicate-imports.md',
   ]);

diff --git a/packages/eslint-plugin/tools/generate-breaking-changes.mts b/packages/eslint-plugin/tools/generate-breaking-changes.mts
@@ -141,7 +141,7 @@ async function main(): Promise<void> {
           recommended === 'recommended' ? '🟩' : '',
           recommended === 'strict' ? '🔵' : '',
           recommended === 'stylistic' ? '🔸' : '',
-          meta.type === 'layout' ? 'layout 💩' : '(todo)',
+          meta.type === 'layout' ? 'layout 📐' : '(todo)',
         ];
       }),
     ]),

diff --git a/packages/website/sidebars/sidebar.rules.js b/packages/website/sidebars/sidebar.rules.js
@@ -1,6 +1,3 @@
-const globby = require('globby');
-const path = require('path');
-
 const plugin = require('@typescript-eslint/eslint-plugin');
 
 const rules = Object.entries(plugin.rules).map(([name, rule]) => {
@@ -10,43 +7,6 @@ const rules = Object.entries(plugin.rules).map(([name, rule]) => {
   };
 });
 
-const deprecatedRules = new Set(rules.filter(rule => rule.meta.deprecated));
-
-const formattingRules = new Set(
-  rules.filter(rule => !rule.meta.deprecated && rule.meta.type === 'layout'),
-);
-
-const extensionRules = new Set(
-  rules.filter(
-    rule => rule.meta.docs?.extendsBaseRule && !formattingRules.has(rule),
-  ),
-);
-
-const typescriptRules = rules.filter(
-  rule =>
-    !rule.meta.deprecated &&
-    !extensionRules.has(rule) &&
-    !deprecatedRules.has(rule) &&
-    !formattingRules.has(rule),
-);
-
-const paths = globby
-  .sync('*.md', {
-    cwd: path.join(__dirname, '../../eslint-plugin/docs/rules'),
-  })
-  .map(item => {
-    return {
-      name: path.basename(item, '.md'),
-    };
-  })
-  .filter(item => {
-    return (
-      item.name !== 'README' &&
-      item.name !== 'TEMPLATE' &&
-      !rules.some(a => a.name === item.name)
-    );
-  });
-
 function createCategory(label, rules, additionalItems = []) {
   return {
     items: [
@@ -68,17 +28,8 @@ module.exports = {
   someSidebar: [
     'README',
     {
-      ...createCategory('TypeScript Rules', Array.from(typescriptRules)),
-      collapsed: false,
-    },
-    {
-      ...createCategory('Extension Rules', Array.from(extensionRules)),
+      ...createCategory('Rules', rules),
       collapsed: false,
     },
-    createCategory('Formatting Rules', Array.from(formattingRules)),
-    createCategory('Deprecated Rules', [
-      ...Array.from(deprecatedRules),
-      ...paths,
-    ]),
   ],
 };