eslint-plugin-jsdoc 61.3.0 → 61.4.1

package/dist/rules/checkTagNames.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"checkTagNames.cjs","names":["_iterateJsdoc","_interopRequireDefault","require","_escapeStringRegexp","e","__esModule","default","jsxTagNames","Set","typedTagsAlwaysUnnecessary","typedTagsNeedingName","typedTagsUnnecessaryOutsideDeclare","_default","exports","iterateJsdoc","context","jsdoc","jsdocNode","node","report","settings","sourceCode","utils","definedTags","enableFixer","inlineTags","jsxTags","typed","options","definedPreferredTags","structuredTags","tagNamePreference","definedStructuredTags","Object","keys","definedNonPreferredTags","length","values","map","preferredTag","undefined","reportSettings","replacement","filter","Boolean","isInAmbientContext","subNode","type","getFilename","endsWith","declare","parent","tagIsRedundantWhenTyped","jsdocTag","has","tag","includes","reportWithTagRemovalFixer","message","tagIndex","additionalTagChanges","reportJSDoc","description","trim","changeTag","postType","removeTag","removeEmptyBlock","checkTagForTypedValidity","postTag","name","tags","tagName","validTags","isValidTag","preferredTagName","getPreferredTagName","allowObjectReturn","defaultMessage","fixer","getText","replace","RegExp","escapeStringRegexp","replaceText","inlineTag","getInlineTags","iterateAllJsdocs","meta","docs","url","fixable","schema","additionalProperties","properties","items","module"],"sources":["../../src/rules/checkTagNames.js"],"sourcesContent":["import iterateJsdoc from '../iterateJsdoc.js';\nimport escapeStringRegexp from 'escape-string-regexp';\n\n// https://babeljs.io/docs/en/babel-plugin-transform-react-jsx/\nconst jsxTagNames = new Set([\n  'jsx',\n  'jsxFrag',\n  'jsxImportSource',\n  'jsxRuntime',\n]);\n\nconst typedTagsAlwaysUnnecessary = new Set([\n  'augments',\n  'callback',\n  'class',\n  'enum',\n  'implements',\n  'private',\n  'property',\n  'protected',\n  'public',\n  'readonly',\n  'this',\n  'type',\n  'typedef',\n]);\n\nconst typedTagsNeedingName = new Set([\n  'template',\n]);\n\nconst typedTagsUnnecessaryOutsideDeclare = new Set([\n  'abstract',\n  'access',\n  'class',\n  'constant',\n  'constructs',\n  'default',\n  'enum',\n  'export',\n  'exports',\n  'function',\n  'global',\n  'inherits',\n  'instance',\n  'interface',\n  'member',\n  'memberof',\n  'memberOf',\n  'method',\n  'mixes',\n  'mixin',\n  'module',\n  'name',\n  'namespace',\n  'override',\n  'property',\n  'requires',\n  'static',\n  'this',\n]);\n\nexport default iterateJsdoc(({\n  context,\n  jsdoc,\n  jsdocNode,\n  node,\n  report,\n  settings,\n  sourceCode,\n  utils,\n}) => {\n  const\n    /**\n     * @type {{\n     *   definedTags: string[],\n     *   enableFixer: boolean,\n     *   inlineTags: string[],\n     *   jsxTags: boolean,\n     *   typed: boolean\n     }} */ {\n      definedTags = [],\n      enableFixer = true,\n      inlineTags = [\n        'link', 'linkcode', 'linkplain', 'tutorial',\n      ],\n      jsxTags,\n      typed,\n    } = context.options[0] || {};\n\n  /** @type {(string|undefined)[]} */\n  let definedPreferredTags = [];\n  const {\n    structuredTags,\n    tagNamePreference,\n  } = settings;\n  const definedStructuredTags = Object.keys(structuredTags);\n  const definedNonPreferredTags = Object.keys(tagNamePreference);\n  if (definedNonPreferredTags.length) {\n    definedPreferredTags = Object.values(tagNamePreference).map((preferredTag) => {\n      if (typeof preferredTag === 'string') {\n        // May become an empty string but will be filtered out below\n        return preferredTag;\n      }\n\n      if (!preferredTag) {\n        return undefined;\n      }\n\n      if (typeof preferredTag !== 'object') {\n        utils.reportSettings(\n          'Invalid `settings.jsdoc.tagNamePreference`. Values must be falsy, a string, or an object.',\n        );\n      }\n\n      return preferredTag.replacement;\n    })\n      .filter(Boolean);\n  }\n\n  /**\n   * @param {import('eslint').Rule.Node} subNode\n   * @returns {boolean}\n   */\n  const isInAmbientContext = (subNode) => {\n    return subNode.type === 'Program' ?\n      context.getFilename().endsWith('.d.ts') :\n      Boolean(\n        /** @type {import('@typescript-eslint/types').TSESTree.VariableDeclaration} */ (\n          subNode\n        ).declare,\n      ) || isInAmbientContext(subNode.parent);\n  };\n\n  /**\n   * @param {import('comment-parser').Spec} jsdocTag\n   * @returns {boolean}\n   */\n  const tagIsRedundantWhenTyped = (jsdocTag) => {\n    if (!typedTagsUnnecessaryOutsideDeclare.has(jsdocTag.tag)) {\n      return false;\n    }\n\n    if (jsdocTag.tag === 'default') {\n      return false;\n    }\n\n    if (node === null) {\n      return false;\n    }\n\n    if (context.getFilename().endsWith('.d.ts') && [\n      null, 'Program', undefined,\n    ].includes(node?.parent?.type)) {\n      return false;\n    }\n\n    if (isInAmbientContext(/** @type {import('eslint').Rule.Node} */ (node))) {\n      return false;\n    }\n\n    return true;\n  };\n\n  /**\n   * @param {string} message\n   * @param {import('comment-parser').Spec} jsdocTag\n   * @param {import('../iterateJsdoc.js').Integer} tagIndex\n   * @param {Partial<import('comment-parser').Tokens>} [additionalTagChanges]\n   * @returns {void}\n   */\n  const reportWithTagRemovalFixer = (message, jsdocTag, tagIndex, additionalTagChanges) => {\n    utils.reportJSDoc(message, jsdocTag, enableFixer ? () => {\n      if (jsdocTag.description.trim()) {\n        utils.changeTag(jsdocTag, {\n          postType: '',\n          type: '',\n          ...additionalTagChanges,\n        });\n      } else {\n        utils.removeTag(tagIndex, {\n          removeEmptyBlock: true,\n        });\n      }\n    } : null, true);\n  };\n\n  /**\n   * @param {import('comment-parser').Spec} jsdocTag\n   * @param {import('../iterateJsdoc.js').Integer} tagIndex\n   * @returns {boolean}\n   */\n  const checkTagForTypedValidity = (jsdocTag, tagIndex) => {\n    if (typedTagsAlwaysUnnecessary.has(jsdocTag.tag)) {\n      reportWithTagRemovalFixer(\n        `'@${jsdocTag.tag}' is redundant when using a type system.`,\n        jsdocTag,\n        tagIndex,\n        {\n          postTag: '',\n          tag: '',\n        },\n      );\n      return true;\n    }\n\n    if (tagIsRedundantWhenTyped(jsdocTag)) {\n      reportWithTagRemovalFixer(\n        `'@${jsdocTag.tag}' is redundant outside of ambient (\\`declare\\`/\\`.d.ts\\`) contexts when using a type system.`,\n        jsdocTag,\n        tagIndex,\n      );\n      return true;\n    }\n\n    if (typedTagsNeedingName.has(jsdocTag.tag) && !jsdocTag.name) {\n      reportWithTagRemovalFixer(\n        `'@${jsdocTag.tag}' without a name is redundant when using a type system.`,\n        jsdocTag,\n        tagIndex,\n      );\n      return true;\n    }\n\n    return false;\n  };\n\n  for (let tagIndex = 0; tagIndex < jsdoc.tags.length; tagIndex += 1) {\n    const jsdocTag = jsdoc.tags[tagIndex];\n    const tagName = jsdocTag.tag;\n    if (jsxTags && jsxTagNames.has(tagName)) {\n      continue;\n    }\n\n    if (typed && checkTagForTypedValidity(jsdocTag, tagIndex)) {\n      continue;\n    }\n\n    const validTags = [\n      ...definedTags,\n      ...(/** @type {string[]} */ (definedPreferredTags)),\n      ...definedNonPreferredTags,\n      ...definedStructuredTags,\n      ...typed ? typedTagsNeedingName : [],\n    ];\n\n    if (utils.isValidTag(tagName, validTags)) {\n      let preferredTagName = utils.getPreferredTagName({\n        allowObjectReturn: true,\n        defaultMessage: `Blacklisted tag found (\\`@${tagName}\\`)`,\n        tagName,\n      });\n      if (!preferredTagName) {\n        continue;\n      }\n\n      let message;\n      if (typeof preferredTagName === 'object') {\n        ({\n          message,\n          replacement: preferredTagName,\n        } = /** @type {{message: string; replacement?: string | undefined;}} */ (\n          preferredTagName\n        ));\n      }\n\n      if (!message) {\n        message = `Invalid JSDoc tag (preference). Replace \"${tagName}\" JSDoc tag with \"${preferredTagName}\".`;\n      }\n\n      if (preferredTagName !== tagName) {\n        report(message, (fixer) => {\n          const replacement = sourceCode.getText(jsdocNode).replace(\n            new RegExp(`@${escapeStringRegexp(tagName)}\\\\b`, 'v'),\n            `@${preferredTagName}`,\n          );\n\n          return fixer.replaceText(jsdocNode, replacement);\n        }, jsdocTag);\n      }\n    } else {\n      report(`Invalid JSDoc tag name \"${tagName}\".`, null, jsdocTag);\n    }\n  }\n\n  for (const inlineTag of utils.getInlineTags()) {\n    if (!inlineTags.includes(inlineTag.tag)) {\n      report(`Invalid JSDoc inline tag name \"${inlineTag.tag}\"`, null, inlineTag);\n    }\n  }\n}, {\n  iterateAllJsdocs: true,\n  meta: {\n    docs: {\n      description: 'Reports invalid block tag names.',\n      url: 'https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/check-tag-names.md#repos-sticky-header',\n    },\n    fixable: 'code',\n    schema: [\n      {\n        additionalProperties: false,\n        properties: {\n          definedTags: {\n            description: `Use an array of \\`definedTags\\` strings to configure additional, allowed tags.\nThe format is as follows:\n\n\\`\\`\\`json\n{\n  \"definedTags\": [\"note\", \"record\"]\n}\n\\`\\`\\``,\n            items: {\n              type: 'string',\n            },\n            type: 'array',\n          },\n          enableFixer: {\n            description: 'Set to `false` to disable auto-removal of types that are redundant with the [`typed` option](#typed).',\n            type: 'boolean',\n          },\n          inlineTags: {\n            description: `List of tags to allow inline.\n\nDefaults to array of \\`'link', 'linkcode', 'linkplain', 'tutorial'\\``,\n            items: {\n              type: 'string',\n            },\n            type: 'array',\n          },\n          jsxTags: {\n            description: `If this is set to \\`true\\`, all of the following tags used to control JSX output are allowed:\n\n\\`\\`\\`\njsx\njsxFrag\njsxImportSource\njsxRuntime\n\\`\\`\\`\n\nFor more information, see the [babel documentation](https://babeljs.io/docs/en/babel-plugin-transform-react-jsx).`,\n            type: 'boolean',\n          },\n          typed: {\n            description: `If this is set to \\`true\\`, additionally checks for tag names that are redundant when using a type checker such as TypeScript.\n\nThese tags are always unnecessary when using TypeScript or similar:\n\n\\`\\`\\`\naugments\ncallback\nclass\nenum\nimplements\nprivate\nproperty\nprotected\npublic\nreadonly\nthis\ntype\ntypedef\n\\`\\`\\`\n\nThese tags are unnecessary except when inside a TypeScript \\`declare\\` context:\n\n\\`\\`\\`\nabstract\naccess\nclass\nconstant\nconstructs\ndefault\nenum\nexport\nexports\nfunction\nglobal\ninherits\ninstance\ninterface\nmember\nmemberof\nmemberOf\nmethod\nmixes\nmixin\nmodule\nname\nnamespace\noverride\nproperty\nrequires\nstatic\nthis\n\\`\\`\\``,\n            type: 'boolean',\n          },\n        },\n        type: 'object',\n      },\n    ],\n    type: 'suggestion',\n  },\n});\n"],"mappings":"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","ignoreList":[]}
+{"version":3,"file":"checkTagNames.cjs","names":["_iterateJsdoc","_interopRequireDefault","require","_escapeStringRegexp","e","__esModule","default","jsxTagNames","Set","typedTagsAlwaysUnnecessary","typedTagsNeedingName","typedTagsUnnecessaryOutsideDeclare","_default","exports","iterateJsdoc","context","jsdoc","jsdocNode","node","report","settings","sourceCode","utils","definedTags","enableFixer","inlineTags","jsxTags","typed","options","definedPreferredTags","structuredTags","tagNamePreference","definedStructuredTags","Object","keys","definedNonPreferredTags","length","values","map","preferredTag","undefined","reportSettings","replacement","filter","Boolean","isInAmbientContext","subNode","type","filename","getFilename","endsWith","declare","parent","tagIsRedundantWhenTyped","jsdocTag","has","tag","includes","reportWithTagRemovalFixer","message","tagIndex","additionalTagChanges","reportJSDoc","description","trim","changeTag","postType","removeTag","removeEmptyBlock","checkTagForTypedValidity","postTag","name","tags","tagName","validTags","isValidTag","preferredTagName","getPreferredTagName","allowObjectReturn","defaultMessage","fixer","getText","replace","RegExp","escapeStringRegexp","replaceText","inlineTag","getInlineTags","iterateAllJsdocs","meta","docs","url","fixable","schema","additionalProperties","properties","items","module"],"sources":["../../src/rules/checkTagNames.js"],"sourcesContent":["import iterateJsdoc from '../iterateJsdoc.js';\nimport escapeStringRegexp from 'escape-string-regexp';\n\n// https://babeljs.io/docs/en/babel-plugin-transform-react-jsx/\nconst jsxTagNames = new Set([\n  'jsx',\n  'jsxFrag',\n  'jsxImportSource',\n  'jsxRuntime',\n]);\n\nconst typedTagsAlwaysUnnecessary = new Set([\n  'augments',\n  'callback',\n  'class',\n  'enum',\n  'implements',\n  'private',\n  'property',\n  'protected',\n  'public',\n  'readonly',\n  'this',\n  'type',\n  'typedef',\n]);\n\nconst typedTagsNeedingName = new Set([\n  'template',\n]);\n\nconst typedTagsUnnecessaryOutsideDeclare = new Set([\n  'abstract',\n  'access',\n  'class',\n  'constant',\n  'constructs',\n  'default',\n  'enum',\n  'export',\n  'exports',\n  'function',\n  'global',\n  'inherits',\n  'instance',\n  'interface',\n  'member',\n  'memberof',\n  'memberOf',\n  'method',\n  'mixes',\n  'mixin',\n  'module',\n  'name',\n  'namespace',\n  'override',\n  'property',\n  'requires',\n  'static',\n  'this',\n]);\n\nexport default iterateJsdoc(({\n  context,\n  jsdoc,\n  jsdocNode,\n  node,\n  report,\n  settings,\n  sourceCode,\n  utils,\n}) => {\n  const\n    /**\n     * @type {{\n     *   definedTags: string[],\n     *   enableFixer: boolean,\n     *   inlineTags: string[],\n     *   jsxTags: boolean,\n     *   typed: boolean\n     }} */ {\n      definedTags = [],\n      enableFixer = true,\n      inlineTags = [\n        'link', 'linkcode', 'linkplain', 'tutorial',\n      ],\n      jsxTags,\n      typed,\n    } = context.options[0] || {};\n\n  /** @type {(string|undefined)[]} */\n  let definedPreferredTags = [];\n  const {\n    structuredTags,\n    tagNamePreference,\n  } = settings;\n  const definedStructuredTags = Object.keys(structuredTags);\n  const definedNonPreferredTags = Object.keys(tagNamePreference);\n  if (definedNonPreferredTags.length) {\n    definedPreferredTags = Object.values(tagNamePreference).map((preferredTag) => {\n      if (typeof preferredTag === 'string') {\n        // May become an empty string but will be filtered out below\n        return preferredTag;\n      }\n\n      if (!preferredTag) {\n        return undefined;\n      }\n\n      if (typeof preferredTag !== 'object') {\n        utils.reportSettings(\n          'Invalid `settings.jsdoc.tagNamePreference`. Values must be falsy, a string, or an object.',\n        );\n      }\n\n      return preferredTag.replacement;\n    })\n      .filter(Boolean);\n  }\n\n  /**\n   * @param {import('eslint').Rule.Node} subNode\n   * @returns {boolean}\n   */\n  const isInAmbientContext = (subNode) => {\n    return subNode.type === 'Program' ?\n      /* c8 ignore next -- Support old ESLint */\n      (context.filename ?? context.getFilename()).endsWith('.d.ts') :\n      Boolean(\n        /** @type {import('@typescript-eslint/types').TSESTree.VariableDeclaration} */ (\n          subNode\n        ).declare,\n      ) || isInAmbientContext(subNode.parent);\n  };\n\n  /**\n   * @param {import('comment-parser').Spec} jsdocTag\n   * @returns {boolean}\n   */\n  const tagIsRedundantWhenTyped = (jsdocTag) => {\n    if (!typedTagsUnnecessaryOutsideDeclare.has(jsdocTag.tag)) {\n      return false;\n    }\n\n    if (jsdocTag.tag === 'default') {\n      return false;\n    }\n\n    if (node === null) {\n      return false;\n    }\n\n    /* c8 ignore next -- Support old ESLint */\n    if ((context.filename ?? context.getFilename()).endsWith('.d.ts') && [\n      null, 'Program', undefined,\n    ].includes(node?.parent?.type)) {\n      return false;\n    }\n\n    if (isInAmbientContext(/** @type {import('eslint').Rule.Node} */ (node))) {\n      return false;\n    }\n\n    return true;\n  };\n\n  /**\n   * @param {string} message\n   * @param {import('comment-parser').Spec} jsdocTag\n   * @param {import('../iterateJsdoc.js').Integer} tagIndex\n   * @param {Partial<import('comment-parser').Tokens>} [additionalTagChanges]\n   * @returns {void}\n   */\n  const reportWithTagRemovalFixer = (message, jsdocTag, tagIndex, additionalTagChanges) => {\n    utils.reportJSDoc(message, jsdocTag, enableFixer ? () => {\n      if (jsdocTag.description.trim()) {\n        utils.changeTag(jsdocTag, {\n          postType: '',\n          type: '',\n          ...additionalTagChanges,\n        });\n      } else {\n        utils.removeTag(tagIndex, {\n          removeEmptyBlock: true,\n        });\n      }\n    } : null, true);\n  };\n\n  /**\n   * @param {import('comment-parser').Spec} jsdocTag\n   * @param {import('../iterateJsdoc.js').Integer} tagIndex\n   * @returns {boolean}\n   */\n  const checkTagForTypedValidity = (jsdocTag, tagIndex) => {\n    if (typedTagsAlwaysUnnecessary.has(jsdocTag.tag)) {\n      reportWithTagRemovalFixer(\n        `'@${jsdocTag.tag}' is redundant when using a type system.`,\n        jsdocTag,\n        tagIndex,\n        {\n          postTag: '',\n          tag: '',\n        },\n      );\n      return true;\n    }\n\n    if (tagIsRedundantWhenTyped(jsdocTag)) {\n      reportWithTagRemovalFixer(\n        `'@${jsdocTag.tag}' is redundant outside of ambient (\\`declare\\`/\\`.d.ts\\`) contexts when using a type system.`,\n        jsdocTag,\n        tagIndex,\n      );\n      return true;\n    }\n\n    if (typedTagsNeedingName.has(jsdocTag.tag) && !jsdocTag.name) {\n      reportWithTagRemovalFixer(\n        `'@${jsdocTag.tag}' without a name is redundant when using a type system.`,\n        jsdocTag,\n        tagIndex,\n      );\n      return true;\n    }\n\n    return false;\n  };\n\n  for (let tagIndex = 0; tagIndex < jsdoc.tags.length; tagIndex += 1) {\n    const jsdocTag = jsdoc.tags[tagIndex];\n    const tagName = jsdocTag.tag;\n    if (jsxTags && jsxTagNames.has(tagName)) {\n      continue;\n    }\n\n    if (typed && checkTagForTypedValidity(jsdocTag, tagIndex)) {\n      continue;\n    }\n\n    const validTags = [\n      ...definedTags,\n      ...(/** @type {string[]} */ (definedPreferredTags)),\n      ...definedNonPreferredTags,\n      ...definedStructuredTags,\n      ...typed ? typedTagsNeedingName : [],\n    ];\n\n    if (utils.isValidTag(tagName, validTags)) {\n      let preferredTagName = utils.getPreferredTagName({\n        allowObjectReturn: true,\n        defaultMessage: `Blacklisted tag found (\\`@${tagName}\\`)`,\n        tagName,\n      });\n      if (!preferredTagName) {\n        continue;\n      }\n\n      let message;\n      if (typeof preferredTagName === 'object') {\n        ({\n          message,\n          replacement: preferredTagName,\n        } = /** @type {{message: string; replacement?: string | undefined;}} */ (\n          preferredTagName\n        ));\n      }\n\n      if (!message) {\n        message = `Invalid JSDoc tag (preference). Replace \"${tagName}\" JSDoc tag with \"${preferredTagName}\".`;\n      }\n\n      if (preferredTagName !== tagName) {\n        report(message, (fixer) => {\n          const replacement = sourceCode.getText(jsdocNode).replace(\n            new RegExp(`@${escapeStringRegexp(tagName)}\\\\b`, 'v'),\n            `@${preferredTagName}`,\n          );\n\n          return fixer.replaceText(jsdocNode, replacement);\n        }, jsdocTag);\n      }\n    } else {\n      report(`Invalid JSDoc tag name \"${tagName}\".`, null, jsdocTag);\n    }\n  }\n\n  for (const inlineTag of utils.getInlineTags()) {\n    if (!inlineTags.includes(inlineTag.tag)) {\n      report(`Invalid JSDoc inline tag name \"${inlineTag.tag}\"`, null, inlineTag);\n    }\n  }\n}, {\n  iterateAllJsdocs: true,\n  meta: {\n    docs: {\n      description: 'Reports invalid block tag names.',\n      url: 'https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/check-tag-names.md#repos-sticky-header',\n    },\n    fixable: 'code',\n    schema: [\n      {\n        additionalProperties: false,\n        properties: {\n          definedTags: {\n            description: `Use an array of \\`definedTags\\` strings to configure additional, allowed tags.\nThe format is as follows:\n\n\\`\\`\\`json\n{\n  \"definedTags\": [\"note\", \"record\"]\n}\n\\`\\`\\``,\n            items: {\n              type: 'string',\n            },\n            type: 'array',\n          },\n          enableFixer: {\n            description: 'Set to `false` to disable auto-removal of types that are redundant with the [`typed` option](#typed).',\n            type: 'boolean',\n          },\n          inlineTags: {\n            description: `List of tags to allow inline.\n\nDefaults to array of \\`'link', 'linkcode', 'linkplain', 'tutorial'\\``,\n            items: {\n              type: 'string',\n            },\n            type: 'array',\n          },\n          jsxTags: {\n            description: `If this is set to \\`true\\`, all of the following tags used to control JSX output are allowed:\n\n\\`\\`\\`\njsx\njsxFrag\njsxImportSource\njsxRuntime\n\\`\\`\\`\n\nFor more information, see the [babel documentation](https://babeljs.io/docs/en/babel-plugin-transform-react-jsx).`,\n            type: 'boolean',\n          },\n          typed: {\n            description: `If this is set to \\`true\\`, additionally checks for tag names that are redundant when using a type checker such as TypeScript.\n\nThese tags are always unnecessary when using TypeScript or similar:\n\n\\`\\`\\`\naugments\ncallback\nclass\nenum\nimplements\nprivate\nproperty\nprotected\npublic\nreadonly\nthis\ntype\ntypedef\n\\`\\`\\`\n\nThese tags are unnecessary except when inside a TypeScript \\`declare\\` context:\n\n\\`\\`\\`\nabstract\naccess\nclass\nconstant\nconstructs\ndefault\nenum\nexport\nexports\nfunction\nglobal\ninherits\ninstance\ninterface\nmember\nmemberof\nmemberOf\nmethod\nmixes\nmixin\nmodule\nname\nnamespace\noverride\nproperty\nrequires\nstatic\nthis\n\\`\\`\\``,\n            type: 'boolean',\n          },\n        },\n        type: 'object',\n      },\n    ],\n    type: 'suggestion',\n  },\n});\n"],"mappings":"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","ignoreList":[]}

