@depup/eslint-plugin-jsdoc 62.8.0-depup.0

package/src/rules/requireParamDescription.js

@@ -0,0 +1,110 @@
+import iterateJsdoc from '../iterateJsdoc.js';
+
+export default iterateJsdoc(({
+  context,
+  report,
+  settings,
+  utils,
+}) => {
+  const {
+    defaultDestructuredRootDescription = 'The root object',
+    setDefaultDestructuredRootDescription = false,
+  } = context.options[0] || {};
+
+  const functionParameterNames = utils.getFunctionParameterNames();
+
+  let rootCount = -1;
+  utils.forEachPreferredTag('param', (jsdocParameter, targetTagName) => {
+    rootCount += jsdocParameter.name.includes('.') ? 0 : 1;
+    if (!jsdocParameter.description.trim()) {
+      if (Array.isArray(functionParameterNames[rootCount])) {
+        if (settings.exemptDestructuredRootsFromChecks) {
+          return;
+        }
+
+        if (setDefaultDestructuredRootDescription) {
+          utils.reportJSDoc(`Missing root description for @${targetTagName}.`, jsdocParameter, () => {
+            utils.changeTag(jsdocParameter, {
+              description: defaultDestructuredRootDescription,
+              postName: ' ',
+            });
+          });
+          return;
+        }
+      }
+
+      report(
+        `Missing JSDoc @${targetTagName} "${jsdocParameter.name}" description.`,
+        null,
+        jsdocParameter,
+      );
+    }
+  });
+}, {
+  contextDefaults: true,
+  meta: {
+    docs: {
+      description: 'Requires that each `@param` tag has a `description` value.',
+      url: 'https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/require-param-description.md#repos-sticky-header',
+    },
+    fixable: 'code',
+    schema: [
+      {
+        additionalProperties: false,
+        properties: {
+          contexts: {
+            description: `Set this to an array of strings representing the AST context (or an object 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\`). Set to \`"any"\` if you want
+the rule to apply to any JSDoc block throughout your files (as is necessary
+for finding function blocks not attached to a function declaration or
+expression, i.e., \`@callback\` or \`@function\` (or its aliases \`@func\` or
+\`@method\`) (including those associated with an \`@interface\`).
+
+See the ["AST and Selectors"](../#advanced-ast-and-selectors)
+section of our Advanced docs for more on the expected format.`,
+            items: {
+              anyOf: [
+                {
+                  type: 'string',
+                },
+                {
+                  additionalProperties: false,
+                  properties: {
+                    comment: {
+                      type: 'string',
+                    },
+                    context: {
+                      type: 'string',
+                    },
+                  },
+                  type: 'object',
+                },
+              ],
+            },
+            type: 'array',
+          },
+          defaultDestructuredRootDescription: {
+            description: `The description string to set by default for destructured roots. Defaults to
+"The root object".`,
+            type: 'string',
+          },
+          setDefaultDestructuredRootDescription: {
+            description: `Whether to set a default destructured root description. For example, you may
+wish to avoid manually having to set the description for a \`@param\`
+corresponding to a destructured root object as it should always be the same
+type of object. Uses \`defaultDestructuredRootDescription\` for the description
+string. Defaults to \`false\`.`,
+            type: 'boolean',
+          },
+        },
+        type: 'object',
+      },
+    ],
+    type: 'suggestion',
+  },
+});

package/src/rules/requireParamName.js

