feat(lines-before-block): add default-on ignoreSingleLines option; fixes #1295 (#1408)

Author: brettz9

.README/rules/lines-before-block.md

@@ -19,6 +19,11 @@ The minimum number of lines to require. Defaults to 1.
 This option excludes cases where the JSDoc block occurs on the same line as a
 preceding code or comment. Defaults to `true`.
 
+### `ignoreSingleLines`
+
+This option excludes cases where the JSDoc block is only one line long.
+Defaults to `true`.
+
 ### `excludedTags`
 
 An array of tags whose presence in the JSDoc block will prevent the
@@ -31,7 +36,7 @@ lines before the block will not be added).
 |Tags|N/A|
 |Recommended|false|
 |Settings||
-|Options|`checkBlockStarts`, `excludedTags`, `ignoreSameLine`, `lines`|
+|Options|`checkBlockStarts`, `excludedTags`, `ignoreSameLine`, `ignoreSingleLines`, `lines`|
 
 ## Failing examples
 

docs/rules/lines-before-block.md

@@ -29,6 +29,13 @@ The minimum number of lines to require. Defaults to 1.
 This option excludes cases where the JSDoc block occurs on the same line as a
 preceding code or comment. Defaults to `true`.
 
+<a name="user-content-lines-before-block-options-ignoresinglelines"></a>
+<a name="lines-before-block-options-ignoresinglelines"></a>
+### <code>ignoreSingleLines</code>
+
+This option excludes cases where the JSDoc block is only one line long.
+Defaults to `true`.
+
 <a name="user-content-lines-before-block-options-excludedtags"></a>
 <a name="lines-before-block-options-excludedtags"></a>
 ### <code>excludedTags</code>
@@ -43,7 +50,7 @@ lines before the block will not be added).
 |Tags|N/A|
 |Recommended|false|
 |Settings||
-|Options|`checkBlockStarts`, `excludedTags`, `ignoreSameLine`, `lines`|
+|Options|`checkBlockStarts`, `excludedTags`, `ignoreSameLine`, `ignoreSingleLines`, `lines`|
 
 <a name="user-content-lines-before-block-failing-examples"></a>
 <a name="lines-before-block-failing-examples"></a>
@@ -65,7 +72,7 @@ someCode; /**
 // Message: Required 1 line(s) before JSDoc block
 
 someCode; /** */
-// "jsdoc/lines-before-block": ["error"|"warn", {"ignoreSameLine":false}]
+// "jsdoc/lines-before-block": ["error"|"warn", {"ignoreSameLine":false,"ignoreSingleLines":false}]
 // Message: Required 1 line(s) before JSDoc block
 
 someCode;
@@ -166,14 +173,27 @@ type IntersectionDocumentation =
   { someProp: number } &
   /** Description. */
   { otherProp: string }
+// "jsdoc/lines-before-block": ["error"|"warn", {"ignoreSingleLines":false}]
 // Message: Required 1 line(s) before JSDoc block
 
 type IntersectionDocumentation = {
   someProp: number;
 } & /** Description. */ {
   otherProp: string;
 };
-// "jsdoc/lines-before-block": ["error"|"warn", {"ignoreSameLine":false}]
+// "jsdoc/lines-before-block": ["error"|"warn", {"ignoreSameLine":false,"ignoreSingleLines":false}]
+// Message: Required 1 line(s) before JSDoc block
+
+/** The parameters for a request */
+export type RequestParams = {
+  /** The year to retrieve. */
+  year: `${number}`;
+  /**
+   * The month to retrieve.
+   */
+  month: `${number}`;
+}
+// "jsdoc/lines-before-block": ["error"|"warn", {"ignoreSingleLines":true}]
 // Message: Required 1 line(s) before JSDoc block
 ````
 
@@ -304,5 +324,14 @@ type IntersectionDocumentation = {
 } & /** Description. */ {
   otherProp: string;
 };
+
+/** The parameters for a request */
+export type RequestParams = {
+  /** The year to retrieve. */
+  year: `${number}`;
+  /** The month to retrieve. */
+  month: `${number}`;
+}
+// "jsdoc/lines-before-block": ["error"|"warn", {"ignoreSingleLines":true}]
 ````
 

src/rules/linesBeforeBlock.js

@@ -22,6 +22,7 @@ export default iterateJsdoc(({
       'type',
     ],
     ignoreSameLine = true,
+    ignoreSingleLines = true,
     lines = 1,
   } = context.options[0] || {};
 
@@ -54,6 +55,10 @@ export default iterateJsdoc(({
       return;
     }
 
+    if (ignoreSingleLines && jsdocNode.loc?.start.line === jsdocNode.loc?.end.line) {
+      return;
+    }
+
     /** @type {import('eslint').Rule.ReportFixer} */
     const fix = (fixer) => {
       let indent = '';
@@ -114,6 +119,9 @@ export default iterateJsdoc(({
           ignoreSameLine: {
             type: 'boolean',
           },
+          ignoreSingleLines: {
+            type: 'boolean',
+          },
           lines: {
             type: 'integer',
           },

test/rules/assertions/linesBeforeBlock.js

@@ -63,6 +63,7 @@ export default /** @type {import('../index.js').TestCases} */ ({
       options: [
         {
           ignoreSameLine: false,
+          ignoreSingleLines: false,
         },
       ],
       output: `
@@ -388,6 +389,11 @@ export default /** @type {import('../index.js').TestCases} */ ({
       languageOptions: {
         parser: typescriptEslintParser,
       },
+      options: [
+        {
+          ignoreSingleLines: false,
+        },
+      ],
       output: `
         type UnionDocumentation =
           /** Description. */
@@ -426,6 +432,7 @@ export default /** @type {import('../index.js').TestCases} */ ({
       options: [
         {
           ignoreSameLine: false,
+          ignoreSingleLines: false,
         },
       ],
       output: `
@@ -438,6 +445,45 @@ export default /** @type {import('../index.js').TestCases} */ ({
         };
       `,
     },
+    {
+      code: `
+        /** The parameters for a request */
+        export type RequestParams = {
+          /** The year to retrieve. */
+          year: \`\${number}\`;
+          /**
+           * The month to retrieve.
+           */
+          month: \`\${number}\`;
+        }
+      `,
+      errors: [
+        {
+          line: 6,
+          message: 'Required 1 line(s) before JSDoc block',
+        },
+      ],
+      languageOptions: {
+        parser: typescriptEslintParser,
+      },
+      options: [
+        {
+          ignoreSingleLines: true,
+        },
+      ],
+      output: `
+        /** The parameters for a request */
+        export type RequestParams = {
+          /** The year to retrieve. */
+          year: \`\${number}\`;
+
+          /**
+           * The month to retrieve.
+           */
+          month: \`\${number}\`;
+        }
+      `,
+    },
   ],
   valid: [
     {
@@ -621,5 +667,24 @@ export default /** @type {import('../index.js').TestCases} */ ({
         parser: typescriptEslintParser,
       },
     },
+    {
+      code: `
+        /** The parameters for a request */
+        export type RequestParams = {
+          /** The year to retrieve. */
+          year: \`\${number}\`;
+          /** The month to retrieve. */
+          month: \`\${number}\`;
+        }
+      `,
+      languageOptions: {
+        parser: typescriptEslintParser,
+      },
+      options: [
+        {
+          ignoreSingleLines: true,
+        },
+      ],
+    },
   ],
 });