fix(convert-to-jsdoc-comments): handle "any" context and avoid extra line break when there is already multiline text

docs/rules/convert-to-jsdoc-comments.md

@@ -216,6 +216,15 @@ class TestClass {
 var a = []; // Test comment
 // "jsdoc/convert-to-jsdoc-comments": ["error"|"warn", {"contextsBeforeAndAfter":["VariableDeclarator"]}]
 // Message: Line comments should be JSDoc-style.
+
+/*
+ * Seniority levels that participate in distribution, in display
+ * order. `custom` is never a real distribution key. Every test shown in this
+ * modal can recruit each of these levels, so all three are always editable.
+ */
+const SENIORITY_ORDER = ['senior', 'middle', 'specialist'];
+// "jsdoc/convert-to-jsdoc-comments": ["error"|"warn", {"contexts":["any"],"lineOrBlockStyle":"block"}]
+// Message: Block comments should be JSDoc-style.
 ````
 
 

docs/rules/no-blank-block-descriptions.md

@@ -48,6 +48,23 @@ function functionWithClearName(x) {}
  */
 function functionWithClearName() {}
 // Message: There should be no extra blank lines in block descriptions not followed by tags.
+
+/**
+ *
+ * Some text
+ * @param {number} x
+ */
+function functionWithClearName(x) {}
+// Message: There should be no blank lines in block descriptions followed by tags.
+
+/**
+ *
+ * Seniority levels that participate in distribution, in display
+ * order. `custom` is never a real distribution key. Every test shown in this
+ * modal can recruit each of these levels, so all three are always editable.
+ */
+const SENIORITY_ORDER = ['senior', 'middle', 'specialist'];
+// Message: There should be no extra blank lines in block descriptions not followed by tags.
 ````
 
 

src/jsdocUtils.js

@@ -405,7 +405,7 @@
 
           // case 'MemberExpression':
         default:
         // Todo: We should really create a structure (and a corresponding
         //   option analogous to `checkRestProperty`) which allows for
         //   (and optionally requires) dynamic properties to have a single
         //   line of documentation
@@ -1655,9 +1655,10 @@
  * @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 @@
         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);
     }
 

src/rules/convertToJsdocComments.js

@@ -185,6 +185,31 @@
       }
     };
 
+    /**
+     * 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 @@
 
       /** @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 @@
 
       /** @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 [
@@ -263,17 +280,21 @@
       reportings(comment, node, addComment, ctxts);
     };
 
     // Todo: add contexts to check after (and handle if want both before and after)
     return {
       ...getContextObject(
         enforcedContexts(context, true, settings),
         checkNonJsdoc,
+        undefined,
+        true,
       ),
       ...getContextObject(
         contextsAfter,
         (_info, _handler, node) => {
           checkNonJsdocAfter(node, contextsAfter);
         },
+        undefined,
+        true,
       ),
       ...getContextObject(
         contextsBeforeAndAfter,
@@ -283,6 +304,8 @@
             checkNonJsdocAfter(node, contextsBeforeAndAfter);
           }
         },
+        undefined,
+        true,
       ),
     };
   },

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: {

test/rules/assertions/convertToJsdocComments.js

@@ -503,6 +503,38 @@ export default /** @type {import('../index.js').TestCases} */ ({
         var a = []; ` + `
       `,
     },
+    {
+      code: `
+        /*
+         * Seniority levels that participate in distribution, in display
+         * order. \`custom\` is never a real distribution key. Every test shown in this
+         * modal can recruit each of these levels, so all three are always editable.
+         */
+        const SENIORITY_ORDER = ['senior', 'middle', 'specialist'];
+      `,
+      errors: [
+        {
+          line: 2,
+          message: 'Block comments should be JSDoc-style.',
+        },
+      ],
+      options: [
+        {
+          contexts: [
+            'any',
+          ],
+          lineOrBlockStyle: 'block',
+        },
+      ],
+      output: `
+        /**
+         * Seniority levels that participate in distribution, in display
+         * order. \`custom\` is never a real distribution key. Every test shown in this
+         * modal can recruit each of these levels, so all three are always editable.
+         */
+        const SENIORITY_ORDER = ['senior', 'middle', 'specialist'];
+      `,
+    },
   ],
   valid: [
     {