eslint-plugin-jsdoc 59.1.0 → 60.1.0

package/dist/rules.d.ts

@@ -2370,6 +2370,26 @@ export interface Rules {
         }
       ];
 
+  /** Requires tags be present, optionally for specific contexts */
+  "jsdoc/require-tags": 
+    | []
+    | [
+        {
+          /**
+           * May be an array of either strings or objects with
+           * a string `tag` property and `context` string property.
+           */
+          tags?: (
+            | string
+            | {
+                context?: string;
+                tag?: string;
+                [k: string]: unknown;
+              }
+          )[];
+        }
+      ];
+
   /** Requires `@template` tags be present when type parameters are used. */
   "jsdoc/require-template": 
     | []
@@ -2580,26 +2600,6 @@ export interface Rules {
   /** Requires a type for `@yields` tags */
   "jsdoc/require-yields-type": [];
 
-  /** Requires tags be present, optionally for specific contexts */
-  "jsdoc/required-tags": 
-    | []
-    | [
-        {
-          /**
-           * May be an array of either strings or objects with
-           * a string `tag` property and `context` string property.
-           */
-          tags?: (
-            | string
-            | {
-                context?: string;
-                tag?: string;
-                [k: string]: unknown;
-              }
-          )[];
-        }
-      ];
-
   /** Sorts tags by a specified sequence according to tag name, optionally adding line breaks between tag groups. */
   "jsdoc/sort-tags": 
     | []
@@ -2826,7 +2826,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"]
@@ -2853,6 +2853,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,

package/package.json

@@ -172,5 +172,5 @@
     "test-cov": "TIMING=1 c8 --reporter text pnpm run test-no-cov",
     "test-index": "pnpm run test-no-cov test/rules/index.js"
   },
-  "version": "59.1.0"
+  "version": "60.1.0"
 }

package/src/index-cjs.js

@@ -40,7 +40,6 @@ import noUndefinedTypes from './rules/noUndefinedTypes.js';
 import requireAsteriskPrefix from './rules/requireAsteriskPrefix.js';
 import requireDescription from './rules/requireDescription.js';
 import requireDescriptionCompleteSentence from './rules/requireDescriptionCompleteSentence.js';
-import requiredTags from './rules/requiredTags.js';
 import requireExample from './rules/requireExample.js';
 import requireFileOverview from './rules/requireFileOverview.js';
 import requireHyphenBeforeParamDescription from './rules/requireHyphenBeforeParamDescription.js';
@@ -57,6 +56,7 @@ import requireReturns from './rules/requireReturns.js';
 import requireReturnsCheck from './rules/requireReturnsCheck.js';
 import requireReturnsDescription from './rules/requireReturnsDescription.js';
 import requireReturnsType from './rules/requireReturnsType.js';
+import requireTags from './rules/requireTags.js';
 import requireTemplate from './rules/requireTemplate.js';
 import requireThrows from './rules/requireThrows.js';
 import requireYields from './rules/requireYields.js';
