eslint-plugin-jsdoc 57.2.1 → 58.0.0

package/src/rules/checkTypes.js

@@ -1,10 +1,6 @@
-import iterateJsdoc from '../iterateJsdoc.js';
 import {
-  parse,
-  stringify,
-  traverse,
-  tryParse,
-} from '@es-joy/jsdoccomment';
+  buildRejectOrPreferRuleDefinition,
+} from '../buildRejectOrPreferRuleDefinition.js';
 
 const strictNativeTypes = [
   'undefined',
@@ -22,535 +18,110 @@ const strictNativeTypes = [
 ];
 
 /**
- * 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
+ * @callback CheckNativeTypes
+ * Iterates strict types to see if any should be added to `invalidTypes` (and
+ * the the relevant strict type returned as the new preferred type).
+ * @param {import('../iterateJsdoc.js').PreferredTypes} preferredTypes
  * @param {string} typeNodeName
- * @param {import('jsdoc-type-pratt-parser').NonRootResult} node
+ * @param {string|undefined} preferred
  * @param {import('jsdoc-type-pratt-parser').NonRootResult|undefined} parentNode
- * @returns {void}
+ * @param {(string|false|undefined)[][]} invalidTypes
+ * @returns {string|undefined} The `preferred` type string, optionally changed
  */
-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,
-};
-
-export default 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,
-    } = 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 typeName = 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
-        ) {
-          typeName += checkPostFix;
-
-          return true;
-        }
-
-        return false;
-      });
-    }
 
+/** @type {CheckNativeTypes} */
+const checkNativeTypes = (preferredTypes, typeNodeName, preferred, parentNode, invalidTypes) => {
+  let changedPreferred = preferred;
+  for (const strictNativeType of strictNativeTypes) {
     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
-        ) {
-          typeName = 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, typeName, isGenericMatch,
-    ];
-  };
-
-  /**
-   * Iterates strict types to see if any should be added to `invalidTypes` (and
-   * the the relevant strict type returned as the new preferred type).
-   * @param {string} typeNodeName
-   * @param {string|undefined} preferred
-   * @param {import('jsdoc-type-pratt-parser').NonRootResult|undefined} parentNode
-   * @param {(string|false|undefined)[][]} invalidTypes
-   * @returns {string|undefined} The `preferred` type string, optionally changed
-   */
-  const checkNativeTypes = (typeNodeName, preferred, parentNode, invalidTypes) => {
-    let changedPreferred = preferred;
-    for (const strictNativeType of strictNativeTypes) {
-      if (
-        strictNativeType === 'object' &&
+      strictNativeType === 'object' &&
+      (
+        // This is not set to remap with exact type match (e.g.,
+        //   `object: 'Object'`), so can ignore (including if circular)
+        !preferredTypes?.[typeNodeName] ||
+        // Although present on `preferredTypes` for remapping, this is a
+        //   parent object without a parent match (and not
+        //   `unifyParentAndChildTypeChecks`) and we don't want
+        //   `object<>` given TypeScript issue https://github.com/microsoft/TypeScript/issues/20555
+        /**
+         * @type {import('jsdoc-type-pratt-parser').GenericResult}
+         */
         (
-          // This is not set to remap with exact type match (e.g.,
-          //   `object: 'Object'`), so can ignore (including if circular)
-          !preferredTypes?.[typeNodeName] ||
-          // Although present on `preferredTypes` for remapping, this is a
-          //   parent object without a parent match (and not
-          //   `unifyParentAndChildTypeChecks`) and we don't want
-          //   `object<>` given TypeScript issue https://github.com/microsoft/TypeScript/issues/20555
-          /**
-           * @type {import('jsdoc-type-pratt-parser').GenericResult}
-           */
+          parentNode
+        )?.elements?.length && (
+        /**
+         * @type {import('jsdoc-type-pratt-parser').GenericResult}
+         */
           (
             parentNode
-          )?.elements?.length && (
+          )?.left?.type === 'JsdocTypeName' &&
           /**
            * @type {import('jsdoc-type-pratt-parser').GenericResult}
            */
-            (
-              parentNode
-            )?.left?.type === 'JsdocTypeName' &&
-            /**
-             * @type {import('jsdoc-type-pratt-parser').GenericResult}
-             */
-            (parentNode)?.left?.value === 'Object'
-          )
+          (parentNode)?.left?.value === 'Object'
         )
-      ) {
-        continue;
-      }
-
-      if (strictNativeType !== typeNodeName &&
-        strictNativeType.toLowerCase() === typeNodeName.toLowerCase() &&
-
-        // Don't report if user has own map for a strict native type
-        (!preferredTypes || preferredTypes?.[strictNativeType] === undefined)
-      ) {
-        changedPreferred = strictNativeType;
-        invalidTypes.push([
-          typeNodeName, changedPreferred,
-        ]);
-        break;
-      }
+      )
+    ) {
+      continue;
     }
 