package/dist/rules/requireRejects.cjs

@@ -0,0 +1,226 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.default = void 0;
+var _iterateJsdoc = _interopRequireDefault(require("../iterateJsdoc.cjs"));
+function _interopRequireDefault(e) { return e && e.__esModule ? e : { default: e }; }
+/**
+ * Checks if a node or its children contain Promise rejection patterns
+ * @param {import('eslint').Rule.Node} node
+ * @param {boolean} [innerFunction]
+ * @param {boolean} [isAsync]
+ * @returns {boolean}
+ */
+// eslint-disable-next-line complexity -- Temporary
+const hasRejectValue = (node, innerFunction, isAsync) => {
+  if (!node) {
+    return false;
+  }
+  switch (node.type) {
+    case 'ArrowFunctionExpression':
+    case 'FunctionDeclaration':
+    case 'FunctionExpression':
+      {
+        // For inner functions in async contexts, check if they throw
+        // (they could be called and cause rejection)
+        if (innerFunction) {
+          // Check inner functions for throws - if called from async context, throws become rejections
+          const innerIsAsync = node.async;
+          // Pass isAsync=true if the inner function is async OR if we're already in an async context
+          return hasRejectValue(/** @type {import('eslint').Rule.Node} */node.body, false, innerIsAsync || isAsync);
+        }
+
+        // This is the top-level function we're checking
+        return hasRejectValue(/** @type {import('eslint').Rule.Node} */node.body, true, node.async);
+      }
+    case 'BlockStatement':
+      {
+        return node.body.some(bodyNode => {
+          return hasRejectValue(/** @type {import('eslint').Rule.Node} */bodyNode, innerFunction, isAsync);
+        });
+      }
+    case 'CallExpression':
+      {
+        // Check for Promise.reject()
+        if (node.callee.type === 'MemberExpression' && node.callee.object.type === 'Identifier' && node.callee.object.name === 'Promise' && node.callee.property.type === 'Identifier' && node.callee.property.name === 'reject') {
+          return true;
+        }
+
+        // Check for reject() call (in Promise executor context)
+        if (node.callee.type === 'Identifier' && node.callee.name === 'reject') {
+          return true;
+        }
+
+        // Check if this is calling an inner function that might reject
+        if (innerFunction && node.callee.type === 'Identifier') {
+          // We found a function call inside - check if it could be calling a function that rejects
+          // We'll handle this in function body traversal
+          return false;
+        }
+        return false;
+      }
+    case 'DoWhileStatement':
+    case 'ForInStatement':
+    case 'ForOfStatement':
+    case 'ForStatement':
+    case 'LabeledStatement':
+    case 'WhileStatement':
+    case 'WithStatement':
+      {
+        return hasRejectValue(/** @type {import('eslint').Rule.Node} */node.body, innerFunction, isAsync);
+      }
+    case 'ExpressionStatement':
+      {
+        return hasRejectValue(/** @type {import('eslint').Rule.Node} */node.expression, innerFunction, isAsync);
+      }
+    case 'IfStatement':
+      {
+        return hasRejectValue(/** @type {import('eslint').Rule.Node} */node.consequent, innerFunction, isAsync) || hasRejectValue(/** @type {import('eslint').Rule.Node} */node.alternate, innerFunction, isAsync);
+      }
+    case 'NewExpression':
+      {
+        // Check for new Promise((resolve, reject) => { reject(...) })
+        if (node.callee.type === 'Identifier' && node.callee.name === 'Promise' && node.arguments.length > 0) {
+          const executor = node.arguments[0];
+          if (executor.type === 'ArrowFunctionExpression' || executor.type === 'FunctionExpression') {
+            // Check if the executor has reject() calls
+            return hasRejectValue(/** @type {import('eslint').Rule.Node} */executor.body, false, false);
+          }
+        }
+        return false;
+      }
+    case 'ReturnStatement':
+      {
+        if (node.argument) {
+          return hasRejectValue(/** @type {import('eslint').Rule.Node} */node.argument, innerFunction, isAsync);
+        }
+        return false;
+      }
+    case 'SwitchStatement':
+      {
+        return node.cases.some(someCase => {
+          return someCase.consequent.some(nde => {
+            return hasRejectValue(/** @type {import('eslint').Rule.Node} */nde, innerFunction, isAsync);
+          });
+        });
+      }
+
+    // Throw statements in async functions become rejections
+    case 'ThrowStatement':
+      {
+        return isAsync === true;
+      }
+    case 'TryStatement':
+      {
+        return hasRejectValue(/** @type {import('eslint').Rule.Node} */node.handler && node.handler.body, innerFunction, isAsync) || hasRejectValue(/** @type {import('eslint').Rule.Node} */node.finalizer, innerFunction, isAsync);
+      }
+    default:
+      {
+        return false;
+      }
+  }
+};
+
+/**
+ * We can skip checking for a rejects value, in case the documentation is inherited
+ * or the method is abstract.
+ * @param {import('../iterateJsdoc.js').Utils} utils
+ * @returns {boolean}
+ */
+const canSkip = utils => {
+  return utils.hasATag(['abstract', 'virtual', 'type']) || utils.avoidDocs();
+};
+var _default = exports.default = (0, _iterateJsdoc.default)(({
+  node,
+  report,
+  utils
+}) => {
+  if (canSkip(utils)) {
+    return;
+  }
+  const tagName = /** @type {string} */utils.getPreferredTagName({
+    tagName: 'rejects'
+  });
+  if (!tagName) {
+    return;
+  }
+  const tags = utils.getTags(tagName);
+  const iteratingFunction = utils.isIteratingFunction();
+  const [tag] = tags;
+  const missingRejectsTag = typeof tag === 'undefined' || tag === null;
+  const shouldReport = () => {
+    if (!missingRejectsTag) {
+      return false;
+    }
+
+    // Check if this is an async function or returns a Promise
+    const isAsync = utils.isAsync();
+    if (!isAsync && !iteratingFunction) {
+      return false;
+    }
+
+    // For async functions, check for throw statements
+    // For regular functions, check for Promise.reject or reject calls
+    return hasRejectValue(/** @type {import('eslint').Rule.Node} */node);
+  };
+  if (shouldReport()) {
+    report('Promise-rejecting function requires `@reject` tag');
+  }
+}, {
+  contextDefaults: true,
+  meta: {
+    docs: {
+      description: 'Requires that Promise rejections are documented with `@rejects` tags.',
+      url: 'https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/require-rejects.md#repos-sticky-header'
+    },
+    schema: [{
+      additionalProperties: false,
+      properties: {
+        contexts: {
+          description: `Set this to an array of strings representing the AST context
+(or objects with optional \`context\` and \`comment\` properties) where you wish
+the rule to be applied.
+
+\`context\` defaults to \`any\` and \`comment\` defaults to no specific comment context.
+
+Overrides the default contexts (\`ArrowFunctionExpression\`, \`FunctionDeclaration\`,
+\`FunctionExpression\`).`,
+          items: {
+            anyOf: [{
+              type: 'string'
+            }, {
+              additionalProperties: false,
+              properties: {
+                comment: {
+                  type: 'string'
+                },
+                context: {
+                  type: 'string'
+                }
+              },
+              type: 'object'
+            }]
+          },
+          type: 'array'
+        },
+        exemptedBy: {
+          description: `Array of tags (e.g., \`['type']\`) whose presence on the
+document block avoids the need for a \`@rejects\`. Defaults to an array
+with \`abstract\`, \`virtual\`, and \`type\`. If you set this array, it will overwrite the default,
+so be sure to add back those tags if you wish their presence to cause
+exemption of the rule.`,
+          items: {
+            type: 'string'
+          },
+          type: 'array'
+        }
+      },
+      type: 'object'
+    }],
+    type: 'suggestion'
+  }
+});
+module.exports = exports.default;
+//# sourceMappingURL=requireRejects.cjs.map