@@ -179,6 +179,7 @@ index.rules = {
   'require-returns-check': requireReturnsCheck,
   'require-returns-description': requireReturnsDescription,
   'require-returns-type': requireReturnsType,
+  'require-tags': requireTags,
   'require-template': requireTemplate,
   'require-throws': requireThrows,
   'require-throws-description': buildForbidRuleDefinition({
@@ -227,7 +228,6 @@ index.rules = {
     description: 'Requires a type for `@yields` tags',
     url: 'https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/require-yields-type.md#repos-sticky-header',
   }),
-  'required-tags': requiredTags,
   'sort-tags': sortTags,
   'tag-lines': tagLines,
   'text-escaping': textEscaping,
@@ -306,6 +306,7 @@ const createRecommendedRuleset = (warnOrError, flatName) => {
       'jsdoc/require-returns-check': warnOrError,
       'jsdoc/require-returns-description': warnOrError,
       'jsdoc/require-returns-type': warnOrError,
+      'jsdoc/require-tags': 'off',
       'jsdoc/require-template': 'off',
       'jsdoc/require-throws': 'off',
       'jsdoc/require-throws-description': 'off',
@@ -314,7 +315,6 @@ const createRecommendedRuleset = (warnOrError, flatName) => {
       'jsdoc/require-yields-check': warnOrError,
       'jsdoc/require-yields-description': 'off',
       'jsdoc/require-yields-type': warnOrError,
-      'jsdoc/required-tags': 'off',
       'jsdoc/sort-tags': 'off',
       'jsdoc/tag-lines': warnOrError,
       'jsdoc/text-escaping': 'off',

package/src/index.js

@@ -46,7 +46,6 @@ import noUndefinedTypes from './rules/noUndefinedTypes.js';
 import requireAsteriskPrefix from './rules/requireAsteriskPrefix.js';
 import requireDescription from './rules/requireDescription.js';
 import requireDescriptionCompleteSentence from './rules/requireDescriptionCompleteSentence.js';
-import requiredTags from './rules/requiredTags.js';
 import requireExample from './rules/requireExample.js';
 import requireFileOverview from './rules/requireFileOverview.js';
 import requireHyphenBeforeParamDescription from './rules/requireHyphenBeforeParamDescription.js';
@@ -63,6 +62,7 @@ import requireReturns from './rules/requireReturns.js';
 import requireReturnsCheck from './rules/requireReturnsCheck.js';
 import requireReturnsDescription from './rules/requireReturnsDescription.js';
 import requireReturnsType from './rules/requireReturnsType.js';
+import requireTags from './rules/requireTags.js';
 import requireTemplate from './rules/requireTemplate.js';
 import requireThrows from './rules/requireThrows.js';
 import requireYields from './rules/requireYields.js';
@@ -185,6 +185,7 @@ index.rules = {
   'require-returns-check': requireReturnsCheck,
   'require-returns-description': requireReturnsDescription,
   'require-returns-type': requireReturnsType,
+  'require-tags': requireTags,
   'require-template': requireTemplate,
   'require-throws': requireThrows,
   'require-throws-description': buildForbidRuleDefinition({
@@ -233,7 +234,6 @@ index.rules = {
     description: 'Requires a type for `@yields` tags',
     url: 'https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/require-yields-type.md#repos-sticky-header',
   }),
-  'required-tags': requiredTags,
   'sort-tags': sortTags,
   'tag-lines': tagLines,
   'text-escaping': textEscaping,
@@ -312,6 +312,7 @@ const createRecommendedRuleset = (warnOrError, flatName) => {
       'jsdoc/require-returns-check': warnOrError,
       'jsdoc/require-returns-description': warnOrError,
       'jsdoc/require-returns-type': warnOrError,
+      'jsdoc/require-tags': 'off',
       'jsdoc/require-template': 'off',
       'jsdoc/require-throws': 'off',
       'jsdoc/require-throws-description': 'off',
@@ -320,7 +321,6 @@ const createRecommendedRuleset = (warnOrError, flatName) => {
       'jsdoc/require-yields-check': warnOrError,
       'jsdoc/require-yields-description': 'off',
       'jsdoc/require-yields-type': warnOrError,
-      'jsdoc/required-tags': 'off',
       'jsdoc/sort-tags': 'off',
       'jsdoc/tag-lines': warnOrError,
       'jsdoc/text-escaping': 'off',

package/src/rules/{requiredTags.js → requireTags.js}

@@ -7,7 +7,7 @@ export default buildForbidRuleDefinition({
   getContexts (context, report) {
     // Transformed options to this option in `modifyContext`:
     if (!context.options[0].contexts) {
-      report('Rule `required-tags` is missing a `tags` option.');
+      report('Rule `require-tags` is missing a `tags` option.');
       return false;
     }
 
@@ -81,5 +81,5 @@ a string \`tag\` property and \`context\` string property.`,
       type: 'object',
     },
   ],
-  url: 'https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/required-tags.md#repos-sticky-header',
+  url: 'https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/require-tags.md#repos-sticky-header',
 });

package/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: [

package/src/rules.d.ts

@@ -2370,6 +2370,26 @@ export interface Rules {
         }
       ];
 
+  /** Requires tags be present, optionally for specific contexts */
+  "jsdoc/require-tags": 
+    | []
+    | [
+        {
+          /**
+           * May be an array of either strings or objects with
+           * a string `tag` property and `context` string property.
+           */
+          tags?: (
+            | string
+            | {
+                context?: string;
+                tag?: string;
+                [k: string]: unknown;
+              }
+          )[];
+        }
+      ];
+
   /** Requires `@template` tags be present when type parameters are used. */
   "jsdoc/require-template": 
     | []
@@ -2580,26 +2600,6 @@ export interface Rules {
   /** Requires a type for `@yields` tags */
   "jsdoc/require-yields-type": [];
 
-  /** Requires tags be present, optionally for specific contexts */
-  "jsdoc/required-tags": 
-    | []
-    | [
-        {
-          /**
-           * May be an array of either strings or objects with
-           * a string `tag` property and `context` string property.
-           */
-          tags?: (
-            | string
-            | {
-                context?: string;
-                tag?: string;
-                [k: string]: unknown;
-              }
-          )[];
-        }
-      ];
-
   /** Sorts tags by a specified sequence according to tag name, optionally adding line breaks between tag groups. */
   "jsdoc/sort-tags": 
     | []
@@ -2826,7 +2826,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"]
@@ -2853,6 +2853,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,

package/dist/rules/requiredTags.cjs.map

@@ -1 +0,0 @@
-{"version":3,"file":"requiredTags.cjs","names":["_buildForbidRuleDefinition","require","_default","exports","default","buildForbidRuleDefinition","description","getContexts","context","report","options","contexts","modifyContext","tags","cntxts","map","tag","tagName","comment","message","propertyDescriptors","Object","getOwnPropertyDescriptors","create","getPrototypeOf","value","schema","additionalProperties","properties","items","anyOf","type","url","module"],"sources":["../../src/rules/requiredTags.js"],"sourcesContent":["import {\n  buildForbidRuleDefinition,\n} from '../buildForbidRuleDefinition.js';\n\nexport default buildForbidRuleDefinition({\n  description: 'Requires tags be present, optionally for specific contexts',\n  getContexts (context, report) {\n    // Transformed options to this option in `modifyContext`:\n    if (!context.options[0].contexts) {\n      report('Rule `required-tags` is missing a `tags` option.');\n      return false;\n    }\n\n    const {\n      contexts,\n    } = context.options[0];\n\n    return contexts;\n  },\n  modifyContext (context) {\n    const tags = /** @type {(string|{tag: string, context: string})[]} */ (\n      context.options?.[0]?.tags\n    );\n\n    const cntxts = tags?.map((tag) => {\n      const tagName = typeof tag === 'string' ? tag : tag.tag;\n      return {\n        comment: `JsdocBlock:not(*:has(JsdocTag[tag=${\n          tagName\n        }]))`,\n        context: typeof tag === 'string' ? 'any' : tag.context,\n        message: `Missing required tag \"${tagName}\"`,\n      };\n    });\n\n    // Reproduce context object with our own `contexts`\n    const propertyDescriptors = Object.getOwnPropertyDescriptors(context);\n    return Object.create(\n      Object.getPrototypeOf(context),\n      {\n        ...propertyDescriptors,\n        options: {\n          ...propertyDescriptors.options,\n          value: [\n            {\n              contexts: cntxts,\n            },\n          ],\n        },\n      },\n    );\n  },\n  schema: [\n    {\n      additionalProperties: false,\n      properties: {\n        tags: {\n          description: `May be an array of either strings or objects with\na string \\`tag\\` property and \\`context\\` string property.`,\n          items: {\n            anyOf: [\n              {\n                type: 'string',\n              },\n              {\n                properties: {\n                  context: {\n                    type: 'string',\n                  },\n                  tag: {\n                    type: 'string',\n                  },\n                },\n                type: 'object',\n              },\n            ],\n          },\n          type: 'array',\n        },\n      },\n      type: 'object',\n    },\n  ],\n  url: 'https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/required-tags.md#repos-sticky-header',\n});\n"],"mappings":";;;;;;AAAA,IAAAA,0BAAA,GAAAC,OAAA;AAEyC,IAAAC,QAAA,GAAAC,OAAA,CAAAC,OAAA,GAE1B,IAAAC,oDAAyB,EAAC;EACvCC,WAAW,EAAE,4DAA4D;EACzEC,WAAWA,CAAEC,OAAO,EAAEC,MAAM,EAAE;IAC5B;IACA,IAAI,CAACD,OAAO,CAACE,OAAO,CAAC,CAAC,CAAC,CAACC,QAAQ,EAAE;MAChCF,MAAM,CAAC,kDAAkD,CAAC;MAC1D,OAAO,KAAK;IACd;IAEA,MAAM;MACJE;IACF,CAAC,GAAGH,OAAO,CAACE,OAAO,CAAC,CAAC,CAAC;IAEtB,OAAOC,QAAQ;EACjB,CAAC;EACDC,aAAaA,CAAEJ,OAAO,EAAE;IACtB,MAAMK,IAAI,GAAG;IACXL,OAAO,CAACE,OAAO,GAAG,CAAC,CAAC,EAAEG,IACvB;IAED,MAAMC,MAAM,GAAGD,IAAI,EAAEE,GAAG,CAAEC,GAAG,IAAK;MAChC,MAAMC,OAAO,GAAG,OAAOD,GAAG,KAAK,QAAQ,GAAGA,GAAG,GAAGA,GAAG,CAACA,GAAG;MACvD,OAAO;QACLE,OAAO,EAAE,qCACPD,OAAO,KACJ;QACLT,OAAO,EAAE,OAAOQ,GAAG,KAAK,QAAQ,GAAG,KAAK,GAAGA,GAAG,CAACR,OAAO;QACtDW,OAAO,EAAE,yBAAyBF,OAAO;MAC3C,CAAC;IACH,CAAC,CAAC;;IAEF;IACA,MAAMG,mBAAmB,GAAGC,MAAM,CAACC,yBAAyB,CAACd,OAAO,CAAC;IACrE,OAAOa,MAAM,CAACE,MAAM,CAClBF,MAAM,CAACG,cAAc,CAAChB,OAAO,CAAC,EAC9B;MACE,GAAGY,mBAAmB;MACtBV,OAAO,EAAE;QACP,GAAGU,mBAAmB,CAACV,OAAO;QAC9Be,KAAK,EAAE,CACL;UACEd,QAAQ,EAAEG;QACZ,CAAC;MAEL;IACF,CACF,CAAC;EACH,CAAC;EACDY,MAAM,EAAE,CACN;IACEC,oBAAoB,EAAE,KAAK;IAC3BC,UAAU,EAAE;MACVf,IAAI,EAAE;QACJP,WAAW,EAAE;AACvB,2DAA2D;QACjDuB,KAAK,EAAE;UACLC,KAAK,EAAE,CACL;YACEC,IAAI,EAAE;UACR,CAAC,EACD;YACEH,UAAU,EAAE;cACVpB,OAAO,EAAE;gBACPuB,IAAI,EAAE;cACR,CAAC;cACDf,GAAG,EAAE;gBACHe,IAAI,EAAE;cACR;YACF,CAAC;YACDA,IAAI,EAAE;UACR,CAAC;QAEL,CAAC;QACDA,IAAI,EAAE;MACR;IACF,CAAC;IACDA,IAAI,EAAE;EACR,CAAC,CACF;EACDC,GAAG,EAAE;AACP,CAAC,CAAC;AAAAC,MAAA,CAAA9B,OAAA,GAAAA,OAAA,CAAAC,OAAA","ignoreList":[]}