eslint-plugin-jsdoc 61.5.0 → 62.0.0

package/package.json

@@ -5,14 +5,14 @@
     "url": "http://gajus.com"
   },
   "dependencies": {
-    "@es-joy/jsdoccomment": "~0.76.0",
+    "@es-joy/jsdoccomment": "~0.79.0",
     "@es-joy/resolve.exports": "1.2.0",
     "are-docs-informative": "^0.0.2",
     "comment-parser": "1.4.1",
     "debug": "^4.4.3",
     "escape-string-regexp": "^4.0.0",
-    "espree": "^10.4.0",
-    "esquery": "^1.6.0",
+    "espree": "^11.0.0",
+    "esquery": "^1.7.0",
     "html-entities": "^2.6.0",
     "object-deep-merge": "^2.0.0",
     "parse-imports-exports": "^0.2.4",
@@ -30,13 +30,13 @@
     "@babel/plugin-transform-flow-strip-types": "^7.27.1",
     "@babel/preset-env": "^7.28.5",
     "@es-joy/escodegen": "^4.2.0",
-    "@es-joy/jsdoc-eslint-parser": "^0.25.0",
-    "@eslint/core": "^0.17.0",
+    "@es-joy/jsdoc-eslint-parser": "^0.27.0",
+    "@eslint/core": "^1.0.0",
     "@hkdobrev/run-if-changed": "^0.6.3",
     "@rollup/plugin-node-resolve": "^16.0.3",
     "@semantic-release/commit-analyzer": "^13.0.1",
-    "@semantic-release/github": "^12.0.1",
-    "@semantic-release/npm": "^13.1.1",
+    "@semantic-release/github": "^12.0.2",
+    "@semantic-release/npm": "^13.1.3",
     "@types/chai": "^5.2.3",
     "@types/debug": "^4.1.12",
     "@types/espree": "^10.1.0",
@@ -44,41 +44,41 @@
     "@types/estree": "^1.0.8",
     "@types/json-schema": "^7.0.15",
     "@types/mocha": "^10.0.10",
-    "@types/node": "^24.10.0",
+    "@types/node": "^25.0.3",
     "@types/semver": "^7.7.1",
     "@types/spdx-expression-parse": "^3.0.5",
-    "@typescript-eslint/types": "^8.46.2",
+    "@typescript-eslint/types": "^8.52.0",
     "babel-plugin-add-module-exports": "^1.0.4",
     "babel-plugin-istanbul": "^7.0.1",
     "babel-plugin-transform-import-meta": "^2.3.3",
     "c8": "^10.1.3",
-    "camelcase": "^8.0.0",
-    "chai": "^6.2.0",
+    "camelcase": "^9.0.0",
+    "chai": "^6.2.2",
     "decamelize": "^6.0.1",
-    "eslint": "9.39.0",
-    "eslint-config-canonical": "^45.0.1",
+    "eslint": "9.39.2",
+    "eslint-config-canonical": "^47.3.7",
     "gitdown": "^4.1.1",
-    "glob": "^11.0.3",
-    "globals": "^16.5.0",
+    "glob": "^13.0.0",
+    "globals": "^17.0.0",
     "husky": "^9.1.7",
-    "jsdoc-type-pratt-parser": "^6.11.0",
+    "jsdoc-type-pratt-parser": "^7.0.0",
     "json-schema": "^0.4.0",
     "json-schema-to-typescript": "^15.0.4",
-    "lint-staged": "^16.2.6",
-    "mocha": "^11.7.4",
-    "open-editor": "^5.1.0",
-    "playwright": "^1.56.1",
+    "lint-staged": "^16.2.7",
+    "mocha": "^11.7.5",
+    "open-editor": "^6.0.0",
+    "playwright": "^1.57.0",
     "replace": "^1.2.2",
-    "rimraf": "^6.1.0",
-    "rollup": "^4.52.5",
-    "semantic-release": "^25.0.1",
-    "sinon": "^21.0.0",
-    "ts-api-utils": "^2.1.0",
+    "rimraf": "^6.1.2",
+    "rollup": "^4.55.1",
+    "semantic-release": "^25.0.2",
+    "sinon": "^21.0.1",
+    "ts-api-utils": "^2.4.0",
     "typescript": "5.9.3",
-    "typescript-eslint": "^8.46.2"
+    "typescript-eslint": "^8.52.0"
   },
   "engines": {
-    "node": ">=20.11.0"
+    "node": "^20.19.0 || ^22.13.0 || >=24"
   },
   "keywords": [
     "eslint",
@@ -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.5.0"
+  "version": "62.0.0"
 }

