eslint-plugin-jsdoc 57.2.1 → 58.1.0

package/src/index-cjs.js

@@ -1,6 +1,9 @@
 import {
   buildForbidRuleDefinition,
 } from './buildForbidRuleDefinition.js';
+import {
+  buildRejectOrPreferRuleDefinition,
+} from './buildRejectOrPreferRuleDefinition.js';
 import {
   getJsdocProcessorPlugin,
 } from './getJsdocProcessorPlugin.js';
@@ -107,6 +110,33 @@ index.rules = {
   'no-restricted-syntax': noRestrictedSyntax,
   'no-types': noTypes,
   'no-undefined-types': noUndefinedTypes,
+  'reject-any-type': buildRejectOrPreferRuleDefinition({
+    description: 'Reports use of `any` or `*` type',
+    overrideSettings: {
+      '*': {
+        message: 'Prefer a more specific type to `*`',
+        replacement: false,
+        unifyParentAndChildTypeChecks: true,
+      },
+      any: {
+        message: 'Prefer a more specific type to `any`',
+        replacement: false,
+        unifyParentAndChildTypeChecks: true,
+      },
+    },
+    url: 'https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/reject-any-type.md#repos-sticky-header',
+  }),
+  'reject-function-type': buildRejectOrPreferRuleDefinition({
+    description: 'Reports use of `Function` type',
+    overrideSettings: {
+      Function: {
+        message: 'Prefer a more specific type to `Function`',
+        replacement: false,
+        unifyParentAndChildTypeChecks: true,
+      },
+    },
+    url: 'https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/reject-function-type.md#repos-sticky-header',
+  }),
   'require-asterisk-prefix': requireAsteriskPrefix,
   'require-description': requireDescription,
   'require-description-complete-sentence': requireDescriptionCompleteSentence,
@@ -122,7 +152,7 @@ index.rules = {
         message: '@next should have a type',
       },
     ],
-    description: 'Requires a type for @next tags',
+    description: 'Requires a type for `@next` tags',
     url: 'https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/require-next-type.md#repos-sticky-header',
   }),
   'require-param': requireParam,
@@ -147,7 +177,7 @@ index.rules = {
         message: '@throws should have a type',
       },
     ],
-    description: 'Requires a type for @throws tags',
+    description: 'Requires a type for `@throws` tags',
     url: 'https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/require-throws-type.md#repos-sticky-header',
   }),
   'require-yields': requireYields,
@@ -160,7 +190,7 @@ index.rules = {
         message: '@yields should have a type',
       },
     ],
-    description: 'Requires a type for @yields tags',
+    description: 'Requires a type for `@yields` tags',
     url: 'https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/require-yields-type.md#repos-sticky-header',
   }),
   'sort-tags': sortTags,
@@ -218,6 +248,8 @@ const createRecommendedRuleset = (warnOrError, flatName) => {
       'jsdoc/no-restricted-syntax': 'off',
       'jsdoc/no-types': 'off',
       'jsdoc/no-undefined-types': warnOrError,
+      'jsdoc/reject-any-type': warnOrError,
+      'jsdoc/reject-function-type': warnOrError,
       'jsdoc/require-asterisk-prefix': 'off',
       'jsdoc/require-description': 'off',
       'jsdoc/require-description-complete-sentence': 'off',

package/src/index-esm.js

@@ -8,6 +8,9 @@ import index from './index-cjs.js';
 import {
   buildForbidRuleDefinition,
 } from './buildForbidRuleDefinition.js';
+import {
+  buildRejectOrPreferRuleDefinition,
+} from './buildRejectOrPreferRuleDefinition.js';
 
 // eslint-disable-next-line unicorn/prefer-export-from --- Reusing `index`
 export default index;
@@ -22,7 +25,7 @@ export default index;
  *     settings?: Partial<import('./iterateJsdoc.js').Settings>,
  *     rules?: {[key in keyof import('./rules.d.ts').Rules]?: import('eslint').Linter.RuleEntry<import('./rules.d.ts').Rules[key]>},
  *     extraRuleDefinitions?: {
- *       forbid: {
+ *       forbid?: {
  *         [contextName: string]: {
  *           description?: string,
  *           url?: string,
@@ -32,6 +35,19 @@ export default index;
  *             comment: string
  *           })[]
  *         }
+ *       },
+ *       preferTypes?: {
+ *         [typeName: string]: {
+ *           description: string,
+ *           overrideSettings: {
+ *             [typeNodeName: string]: {
+ *               message: string,
+ *               replacement?: false|string,
+ *               unifyParentAndChildTypeChecks?: boolean,
+ *             }
+ *           },
+ *           url: string,
+ *         }
  *       }
  *     }
  *   }
@@ -125,6 +141,25 @@ export const jsdoc = function (cfg) {
             });
         }
       }
+
+      if (cfg.extraRuleDefinitions.preferTypes) {
+        for (const [
+          typeName,
+          {
+            description,
+            overrideSettings,
+            url,
+          },
+        ] of Object.entries(cfg.extraRuleDefinitions.preferTypes)) {
+          outputConfig.plugins.jsdoc.rules[`prefer-type-${typeName}`] =
+            buildRejectOrPreferRuleDefinition({
+              description,
+              overrideSettings,
+              typeName,
+              url,
+            });
+        }
+      }
     }
   }
 

