eslint-plugin-jsdoc 57.2.0 → 58.0.0

package/dist/rules.d.ts

@@ -1,4 +1,7 @@
 export interface Rules {
+  /** Checks that `@access` tags have a valid value. */
+  "jsdoc/check-access": [];
+
   /** Reports invalid alignment of JSDoc block asterisks. */
   "jsdoc/check-alignment": 
     | []
@@ -90,6 +93,9 @@ export interface Rules {
         }
       ];
 
+  /** Reports against syntax not valid for the mode (e.g., Google Closure Compiler in non-Closure mode). */
+  "jsdoc/check-syntax": [];
+
   /** Reports invalid block tag names. */
   "jsdoc/check-tag-names": 
     | []
@@ -102,6 +108,9 @@ export interface Rules {
         }
       ];
 
+  /** Checks that any `@template` names are actually used in the connected `@typedef` or type alias. */
+  "jsdoc/check-template-names": [];
+
   /** Reports invalid types. */
   "jsdoc/check-types": 
     | []
@@ -188,6 +197,9 @@ export interface Rules {
         }
       ];
 
+  /** Reports if JSDoc `import()` statements point to a package which is not listed in `dependencies` or `devDependencies` */
+  "jsdoc/imports-as-dependencies": [];
+
   /** This rule reports doc comments that only restate their attached name. */
   "jsdoc/informative-docs": 
     | []
@@ -300,6 +312,9 @@ export interface Rules {
         }
       ];
 
+  /** Detects and removes extra lines of a blank block description */
+  "jsdoc/no-blank-block-descriptions": [];
+
   /** Removes empty blocks with nothing but possibly line breaks */
   "jsdoc/no-blank-blocks": 
     | []
@@ -395,6 +410,12 @@ export interface Rules {
         }
       ];
 
+  /** Reports use of `any` or `*` type */
+  "jsdoc/reject-any-type": [];
+
+  /** Reports use of `Function` type */
+  "jsdoc/reject-function-type": [];
+
   /** Requires that each JSDoc line starts with an `*`. */
   "jsdoc/require-asterisk-prefix": 
     | []
@@ -542,6 +563,9 @@ export interface Rules {
         }
       ];
 
+  /** Requires a type for `@next` tags */
+  "jsdoc/require-next-type": [];
+
   /** Requires that all function parameters are documented. */
   "jsdoc/require-param": 
     | []
@@ -621,6 +645,18 @@ export interface Rules {
         }
       ];
 
+  /** Requires that all `@typedef` and `@namespace` tags have `@property` when their type is a plain `object`, `Object`, or `PlainObject`. */
+  "jsdoc/require-property": [];
+
+  /** Requires that each `@property` tag has a `description` value. */
+  "jsdoc/require-property-description": [];
+
+  /** Requires that all function `@property` tags have names. */
+  "jsdoc/require-property-name": [];
+
+  /** Requires that each `@property` tag has a `type` value. */
+  "jsdoc/require-property-type": [];
+
   /** Requires that returns are documented. */
   "jsdoc/require-returns": 
     | []
@@ -718,6 +754,9 @@ export interface Rules {
         }
       ];
 
+  /** Requires a type for `@throws` tags */
+  "jsdoc/require-throws-type": [];
+
   /** Requires yields are documented. */
   "jsdoc/require-yields": 
     | []
@@ -757,6 +796,9 @@ export interface Rules {
         }
       ];
 
+  /** Requires a type for `@yields` tags */
+  "jsdoc/require-yields-type": [];
+
   /** Sorts tags by a specified sequence according to tag name. */
   "jsdoc/sort-tags": 
     | []

package/package.json

@@ -172,5 +172,5 @@
     "test-cov": "TIMING=1 c8 --reporter text pnpm run test-no-cov",
     "test-index": "pnpm run test-no-cov test/rules/index.js"
   },
-  "version": "57.2.0"
+  "version": "58.0.0"
 }

