fix(lines-before-block): Switch to a whitelist of punctuators (#1385)

Author: LukeAbby

docs/rules/lines-before-block.md

@@ -131,6 +131,30 @@ const values = [
 // "jsdoc/lines-before-block": ["error"|"warn", {"checkBlockStarts":true}]
 // Message: Required 1 line(s) before JSDoc block
 
+const values = [
+  value1,
+  /**
+   * Description.
+   */
+  value2
+];
+// Message: Required 1 line(s) before JSDoc block
+
+const values = [
+  value1,
+  value2
+]
+/**
+ * Description.
+ */
+// Message: Required 1 line(s) before JSDoc block
+
+const value = 123
+/**
+ * Description.
+ */
+// Message: Required 1 line(s) before JSDoc block
+
 type UnionDocumentation =
   /** Description. */
   | { someProp: number }

src/rules/linesBeforeBlock.js

@@ -1,11 +1,11 @@
 import iterateJsdoc from '../iterateJsdoc.js';
 
 /**
- * `;` ends a previous statement, `}` ends a previous block, `|` is seen the middle of a union, and
- * `&` is seen in the middle of an intersection. All other punctuators are for things like arrays,
- * functions, type aliases, and so on that shouldn't require a line before it.
+ * Punctuators that begin a logical group should not require a line before it skipped. Specifically
+ * `[` starts an array, `{` starts an object or block, `(` starts a grouping, and `=` starts a
+ * declaration (like a variable or a type alias).
  */
-const lintedPunctuators = new Set([';', '}', '|', '&']);
+const startPunctuators = new Set(['[', '{', '(', '=']);
 
 export default iterateJsdoc(({
   context,
@@ -31,7 +31,7 @@ export default iterateJsdoc(({
     !tokenBefore || (
       tokenBefore.type === 'Punctuator' &&
       !checkBlockStarts &&
-      !lintedPunctuators.has(tokenBefore.value)
+      startPunctuators.has(tokenBefore.value)
     )
   ) {
     return;

test/rules/assertions/linesBeforeBlock.js

@@ -267,6 +267,82 @@ export default /** @type {import('../index.js').TestCases} */ ({
         ];
       `,
     },
+    {
+      code: `
+        const values = [
+          value1,
+          /**
+           * Description.
+           */
+          value2
+        ];
+      `,
+      errors: [
+        {
+          line: 4,
+          message: 'Required 1 line(s) before JSDoc block'
+        }
+      ],
+      output: `
+        const values = [
+          value1,
+
+          /**
+           * Description.
+           */
+          value2
+        ];
+      `,
+    },
+    {
+      code: `
+        const values = [
+          value1,
+          value2
+        ]
+        /**
+         * Description.
+         */
+      `,
+      errors: [
+        {
+          line: 6,
+          message: 'Required 1 line(s) before JSDoc block'
+        }
+      ],
+      output: `
+        const values = [
+          value1,
+          value2
+        ]
+
+        /**
+         * Description.
+         */
+      `,
+    },
+    {
+      // This test is interesting due to the lack of semicolons.
+      code: `
+        const value = 123
+        /**
+         * Description.
+         */
+      `,
+      errors: [
+        {
+          line: 3,
+          message: 'Required 1 line(s) before JSDoc block'
+        }
+      ],
+      output: `
+        const value = 123
+
+        /**
+         * Description.
+         */
+      `,
+    },
     {
       code: `
         type UnionDocumentation =