eslint-plugin-jsdoc 61.2.1 → 61.4.0

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

@@ -47,6 +47,10 @@ export interface Rules {
     | []
     | [
         {
+          /**
+           * Allows indentation of nested sections on subsequent lines (like bullet lists)
+           */
+          allowIndentedSections?: boolean;
           /**
            * Array of tags (e.g., `['example', 'description']`) whose content will be
            * "hidden" from the `check-indentation` rule. Defaults to `['example']`.
@@ -2192,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": 
     | []