package/dist/rules/requireRejects.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"requireRejects.cjs","names":["_iterateJsdoc","_interopRequireDefault","require","e","__esModule","default","hasRejectValue","node","innerFunction","isAsync","type","innerIsAsync","async","body","some","bodyNode","callee","object","name","property","expression","consequent","alternate","arguments","length","executor","argument","cases","someCase","nde","handler","finalizer","canSkip","utils","hasATag","avoidDocs","_default","exports","iterateJsdoc","report","tagName","getPreferredTagName","tags","getTags","iteratingFunction","isIteratingFunction","tag","missingRejectsTag","shouldReport","contextDefaults","meta","docs","description","url","schema","additionalProperties","properties","contexts","items","anyOf","comment","context","exemptedBy","module"],"sources":["../../src/rules/requireRejects.js"],"sourcesContent":["import iterateJsdoc from '../iterateJsdoc.js';\n\n/**\n * Checks if a node or its children contain Promise rejection patterns\n * @param {import('eslint').Rule.Node} node\n * @param {boolean} [innerFunction]\n * @param {boolean} [isAsync]\n * @returns {boolean}\n */\n// eslint-disable-next-line complexity -- Temporary\nconst hasRejectValue = (node, innerFunction, isAsync) => {\n  if (!node) {\n    return false;\n  }\n\n  switch (node.type) {\n    case 'ArrowFunctionExpression':\n    case 'FunctionDeclaration':\n    case 'FunctionExpression': {\n      // For inner functions in async contexts, check if they throw\n      // (they could be called and cause rejection)\n      if (innerFunction) {\n        // Check inner functions for throws - if called from async context, throws become rejections\n        const innerIsAsync = node.async;\n        // Pass isAsync=true if the inner function is async OR if we're already in an async context\n        return hasRejectValue(/** @type {import('eslint').Rule.Node} */ (node.body), false, innerIsAsync || isAsync);\n      }\n\n      // This is the top-level function we're checking\n      return hasRejectValue(/** @type {import('eslint').Rule.Node} */ (node.body), true, node.async);\n    }\n\n    case 'BlockStatement': {\n      return node.body.some((bodyNode) => {\n        return hasRejectValue(/** @type {import('eslint').Rule.Node} */ (bodyNode), innerFunction, isAsync);\n      });\n    }\n\n    case 'CallExpression': {\n      // Check for Promise.reject()\n      if (node.callee.type === 'MemberExpression' &&\n          node.callee.object.type === 'Identifier' &&\n          node.callee.object.name === 'Promise' &&\n          node.callee.property.type === 'Identifier' &&\n          node.callee.property.name === 'reject') {\n        return true;\n      }\n\n      // Check for reject() call (in Promise executor context)\n      if (node.callee.type === 'Identifier' && node.callee.name === 'reject') {\n        return true;\n      }\n\n      // Check if this is calling an inner function that might reject\n      if (innerFunction && node.callee.type === 'Identifier') {\n        // We found a function call inside - check if it could be calling a function that rejects\n        // We'll handle this in function body traversal\n        return false;\n      }\n\n      return false;\n    }\n\n    case 'DoWhileStatement':\n    case 'ForInStatement':\n    case 'ForOfStatement':\n    case 'ForStatement':\n    case 'LabeledStatement':\n    case 'WhileStatement':\n\n    case 'WithStatement': {\n      return hasRejectValue(/** @type {import('eslint').Rule.Node} */ (node.body), innerFunction, isAsync);\n    }\n\n    case 'ExpressionStatement': {\n      return hasRejectValue(/** @type {import('eslint').Rule.Node} */ (node.expression), innerFunction, isAsync);\n    }\n\n    case 'IfStatement': {\n      return hasRejectValue(/** @type {import('eslint').Rule.Node} */ (node.consequent), innerFunction, isAsync) || hasRejectValue(/** @type {import('eslint').Rule.Node} */ (node.alternate), innerFunction, isAsync);\n    }\n\n    case 'NewExpression': {\n      // Check for new Promise((resolve, reject) => { reject(...) })\n      if (node.callee.type === 'Identifier' && node.callee.name === 'Promise' && node.arguments.length > 0) {\n        const executor = node.arguments[0];\n        if (executor.type === 'ArrowFunctionExpression' || executor.type === 'FunctionExpression') {\n          // Check if the executor has reject() calls\n          return hasRejectValue(/** @type {import('eslint').Rule.Node} */ (executor.body), false, false);\n        }\n      }\n\n      return false;\n    }\n\n    case 'ReturnStatement': {\n      if (node.argument) {\n        return hasRejectValue(/** @type {import('eslint').Rule.Node} */ (node.argument), innerFunction, isAsync);\n      }\n\n      return false;\n    }\n\n    case 'SwitchStatement': {\n      return node.cases.some(\n        (someCase) => {\n          return someCase.consequent.some((nde) => {\n            return hasRejectValue(/** @type {import('eslint').Rule.Node} */ (nde), innerFunction, isAsync);\n          });\n        },\n      );\n    }\n\n    // Throw statements in async functions become rejections\n    case 'ThrowStatement': {\n      return isAsync === true;\n    }\n\n    case 'TryStatement': {\n      return hasRejectValue(/** @type {import('eslint').Rule.Node} */ (node.handler && node.handler.body), innerFunction, isAsync) ||\n        hasRejectValue(/** @type {import('eslint').Rule.Node} */ (node.finalizer), innerFunction, isAsync);\n    }\n\n    default: {\n      return false;\n    }\n  }\n};\n\n/**\n * We can skip checking for a rejects value, in case the documentation is inherited\n * or the method is abstract.\n * @param {import('../iterateJsdoc.js').Utils} utils\n * @returns {boolean}\n */\nconst canSkip = (utils) => {\n  return utils.hasATag([\n    'abstract',\n    'virtual',\n    'type',\n  ]) ||\n    utils.avoidDocs();\n};\n\nexport default iterateJsdoc(({\n  node,\n  report,\n  utils,\n}) => {\n  if (canSkip(utils)) {\n    return;\n  }\n\n  const tagName = /** @type {string} */ (utils.getPreferredTagName({\n    tagName: 'rejects',\n  }));\n  if (!tagName) {\n    return;\n  }\n\n  const tags = utils.getTags(tagName);\n  const iteratingFunction = utils.isIteratingFunction();\n\n  const [\n    tag,\n  ] = tags;\n  const missingRejectsTag = typeof tag === 'undefined' || tag === null;\n\n  const shouldReport = () => {\n    if (!missingRejectsTag) {\n      return false;\n    }\n\n    // Check if this is an async function or returns a Promise\n    const isAsync = utils.isAsync();\n    if (!isAsync && !iteratingFunction) {\n      return false;\n    }\n\n    // For async functions, check for throw statements\n    // For regular functions, check for Promise.reject or reject calls\n    return hasRejectValue(/** @type {import('eslint').Rule.Node} */ (node));\n  };\n\n  if (shouldReport()) {\n    report('Promise-rejecting function requires `@reject` tag');\n  }\n}, {\n  contextDefaults: true,\n  meta: {\n    docs: {\n      description: 'Requires that Promise rejections are documented with `@rejects` tags.',\n      url: 'https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/require-rejects.md#repos-sticky-header',\n    },\n    schema: [\n      {\n        additionalProperties: false,\n        properties: {\n          contexts: {\n            description: `Set this to an array of strings representing the AST context\n(or objects with optional \\`context\\` and \\`comment\\` properties) where you wish\nthe rule to be applied.\n\n\\`context\\` defaults to \\`any\\` and \\`comment\\` defaults to no specific comment context.\n\nOverrides the default contexts (\\`ArrowFunctionExpression\\`, \\`FunctionDeclaration\\`,\n\\`FunctionExpression\\`).`,\n            items: {\n              anyOf: [\n                {\n                  type: 'string',\n                },\n                {\n                  additionalProperties: false,\n                  properties: {\n                    comment: {\n                      type: 'string',\n                    },\n                    context: {\n                      type: 'string',\n                    },\n                  },\n                  type: 'object',\n                },\n              ],\n            },\n            type: 'array',\n          },\n          exemptedBy: {\n            description: `Array of tags (e.g., \\`['type']\\`) whose presence on the\ndocument block avoids the need for a \\`@rejects\\`. Defaults to an array\nwith \\`abstract\\`, \\`virtual\\`, and \\`type\\`. If you set this array, it will overwrite the default,\nso be sure to add back those tags if you wish their presence to cause\nexemption of the rule.`,\n            items: {\n              type: 'string',\n            },\n            type: 'array',\n          },\n        },\n        type: 'object',\n      },\n    ],\n    type: 'suggestion',\n  },\n});\n"],"mappings":"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","ignoreList":[]}