package/src/buildRejectOrPreferRuleDefinition.js

@@ -0,0 +1,472 @@
+import iterateJsdoc from './iterateJsdoc.js';
+import {
+  parse,
+  stringify,
+  traverse,
+  tryParse,
+} from '@es-joy/jsdoccomment';
+
+/**
+ * Adjusts the parent type node `meta` for generic matches (or type node
+ * `type` for `JsdocTypeAny`) and sets the type node `value`.
+ * @param {string} type The actual type
+ * @param {string} preferred The preferred type
+ * @param {boolean} isGenericMatch
+ * @param {string} typeNodeName
+ * @param {import('jsdoc-type-pratt-parser').NonRootResult} node
+ * @param {import('jsdoc-type-pratt-parser').NonRootResult|undefined} parentNode
+ * @returns {void}
+ */
+const adjustNames = (type, preferred, isGenericMatch, typeNodeName, node, parentNode) => {
+  let ret = preferred;
+  if (isGenericMatch) {
+    const parentMeta = /** @type {import('jsdoc-type-pratt-parser').GenericResult} */ (
+      parentNode
+    ).meta;
+    if (preferred === '[]') {
+      parentMeta.brackets = 'square';
+      parentMeta.dot = false;
+      ret = 'Array';
+    } else {
+      const dotBracketEnd = preferred.match(/\.(?:<>)?$/v);
+      if (dotBracketEnd) {
+        parentMeta.brackets = 'angle';
+        parentMeta.dot = true;
+        ret = preferred.slice(0, -dotBracketEnd[0].length);
+      } else {
+        const bracketEnd = preferred.endsWith('<>');
+        if (bracketEnd) {
+          parentMeta.brackets = 'angle';
+          parentMeta.dot = false;
+          ret = preferred.slice(0, -2);
+        } else if (
+          parentMeta?.brackets === 'square' &&
+          (typeNodeName === '[]' || typeNodeName === 'Array')
+        ) {
+          parentMeta.brackets = 'angle';
+          parentMeta.dot = false;
+        }
+      }
+    }
+  } else if (type === 'JsdocTypeAny') {
+    node.type = 'JsdocTypeName';
+  }
+
+  /** @type {import('jsdoc-type-pratt-parser').NameResult} */ (
+    node
+  ).value = ret.replace(/(?:\.|<>|\.<>|\[\])$/v, '');
+
+  // For bare pseudo-types like `<>`
+  if (!ret) {
+    /** @type {import('jsdoc-type-pratt-parser').NameResult} */ (
+      node
+    ).value = typeNodeName;
+  }
+};
+
+/**
+ * @param {boolean} [upperCase]
+ * @returns {string}
+ */
+const getMessage = (upperCase) => {
+  return 'Use object shorthand or index signatures instead of ' +
+  '`' + (upperCase ? 'O' : 'o') + 'bject`, e.g., `{[key: string]: string}`';
+};
+
+/**
+ * @type {{
+ *   message: string,
+ *   replacement: false
+ * }}
+ */
+const info = {
+  message: getMessage(),
+  replacement: false,
+};
+
+/**
+ * @type {{
+ *   message: string,
+ *   replacement: false
+ * }}
+ */
+const infoUC = {
+  message: getMessage(true),
+  replacement: false,
+};
+
+/**
+ * @param {{
+ *   checkNativeTypes?: import('./rules/checkTypes.js').CheckNativeTypes|null
+ *   overrideSettings?: import('./iterateJsdoc.js').Settings['preferredTypes']|null,
+ *   description?: string,
+ *   schema?: import('eslint').Rule.RuleMetaData['schema'],
+ *   typeName?: string,
+ *   url?: string,
+ * }} cfg
+ * @returns {import('@eslint/core').RuleDefinition<
+ *   import('@eslint/core').RuleDefinitionTypeOptions
+ * >}
+ */
+export const buildRejectOrPreferRuleDefinition = ({
+  checkNativeTypes = null,
+  typeName,
+  description = typeName ?? 'Reports invalid types.',
+  overrideSettings = null,
+  schema = [],
+  url = 'https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/check-types.md#repos-sticky-header',
+}) => {
+  return iterateJsdoc(
+    ({
+      context,
+      jsdocNode,
+      report,
+      settings,
+      sourceCode,
+      utils,
+    }) => {
+      const jsdocTagsWithPossibleType = utils.filterTags((tag) => {
+        return Boolean(utils.tagMightHaveTypePosition(tag.tag));
+      });
+
+      const
+        /**
+         * @type {{
+         *   preferredTypes: import('./iterateJsdoc.js').PreferredTypes,
+         *   structuredTags: import('./iterateJsdoc.js').StructuredTags,
+         *   mode: import('./jsdocUtils.js').ParserMode
+         * }}
+         */
+        {
+          mode,
+          preferredTypes: preferredTypesOriginal,
+          structuredTags,
+        } = overrideSettings ? {
+          mode: settings.mode,
+          preferredTypes: overrideSettings,
+          structuredTags: {},
+        } : settings;
+
+      const injectObjectPreferredTypes = !('Object' in preferredTypesOriginal ||
+        'object' in preferredTypesOriginal ||
+        'object.<>' in preferredTypesOriginal ||
+        'Object.<>' in preferredTypesOriginal ||
+        'object<>' in preferredTypesOriginal);
+
+      /** @type {import('./iterateJsdoc.js').PreferredTypes} */
+      const typeToInject = mode === 'typescript' ?
+        {
+          Object: 'object',
+          'object.<>': info,
+          'Object.<>': infoUC,
+          'object<>': info,
+          'Object<>': infoUC,
+        } :
+        {
+          Object: 'object',
+          'object.<>': 'Object<>',
+          'Object.<>': 'Object<>',
+          'object<>': 'Object<>',
+        };
+
+      /** @type {import('./iterateJsdoc.js').PreferredTypes} */
+      const preferredTypes = {
+        ...injectObjectPreferredTypes ?
+          typeToInject :
+          {},
+        ...preferredTypesOriginal,
+      };
+
+      const
+        /**
+         * @type {{
+         *   noDefaults: boolean,
+         *   unifyParentAndChildTypeChecks: boolean,
+         *   exemptTagContexts: ({
+         *     tag: string,
+         *     types: true|string[]
+         *   })[]
+         * }}
+         */ {
+          exemptTagContexts = [],
+          noDefaults,
+          unifyParentAndChildTypeChecks,
+        } = context.options[0] || {};
+
+      /**
+       * Gets information about the preferred type: whether there is a matching
+       * preferred type, what the type is, and whether it is a match to a generic.
+       * @param {string} _type Not currently in use
+       * @param {string} typeNodeName
+       * @param {import('jsdoc-type-pratt-parser').NonRootResult|undefined} parentNode
+       * @param {string|undefined} property
+       * @returns {[hasMatchingPreferredType: boolean, typeName: string, isGenericMatch: boolean]}
+       */
+      const getPreferredTypeInfo = (_type, typeNodeName, parentNode, property) => {
+        let hasMatchingPreferredType = false;
+        let isGenericMatch = false;
+        let typName = typeNodeName;
+
+        const isNameOfGeneric = parentNode !== undefined && parentNode.type === 'JsdocTypeGeneric' && property === 'left';
+
+        const brackets = /** @type {import('jsdoc-type-pratt-parser').GenericResult} */ (
+          parentNode
+        )?.meta?.brackets;
+        const dot = /** @type {import('jsdoc-type-pratt-parser').GenericResult} */ (
+          parentNode
+        )?.meta?.dot;
+
+        if (brackets === 'angle') {
+          const checkPostFixes = dot ? [
+            '.', '.<>',
+          ] : [
+            '<>',
+          ];
+          isGenericMatch = checkPostFixes.some((checkPostFix) => {
+            const preferredType = preferredTypes?.[typeNodeName + checkPostFix];
+
+            // Does `unifyParentAndChildTypeChecks` need to be checked here?
+            if (
+              (unifyParentAndChildTypeChecks || isNameOfGeneric ||
+                /* c8 ignore next 2 -- If checking `unifyParentAndChildTypeChecks` */
+                (typeof preferredType === 'object' &&
+                  preferredType?.unifyParentAndChildTypeChecks)
+              ) &&
+              preferredType !== undefined
+            ) {
+              typName += checkPostFix;
+
+              return true;
+            }
+
+            return false;
+          });
+        }
+
+        if (
+          !isGenericMatch && property &&
+          /** @type {import('jsdoc-type-pratt-parser').NonRootResult} */ (
+            parentNode
+          ).type === 'JsdocTypeGeneric'
+        ) {
+          const checkPostFixes = dot ? [
+            '.', '.<>',
+          ] : [
+            brackets === 'angle' ? '<>' : '[]',
+          ];
+
+          isGenericMatch = checkPostFixes.some((checkPostFix) => {
+            const preferredType = preferredTypes?.[checkPostFix];
+            if (
+              // Does `unifyParentAndChildTypeChecks` need to be checked here?
+              (unifyParentAndChildTypeChecks || isNameOfGeneric ||
+                /* c8 ignore next 2 -- If checking `unifyParentAndChildTypeChecks` */
+                (typeof preferredType === 'object' &&
+                preferredType?.unifyParentAndChildTypeChecks)) &&
+                preferredType !== undefined
+            ) {
+              typName = checkPostFix;
+
+              return true;
+            }
+
+            return false;
+          });
+        }
+
+        const prefType = preferredTypes?.[typeNodeName];
+        const directNameMatch = prefType !== undefined &&
+          !Object.values(preferredTypes).includes(typeNodeName);
+        const specificUnify = typeof prefType === 'object' &&
+          prefType?.unifyParentAndChildTypeChecks;
+        const unifiedSyntaxParentMatch = property && directNameMatch && (unifyParentAndChildTypeChecks || specificUnify);
+        isGenericMatch = isGenericMatch || Boolean(unifiedSyntaxParentMatch);
+
+        hasMatchingPreferredType = isGenericMatch ||
+          directNameMatch && !property;
+
+        return [
+          hasMatchingPreferredType, typName, isGenericMatch,
+        ];
+      };
+
+      /**
+       * Collect invalid type info.
+       * @param {string} type
+       * @param {string} value
+       * @param {string} tagName
+       * @param {string} nameInTag
+       * @param {number} idx
+       * @param {string|undefined} property
+       * @param {import('jsdoc-type-pratt-parser').NonRootResult} node
+       * @param {import('jsdoc-type-pratt-parser').NonRootResult|undefined} parentNode
+       * @param {(string|false|undefined)[][]} invalidTypes
+       * @returns {void}
+       */
+      const getInvalidTypes = (type, value, tagName, nameInTag, idx, property, node, parentNode, invalidTypes) => {
+        let typeNodeName = type === 'JsdocTypeAny' ? '*' : value;
+
+        const [
+          hasMatchingPreferredType,
+          typName,
+          isGenericMatch,
+        ] = getPreferredTypeInfo(type, typeNodeName, parentNode, property);
+
+        let preferred;
+        let types;
+        if (hasMatchingPreferredType) {
+          const preferredSetting = preferredTypes[typName];
+          typeNodeName = typName === '[]' ? typName : typeNodeName;
+
+          if (!preferredSetting) {
+            invalidTypes.push([
+              typeNodeName,
+            ]);
+          } else if (typeof preferredSetting === 'string') {
+            preferred = preferredSetting;
+            invalidTypes.push([
+              typeNodeName, preferred,
+            ]);
+          } else if (preferredSetting && typeof preferredSetting === 'object') {
+            const nextItem = preferredSetting.skipRootChecking && jsdocTagsWithPossibleType[idx + 1];
+
+            if (!nextItem || !nextItem.name.startsWith(`${nameInTag}.`)) {
+              preferred = preferredSetting.replacement;
+              invalidTypes.push([
+                typeNodeName,
+                preferred,
+                preferredSetting.message,
+              ]);
+            }
+          } else {
+            utils.reportSettings(
+              'Invalid `settings.jsdoc.preferredTypes`. Values must be falsy, a string, or an object.',
+            );
+
+            return;
+          }
+        } else if (Object.entries(structuredTags).some(([
+          tag,
+          {
+            type: typs,
+          },
+        ]) => {
+          types = typs;
+
+          return tag === tagName &&
+            Array.isArray(types) &&
+            !types.includes(typeNodeName);
+        })) {
+          invalidTypes.push([
+            typeNodeName, types,
+          ]);
+        } else if (checkNativeTypes && !noDefaults && type === 'JsdocTypeName') {
+          preferred = checkNativeTypes(
+            preferredTypes, typeNodeName, preferred, parentNode, invalidTypes,
+          );
+        }
+
+        // For fixer
+        if (preferred) {
+          adjustNames(type, preferred, isGenericMatch, typeNodeName, node, parentNode);
+        }
+      };
+
+      for (const [
+        idx,
+        jsdocTag,
+      ] of jsdocTagsWithPossibleType.entries()) {
+        /** @type {(string|false|undefined)[][]} */
+        const invalidTypes = [];
+        let typeAst;
+
+        try {
+          typeAst = mode === 'permissive' ? tryParse(jsdocTag.type) : parse(jsdocTag.type, mode);
+        } catch {
+          continue;
+        }
+
+        const {
+          name: nameInTag,
+          tag: tagName,
+        } = jsdocTag;
+
+        traverse(typeAst, (node, parentNode, property) => {
+          const {
+            type,
+            value,
+          } =
+            /**
+             * @type {import('jsdoc-type-pratt-parser').NameResult}
+             */ (node);
+          if (![
+            'JsdocTypeAny', 'JsdocTypeName',
+          ].includes(type)) {
+            return;
+          }
+
+          getInvalidTypes(type, value, tagName, nameInTag, idx, property, node, parentNode, invalidTypes);
+        });
+
+        if (invalidTypes.length) {
+          const fixedType = stringify(typeAst);
+
+          /**
+           * @type {import('eslint').Rule.ReportFixer}
+           */
+          const fix = (fixer) => {
+            return fixer.replaceText(
+              jsdocNode,
+              sourceCode.getText(jsdocNode).replace(
+                `{${jsdocTag.type}}`,
+                `{${fixedType}}`,
+              ),
+            );
+          };
+
+          for (const [
+            badType,
+            preferredType = '',
+            msg,
+          ] of invalidTypes) {
+            const tagValue = jsdocTag.name ? ` "${jsdocTag.name}"` : '';
+            if (exemptTagContexts.some(({
+              tag,
+              types,
+            }) => {
+              return tag === tagName &&
+                (types === true || types.includes(jsdocTag.type));
+            })) {
+              continue;
+            }
+
+            report(
+              msg ||
+                `Invalid JSDoc @${tagName}${tagValue} type "${badType}"` +
+                (preferredType ? '; ' : '.') +
+                (preferredType ? `prefer: ${JSON.stringify(preferredType)}.` : ''),
+              preferredType ? fix : null,
+              jsdocTag,
+              msg ? {
+                tagName,
+                tagValue,
+              } : undefined,
+            );
+          }
+        }
+      }
+    },
+    {
+      iterateAllJsdocs: true,
+      meta: {
+        docs: {
+          description,
+          url,
+        },
+        fixable: 'code',
+        schema,
+        type: 'suggestion',
+      },
+    },
+  );
+};

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',