fix(lines-before-block): Only trigger after ';', '}', '|', and '&' (#1383)

* fix(lines-before-block): Only trigger after ';', '}', '|', and '&'; fixes #1379 and #1343

* fix(lines-before-block): Switch lintedPunctuators to a Set

---------

Co-authored-by: Brett Zamir <[email protected]>

Author: LukeAbby

docs/rules/lines-before-block.md

@@ -130,6 +130,27 @@ const values = [
 ];
 // "jsdoc/lines-before-block": ["error"|"warn", {"checkBlockStarts":true}]
 // Message: Required 1 line(s) before JSDoc block
+
+type UnionDocumentation =
+  /** Description. */
+  | { someProp: number }
+  /** Description. */
+  | { otherProp: string }
+
+type IntersectionDocumentation =
+  /** Description. */
+  { someProp: number } &
+  /** Description. */
+  { otherProp: string }
+// Message: Required 1 line(s) before JSDoc block
+
+type IntersectionDocumentation = {
+  someProp: number;
+} & /** Description. */ {
+  otherProp: string;
+};
+// "jsdoc/lines-before-block": ["error"|"warn", {"ignoreSameLine":false}]
+// Message: Required 1 line(s) before JSDoc block
 ````
 
 
@@ -210,5 +231,54 @@ function myFunction() {
    */
   let value;
 }
+
+class SomeClass {
+  constructor(
+    /**
+     * Description.
+     */
+    param
+  ) {};
+
+  method(
+    /**
+     * Description.
+     */
+    param
+  ) {};
+}
+
+type FunctionAlias1 =
+  /**
+   * @param param - Description.
+   */
+  (param: number) => void;
+
+type FunctionAlias2 = (
+  /**
+   * @param param - Description.
+   */
+  param: number
+) => void;
+
+type UnionDocumentation =
+  /** Description. */
+  | { someProp: number }
+
+  /** Description. */
+  | { otherProp: string }
+
+type IntersectionDocumentation =
+  /** Description. */
+  { someProp: number } &
+
+  /** Description. */
+  { otherProp: string }
+
+type IntersectionDocumentation = {
+  someProp: number;
+} & /** Description. */ {
+  otherProp: string;
+};
 ````
 

src/rules/linesBeforeBlock.js

@@ -1,5 +1,12 @@
 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.
+ */
+const lintedPunctuators = new Set([';', '}', '|', '&']);
+
 export default iterateJsdoc(({
   context,
   jsdocNode,
@@ -19,8 +26,14 @@ export default iterateJsdoc(({
   }
 
   const tokensBefore = sourceCode.getTokensBefore(jsdocNode, {includeComments: true});
-  const tokenBefore = tokensBefore.slice(-1)[0];
-  if (!tokenBefore || (tokenBefore.value === '{' && !checkBlockStarts)) {
+  const tokenBefore = tokensBefore.at(-1);
+  if (
+    !tokenBefore || (
+      tokenBefore.type === 'Punctuator' &&
+      !checkBlockStarts &&
+      !lintedPunctuators.has(tokenBefore.value)
+    )
+  ) {
     return;
   }
 

test/rules/assertions/linesBeforeBlock.js

@@ -1,3 +1,5 @@
+import {parser as typescriptEslintParser} from 'typescript-eslint';
+
 export default /** @type {import('../index.js').TestCases} */ ({
   invalid: [
     {
@@ -264,6 +266,83 @@ export default /** @type {import('../index.js').TestCases} */ ({
           value,
         ];
       `,
+    },
+    {
+      code: `
+        type UnionDocumentation =
+          /** Description. */
+          | { someProp: number }
+          /** Description. */
+          | { otherProp: string }
+
+        type IntersectionDocumentation =
+          /** Description. */
+          { someProp: number } &
+          /** Description. */
+          { otherProp: string }
+      `,
+      errors: [
+        {
+          line: 5,
+          message: 'Required 1 line(s) before JSDoc block'
+        },
+        {
+          line: 11,
+          message: 'Required 1 line(s) before JSDoc block'
+        }
+      ],
+      languageOptions: {
+        parser: typescriptEslintParser
+      },
+      output: `
+        type UnionDocumentation =
+          /** Description. */
+          | { someProp: number }
+
+          /** Description. */
+          | { otherProp: string }
+
+        type IntersectionDocumentation =
+          /** Description. */
+          { someProp: number } &
+
+          /** Description. */
+          { otherProp: string }
+      `,
+    },
+    {
+      // While this looks ugly this is exactly how Prettier currently requires such an intersection
+      // to be formatted. See https://github.com/prettier/prettier/issues/3986.
+      code: `
+        type IntersectionDocumentation = {
+          someProp: number;
+        } & /** Description. */ {
+          otherProp: string;
+        };
+      `,
+      errors: [
+        {
+          line: 4,
+          message: 'Required 1 line(s) before JSDoc block'
+        },
+      ],
+      languageOptions: {
+        parser: typescriptEslintParser
+      },
+      options: [
+        {
+          ignoreSameLine: false,
+        }
+      ],
+      output: `
+        type IntersectionDocumentation = {
+          someProp: number;
+        } &
+
+        /** Description. */ {
+          otherProp: string;
+        };
+      `
     }
   ],
   valid: [
@@ -375,6 +454,76 @@ export default /** @type {import('../index.js').TestCases} */ ({
           let value;
         }
       `,
+    },
+    {
+      code: `
+        class SomeClass {
+          constructor(
+            /**
+             * Description.
+             */
+            param
+          ) {};
+
+          method(
+            /**
+             * Description.
+             */
+            param
+          ) {};
+        }
+      `,
+    },
+    {
+      code: `
+        type FunctionAlias1 =
+          /**
+           * @param param - Description.
+           */
+          (param: number) => void;
+
+        type FunctionAlias2 = (
+          /**
+           * @param param - Description.
+           */
+          param: number
+        ) => void;
+      `,
+      languageOptions: {
+        parser: typescriptEslintParser
+      },
+    },
+    {
+      code: `
+        type UnionDocumentation =
+          /** Description. */
+          | { someProp: number }
+
+          /** Description. */
+          | { otherProp: string }
+
+        type IntersectionDocumentation =
+          /** Description. */
+          { someProp: number } &
+
+          /** Description. */
+          { otherProp: string }
+      `,
+      languageOptions: {
+        parser: typescriptEslintParser
+      },
+    },
+    {
+      code: `
+        type IntersectionDocumentation = {
+          someProp: number;
+        } & /** Description. */ {
+          otherProp: string;
+        };
+      `,
+      languageOptions: {
+        parser: typescriptEslintParser
+      },
     }
   ],
 });