@depup/eslint-plugin-jsdoc 64.3.2-depup.0 → 64.3.3-depup.0

package/README.md

@@ -13,16 +13,17 @@ npm install @depup/eslint-plugin-jsdoc
 
 | Field | Value |
 |-------|-------|
-| Original | [eslint-plugin-jsdoc](https://www.npmjs.com/package/eslint-plugin-jsdoc) @ 64.3.2 |
-| Processed | 2026-08-31 |
+| Original | [eslint-plugin-jsdoc](https://www.npmjs.com/package/eslint-plugin-jsdoc) @ 64.3.3 |
+| Processed | 2026-09-01 |
 | Smoke test | passed |
-| Deps updated | 1 |
+| Deps updated | 2 |
 
 ## Dependency Changes
 
 | Dependency | From | To |
 |------------|------|-----|
 | @es-joy/jsdoccomment | ~0.95.1 | ^0.96.0 |
+| @typescript-eslint/utils | ^8.68.0 | ^8.69.0 |
 
 ---
 

package/changes.json

@@ -3,8 +3,12 @@
     "@es-joy/jsdoccomment": {
       "from": "~0.95.1",
       "to": "^0.96.0"
+    },
+    "@typescript-eslint/utils": {
+      "from": "^8.68.0",
+      "to": "^8.69.0"
     }
   },
-  "timestamp": "2026-08-31T00:36:03.183Z",
-  "totalUpdated": 1
+  "timestamp": "2026-09-01T00:40:40.623Z",
+  "totalUpdated": 2
 }

package/dist/jsdocUtils.d.ts

