eslint-plugin-jsdoc 61.3.0 → 61.4.1

package/src/rules/checkLineAlignment.js

@@ -8,6 +8,54 @@ const {
   flow: commentFlow,
 } = transforms;
 
+/**
+ * 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);
+};
+
+/**
+ * Checks if we should allow extra indentation beyond wrapIndent.
+ * This is true for list continuation lines (lines with more indent than wrapIndent
+ * that follow a list item).
+ * @param {import('comment-parser').Spec} tag - The tag being checked
+ * @param {import('../iterateJsdoc.js').Integer} idx - Current line index (0-based in tag.source.slice(1))
+ * @returns {boolean} - True if extra indentation should be allowed
+ */
+const shouldAllowExtraIndent = (tag, idx) => {
+  // Check if any previous line in this tag had a list marker
+  // idx is 0-based in the continuation lines (tag.source.slice(1))
+  // So tag.source[0] is the tag line, tag.source[idx+1] is current line
+  let hasSeenListMarker = false;
+
+  // Check all lines from the tag line onwards
+  for (let lineIdx = 0; lineIdx <= idx + 1; lineIdx++) {
+    const line = tag.source[lineIdx];
+    const isFirstLine = lineIdx === 0;
+    if (line?.tokens?.description && startsWithListMarker(line.tokens.description, isFirstLine)) {
+      hasSeenListMarker = true;
+      break;
+    }
+  }
+
+  return hasSeenListMarker;
+};
+
 /**
  * @typedef {{
  *   postDelimiter: import('../iterateJsdoc.js').Integer,
@@ -298,7 +346,17 @@ export default iterateJsdoc(({
         }
 
         // Don't include a single separating space/tab
-        if (!disableWrapIndent && tokens.postDelimiter.slice(1) !== wrapIndent) {
+        const actualIndent = tokens.postDelimiter.slice(1);
+        const hasCorrectWrapIndent = actualIndent === wrapIndent;
+
+        // Allow extra indentation if this line or previous lines contain list markers
+        // This preserves nested list structure
+        const hasExtraIndent = actualIndent.length > wrapIndent.length &&
+                                actualIndent.startsWith(wrapIndent);
+        const isInListContext = shouldAllowExtraIndent(tag, idx - 1);
+
+        if (!disableWrapIndent && !hasCorrectWrapIndent &&
+            !(hasExtraIndent && isInListContext)) {
           utils.reportJSDoc('Expected wrap indent', {
             line: tag.source[0].number + idx,
           }, () => {

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,246 @@
+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]
+ * @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();
+};
+
+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": 
     | []