package/dist/rules/requireRejects.d.ts

@@ -0,0 +1,3 @@
+declare const _default: import("eslint").Rule.RuleModule;
+export default _default;
+//# sourceMappingURL=requireRejects.d.ts.map

package/dist/rules.d.ts

@@ -2196,6 +2196,39 @@ export interface Rules {
   /** Requires that each `@property` tag has a type value (in curly brackets). */
   "jsdoc/require-property-type": [];
 
+  /** Requires that Promise rejections are documented with `@rejects` tags. */
+  "jsdoc/require-rejects": 
+    | []
+    | [
+        {
+          /**
+           * Set this to an array of strings representing the AST context
+           * (or objects with optional `context` and `comment` properties) where you wish
+           * the rule to be applied.
+           *
+           * `context` defaults to `any` and `comment` defaults to no specific comment context.
+           *
+           * Overrides the default contexts (`ArrowFunctionExpression`, `FunctionDeclaration`,
+           * `FunctionExpression`).
+           */
+          contexts?: (
+            | string
+            | {
+                comment?: string;
+                context?: string;
+              }
+          )[];
+          /**
+           * Array of tags (e.g., `['type']`) whose presence on the
+           * document block avoids the need for a `@rejects`. Defaults to an array
+           * with `abstract`, `virtual`, and `type`. If you set this array, it will overwrite the default,
+           * so be sure to add back those tags if you wish their presence to cause
+           * exemption of the rule.
+           */
+          exemptedBy?: string[];
+        }
+      ];
+
   /** Requires that returns are documented with `@returns`. */
   "jsdoc/require-returns": 
     | []

package/package.json

@@ -192,5 +192,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": "61.3.0"
+  "version": "61.4.1"
 }