@@ -0,0 +1,69 @@
+import iterateJsdoc from '../iterateJsdoc.js';
+
+export default iterateJsdoc(({
+  report,
+  utils,
+}) => {
+  utils.forEachPreferredTag('param', (jsdocParameter, targetTagName) => {
+    if (jsdocParameter.tag && jsdocParameter.name === '') {
+      report(
+        `There must be an identifier after @${targetTagName} ${jsdocParameter.type === '' ? 'type' : 'tag'}.`,
+        null,
+        jsdocParameter,
+      );
+    }
+  });
+}, {
+  contextDefaults: true,
+  meta: {
+    docs: {
+      description: 'Requires that all `@param` tags have names.',
+      url: 'https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/require-param-name.md#repos-sticky-header',
+    },
+    schema: [
+      {
+        additionalProperties: false,
+        properties: {
+          contexts: {
+            description: `Set this to an array of strings representing the AST context (or an object 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\`). Set to \`"any"\` if you want
+the rule to apply to any JSDoc block throughout your files (as is necessary
+for finding function blocks not attached to a function declaration or
+expression, i.e., \`@callback\` or \`@function\` (or its aliases \`@func\` or
+\`@method\`) (including those associated with an \`@interface\`).
+
+See the ["AST and Selectors"](../#advanced-ast-and-selectors)
+section of our Advanced docs for more on the expected format.`,
+            items: {
+              anyOf: [
+                {
+                  type: 'string',
+                },
+                {
+                  additionalProperties: false,
+                  properties: {
+                    comment: {
+                      type: 'string',
+                    },
+                    context: {
+                      type: 'string',
+                    },
+                  },
+                  type: 'object',
+                },
+              ],
+            },
+            type: 'array',
+          },
+        },
+        type: 'object',
+      },
+    ],
+    type: 'suggestion',
+  },
+});

package/src/rules/requireParamType.js

@@ -0,0 +1,109 @@
+import iterateJsdoc from '../iterateJsdoc.js';
+
+export default iterateJsdoc(({
+  context,
+  report,
+  settings,
+  utils,
+}) => {
+  const {
+    defaultDestructuredRootType = 'object',
+    setDefaultDestructuredRootType = false,
+  } = context.options[0] || {};
+
+  const functionParameterNames = utils.getFunctionParameterNames();
+
+  let rootCount = -1;
+  utils.forEachPreferredTag('param', (jsdocParameter, targetTagName) => {
+    rootCount += jsdocParameter.name.includes('.') ? 0 : 1;
+    if (!jsdocParameter.type) {
+      if (Array.isArray(functionParameterNames[rootCount])) {
+        if (settings.exemptDestructuredRootsFromChecks) {
+          return;
+        }
+
+        if (setDefaultDestructuredRootType) {
+          utils.reportJSDoc(`Missing root type for @${targetTagName}.`, jsdocParameter, () => {
+            utils.changeTag(jsdocParameter, {
+              postType: ' ',
+              type: `{${defaultDestructuredRootType}}`,
+            });
+          });
+          return;
+        }
+      }
+
+      report(
+        `Missing JSDoc @${targetTagName} "${jsdocParameter.name}" type.`,
+        null,
+        jsdocParameter,
+      );
+    }
+  });
+}, {
+  contextDefaults: true,
+  meta: {
+    docs: {
+      description: 'Requires that each `@param` tag has a type value (in curly brackets).',
+      url: 'https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/require-param-type.md#repos-sticky-header',
+    },
+    fixable: 'code',
+    schema: [
+      {
+        additionalProperties: false,
+        properties: {
+          contexts: {
+            description: `Set this to an array of strings representing the AST context (or an object 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\`). Set to \`"any"\` if you want
+the rule to apply to any JSDoc block throughout your files (as is necessary
+for finding function blocks not attached to a function declaration or
+expression, i.e., \`@callback\` or \`@function\` (or its aliases \`@func\` or
+\`@method\`) (including those associated with an \`@interface\`).
+
+See the ["AST and Selectors"](../#advanced-ast-and-selectors)
+section of our Advanced docs for more on the expected format.`,
+            items: {
+              anyOf: [
+                {
+                  type: 'string',
+                },
+                {
+                  additionalProperties: false,
+                  properties: {
+                    comment: {
+                      type: 'string',
+                    },
+                    context: {
+                      type: 'string',
+                    },
+                  },
+                  type: 'object',
+                },
+              ],
+            },
+            type: 'array',
+          },
+          defaultDestructuredRootType: {
+            description: 'The type string to set by default for destructured roots. Defaults to "object".',
+            type: 'string',
+          },
+          setDefaultDestructuredRootType: {
+            description: `Whether to set a default destructured root type. For example, you may wish
+to avoid manually having to set the type for a \`@param\`
+corresponding to a destructured root object as it is always going to be an
+object. Uses \`defaultDestructuredRootType\` for the type string. Defaults to
+\`false\`.`,
+            type: 'boolean',
+          },
+        },
+        type: 'object',
+      },
+    ],
+    type: 'suggestion',
+  },
+});

package/src/rules/requireProperty.js