-    return changedPreferred;
-  };
-
-  /**
-   * 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;
+    if (strictNativeType !== typeNodeName &&
+      strictNativeType.toLowerCase() === typeNodeName.toLowerCase() &&
 
-    const [
-      hasMatchingPreferredType,
-      typeName,
-      isGenericMatch,
-    ] = getPreferredTypeInfo(type, typeNodeName, parentNode, property);
-
-    let preferred;
-    let types;
-    if (hasMatchingPreferredType) {
-      const preferredSetting = preferredTypes[typeName];
-      typeNodeName = typeName === '[]' ? typeName : 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);
-    })) {
+      // Don't report if user has own map for a strict native type
+      (!preferredTypes || preferredTypes?.[strictNativeType] === undefined)
+    ) {
+      changedPreferred = strictNativeType;
       invalidTypes.push([
-        typeNodeName, types,
+        typeNodeName, changedPreferred,
       ]);
-    } else if (!noDefaults && type === 'JsdocTypeName') {
-      preferred = checkNativeTypes(typeNodeName, preferred, parentNode, invalidTypes);
-    }
-
-    // For fixer
-    if (preferred) {
-      adjustNames(type, preferred, isGenericMatch, typeNodeName, node, parentNode);
+      break;
     }
-  };
-
-  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;
-        }
+  return changedPreferred;
+};
 
-        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: 'Reports invalid types.',
-      url: 'https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/check-types.md#repos-sticky-header',
-    },
-    fixable: 'code',
-    schema: [
-      {
-        additionalProperties: false,
-        properties: {
-          exemptTagContexts: {
-            items: {
-              additionalProperties: false,
-              properties: {
-                tag: {
-                  type: 'string',
-                },
-                types: {
-                  oneOf: [
-                    {
-                      type: 'boolean',
-                    },
-                    {
-                      items: {
-                        type: 'string',
-                      },
-                      type: 'array',
+export default buildRejectOrPreferRuleDefinition({
+  checkNativeTypes,
+  schema: [
+    {
+      additionalProperties: false,
+      properties: {
+        exemptTagContexts: {
+          items: {
+            additionalProperties: false,
+            properties: {
+              tag: {
+                type: 'string',
+              },
+              types: {
+                oneOf: [
+                  {
+                    type: 'boolean',
+                  },
+                  {
+                    items: {
+                      type: 'string',
                     },
-                  ],
-                },
+                    type: 'array',
+                  },
+                ],
               },
-              type: 'object',
             },
-            type: 'array',
-          },
-          noDefaults: {
-            type: 'boolean',
-          },
-          unifyParentAndChildTypeChecks: {
-            description: '@deprecated Use the `preferredTypes[preferredType]` setting of the same name instead',
-            type: 'boolean',
+            type: 'object',
           },
+          type: 'array',
+        },
+        noDefaults: {
+          type: 'boolean',
+        },
+        unifyParentAndChildTypeChecks: {
+          description: '@deprecated Use the `preferredTypes[preferredType]` setting of the same name instead',
+          type: 'boolean',
         },
-        type: 'object',
       },
-    ],
-    type: 'suggestion',
-  },
+      type: 'object',
+    },
+  ],
 });

package/src/rules.d.ts

@@ -410,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": 
     | []
@@ -557,7 +563,7 @@ export interface Rules {
         }
       ];
 
-  /** Requires a type for @next tags */
+  /** Requires a type for `@next` tags */
   "jsdoc/require-next-type": [];
 
   /** Requires that all function parameters are documented. */
@@ -748,7 +754,7 @@ export interface Rules {
         }
       ];
 
-  /** Requires a type for @throws tags */
+  /** Requires a type for `@throws` tags */
   "jsdoc/require-throws-type": [];
 
   /** Requires yields are documented. */
@@ -790,7 +796,7 @@ export interface Rules {
         }
       ];
 
-  /** Requires a type for @yields tags */
+  /** Requires a type for `@yields` tags */
   "jsdoc/require-yields-type": [];
 
   /** Sorts tags by a specified sequence according to tag name. */