eslint-plugin-jsdoc 61.3.0 → 61.4.0

package/dist/rules/requireRejects.cjs

@@ -0,0 +1,221 @@
+"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]
+ * @returns {boolean}
+ */
+// eslint-disable-next-line complexity -- Temporary
+const hasRejectValue = (node, innerFunction) => {
+  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 the inner function's body for throw statements
+          return hasRejectValue(/** @type {import('eslint').Rule.Node} */node.body, false);
+        }
+        return hasRejectValue(/** @type {import('eslint').Rule.Node} */node.body, true);
+      }
+    case 'BlockStatement':
+      {
+        return node.body.some(bodyNode => {
+          return hasRejectValue(/** @type {import('eslint').Rule.Node} */bodyNode, innerFunction);
+        });
+      }
+    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);
+      }
+    case 'ExpressionStatement':
+      {
+        return hasRejectValue(/** @type {import('eslint').Rule.Node} */node.expression, innerFunction);
+      }
+    case 'IfStatement':
+      {
+        return hasRejectValue(/** @type {import('eslint').Rule.Node} */node.consequent, innerFunction) || hasRejectValue(/** @type {import('eslint').Rule.Node} */node.alternate, innerFunction);
+      }
+    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);
+          }
+        }
+        return false;
+      }
+    case 'ReturnStatement':
+      {
+        if (node.argument) {
+          return hasRejectValue(/** @type {import('eslint').Rule.Node} */node.argument, innerFunction);
+        }
+        return false;
+      }
+    case 'SwitchStatement':
+      {
+        return node.cases.some(someCase => {
+          return someCase.consequent.some(nde => {
+            return hasRejectValue(/** @type {import('eslint').Rule.Node} */nde, innerFunction);
+          });
+        });
+      }
+
+    // Throw statements in async functions become rejections
+    case 'ThrowStatement':
+      {
+        return true;
+      }
+    case 'TryStatement':
+      {
+        return hasRejectValue(/** @type {import('eslint').Rule.Node} */node.handler && node.handler.body, innerFunction) || hasRejectValue(/** @type {import('eslint').Rule.Node} */node.finalizer, innerFunction);
+      }
+    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","type","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","isAsync","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 * @returns {boolean}\n */\n// eslint-disable-next-line complexity -- Temporary\nconst hasRejectValue = (node, innerFunction) => {\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 the inner function's body for throw statements\n        return hasRejectValue(/** @type {import('eslint').Rule.Node} */ (node.body), false);\n      }\n\n      return hasRejectValue(/** @type {import('eslint').Rule.Node} */ (node.body), true);\n    }\n\n    case 'BlockStatement': {\n      return node.body.some((bodyNode) => {\n        return hasRejectValue(/** @type {import('eslint').Rule.Node} */ (bodyNode), innerFunction);\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);\n    }\n\n    case 'ExpressionStatement': {\n      return hasRejectValue(/** @type {import('eslint').Rule.Node} */ (node.expression), innerFunction);\n    }\n\n    case 'IfStatement': {\n      return hasRejectValue(/** @type {import('eslint').Rule.Node} */ (node.consequent), innerFunction) || hasRejectValue(/** @type {import('eslint').Rule.Node} */ (node.alternate), innerFunction);\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);\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);\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);\n          });\n        },\n      );\n    }\n\n    // Throw statements in async functions become rejections\n    case 'ThrowStatement': {\n      return true;\n    }\n\n    case 'TryStatement': {\n      return hasRejectValue(/** @type {import('eslint').Rule.Node} */ (node.handler && node.handler.body), innerFunction) ||\n        hasRejectValue(/** @type {import('eslint').Rule.Node} */ (node.finalizer), innerFunction);\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.0"
 }

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',
+                ],
+              },
             },
           } :
           {},

package/src/rules/checkTagNames.js

@@ -124,7 +124,8 @@ export default iterateJsdoc(({
    */
   const isInAmbientContext = (subNode) => {
     return subNode.type === 'Program' ?
-      context.getFilename().endsWith('.d.ts') :
+      /* c8 ignore next -- Support old ESLint */
+      (context.filename ?? context.getFilename()).endsWith('.d.ts') :
       Boolean(
         /** @type {import('@typescript-eslint/types').TSESTree.VariableDeclaration} */ (
           subNode
@@ -149,7 +150,8 @@ export default iterateJsdoc(({
       return false;
     }
 
-    if (context.getFilename().endsWith('.d.ts') && [
+    /* c8 ignore next -- Support old ESLint */
+    if ((context.filename ?? context.getFilename()).endsWith('.d.ts') && [
       null, 'Program', undefined,
     ].includes(node?.parent?.type)) {
       return false;

package/src/rules/requireRejects.js

@@ -0,0 +1,242 @@
+import iterateJsdoc from '../iterateJsdoc.js';
+
+/**
+ * Checks if a node or its children contain Promise rejection patterns
+ * @param {import('eslint').Rule.Node} node
+ * @param {boolean} [innerFunction]
+ * @returns {boolean}
+ */
+// eslint-disable-next-line complexity -- Temporary
+const hasRejectValue = (node, innerFunction) => {
+  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 the inner function's body for throw statements
+        return hasRejectValue(/** @type {import('eslint').Rule.Node} */ (node.body), false);
+      }
+
+      return hasRejectValue(/** @type {import('eslint').Rule.Node} */ (node.body), true);
+    }
+
+    case 'BlockStatement': {
+      return node.body.some((bodyNode) => {
+        return hasRejectValue(/** @type {import('eslint').Rule.Node} */ (bodyNode), innerFunction);
+      });
+    }
+
+    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);
+    }
+
+    case 'ExpressionStatement': {
+      return hasRejectValue(/** @type {import('eslint').Rule.Node} */ (node.expression), innerFunction);
+    }
+
+    case 'IfStatement': {
+      return hasRejectValue(/** @type {import('eslint').Rule.Node} */ (node.consequent), innerFunction) || hasRejectValue(/** @type {import('eslint').Rule.Node} */ (node.alternate), innerFunction);
+    }
+
+    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);
+        }
+      }
+
+      return false;
+    }
+
+    case 'ReturnStatement': {
+      if (node.argument) {
+        return hasRejectValue(/** @type {import('eslint').Rule.Node} */ (node.argument), innerFunction);
+      }
+
+      return false;
+    }
+
+    case 'SwitchStatement': {
+      return node.cases.some(
+        (someCase) => {
+          return someCase.consequent.some((nde) => {
+            return hasRejectValue(/** @type {import('eslint').Rule.Node} */ (nde), innerFunction);
+          });
+        },
+      );
+    }
+
+    // Throw statements in async functions become rejections
+    case 'ThrowStatement': {
+      return true;
+    }
+
+    case 'TryStatement': {
+      return hasRejectValue(/** @type {import('eslint').Rule.Node} */ (node.handler && node.handler.body), innerFunction) ||
+        hasRejectValue(/** @type {import('eslint').Rule.Node} */ (node.finalizer), innerFunction);
+    }
+
+    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();
+};
+
+export default iterateJsdoc(({
+  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',
+  },
+});

package/src/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": 
     | []