@@ -0,0 +1,66 @@
+import iterateJsdoc from '../iterateJsdoc.js';
+
+export default iterateJsdoc(({
+  context,
+  utils,
+}) => {
+  const propertyAssociatedTags = utils.filterTags(({
+    tag,
+  }) => {
+    return [
+      'namespace', 'typedef',
+    ].includes(tag);
+  });
+  if (!propertyAssociatedTags.length) {
+    return;
+  }
+
+  const targetTagName = /** @type {string} */ (utils.getPreferredTagName({
+    tagName: 'property',
+  }));
+
+  if (!targetTagName) {
+    context.report({
+      loc: {
+        end: {
+          column: 1,
+          line: 1,
+        },
+        start: {
+          column: 1,
+          line: 1,
+        },
+      },
+      message: 'Cannot prohibit `@property` in the `tagNamePreference` setting while using the `require-property` rule.',
+    });
+    return;
+  }
+
+  if (utils.hasATag([
+    targetTagName,
+  ])) {
+    return;
+  }
+
+  for (const propertyAssociatedTag of propertyAssociatedTags) {
+    if (![
+      'object', 'Object', 'PlainObject',
+    ].includes(propertyAssociatedTag.type)) {
+      continue;
+    }
+
+    utils.reportJSDoc(`Missing JSDoc @${targetTagName}.`, null, () => {
+      utils.addTag(targetTagName);
+    });
+  }
+}, {
+  iterateAllJsdocs: true,
+  meta: {
+    docs: {
+      description: 'Requires that all `@typedef` and `@namespace` tags have `@property` when their type is a plain `object`, `Object`, or `PlainObject`.',
+      url: 'https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/require-property.md#repos-sticky-header',
+    },
+    fixable: 'code',
+    type: 'suggestion',
+  },
+});

package/src/rules/requirePropertyDescription.js

@@ -0,0 +1,25 @@
+import iterateJsdoc from '../iterateJsdoc.js';
+
+export default iterateJsdoc(({
+  report,
+  utils,
+}) => {
+  utils.forEachPreferredTag('property', (jsdoc, targetTagName) => {
+    if (!jsdoc.description.trim()) {
+      report(
+        `Missing JSDoc @${targetTagName} "${jsdoc.name}" description.`,
+        null,
+        jsdoc,
+      );
+    }
+  });
+}, {
+  iterateAllJsdocs: true,
+  meta: {
+    docs: {
+      description: 'Requires that each `@property` tag has a `description` value.',
+      url: 'https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/require-property-description.md#repos-sticky-header',
+    },
+    type: 'suggestion',
+  },
+});

package/src/rules/requirePropertyName.js

@@ -0,0 +1,25 @@
+import iterateJsdoc from '../iterateJsdoc.js';
+
+export default iterateJsdoc(({
+  report,
+  utils,
+}) => {
+  utils.forEachPreferredTag('property', (jsdoc, targetTagName) => {
+    if (jsdoc.tag && jsdoc.name === '') {
+      report(
+        `There must be an identifier after @${targetTagName} ${jsdoc.type === '' ? 'type' : 'tag'}.`,
+        null,
+        jsdoc,
+      );
+    }
+  });
+}, {
+  iterateAllJsdocs: true,
+  meta: {
+    docs: {
+      description: 'Requires that all `@property` tags have names.',
+      url: 'https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/require-property-name.md#repos-sticky-header',
+    },
+    type: 'suggestion',
+  },
+});

package/src/rules/requirePropertyType.js

@@ -0,0 +1,25 @@
+import iterateJsdoc from '../iterateJsdoc.js';
+
+export default iterateJsdoc(({
+  report,
+  utils,
+}) => {
+  utils.forEachPreferredTag('property', (jsdoc, targetTagName) => {
+    if (!jsdoc.type) {
+      report(
+        `Missing JSDoc @${targetTagName} "${jsdoc.name}" type.`,
+        null,
+        jsdoc,
+      );
+    }
+  });
+}, {
+  iterateAllJsdocs: true,
+  meta: {
+    docs: {
+      description: 'Requires that each `@property` tag has a type value (in curly brackets).',
+      url: 'https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/require-property-type.md#repos-sticky-header',
+    },
+    type: 'suggestion',
+  },
+});

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 `@rejects` 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',
+  },
+});