docs: add meta.schema descriptions to rule options (#6)

JasonWeinzierl · web-flow · commit ee705d23efe7 · 2024-11-05T16:36:16.000-06:00
- Add eslint-plugin-eslint-plugin.
- Add programmatic documentation on the options of each rule and
auto-generate the documentation from them.
  - Enforce with `eslint-plugin/require-meta-schema-description`.
diff --git a/docs/rules/finnish.md b/docs/rules/finnish.md
@@ -24,22 +24,22 @@ const answer$ = of(42, 54);
 
 <!-- begin auto-generated rule options list -->
 
-| Name         | Type    |
-| :----------- | :------ |
-| `functions`  | Boolean |
-| `methods`    | Boolean |
-| `names`      | Object  |
-| `parameters` | Boolean |
-| `properties` | Boolean |
-| `strict`     | Boolean |
-| `types`      | Object  |
-| `variables`  | Boolean |
+| Name         | Description                                                          | Type    |
+| :----------- | :------------------------------------------------------------------- | :------ |
+| `functions`  | Require for functions.                                               | Boolean |
+| `methods`    | Require for methods.                                                 | Boolean |
+| `names`      | Enforce for specific names. Keys are a RegExp, values are a boolean. | Object  |
+| `parameters` | Require for parameters.                                              | Boolean |
+| `properties` | Require for properties.                                              | Boolean |
+| `strict`     | Disallow Finnish notation for non-Observables.                       | Boolean |
+| `types`      | Enforce for specific types. Keys are a RegExp, values are a boolean. | Object  |
+| `variables`  | Require for variables.                                               | Boolean |
 
 <!-- end auto-generated rule options list -->
 
 This rule accepts a single option which is an object with properties that determine whether Finnish notation is enforced for `functions`, `methods`, `parameters`, `properties` and `variables`. It also contains:
 
-- `names` and `types` properties that determine whether of not Finnish notation is to be enforced for specific names or types.
+- `names` and `types` properties that determine whether or not Finnish notation is to be enforced for specific names or types.
 - a `strict` property that, if `true`, allows the `$` suffix to be used _only_ with identifiers that have an `Observable` type.
 
 The default (Angular-friendly) configuration looks like this:
diff --git a/docs/rules/no-cyclic-action.md b/docs/rules/no-cyclic-action.md
@@ -56,9 +56,9 @@ Or you can use an ESLint [inline comment](https://eslint.org/docs/user-guide/con
 
 <!-- begin auto-generated rule options list -->
 
-| Name         | Type   |
-| :----------- | :----- |
-| `observable` | String |
+| Name         | Description                                                   | Type   | Default                  |
+| :----------- | :------------------------------------------------------------ | :----- | :----------------------- |
+| `observable` | A RegExp that matches an effect or epic's actions observable. | String | `[Aa]ction(s\|s\$\|\$)$` |
 
 <!-- end auto-generated rule options list -->
 
diff --git a/docs/rules/no-exposed-subjects.md b/docs/rules/no-exposed-subjects.md
@@ -33,9 +33,9 @@ class Answers {
 
 <!-- begin auto-generated rule options list -->
 
-| Name             | Type    |
-| :--------------- | :------ |
-| `allowProtected` | Boolean |
+| Name             | Description               | Type    | Default |
+| :--------------- | :------------------------ | :------ | :------ |
+| `allowProtected` | Allow protected subjects. | Boolean | `false` |
 
 <!-- end auto-generated rule options list -->
 
diff --git a/docs/rules/no-implicit-any-catch.md b/docs/rules/no-implicit-any-catch.md
@@ -72,9 +72,9 @@ throwError(() => new Error("Kaboom!")).pipe(
 
 <!-- begin auto-generated rule options list -->
 
-| Name               | Type    |
-| :----------------- | :------ |
-| `allowExplicitAny` | Boolean |
+| Name               | Description                                           | Type    | Default |
+| :----------------- | :---------------------------------------------------- | :------ | :------ |
+| `allowExplicitAny` | Allow error variable to be explicitly typed as `any`. | Boolean | `false` |
 
 <!-- end auto-generated rule options list -->
 
diff --git a/docs/rules/no-sharereplay.md b/docs/rules/no-sharereplay.md
@@ -12,9 +12,9 @@ The behavior of `shareReplay` has changed several times - see the blog post link
 
 <!-- begin auto-generated rule options list -->
 
-| Name          | Type    |
-| :------------ | :------ |
-| `allowConfig` | Boolean |
+| Name          | Description                                          | Type    | Default |
+| :------------ | :--------------------------------------------------- | :------ | :------ |
+| `allowConfig` | Allow shareReplay if a config argument is specified. | Boolean | `true`  |
 
 <!-- end auto-generated rule options list -->
 
diff --git a/docs/rules/no-unsafe-catch.md b/docs/rules/no-unsafe-catch.md
@@ -44,9 +44,9 @@ actions.pipe(
 
 <!-- begin auto-generated rule options list -->
 
-| Name         | Type   |
-| :----------- | :----- |
-| `observable` | String |
+| Name         | Description                                                   | Type   | Default                  |
+| :----------- | :------------------------------------------------------------ | :----- | :----------------------- |
+| `observable` | A RegExp that matches an effect or epic's actions observable. | String | `[Aa]ction(s\|s\$\|\$)$` |
 
 <!-- end auto-generated rule options list -->
 
diff --git a/docs/rules/no-unsafe-first.md b/docs/rules/no-unsafe-first.md
@@ -10,9 +10,9 @@ This rule effects failures if `first` is used in an effect or epic in a manner t
 
 <!-- begin auto-generated rule options list -->
 
-| Name         | Type   |
-| :----------- | :----- |
-| `observable` | String |
+| Name         | Description                                                   | Type   | Default                  |
+| :----------- | :------------------------------------------------------------ | :----- | :----------------------- |
+| `observable` | A RegExp that matches an effect or epic's actions observable. | String | `[Aa]ction(s\|s\$\|\$)$` |
 
 <!-- end auto-generated rule options list -->
 
diff --git a/docs/rules/no-unsafe-switchmap.md b/docs/rules/no-unsafe-switchmap.md
@@ -10,11 +10,11 @@ This rule effects failures if `switchMap` is used in effects or epics that perfo
 
 <!-- begin auto-generated rule options list -->
 
-| Name         |
-| :----------- |
-| `allow`      |
-| `disallow`   |
-| `observable` |
+| Name         | Description                                                                                  | Type   | Default                  |
+| :----------- | :------------------------------------------------------------------------------------------- | :----- | :----------------------- |
+| `allow`      | Action types that are allowed to be used with switchMap. Mutually exclusive with `disallow`. |        |                          |
+| `disallow`   | Action types that are disallowed to be used with switchMap. Mutually exclusive with `allow`. |        |                          |
+| `observable` | A RegExp that matches an effect or epic's actions observable.                                | String | `[Aa]ction(s\|s\$\|\$)$` |
 
 <!-- end auto-generated rule options list -->
 
diff --git a/docs/rules/no-unsafe-takeuntil.md b/docs/rules/no-unsafe-takeuntil.md
@@ -32,10 +32,10 @@ const combined = source
 
 <!-- begin auto-generated rule options list -->
 
-| Name    | Type     |
-| :------ | :------- |
-| `alias` | String[] |
-| `allow` | String[] |
+| Name    | Description                                                                 | Type     | Default                                                                                                                                                                                                                                                    |
+| :------ | :-------------------------------------------------------------------------- | :------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `alias` | An array of operator names that should be treated similarly to `takeUntil`. | String[] |                                                                                                                                                                                                                                                            |
+| `allow` | An array of operator names that are allowed to follow `takeUntil`.          | String[] | [`count`, `defaultIfEmpty`, `endWith`, `every`, `finalize`, `finally`, `isEmpty`, `last`, `max`, `min`, `publish`, `publishBehavior`, `publishLast`, `publishReplay`, `reduce`, `share`, `shareReplay`, `skipLast`, `takeLast`, `throwIfEmpty`, `toArray`] |
 
 <!-- end auto-generated rule options list -->
 
diff --git a/docs/rules/prefer-observer.md b/docs/rules/prefer-observer.md
@@ -30,9 +30,9 @@ of(42, 54).subscribe({
 
 <!-- begin auto-generated rule options list -->
 
-| Name        | Type    |
-| :---------- | :------ |
-| `allowNext` | Boolean |
+| Name        | Description                      | Type    | Default |
+| :---------- | :------------------------------- | :------ | :------ |
+| `allowNext` | Allows a single `next` callback. | Boolean | `true`  |
 
 <!-- end auto-generated rule options list -->
 
diff --git a/docs/rules/suffix-subjects.md b/docs/rules/suffix-subjects.md
@@ -24,13 +24,13 @@ const answersSubject = new Subject<number>();
 
 <!-- begin auto-generated rule options list -->
 
-| Name         | Type    |
-| :----------- | :------ |
-| `parameters` | Boolean |
-| `properties` | Boolean |
-| `suffix`     | String  |
-| `types`      | Object  |
-| `variables`  | Boolean |
+| Name         | Description                                                          | Type    |
+| :----------- | :------------------------------------------------------------------- | :------ |
+| `parameters` | Require for parameters.                                              | Boolean |
+| `properties` | Require for properties.                                              | Boolean |
+| `suffix`     | The suffix to enforce.                                               | String  |
+| `types`      | Enforce for specific types. Keys are a RegExp, values are a boolean. | Object  |
+| `variables`  | Require for variables.                                               | Boolean |
 
 <!-- end auto-generated rule options list -->
 
diff --git a/eslint.config.mjs b/eslint.config.mjs
@@ -6,6 +6,11 @@ import importX from 'eslint-plugin-import-x';
 import n from 'eslint-plugin-n';
 import tseslint from 'typescript-eslint';
 import vitest from '@vitest/eslint-plugin';
+import eslintPlugin from 'eslint-plugin-eslint-plugin';
+
+/** @type {import('@typescript-eslint/utils').TSESLint.FlatConfig.Config} */
+// @ts-expect-error -- eslint-plugin does not provide types.
+const eslintPluginConfig = eslintPlugin.configs['flat/recommended'];
 
 export default tseslint.config(gitignore(), {
   files: [
@@ -29,6 +34,7 @@ export default tseslint.config(gitignore(), {
     n.configs['flat/recommended-module'],
     importX.flatConfigs.recommended,
     importX.flatConfigs.typescript,
+    eslintPluginConfig,
   ],
   languageOptions: {
     parserOptions: {
@@ -59,6 +65,15 @@ export default tseslint.config(gitignore(), {
 
     'n/no-missing-import': 'off',
 
+    'eslint-plugin/require-meta-docs-description': [
+      'error',
+      {
+        pattern: '^(Enforce|Require|Disallow)',
+      },
+    ],
+    'eslint-plugin/prefer-placeholders': 'error',
+    'eslint-plugin/require-meta-schema-description': 'error',
+
     '@typescript-eslint/no-unnecessary-condition': 'off',
     '@typescript-eslint/restrict-template-expressions': [
       'error',
diff --git a/package.json b/package.json
@@ -79,6 +79,7 @@
     "eslint-config-flat-gitignore": "^0.3.0",
     "eslint-doc-generator": "^1.7.1",
     "eslint-import-resolver-typescript": "^3.6.3",
+    "eslint-plugin-eslint-plugin": "^6.3.1",
     "eslint-plugin-import-x": "^4.4.0",
     "eslint-plugin-n": "^17.12.0",
     "markdownlint-cli2": "^0.14.0",
diff --git a/src/rules/finnish.ts b/src/rules/finnish.ts
@@ -30,14 +30,14 @@ export const finnishRule = ruleCreator({
     schema: [
       {
         properties: {
-          functions: { type: 'boolean' },
-          methods: { type: 'boolean' },
-          names: { type: 'object' },
-          parameters: { type: 'boolean' },
-          properties: { type: 'boolean' },
-          strict: { type: 'boolean' },
-          types: { type: 'object' },
-          variables: { type: 'boolean' },
+          functions: { type: 'boolean', description: 'Require for functions.' },
+          methods: { type: 'boolean', description: 'Require for methods.' },
+          names: { type: 'object', description: 'Enforce for specific names. Keys are a RegExp, values are a boolean.' },
+          parameters: { type: 'boolean', description: 'Require for parameters.' },
+          properties: { type: 'boolean', description: 'Require for properties.' },
+          strict: { type: 'boolean', description: 'Disallow Finnish notation for non-Observables.' },
+          types: { type: 'object', description: 'Enforce for specific types. Keys are a RegExp, values are a boolean.' },
+          variables: { type: 'boolean', description: 'Require for variables.' },
         },
         type: 'object',
       },
diff --git a/src/rules/no-cyclic-action.ts b/src/rules/no-cyclic-action.ts
@@ -28,7 +28,7 @@ export const noCyclicActionRule = ruleCreator({
     schema: [
       {
         properties: {
-          observable: { type: 'string' },
+          observable: { type: 'string', description: 'A RegExp that matches an effect or epic\'s actions observable.', default: defaultObservable },
         },
         type: 'object',
         description: stripIndent`
diff --git a/src/rules/no-exposed-subjects.ts b/src/rules/no-exposed-subjects.ts
@@ -22,7 +22,7 @@ export const noExposedSubjectsRule = ruleCreator({
     schema: [
       {
         properties: {
-          allowProtected: { type: 'boolean' },
+          allowProtected: { type: 'boolean', description: 'Allow protected subjects.', default: false },
         },
         type: 'object',
       },
diff --git a/src/rules/no-implicit-any-catch.ts b/src/rules/no-implicit-any-catch.ts
@@ -58,6 +58,8 @@ export const noImplicitAnyCatchRule = ruleCreator({
         properties: {
           allowExplicitAny: {
             type: 'boolean',
+            description: 'Allow error variable to be explicitly typed as `any`.',
+            default: false,
           },
         },
         type: 'object',
diff --git a/src/rules/no-sharereplay.ts b/src/rules/no-sharereplay.ts
@@ -20,7 +20,7 @@ export const noSharereplayRule = ruleCreator({
     schema: [
       {
         properties: {
-          allowConfig: { type: 'boolean' },
+          allowConfig: { type: 'boolean', description: 'Allow shareReplay if a config argument is specified.', default: true },
         },
         type: 'object',
       },
diff --git a/src/rules/no-unsafe-catch.ts b/src/rules/no-unsafe-catch.ts
@@ -26,7 +26,7 @@ export const noUnsafeCatchRule = ruleCreator({
     schema: [
       {
         properties: {
-          observable: { type: 'string' },
+          observable: { type: 'string', description: 'A RegExp that matches an effect or epic\'s actions observable.', default: defaultObservable },
         },
         type: 'object',
         description: stripIndent`
diff --git a/src/rules/no-unsafe-first.ts b/src/rules/no-unsafe-first.ts
@@ -22,7 +22,7 @@ export const noUnsafeFirstRule = ruleCreator({
     schema: [
       {
         properties: {
-          observable: { type: 'string' },
+          observable: { type: 'string', description: 'A RegExp that matches an effect or epic\'s actions observable.', default: defaultObservable },
         },
         type: 'object',
         description: stripIndent`
diff --git a/src/rules/no-unsafe-switchmap.ts b/src/rules/no-unsafe-switchmap.ts
@@ -29,22 +29,23 @@ export const noUnsafeSwitchmapRule = ruleCreator({
       {
         properties: {
           allow: {
+            description: 'Action types that are allowed to be used with switchMap. Mutually exclusive with `disallow`.',
             oneOf: [
-              { type: 'string' },
-              { type: 'array', items: { type: 'string' } },
+              { type: 'string', description: 'A regular expression string.' },
+              { type: 'array', items: { type: 'string' }, description: 'An array of words.' },
             ],
           },
           disallow: {
+            description: 'Action types that are disallowed to be used with switchMap. Mutually exclusive with `allow`.',
             oneOf: [
-              { type: 'string' },
-              { type: 'array', items: { type: 'string' } },
+              { type: 'string', description: 'A regular expression string.' },
+              { type: 'array', items: { type: 'string' }, description: 'An array of words.' },
             ],
           },
           observable: {
-            oneOf: [
-              { type: 'string' },
-              { type: 'array', items: { type: 'string' } },
-            ],
+            type: 'string',
+            description: 'A RegExp that matches an effect or epic\'s actions observable.',
+            default: defaultObservable,
           },
         },
         type: 'object',
diff --git a/src/rules/no-unsafe-takeuntil.ts b/src/rules/no-unsafe-takeuntil.ts
diff --git a/src/rules/prefer-observer.ts b/src/rules/prefer-observer.ts
diff --git a/src/rules/suffix-subjects.ts b/src/rules/suffix-subjects.ts
diff --git a/yarn.lock b/yarn.lock
