feat(tag-lines): maxBlockLines option; fixes #1346

Author: brettz9

.README/rules/tag-lines.md

@@ -27,7 +27,7 @@ Removes or adds lines between tags or trailing tags.
 |Tags|Any|
 |Recommended|true|
 |Settings|N/A|
-|Options|string ("always", "any", "never") followed by object with `applyToEndTag`, `count`, `endLines`, `startLines`, `tags`|
+|Options|string ("always", "any", "never") followed by object with `applyToEndTag`, `count`, `endLines`, `maxBlockLines`, `startLines`, `tags`|
 
 ## Failing examples
 

README.md

@@ -488,7 +488,7 @@ non-default-recommended fixer).
 ||| [require-yields-description](./docs/rules/require-yields-description.md#readme) | Requires a description for `@yields` tags |
 |:heavy_check_mark:|| [require-yields-type](./docs/rules/require-yields-type.md#readme) | Requires a type for `@yields` tags |
 ||:wrench:| [sort-tags](./docs/rules/sort-tags.md#readme) | Sorts tags by a specified sequence according to tag name, optionally adding line breaks between tag groups. |
-|:heavy_check_mark:|:wrench:| [tag-lines](./docs/rules/tag-lines.md#readme) | Enforces lines (or no lines) between tags. |
+|:heavy_check_mark:|:wrench:| [tag-lines](./docs/rules/tag-lines.md#readme) | Enforces lines (or no lines) before, after, or between tags. |
 ||:wrench:| [text-escaping](./docs/rules/text-escaping.md#readme) | Auto-escape certain characters that are input within block and tag descriptions. |
 ||:wrench:| [type-formatting](./docs/rules/type-formatting.md#readme) | Formats JSDoc type values. |
 |:heavy_check_mark:|| [valid-types](./docs/rules/valid-types.md#readme) | Requires all types/namepaths to be valid JSDoc, Closure compiler, or TypeScript types (configurable in settings). |

docs/rules/tag-lines.md

@@ -7,6 +7,7 @@
     * [`applyToEndTag`](#user-content-tag-lines-options-applytoendtag)
     * [`count`](#user-content-tag-lines-options-count)
     * [`endLines`](#user-content-tag-lines-options-endlines)
+    * [`maxBlockLines`](#user-content-tag-lines-options-maxblocklines)
     * [`startLines`](#user-content-tag-lines-options-startlines)
     * [`tags`](#user-content-tag-lines-options-tags)
 * [Context and settings](#user-content-tag-lines-context-and-settings)
@@ -35,7 +36,7 @@ Removes or adds lines between tags or trailing tags.
 
 The first option is a string with the following possible values: "always", "any", "never".
 Defaults to "never". "any" is only useful with `tags` (allowing non-enforcement of lines except
-for particular tags) or with `startLines` or `endLines`. It is also
+for particular tags) or with `startLines`, `endLines`, or `maxBlockLines`. It is also
 necessary if using the linebreak-setting options of the `sort-tags` rule
 so that the two rules won't conflict in both attempting to set lines
 between tags.
@@ -65,6 +66,15 @@ If not set to `null`, will enforce end lines to the given count on the
 final tag only.
 
 Defaults to `0`.
+<a name="user-content-tag-lines-options-maxblocklines"></a>
+<a name="tag-lines-options-maxblocklines"></a>
+### <code>maxBlockLines</code>
+
+If not set to `null`, will enforce a maximum number of lines to the given count anywhere in the block description.
+
+Note that if non-`null`, `maxBlockLines` must be greater than or equal to `startLines`.
+
+Defaults to `null`.
 <a name="user-content-tag-lines-options-startlines"></a>
 <a name="tag-lines-options-startlines"></a>
 ### <code>startLines</code>
@@ -99,7 +109,7 @@ Defaults to empty object.
 |Tags|Any|
 |Recommended|true|
 |Settings|N/A|
-|Options|string ("always", "any", "never") followed by object with `applyToEndTag`, `count`, `endLines`, `startLines`, `tags`|
+|Options|string ("always", "any", "never") followed by object with `applyToEndTag`, `count`, `endLines`, `maxBlockLines`, `startLines`, `tags`|
 
 <a name="user-content-tag-lines-failing-examples"></a>
 <a name="tag-lines-failing-examples"></a>
@@ -288,13 +298,23 @@ The following patterns are considered problems:
 // "jsdoc/tag-lines": ["error"|"warn", "any",{"startLines":1}]
 // Message: Expected only 1 line after block description
 
+/**
+ * Some description
+ *
+ *
+ *
+ * @param {string} a
+ */
+// "jsdoc/tag-lines": ["error"|"warn", "any",{"startLines":2}]
+// Message: Expected only 2 lines after block description
+
 /**
  * Some description
  *
  * @param {string} a
  */
 // "jsdoc/tag-lines": ["error"|"warn", "any",{"startLines":0}]
-// Message: Expected only 0 line after block description
+// Message: Expected only 0 lines after block description
 
 /**
  * Some description
@@ -310,6 +330,68 @@ The following patterns are considered problems:
  */
 // "jsdoc/tag-lines": ["error"|"warn", "any",{"startLines":1}]
 // Message: Expected 1 lines after block description
+
+/**
+ *
+ * Some description
+ *
+ * Abc
+ *
+ *
+ *
+ * Def
+ *
+ * @param {string} a
+ */
+// "jsdoc/tag-lines": ["error"|"warn", "any",{"maxBlockLines":2}]
+// Message: Expected a maximum of 2 lines within block description
+
+/**
+ *
+ * Some description
+ *
+ * Abc
+ *
+ *
+ *
+ * Def
+ *
+ * @param {string} a
+ */
+// "jsdoc/tag-lines": ["error"|"warn", "any",{"maxBlockLines":1}]
+// Message: Expected a maximum of 1 line within block description
+
+/**
+ *
+ * Some description
+ *
+ * Abc
+ *
+ *
+ *
+ * Def
+ *
+ * @param {string} a
+ */
+// "jsdoc/tag-lines": ["error"|"warn", "any",{"maxBlockLines":0}]
+// Message: Expected a maximum of 0 lines within block description
+
+/**
+ *
+ * Some description
+ *
+ * Abc
+ *
+ *
+ * Def
+ *
+ *
+ *
+ *
+ * @param {string} a
+ */
+// "jsdoc/tag-lines": ["error"|"warn", "any",{"maxBlockLines":2,"startLines":5}]
+// Message: If set to a number, `maxBlockLines` must be greater than or equal to `startLines`.
 ````
 
 
@@ -544,5 +626,17 @@ class _Foo {
   }
 }
 // "jsdoc/tag-lines": ["error"|"warn", "any",{"startLines":1}]
+
+/**
+ *
+ * Some description
+ *
+ * Abc
+ *
+ *
+ * Def
+ * @param {string} a
+ */
+// "jsdoc/tag-lines": ["error"|"warn", "any",{"maxBlockLines":2}]
 ````
 

src/rules.d.ts

@@ -2806,7 +2806,7 @@ export interface Rules {
         }
       ];
 
-  /** Enforces lines (or no lines) between tags. */
+  /** Enforces lines (or no lines) before, after, or between tags. */
   "jsdoc/tag-lines": 
     | []
     | ["always" | "any" | "never"]
@@ -2833,6 +2833,14 @@ export interface Rules {
            * Defaults to `0`.
            */
           endLines?: number | null;
+          /**
+           * If not set to `null`, will enforce a maximum number of lines to the given count anywhere in the block description.
+           *
+           * Note that if non-`null`, `maxBlockLines` must be greater than or equal to `startLines`.
+           *
+           * Defaults to `null`.
+           */
+          maxBlockLines?: number | null;
           /**
            * If not set to `null`, will enforce end lines to the given count before the
            * first tag only, unless there is only whitespace content, in which case,

src/rules/tagLines.js

@@ -1,5 +1,66 @@
 import iterateJsdoc from '../iterateJsdoc.js';
 
+/**
+ * @param {{
+ *   maxBlockLines: null|number,
+ *   startLines: null|number,
+ *   utils: import('../iterateJsdoc.js').Utils
+ * }} cfg
+ */
+const checkMaxBlockLines = ({
+  maxBlockLines,
+  startLines,
+  utils,
+}) => {
+  if (typeof maxBlockLines !== 'number') {
+    return false;
+  }
+
+  if (typeof startLines === 'number' && maxBlockLines < startLines) {
+    utils.reportJSDoc(
+      'If set to a number, `maxBlockLines` must be greater than or equal to `startLines`.',
+    );
+    return true;
+  }
+
+  const {
+    description,
+  } = utils.getDescription();
+  const excessBlockLinesRegex = new RegExp('\n{' + (maxBlockLines + 2) + ',}', 'v');
+  const excessBlockLinesMatch = description.match(excessBlockLinesRegex);
+  const excessBlockLines = excessBlockLinesMatch?.[0]?.length ?? 0;
+  if (excessBlockLinesMatch) {
+    const excessIndexLine = description.slice(0, excessBlockLinesMatch.index).match(/\n/gv)?.length ?? 0;
+    utils.reportJSDoc(
+      `Expected a maximum of ${maxBlockLines} line${maxBlockLines === 1 ? '' : 's'} within block description`,
+      {
+        line: excessIndexLine,
+      },
+      () => {
+        utils.setBlockDescription((info, seedTokens, descLines) => {
+          return [
+            ...descLines.slice(0, excessIndexLine),
+            ...descLines.slice(excessIndexLine + excessBlockLines - 1 - maxBlockLines),
+          ].map((desc) => {
+            return {
+              number: 0,
+              source: '',
+              tokens: seedTokens({
+                ...info,
+                description: desc,
+                postDelimiter: desc.trim() ? ' ' : '',
+              }),
+            };
+          });
+        });
+      },
+    );
+    return true;
+  }
+
+  return false;
+};
+
 export default iterateJsdoc(({
   context,
   jsdoc,
@@ -11,6 +72,7 @@ export default iterateJsdoc(({
       applyToEndTag = true,
       count = 1,
       endLines = 0,
+      maxBlockLines = null,
       startLines = 0,
       tags = {},
     } = {},
@@ -218,6 +280,14 @@ export default iterateJsdoc(({
     return false;
   });
 
+  if (checkMaxBlockLines({
+    maxBlockLines,
+    startLines,
+    utils,
+  })) {
+    return;
+  }
+
   if (typeof startLines === 'number') {
     if (!jsdoc.tags.length) {
       return;
@@ -235,7 +305,7 @@ export default iterateJsdoc(({
     const trailingDiff = (trailingLines ?? 0) - startLines;
     if (trailingDiff > 0) {
       utils.reportJSDoc(
-        `Expected only ${startLines} line after block description`,
+        `Expected only ${startLines} line${startLines === 1 ? '' : 's'} after block description`,
         {
           line: lastDescriptionLine - trailingDiff,
         },
@@ -290,14 +360,14 @@ export default iterateJsdoc(({
   iterateAllJsdocs: true,
   meta: {
     docs: {
-      description: 'Enforces lines (or no lines) between tags.',
+      description: 'Enforces lines (or no lines) before, after, or between tags.',
       url: 'https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/tag-lines.md#repos-sticky-header',
     },
     fixable: 'code',
     schema: [
       {
         description: `Defaults to "never". "any" is only useful with \`tags\` (allowing non-enforcement of lines except
-for particular tags) or with \`startLines\` or \`endLines\`. It is also
+for particular tags) or with \`startLines\`, \`endLines\`, or \`maxBlockLines\`. It is also
 necessary if using the linebreak-setting options of the \`sort-tags\` rule
 so that the two rules won't conflict in both attempting to set lines
 between tags.`,
@@ -335,6 +405,21 @@ Defaults to 1.`,
 final tag only.
 
 Defaults to \`0\`.`,
+          },
+          maxBlockLines: {
+            anyOf: [
+              {
+                type: 'integer',
+              },
+              {
+                type: 'null',
+              },
+            ],
+            description: `If not set to \`null\`, will enforce a maximum number of lines to the given count anywhere in the block description.
+
+Note that if non-\`null\`, \`maxBlockLines\` must be greater than or equal to \`startLines\`.
+
+Defaults to \`null\`.`,
           },
           startLines: {
             anyOf: [