package/src/alignTransform.js

@@ -9,6 +9,27 @@ import {
   util,
 } from 'comment-parser';
 
+/**
+ * Detects if a line starts with a markdown list marker
+ * Supports: -, *, numbered lists (1., 2., etc.)
+ * This explicitly excludes hyphens that are part of JSDoc tag syntax
+ * @param {string} text - The text to check
+ * @param {boolean} isFirstLineOfTag - True if this is the first line (tag line)
+ * @returns {boolean} - True if the text starts with a list marker
+ */
+const startsWithListMarker = (text, isFirstLineOfTag = false) => {
+  // On the first line of a tag, the hyphen is typically the JSDoc separator,
+  // not a list marker
+  if (isFirstLineOfTag) {
+    return false;
+  }
+
+  // Match lines that start with optional whitespace, then a list marker
+  // - or * followed by a space
+  // or a number followed by . or ) and a space
+  return /^\s*(?:[\-*]|\d+(?:\.|\)))\s+/v.test(text);
+};
+
 /**
  * @typedef {{
  *   hasNoTypes: boolean,
@@ -144,6 +165,59 @@ const space = (len) => {
   return ''.padStart(len, ' ');
 };
 
+/**
+ * Check if a tag or any of its lines contain list markers
+ * @param {import('./iterateJsdoc.js').Integer} index - Current line index
+ * @param {import('comment-parser').Line[]} source - All source lines
+ * @returns {{hasListMarker: boolean, tagStartIndex: import('./iterateJsdoc.js').Integer}}
+ */
+const checkForListMarkers = (index, source) => {
+  let hasListMarker = false;
+  let tagStartIndex = index;
+  while (tagStartIndex > 0 && source[tagStartIndex].tokens.tag === '') {
+    tagStartIndex--;
+  }
+
+  for (let idx = tagStartIndex; idx <= index; idx++) {
+    const isFirstLine = (idx === tagStartIndex);
+    if (source[idx]?.tokens?.description && startsWithListMarker(source[idx].tokens.description, isFirstLine)) {
+      hasListMarker = true;
+      break;
+    }
+  }
+
+  return {
+    hasListMarker,
+    tagStartIndex,
+  };
+};
+
+/**
+ * Calculate extra indentation for list items relative to the first continuation line
+ * @param {import('./iterateJsdoc.js').Integer} index - Current line index
+ * @param {import('./iterateJsdoc.js').Integer} tagStartIndex - Index of the tag line
+ * @param {import('comment-parser').Line[]} source - All source lines
+ * @returns {string} - Extra indentation spaces
+ */
+const calculateListExtraIndent = (index, tagStartIndex, source) => {
+  // Find the first continuation line to use as baseline
+  let firstContinuationIndent = null;
+  for (let idx = tagStartIndex + 1; idx < source.length; idx++) {
+    if (source[idx].tokens.description && !source[idx].tokens.tag) {
+      firstContinuationIndent = source[idx].tokens.postDelimiter.length;
+      break;
+    }
+  }
+
+  // Calculate the extra indentation of current line relative to the first continuation line
+  const currentOriginalIndent = source[index].tokens.postDelimiter.length;
+  const extraIndent = firstContinuationIndent !== null && currentOriginalIndent > firstContinuationIndent ?
+    ' '.repeat(currentOriginalIndent - firstContinuationIndent) :
+    '';
+
+  return extraIndent;
+};
+
 /**
  * @param {{
  *   customSpacings: import('../src/rules/checkLineAlignment.js').CustomSpacings,
@@ -316,8 +390,20 @@ const alignTransform = ({
     // Not align.
     if (shouldAlign(tags, index, source)) {
       alignTokens(tokens, typelessInfo);
+
       if (!disableWrapIndent && indentTag) {
-        tokens.postDelimiter += wrapIndent;
+        const {
+          hasListMarker,
+          tagStartIndex,
+        } = checkForListMarkers(index, source);
+
+        if (hasListMarker && index > tagStartIndex) {
+          const extraIndent = calculateListExtraIndent(index, tagStartIndex, source);
+          tokens.postDelimiter += wrapIndent + extraIndent;
+        } else {
+          // Normal case: add wrapIndent after the aligned delimiter
+          tokens.postDelimiter += wrapIndent;
+        }
       }
     }
 

package/src/index-cjs.js

@@ -54,6 +54,7 @@ import requireProperty from './rules/requireProperty.js';
 import requirePropertyDescription from './rules/requirePropertyDescription.js';
 import requirePropertyName from './rules/requirePropertyName.js';
 import requirePropertyType from './rules/requirePropertyType.js';
+import requireRejects from './rules/requireRejects.js';
 import requireReturns from './rules/requireReturns.js';
 import requireReturnsCheck from './rules/requireReturnsCheck.js';
 import requireReturnsDescription from './rules/requireReturnsDescription.js';
@@ -188,6 +189,7 @@ index.rules = {
   'require-property-description': requirePropertyDescription,
   'require-property-name': requirePropertyName,
   'require-property-type': requirePropertyType,
+  'require-rejects': requireRejects,
   'require-returns': requireReturns,
   'require-returns-check': requireReturnsCheck,
   'require-returns-description': requireReturnsDescription,
@@ -332,6 +334,7 @@ const createRecommendedRuleset = (warnOrError, flatName) => {
       'jsdoc/require-property-description': warnOrError,
       'jsdoc/require-property-name': warnOrError,
       'jsdoc/require-property-type': warnOrError,
+      'jsdoc/require-rejects': 'off',
       'jsdoc/require-returns': warnOrError,
       'jsdoc/require-returns-check': warnOrError,
       'jsdoc/require-returns-description': warnOrError,

package/src/index-esm.js

@@ -177,6 +177,11 @@ export const jsdoc = function (cfg) {
                   'type',
                 ],
               },
+              rejects: {
+                required: [
+                  'type',
+                ],
+              },
             },
           } :
           {},

package/src/index.js

@@ -60,6 +60,7 @@ import requireProperty from './rules/requireProperty.js';
 import requirePropertyDescription from './rules/requirePropertyDescription.js';
 import requirePropertyName from './rules/requirePropertyName.js';
 import requirePropertyType from './rules/requirePropertyType.js';
+import requireRejects from './rules/requireRejects.js';
 import requireReturns from './rules/requireReturns.js';
 import requireReturnsCheck from './rules/requireReturnsCheck.js';
 import requireReturnsDescription from './rules/requireReturnsDescription.js';
@@ -194,6 +195,7 @@ index.rules = {
   'require-property-description': requirePropertyDescription,
   'require-property-name': requirePropertyName,
   'require-property-type': requirePropertyType,
+  'require-rejects': requireRejects,
   'require-returns': requireReturns,
   'require-returns-check': requireReturnsCheck,
   'require-returns-description': requireReturnsDescription,
@@ -338,6 +340,7 @@ const createRecommendedRuleset = (warnOrError, flatName) => {
       'jsdoc/require-property-description': warnOrError,
       'jsdoc/require-property-name': warnOrError,
       'jsdoc/require-property-type': warnOrError,
+      'jsdoc/require-rejects': 'off',
       'jsdoc/require-returns': warnOrError,
       'jsdoc/require-returns-check': warnOrError,
       'jsdoc/require-returns-description': warnOrError,
@@ -883,6 +886,11 @@ export const jsdoc = function (cfg) {
                   'type',
                 ],
               },
+              rejects: {
+                required: [
+                  'type',
+                ],
+              },
             },
           } :
           {},