package/src/iterateJsdoc.js

@@ -1681,7 +1681,6 @@ const getUtils = (
 
   /** @type {GetClassNode} */
   utils.getClassNode = () => {
-    // eslint-disable-next-line canonical/no-use-extend-native -- Not extending
     return [
       ...ancestors, node,
     ].toReversed().find((parent) => {
@@ -1803,6 +1802,7 @@ const getUtils = (
  *   ignoreInternal?: boolean,
  *   ignorePrivate?: boolean,
  *   exemptDestructuredRootsFromChecks?: boolean,
+ *   skipInvokedExpressionsForCommentFinding?: boolean
  * }} Settings
  */
 
@@ -1822,6 +1822,7 @@ const getUtils = (
  *       implementsReplacesDocs: boolean,
  *       augmentsExtendsReplacesDocs: boolean,
  *       exemptDestructuredRootsFromChecks: boolean,
+ *       skipInvokedExpressionsForCommentFinding: boolean,
  *       mode: import('./jsdocUtils.js').ParserMode,
  *       contexts: Context[],
  *     }
@@ -1841,6 +1842,8 @@ const getSettings = (context) => {
     ignoreInternal: Boolean(context.settings.jsdoc?.ignoreInternal),
     maxLines: Number(context.settings.jsdoc?.maxLines ?? 1),
     minLines: Number(context.settings.jsdoc?.minLines ?? 0),
+    skipInvokedExpressionsForCommentFinding:
+      Boolean(context.settings.jsdoc?.skipInvokedExpressionsForCommentFinding),
 
     // `check-tag-names` and many returns/param rules
     tagNamePreference: context.settings.jsdoc?.tagNamePreference ?? {},

package/src/rules/checkPropertyNames.js

@@ -12,34 +12,50 @@ const validatePropertyNames = (
   enableFixer,
   jsdoc, utils,
 ) => {
-  const propertyTags = Object.entries(jsdoc.tags).filter(([
-    , tag,
-  ]) => {
-    return tag.tag === targetTagName;
-  });
+  const jsdocTypedefs = utils.getJsdocTagsDeep('typedef');
+  let propertyTagGroups;
+  if (jsdocTypedefs && jsdocTypedefs.length > 1) {
+    propertyTagGroups = jsdocTypedefs.map(({
+      idx,
+    }, index) => {
+      return Object.entries(jsdoc.tags).slice(idx, jsdocTypedefs[index + 1]?.idx);
+    });
+  } else {
+    propertyTagGroups = [
+      Object.entries(jsdoc.tags),
+    ];
+  }
 
-  return propertyTags.some(([
-    , tag,
-  ], index) => {
-    /** @type {import('../iterateJsdoc.js').Integer} */
-    let tagsIndex;
-    const dupeTagInfo = propertyTags.find(([
-      tgsIndex,
-      tg,
-    ], idx) => {
-      tagsIndex = Number(tgsIndex);
-
-      return tg.name === tag.name && idx !== index;
+  return propertyTagGroups.some((propertyTagGroup) => {
+    const propertyTags = propertyTagGroup.filter(([
+      , tag,
+    ]) => {
+      return tag.tag === targetTagName;
     });
-    if (dupeTagInfo) {
-      utils.reportJSDoc(`Duplicate @${targetTagName} "${tag.name}"`, dupeTagInfo[1], enableFixer ? () => {
-        utils.removeTag(tagsIndex);
-      } : null);
 
-      return true;
-    }
+    return propertyTags.some(([
+      , tag,
+    ], index) => {
+      /** @type {import('../iterateJsdoc.js').Integer} */
+      let tagsIndex;
+      const dupeTagInfo = propertyTags.find(([
+        tgsIndex,
+        tg,
+      ], idx) => {
+        tagsIndex = Number(tgsIndex);
+
+        return tg.name === tag.name && idx !== index;
+      });
+      if (dupeTagInfo) {
+        utils.reportJSDoc(`Duplicate @${targetTagName} "${tag.name}"`, dupeTagInfo[1], enableFixer ? () => {
+          utils.removeTag(tagsIndex);
+        } : null);
 
-    return false;
+        return true;
+      }
+
+      return false;
+    });
   });
 };
 

package/src/rules/convertToJsdocComments.js

@@ -111,7 +111,6 @@ export default {
 
         const decorator = getDecorator(
           /** @type {import('eslint').Rule.Node} */
-          // @ts-expect-error Bug?
           (baseNode),
         );
         if (decorator) {
@@ -204,7 +203,6 @@ export default {
       reportingNonJsdoc = true;
 
       /** @type {AddComment} */
-      // eslint-disable-next-line unicorn/consistent-function-scoping -- Avoid conflicts
       const addComment = (inlineCommentBlock, commentToAdd, indent, lines, fixer) => {
         const insertion = (
           inlineCommentBlock || enforceJsdocLineStyle === 'single' ?

package/src/rules/requireJsdoc.js

@@ -36,6 +36,13 @@ const OPTIONS_SCHEMA = {
   additionalProperties: false,
   description: 'Has the following optional keys.\n',
   properties: {
+    checkAllFunctionExpressions: {
+      default: false,
+      description: `Normally, when \`FunctionExpression\` is checked, additional checks are
+added to check the parent contexts where reporting is likely to be desired. If you really
+want to check *all* function expressions, then set this to \`true\`.`,
+      type: 'boolean',
+    },
     checkConstructors: {
       default: true,
       description: `A value indicating whether \`constructor\`s should be checked. Defaults to
@@ -378,6 +385,7 @@ const getOption = (context, baseObject, option, key) => {
  * @param {import('eslint').Rule.RuleContext} context
  * @param {import('../iterateJsdoc.js').Settings} settings
  * @returns {{
+ *   checkAllFunctionExpressions: boolean,
  *   contexts: (string|{
  *     context: string,
  *     inlineCommentBlock: boolean,
@@ -396,6 +404,7 @@ const getOption = (context, baseObject, option, key) => {
  */
 const getOptions = (context, settings) => {
   const {
+    checkAllFunctionExpressions = false,
     contexts = settings.contexts || [],
     enableFixer = true,
     exemptEmptyConstructors = true,
@@ -408,6 +417,7 @@ const getOptions = (context, settings) => {
   } = context.options[0] || {};
 
   return {
+    checkAllFunctionExpressions,
     contexts,
     enableFixer,
     exemptEmptyConstructors,
@@ -503,7 +513,7 @@ const isFunctionWithOverload = (node) => {
     return false;
   }
 
-  const functionName = node.id.name;
+  const functionName = node.id?.name;
 
   const idx = parent.body.indexOf(child);
   const prevSibling = parent.body[idx - 1];
@@ -536,6 +546,7 @@ export default {
     const opts = getOptions(context, settings);
 
     const {
+      checkAllFunctionExpressions,
       contexts,
       enableFixer,
       exemptEmptyConstructors,
@@ -670,7 +681,6 @@ export default {
 
         const decorator = getDecorator(
           /** @type {import('eslint').Rule.Node} */
-          // @ts-expect-error Bug?
           (baseNode),
         );
         if (decorator) {
@@ -831,7 +841,7 @@ export default {
           return;
         }
 
-        if (
+        if (checkAllFunctionExpressions ||
           [
             'AssignmentExpression', 'ExportDefaultDeclaration', 'VariableDeclarator',
           ].includes(node.parent.type) ||

package/src/rules.d.ts

@@ -1639,6 +1639,12 @@ export interface Rules {
     | []
     | [
         {
+          /**
+           * Normally, when `FunctionExpression` is checked, additional checks are
+           * added to check the parent contexts where reporting is likely to be desired. If you really
+           * want to check *all* function expressions, then set this to `true`.
+           */
+          checkAllFunctionExpressions?: boolean;
           /**
            * A value indicating whether `constructor`s should be checked. Defaults to
            * `true`. When `true`, `exemptEmptyConstructors` may still avoid reporting when