feat(lines-before-block): move start-of-block checking behind off-by-…

…default `checkBlockStarts` option (gajus#1341)
brettz9 · Nov 26, 2024 · f9b102d · f9b102d
1 parent feba293
commit f9b102d
Show file tree

Hide file tree

Showing 4 changed files with 212 additions and 5 deletions.
diff --git a/.README/rules/lines-before-block.md b/.README/rules/lines-before-block.md
@@ -1,10 +1,15 @@
 # `lines-before-block`
 
 This rule enforces minimum number of newlines before JSDoc comment blocks
-(except at the beginning of a file).
+(except at the beginning of a block or file).
 
 ## Options
 
+### `checkBlockStarts`
+
+Whether to additionally check the start of blocks, such as classes or functions.
+Defaults to `false`.
+
 ### `lines`
 
 The minimum number of lines to require. Defaults to 1.
@@ -26,7 +31,7 @@ lines before the block will not be added).
 |Tags|N/A|
 |Recommended|false|
 |Settings||
-|Options|`excludedTags`, `ignoreSameLine`, `lines`|
+|Options|`checkBlockStarts`, `excludedTags`, `ignoreSameLine`, `lines`|
 
 ## Failing examples
 

diff --git a/docs/rules/lines-before-block.md b/docs/rules/lines-before-block.md
@@ -3,12 +3,19 @@
 # <code>lines-before-block</code>
 
 This rule enforces minimum number of newlines before JSDoc comment blocks
-(except at the beginning of a file).
+(except at the beginning of a block or file).
 
 <a name="user-content-lines-before-block-options"></a>
 <a name="lines-before-block-options"></a>
 ## Options
 
+<a name="user-content-lines-before-block-options-checkblockstarts"></a>
+<a name="lines-before-block-options-checkblockstarts"></a>
+### <code>checkBlockStarts</code>
+
+Whether to additionally check the start of blocks, such as classes or functions.
+Defaults to `false`.
+
 <a name="user-content-lines-before-block-options-lines"></a>
 <a name="lines-before-block-options-lines"></a>
 ### <code>lines</code>
@@ -36,7 +43,7 @@ lines before the block will not be added).
 |Tags|N/A|
 |Recommended|false|
 |Settings||
-|Options|`excludedTags`, `ignoreSameLine`, `lines`|
+|Options|`checkBlockStarts`, `excludedTags`, `ignoreSameLine`, `lines`|
 
 <a name="user-content-lines-before-block-failing-examples"></a>
 <a name="lines-before-block-failing-examples"></a>
@@ -87,6 +94,42 @@ someCode;
  *
  */
 // Message: Required 1 line(s) before JSDoc block
+
+{
+  /**
+   * Description.
+   */
+  let value;
+}
+// "jsdoc/lines-before-block": ["error"|"warn", {"checkBlockStarts":true}]
+// Message: Required 1 line(s) before JSDoc block
+
+class MyClass {
+  /**
+   * Description.
+   */
+  method() {}
+}
+// "jsdoc/lines-before-block": ["error"|"warn", {"checkBlockStarts":true}]
+// Message: Required 1 line(s) before JSDoc block
+
+function myFunction() {
+  /**
+   * Description.
+   */
+  let value;
+}
+// "jsdoc/lines-before-block": ["error"|"warn", {"checkBlockStarts":true}]
+// Message: Required 1 line(s) before JSDoc block
+
+const values = [
+  /**
+   * Description.
+   */
+  value,
+];
+// "jsdoc/lines-before-block": ["error"|"warn", {"checkBlockStarts":true}]
+// Message: Required 1 line(s) before JSDoc block
 ````
 
 
@@ -146,5 +189,26 @@ const a = /** @lends SomeClass */ {
   someProp: (someVal)
 };
 // "jsdoc/lines-before-block": ["error"|"warn", {"excludedTags":["lends"],"ignoreSameLine":false}]
+
+{
+  /**
+   * Description.
+   */
+  let value;
+}
+
+class MyClass {
+  /**
+   * Description.
+   */
+  method() {}
+}
+
+function myFunction() {
+  /**
+   * Description.
+   */
+  let value;
+}
 ````
 
diff --git a/src/rules/linesBeforeBlock.js b/src/rules/linesBeforeBlock.js
@@ -8,6 +8,7 @@ export default iterateJsdoc(({
   utils,
 }) => {
   const {
+    checkBlockStarts,
     lines = 1,
     ignoreSameLine = true,
     excludedTags = ['type']
@@ -19,7 +20,7 @@ export default iterateJsdoc(({
 
   const tokensBefore = sourceCode.getTokensBefore(jsdocNode, {includeComments: true});
   const tokenBefore = tokensBefore.slice(-1)[0];
-  if (!tokenBefore) {
+  if (!tokenBefore || (tokenBefore.value === '{' && !checkBlockStarts)) {
     return;
   }
 
@@ -80,6 +81,9 @@ export default iterateJsdoc(({
       {
         additionalProperties: false,
         properties: {
+          checkBlockStarts: {
+            type: 'boolean',
+          },
           excludedTags: {
             type: 'array',
             items: {

diff --git a/test/rules/assertions/linesBeforeBlock.js b/test/rules/assertions/linesBeforeBlock.js
@@ -161,6 +161,110 @@ export default {
          */
       `,
     },
+    {
+      code: `
+        {
+          /**
+           * Description.
+           */
+          let value;
+        }
+      `,
+      errors: [
+        {
+          line: 3,
+          message: 'Required 1 line(s) before JSDoc block'
+        }
+      ],
+      options: [{ checkBlockStarts: true }],
+      output: `
+        {
+
+          /**
+           * Description.
+           */
+          let value;
+        }
+      `,
+    },
+    {
+      code: `
+        class MyClass {
+          /**
+           * Description.
+           */
+          method() {}
+        }
+      `,
+      errors: [
+        {
+          line: 3,
+          message: 'Required 1 line(s) before JSDoc block'
+        }
+      ],
+      options: [{ checkBlockStarts: true }],
+      output: `
+        class MyClass {
+
+          /**
+           * Description.
+           */
+          method() {}
+        }
+      `,
+    },
+    {
+      code: `
+        function myFunction() {
+          /**
+           * Description.
+           */
+          let value;
+        }
+      `,
+      errors: [
+        {
+          line: 3,
+          message: 'Required 1 line(s) before JSDoc block'
+        }
+      ],
+      options: [{ checkBlockStarts: true }],
+      output: `
+        function myFunction() {
+
+          /**
+           * Description.
+           */
+          let value;
+        }
+      `,
+    },
+    {
+      code: `
+        const values = [
+          /**
+           * Description.
+           */
+          value,
+        ];
+      `,
+      errors: [
+        {
+          line: 3,
+          message: 'Required 1 line(s) before JSDoc block'
+        }
+      ],
+      options: [{ checkBlockStarts: true }],
+      output: `
+        const values = [
+
+          /**
+           * Description.
+           */
+          value,
+        ];
+      `,
+    }
   ],
   valid: [
     {
@@ -242,5 +346,35 @@ export default {
         }
       ]
     },
+    {
+      code: `
+        {
+          /**
+           * Description.
+           */
+          let value;
+        }
+      `,
+    },
+    {
+      code: `
+        class MyClass {
+          /**
+           * Description.
+           */
+          method() {}
+        }
+      `,
+    },
+    {
+      code: `
+        function myFunction() {
+          /**
+           * Description.
+           */
+          let value;
+        }
+      `,
+    }
   ],
 };