@@ -170,9 +170,10 @@ export function getAllTags(jsdoc: import("./iterateJsdoc.js").JsdocBlockWithInli
  * @param {import('./iterateJsdoc.js').Context[]} contexts
  * @param {import('./iterateJsdoc.js').CheckJsdoc} checkJsdoc
  * @param {import('@es-joy/jsdoccomment').CommentHandler} [handler]
+ * @param {boolean} [convertAny]
  * @returns {import('eslint').Rule.RuleListener}
  */
-export function getContextObject(contexts: import("./iterateJsdoc.js").Context[], checkJsdoc: import("./iterateJsdoc.js").CheckJsdoc, handler?: import("@es-joy/jsdoccomment").CommentHandler): import("eslint").Rule.RuleListener;
+export function getContextObject(contexts: import("./iterateJsdoc.js").Context[], checkJsdoc: import("./iterateJsdoc.js").CheckJsdoc, handler?: import("@es-joy/jsdoccomment").CommentHandler, convertAny?: boolean): import("eslint").Rule.RuleListener;
 /**
  * @param {import('eslint').SourceCode} sourceCode
  * @returns {import('comment-parser').Spec[]}

package/package.json

@@ -7,7 +7,7 @@
   "dependencies": {
     "@es-joy/jsdoccomment": "^0.96.0",
     "@es-joy/resolve.exports": "1.2.0",
-    "@typescript-eslint/utils": "^8.68.0",
+    "@typescript-eslint/utils": "^8.69.0",
     "are-docs-informative": "^0.1.1",
     "comment-parser": "1.4.8",
     "debug": "^4.4.3",
@@ -162,18 +162,22 @@
     "test-cov": "TIMING=1 c8 --reporter text pnpm run test-no-cov",
     "test-index": "pnpm run test-no-cov test/rules/index.js"
   },
-  "version": "64.3.2-depup.0",
+  "version": "64.3.3-depup.0",
   "depup": {
     "changes": {
       "@es-joy/jsdoccomment": {
         "from": "~0.95.1",
         "to": "^0.96.0"
+      },
+      "@typescript-eslint/utils": {
+        "from": "^8.68.0",
+        "to": "^8.69.0"
       }
     },
-    "depsUpdated": 1,
+    "depsUpdated": 2,
     "originalPackage": "eslint-plugin-jsdoc",
-    "originalVersion": "64.3.2",
-    "processedAt": "2026-08-31T00:36:26.963Z",
+    "originalVersion": "64.3.3",
+    "processedAt": "2026-09-01T00:41:05.665Z",
     "smokeTest": "passed"
   }
 }

package/src/jsdocUtils.js

@@ -1655,9 +1655,10 @@ const enforcedContexts = (context, defaultContexts, settings) => {
  * @param {import('./iterateJsdoc.js').Context[]} contexts
  * @param {import('./iterateJsdoc.js').CheckJsdoc} checkJsdoc
  * @param {import('@es-joy/jsdoccomment').CommentHandler} [handler]
+ * @param {boolean} [convertAny]
  * @returns {import('eslint').Rule.RuleListener}
  */
-const getContextObject = (contexts, checkJsdoc, handler) => {
+const getContextObject = (contexts, checkJsdoc, handler, convertAny) => {
   /** @type {import('eslint').Rule.RuleListener} */
   const properties = {};
 
@@ -1696,11 +1697,16 @@ const getContextObject = (contexts, checkJsdoc, handler) => {
         value = checkJsdoc.bind(null, selInfo, null);
       }
     } else {
+      property = prop;
+
+      if (convertAny && property === 'any') {
+        property = ':not(Program)';
+      }
+
       const selInfo = {
         lastIndex: idx,
-        selector: prop,
+        selector: property,
       };
-      property = prop;
       value = checkJsdoc.bind(null, selInfo, null);
     }
 

package/src/rules/convertToJsdocComments.js

@@ -185,6 +185,31 @@ export default {
       }
     };
 
+    /**
+     * Builds the opening portion of the JSDoc comment, i.e. everything before
+     * the closing delimiter.
+     * @param {string} indent
+     * @param {Token} comment
+     * @param {boolean|undefined} inlineCommentBlock
+     * @returns {string}
+     */
+    const getCommentOpening = (indent, comment, inlineCommentBlock) => {
+      if (inlineCommentBlock || enforceJsdocLineStyle === 'single') {
+        return `/** ${comment.value.trim()} `;
+      }
+
+      const body = comment.value.trimEnd();
+
+      // When the comment's text already begins on its own line (e.g. a
+      // multi-line block comment), there is no need for the fixer to add a
+      // leading blank `*` line.
+      if ((/^[ \t]*\n/v).test(body)) {
+        return `/**${body.replace(/^[ \t]+/v, '')}\n${indent}`;
+      }
+
+      return `/**\n${indent}*${body}\n${indent}`;
+    };
+
     /**
      * @type {import('../iterateJsdoc.js').CheckJsdoc}
      */
@@ -205,11 +230,7 @@ export default {
 
       /** @type {AddComment} */
       const addComment = (inlineCommentBlock, commentToAdd, indent, lines, fixer) => {
-        const insertion = (
-          inlineCommentBlock || enforceJsdocLineStyle === 'single' ?
-            `/** ${commentToAdd.value.trim()} ` :
-            `/**\n${indent}*${commentToAdd.value.trimEnd()}\n${indent}`
-        ) +
+        const insertion = getCommentOpening(indent, commentToAdd, inlineCommentBlock) +
             `*/${'\n'.repeat((lines || 1) - 1)}`;
 
         return fixer.replaceText(
@@ -242,11 +263,7 @@ export default {
 
       /** @type {AddComment} */
       const addComment = (inlineCommentBlock, commentToAdd, indent, lines, fixer) => {
-        const insertion = (
-          inlineCommentBlock || enforceJsdocLineStyle === 'single' ?
-            `/** ${commentToAdd.value.trim()} ` :
-            `/**\n${indent}*${commentToAdd.value.trimEnd()}\n${indent}`
-        ) +
+        const insertion = getCommentOpening(indent, commentToAdd, inlineCommentBlock) +
             `*/${'\n'.repeat((lines || 1) - 1)}${lines ? `\n${indent.slice(1)}` : ' '}`;
 
         return [
@@ -268,12 +285,16 @@ export default {
       ...getContextObject(
         enforcedContexts(context, true, settings),
         checkNonJsdoc,
+        undefined,
+        true,
       ),
       ...getContextObject(
         contextsAfter,
         (_info, _handler, node) => {
           checkNonJsdocAfter(node, contextsAfter);
         },
+        undefined,
+        true,
       ),
       ...getContextObject(
         contextsBeforeAndAfter,
@@ -283,6 +304,8 @@ export default {
             checkNonJsdocAfter(node, contextsBeforeAndAfter);
           }
         },
+        undefined,
+        true,
       ),
     };
   },

package/src/rules/noBlankBlockDescriptions.js

@@ -1,60 +1,115 @@
 import iterateJsdoc from '../iterateJsdoc.js';
 
-const anyWhitespaceLines = /^\s*$/v;
-const atLeastTwoLinesWhitespace = /^[ \t]*\n[ \t]*\n\s*$/v;
+const anyWhitespaceLine = /^\s*$/v;
 
 export default iterateJsdoc(({
   jsdoc,
   utils,
 }) => {
-  const {
-    description,
-    descriptions,
-    lastDescriptionLine,
-  } = utils.getDescription();
-
-  const regex = jsdoc.tags.length ?
-    anyWhitespaceLines :
-    atLeastTwoLinesWhitespace;
-
-  if (descriptions.length && regex.test(description)) {
-    if (jsdoc.tags.length) {
-      utils.reportJSDoc(
-        'There should be no blank lines in block descriptions followed by tags.',
-        {
-          line: lastDescriptionLine,
-        },
-        () => {
-          utils.setBlockDescription(() => {
-            // Remove all lines
-            return [];
-          });
-        },
-      );
-    } else {
-      utils.reportJSDoc(
-        'There should be no extra blank lines in block descriptions not followed by tags.',
-        {
-          line: lastDescriptionLine,
-        },
-        () => {
-          utils.setBlockDescription((info, seedTokens) => {
-            return [
-              // Keep the starting line
-              {
-                number: 0,
-                source: '',
-                tokens: seedTokens({
-                  ...info,
-                  description: '',
-                }),
-              },
-            ];
-          });
-        },
-      );
+  const hasTags = Boolean(jsdoc.tags.length);
+
+  // Gather the block-description lines (those before the first tag or the
+  //   closing delimiter).
+  let startIdx = -1;
+
+  /**
+   * @type {string[]}
+   */
+  const descLines = [];
+  jsdoc.source.some(({
+    tokens: {
+      delimiter,
+      description,
+      end,
+      tag,
+    },
+  }, idx) => {
+    if (delimiter === '/**') {
+      return false;
+    }
+
+    if (tag || end) {
+      return true;
+    }
+
+    if (startIdx === -1) {
+      startIdx = idx;
+    }
+
+    descLines.push(description);
+
+    return false;
+  });
+
+  if (!descLines.length) {
+    return;
+  }
+
+  let leadingBlankCount = 0;
+  while (
+    leadingBlankCount < descLines.length &&
+    anyWhitespaceLine.test(descLines[leadingBlankCount])
+  ) {
+    leadingBlankCount++;
+  }
+
+  const allBlank = leadingBlankCount === descLines.length;
+
+  /**
+   * Rebuilds the kept description lines after dropping `dropCount` leading
+   *   blank lines.
+   * @param {import('../iterateJsdoc.js').Integer} dropCount
+   * @returns {() => void}
+   */
+  const dropLeadingBlankLines = (dropCount) => {
+    return () => {
+      utils.setBlockDescription((info, seedTokens, descriptions, postDelimiters) => {
+        return descriptions.slice(dropCount).map((description, idx) => {
+          return {
+            number: 0,
+            source: '',
+            tokens: seedTokens({
+              ...info,
+              description,
+              postDelimiter: description ? postDelimiters[idx + dropCount] : '',
+            }),
+          };
+        });
+      });
+    };
+  };
+
+  if (hasTags) {
+    if (!leadingBlankCount) {
+      return;
     }
+
+    utils.reportJSDoc(
+      'There should be no blank lines in block descriptions followed by tags.',
+      {
+        line: startIdx + leadingBlankCount - 1,
+      },
+      dropLeadingBlankLines(leadingBlankCount),
+    );
+
+    return;
+  }
+
+  // Without tags, only the extra (removable) leading blank lines are a problem;
+  //   a single leading blank line with no following content is allowed.
+  const removeCount = allBlank ? descLines.length - 1 : leadingBlankCount;
+
+  if (removeCount < 1) {
+    return;
   }
+
+  utils.reportJSDoc(
+    'There should be no extra blank lines in block descriptions not followed by tags.',
+    {
+      line: startIdx + removeCount,
+    },
+    dropLeadingBlankLines(removeCount),
+  );
 }, {
   iterateAllJsdocs: true,
   meta: {