package/src/index.js

@@ -7,6 +7,9 @@ import {
 import {
   buildForbidRuleDefinition,
 } from './buildForbidRuleDefinition.js';
+import {
+  buildRejectOrPreferRuleDefinition,
+} from './buildRejectOrPreferRuleDefinition.js';
 import {
   getJsdocProcessorPlugin,
 } from './getJsdocProcessorPlugin.js';
@@ -113,6 +116,33 @@ index.rules = {
   'no-restricted-syntax': noRestrictedSyntax,
   'no-types': noTypes,
   'no-undefined-types': noUndefinedTypes,
+  'reject-any-type': buildRejectOrPreferRuleDefinition({
+    description: 'Reports use of `any` or `*` type',
+    overrideSettings: {
+      '*': {
+        message: 'Prefer a more specific type to `*`',
+        replacement: false,
+        unifyParentAndChildTypeChecks: true,
+      },
+      any: {
+        message: 'Prefer a more specific type to `any`',
+        replacement: false,
+        unifyParentAndChildTypeChecks: true,
+      },
+    },
+    url: 'https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/reject-any-type.md#repos-sticky-header',
+  }),
+  'reject-function-type': buildRejectOrPreferRuleDefinition({
+    description: 'Reports use of `Function` type',
+    overrideSettings: {
+      Function: {
+        message: 'Prefer a more specific type to `Function`',
+        replacement: false,
+        unifyParentAndChildTypeChecks: true,
+      },
+    },
+    url: 'https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/reject-function-type.md#repos-sticky-header',
+  }),
   'require-asterisk-prefix': requireAsteriskPrefix,
   'require-description': requireDescription,
   'require-description-complete-sentence': requireDescriptionCompleteSentence,
@@ -128,7 +158,7 @@ index.rules = {
         message: '@next should have a type',
       },
     ],
-    description: 'Requires a type for @next tags',
+    description: 'Requires a type for `@next` tags',
     url: 'https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/require-next-type.md#repos-sticky-header',
   }),
   'require-param': requireParam,
@@ -153,7 +183,7 @@ index.rules = {
         message: '@throws should have a type',
       },
     ],
-    description: 'Requires a type for @throws tags',
+    description: 'Requires a type for `@throws` tags',
     url: 'https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/require-throws-type.md#repos-sticky-header',
   }),
   'require-yields': requireYields,
@@ -166,7 +196,7 @@ index.rules = {
         message: '@yields should have a type',
       },
     ],
-    description: 'Requires a type for @yields tags',
+    description: 'Requires a type for `@yields` tags',
     url: 'https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/require-yields-type.md#repos-sticky-header',
   }),
   'sort-tags': sortTags,
@@ -224,6 +254,8 @@ const createRecommendedRuleset = (warnOrError, flatName) => {
       'jsdoc/no-restricted-syntax': 'off',
       'jsdoc/no-types': 'off',
       'jsdoc/no-undefined-types': warnOrError,
+      'jsdoc/reject-any-type': warnOrError,
+      'jsdoc/reject-function-type': warnOrError,
       'jsdoc/require-asterisk-prefix': 'off',
       'jsdoc/require-description': 'off',
       'jsdoc/require-description-complete-sentence': 'off',
@@ -609,7 +641,7 @@ export default index;
  *     settings?: Partial<import('./iterateJsdoc.js').Settings>,
  *     rules?: {[key in keyof import('./rules.d.ts').Rules]?: import('eslint').Linter.RuleEntry<import('./rules.d.ts').Rules[key]>},
  *     extraRuleDefinitions?: {
- *       forbid: {
+ *       forbid?: {
  *         [contextName: string]: {
  *           description?: string,
  *           url?: string,
@@ -619,6 +651,19 @@ export default index;
  *             comment: string
  *           })[]
  *         }
+ *       },
+ *       preferTypes?: {
+ *         [typeName: string]: {
+ *           description: string,
+ *           overrideSettings: {
+ *             [typeNodeName: string]: {
+ *               message: string,
+ *               replacement?: false|string,
+ *               unifyParentAndChildTypeChecks?: boolean,
+ *             }
+ *           },
+ *           url: string,
+ *         }
  *       }
  *     }
  *   }
@@ -712,6 +757,25 @@ export const jsdoc = function (cfg) {
             });
         }
       }
+
+      if (cfg.extraRuleDefinitions.preferTypes) {
+        for (const [
+          typeName,
+          {
+            description,
+            overrideSettings,
+            url,
+          },
+        ] of Object.entries(cfg.extraRuleDefinitions.preferTypes)) {
+          outputConfig.plugins.jsdoc.rules[`prefer-type-${typeName}`] =
+            buildRejectOrPreferRuleDefinition({
+              description,
+              overrideSettings,
+              typeName,
+              url,
+            });
+        }
+      }
     }
   }