eslint-plugin-jsdoc 53.0.1 → 54.1.0

package/src/rules/multilineBlocks.js

@@ -0,0 +1,493 @@
+import iterateJsdoc from '../iterateJsdoc.js';
+
+/**
+ * @param {import('@es-joy/jsdoccomment').JsdocBlockWithInline} jsdoc
+ * @param {import('../iterateJsdoc.js').Utils} utils
+ * @param {number} requireSingleLineUnderCount
+ */
+const checkForShortTags = (jsdoc, utils, requireSingleLineUnderCount) => {
+  if (!requireSingleLineUnderCount || !jsdoc.tags.length) {
+    return false;
+  }
+
+  let lastLineWithTag = 0;
+  let isUnderCountLimit = false;
+  let hasMultiDescOrType = false;
+  const tagLines = jsdoc.source.reduce((acc, {
+    tokens: {
+      delimiter,
+      description: desc,
+      name,
+      postDelimiter,
+      postName,
+      postTag,
+      postType,
+      start,
+      tag,
+      type,
+    },
+  }, idx) => {
+    if (tag.length) {
+      lastLineWithTag = idx;
+      if (
+        start.length + delimiter.length + postDelimiter.length +
+        type.length + postType.length + name.length + postName.length +
+        tag.length + postTag.length + desc.length <
+          requireSingleLineUnderCount
+      ) {
+        isUnderCountLimit = true;
+      }
+
+      return acc + 1;
+    } else if (desc.length || type.length) {
+      hasMultiDescOrType = true;
+      return acc;
+    }
+
+    return acc;
+  }, 0);
+  // Could be tagLines > 1
+  if (!hasMultiDescOrType && isUnderCountLimit && tagLines === 1) {
+    const fixer = () => {
+      const tokens = jsdoc.source[lastLineWithTag].tokens;
+      jsdoc.source = [
+        {
+          number: 0,
+          source: '',
+          tokens: utils.seedTokens({
+            delimiter: '/**',
+            description: tokens.description.trimEnd() + ' ',
+            end: '*/',
+            name: tokens.name,
+            postDelimiter: ' ',
+            postName: tokens.postName,
+            postTag: tokens.postTag,
+            postType: tokens.postType,
+            start: jsdoc.source[0].tokens.start,
+            tag: tokens.tag,
+            type: tokens.type,
+          }),
+        },
+      ];
+    };
+
+    utils.reportJSDoc(
+      'Description is too short to be multi-line.',
+      null,
+      fixer,
+    );
+    return true;
+  }
+
+  return false;
+};
+
+/**
+ * @param {import('@es-joy/jsdoccomment').JsdocBlockWithInline} jsdoc
+ * @param {import('../iterateJsdoc.js').Utils} utils
+ * @param {number} requireSingleLineUnderCount
+ */
+const checkForShortDescriptions = (jsdoc, utils, requireSingleLineUnderCount) => {
+  if (!requireSingleLineUnderCount || jsdoc.tags.length) {
+    return false;
+  }
+
+  let lastLineWithDesc = 0;
+  let isUnderCountLimit = false;
+  const descLines = jsdoc.source.reduce((acc, {
+    tokens: {
+      delimiter,
+      description: desc,
+      postDelimiter,
+      start,
+    },
+  }, idx) => {
+    if (desc.length) {
+      lastLineWithDesc = idx;
+      if (
+        start.length + delimiter.length + postDelimiter.length + desc.length <
+          requireSingleLineUnderCount
+      ) {
+        isUnderCountLimit = true;
+      }
+
+      return acc + 1;
+    }
+
+    return acc;
+  }, 0);
+  // Could be descLines > 1
+  if (isUnderCountLimit && descLines === 1) {
+    const fixer = () => {
+      const desc = jsdoc.source[lastLineWithDesc].tokens.description;
+      jsdoc.source = [
+        {
+          number: 0,
+          source: '',
+          tokens: utils.seedTokens({
+            delimiter: '/**',
+            description: desc.trimEnd() + ' ',
+            end: '*/',
+            postDelimiter: ' ',
+            start: jsdoc.source[0].tokens.start,
+          }),
+        },
+      ];
+    };
+
+    utils.reportJSDoc(
+      'Description is too short to be multi-line.',
+      null,
+      fixer,
+    );
+    return true;
+  }
+
+  return false;
+};
+
+export default iterateJsdoc(({
+  context,
+  jsdoc,
+  utils,
+}) => {
+  const {
+    allowMultipleTags = true,
+    minimumLengthForMultiline = Number.POSITIVE_INFINITY,
+    multilineTags = [
+      '*',
+    ],
+    noFinalLineText = true,
+    noMultilineBlocks = false,
+    noSingleLineBlocks = false,
+    noZeroLineText = true,
+    requireSingleLineUnderCount = null,
+    singleLineTags = [
+      'lends', 'type',
+    ],
+  } = context.options[0] || {};
+
+  const {
+    source: [
+      {
+        tokens,
+      },
+    ],
+  } = jsdoc;
+  const {
+    description,
+    tag,
+  } = tokens;
+  const sourceLength = jsdoc.source.length;
+
+  /**
+   * @param {string} tagName
+   * @returns {boolean}
+   */
+  const isInvalidSingleLine = (tagName) => {
+    return noSingleLineBlocks &&
+      (!tagName ||
+      !singleLineTags.includes(tagName) && !singleLineTags.includes('*'));
+  };
+
+  if (sourceLength === 1) {
+    if (!isInvalidSingleLine(tag.slice(1))) {
+      return;
+    }
+
+    const fixer = () => {
+      utils.makeMultiline();
+    };
+
+    utils.reportJSDoc(
+      'Single line blocks are not permitted by your configuration.',
+      null,
+      fixer,
+      true,
+    );
+
+    return;
+  }
+
+  if (checkForShortDescriptions(jsdoc, utils, requireSingleLineUnderCount)
+  ) {
+    return;
+  }
+
+  if (checkForShortTags(jsdoc, utils, requireSingleLineUnderCount)
+  ) {
+    return;
+  }
+
+  const lineChecks = () => {
+    if (
+      noZeroLineText &&
+      (tag || description)
+    ) {
+      const fixer = () => {
+        const line = {
+          ...tokens,
+        };
+        utils.emptyTokens(tokens);
+        const {
+          tokens: {
+            delimiter,
+            start,
+          },
+        } = jsdoc.source[1];
+        utils.addLine(1, {
+          ...line,
+          delimiter,
+          start,
+        });
+      };
+
+      utils.reportJSDoc(
+        'Should have no text on the "0th" line (after the `/**`).',
+        null,
+        fixer,
+      );
+
+      return;
+    }
+
+    const finalLine = jsdoc.source[jsdoc.source.length - 1];
+    const finalLineTokens = finalLine.tokens;
+    if (
+      noFinalLineText &&
+      finalLineTokens.description.trim()
+    ) {
+      const fixer = () => {
+        const line = {
+          ...finalLineTokens,
+        };
+        line.description = line.description.trimEnd();
+
+        const {
+          delimiter,
+        } = line;
+
+        for (const prop of [
+          'delimiter',
+          'postDelimiter',
+          'tag',
+          'type',
+          'lineEnd',
+          'postType',
+          'postTag',
+          'name',
+          'postName',
+          'description',
+        ]) {
+          finalLineTokens[
+            /**
+             * @type {"delimiter"|"postDelimiter"|"tag"|"type"|
+             *   "lineEnd"|"postType"|"postTag"|"name"|
+             *   "postName"|"description"}
+             */ (
+              prop
+            )
+          ] = '';
+        }
+
+        utils.addLine(jsdoc.source.length - 1, {
+          ...line,
+          delimiter,
+          end: '',
+        });
+      };
+
+      utils.reportJSDoc(
+        'Should have no text on the final line (before the `*/`).',
+        null,
+        fixer,
+      );
+    }
+  };
+
+  if (noMultilineBlocks) {
+    if (
+      jsdoc.tags.length &&
+      (multilineTags.includes('*') || utils.hasATag(multilineTags))
+    ) {
+      lineChecks();
+
+      return;
+    }
+
+    if (jsdoc.description.length >= minimumLengthForMultiline) {
+      lineChecks();
+
+      return;
+    }
+
+    if (
+      noSingleLineBlocks &&
+      (!jsdoc.tags.length ||
+      !utils.filterTags(({
+        tag: tg,
+      }) => {
+        return !isInvalidSingleLine(tg);
+      }).length)
+    ) {
+      utils.reportJSDoc(
+        'Multiline jsdoc blocks are prohibited by ' +
+          'your configuration but fixing would result in a single ' +
+          'line block which you have prohibited with `noSingleLineBlocks`.',
+      );
+
+      return;
+    }
+
+    if (jsdoc.tags.length > 1) {
+      if (!allowMultipleTags) {
+        utils.reportJSDoc(
+          'Multiline jsdoc blocks are prohibited by ' +
+            'your configuration but the block has multiple tags.',
+        );
+
+        return;
+      }
+    } else if (jsdoc.tags.length === 1 && jsdoc.description.trim()) {
+      if (!allowMultipleTags) {
+        utils.reportJSDoc(
+          'Multiline jsdoc blocks are prohibited by ' +
+            'your configuration but the block has a description with a tag.',
+        );
+
+        return;
+      }
+    } else {
+      const fixer = () => {
+        jsdoc.source = [
+          {
+            number: 1,
+            source: '',
+            tokens: jsdoc.source.reduce((obj, {
+              tokens: {
+                description: desc,
+                lineEnd,
+                name: nme,
+                postName,
+                postTag,
+                postType,
+                tag: tg,
+                type: typ,
+              },
+            }) => {
+              if (typ) {
+                obj.type = typ;
+              }
+
+              if (tg && typ && nme) {
+                obj.postType = postType;
+              }
+
+              if (nme) {
+                obj.name += nme;
+              }
+
+              if (nme && desc) {
+                obj.postName = postName;
+              }
+
+              obj.description += desc;
+
+              const nameOrDescription = obj.description || obj.name;
+              if (
+                nameOrDescription && nameOrDescription.slice(-1) !== ' '
+              ) {
+                obj.description += ' ';
+              }
+
+              obj.lineEnd = lineEnd;
+
+              // Already filtered for multiple tags
+              obj.tag += tg;
+              if (tg) {
+                obj.postTag = postTag || ' ';
+              }
+
+              return obj;
+            }, utils.seedTokens({
+              delimiter: '/**',
+              end: '*/',
+              postDelimiter: ' ',
+            })),
+          },
+        ];
+      };
+
+      utils.reportJSDoc(
+        'Multiline jsdoc blocks are prohibited by ' +
+          'your configuration.',
+        null,
+        fixer,
+      );
+
+      return;
+    }
+  }
+
+  lineChecks();
+}, {
+  iterateAllJsdocs: true,
+  meta: {
+    docs: {
+      description: 'Controls how and whether jsdoc blocks can be expressed as single or multiple line blocks.',
+      url: 'https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/multiline-blocks.md#repos-sticky-header',
+    },
+    fixable: 'code',
+    schema: [
+      {
+        additionalProperties: false,
+        properties: {
+          allowMultipleTags: {
+            type: 'boolean',
+          },
+          minimumLengthForMultiline: {
+            type: 'integer',
+          },
+          multilineTags: {
+            anyOf: [
+              {
+                enum: [
+                  '*',
+                ],
+                type: 'string',
+              }, {
+                items: {
+                  type: 'string',
+                },
+                type: 'array',
+              },
+            ],
+          },
+          noFinalLineText: {
+            type: 'boolean',
+          },
+          noMultilineBlocks: {
+            type: 'boolean',
+          },
+          noSingleLineBlocks: {
+            type: 'boolean',
+          },
+          noZeroLineText: {
+            type: 'boolean',
+          },
+          requireSingleLineUnderCount: {
+            type: 'number',
+          },
+          singleLineTags: {
+            items: {
+              type: 'string',
+            },
+            type: 'array',
+          },
+        },
+        type: 'object',
+      },
+    ],
+    type: 'suggestion',
+  },
+});

package/src/rules/noBadBlocks.js

@@ -0,0 +1,119 @@
+import iterateJsdoc from '../iterateJsdoc.js';
+import {
+  parse as commentParser,
+} from 'comment-parser';
+
+// Neither a single nor 3+ asterisks are valid jsdoc per
+//  https://jsdoc.app/about-getting-started.html#adding-documentation-comments-to-your-code
+const commentRegexp = /^\/\*(?!\*)/v;
+const extraAsteriskCommentRegexp = /^\/\*{3,}/v;
+
+export default iterateJsdoc(({
+  allComments,
+  context,
+  makeReport,
+  sourceCode,
+}) => {
+  const [
+    {
+      ignore = [
+        'ts-check',
+        'ts-expect-error',
+        'ts-ignore',
+        'ts-nocheck',
+      ],
+      preventAllMultiAsteriskBlocks = false,
+    } = {},
+  ] = context.options;
+
+  let extraAsterisks = false;
+  const nonJsdocNodes = /** @type {import('estree').Node[]} */ (
+    allComments
+  ).filter((comment) => {
+    const commentText = sourceCode.getText(comment);
+
+    const initialText = commentText.replace(commentRegexp, '').trimStart();
+    if ([
+      'eslint',
+    ].some((directive) => {
+      return initialText.startsWith(directive);
+    })) {
+      return false;
+    }
+
+    let sliceIndex = 2;
+    if (!commentRegexp.test(commentText)) {
+      const multiline = extraAsteriskCommentRegexp.exec(commentText)?.[0];
+      if (!multiline) {
+        return false;
+      }
+
+      sliceIndex = multiline.length;
+      extraAsterisks = true;
+      if (preventAllMultiAsteriskBlocks) {
+        return true;
+      }
+    }
+
+    const tags = (commentParser(
+      `${commentText.slice(0, 2)}*${commentText.slice(sliceIndex)}`,
+    )[0] || {}).tags ?? [];
+
+    return tags.length && !tags.some(({
+      tag,
+    }) => {
+      return ignore.includes(tag);
+    });
+  });
+
+  if (!nonJsdocNodes.length) {
+    return;
+  }
+
+  for (const node of nonJsdocNodes) {
+    const report = /** @type {import('../iterateJsdoc.js').MakeReport} */ (
+      makeReport
+    )(context, node);
+
+    // eslint-disable-next-line no-loop-func
+    const fix = /** @type {import('eslint').Rule.ReportFixer} */ (fixer) => {
+      const text = sourceCode.getText(node);
+
+      return fixer.replaceText(
+        node,
+        extraAsterisks ?
+          text.replace(extraAsteriskCommentRegexp, '/**') :
+          text.replace('/*', '/**'),
+      );
+    };
+
+    report('Expected JSDoc-like comment to begin with two asterisks.', fix);
+  }
+}, {
+  checkFile: true,
+  meta: {
+    docs: {
+      description: 'This rule checks for multi-line-style comments which fail to meet the criteria of a jsdoc block.',
+      url: 'https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/no-bad-blocks.md#repos-sticky-header',
+    },
+    fixable: 'code',
+    schema: [
+      {
+        additionalProperties: false,
+        properties: {
+          ignore: {
+            items: {
+              type: 'string',
+            },
+            type: 'array',
+          },
+          preventAllMultiAsteriskBlocks: {
+            type: 'boolean',
+          },
+        },
+        type: 'object',
+      },
+    ],
+    type: 'layout',
+  },
+});

package/src/rules/noBlankBlockDescriptions.js

@@ -0,0 +1,69 @@
+import iterateJsdoc from '../iterateJsdoc.js';
+
+const anyWhitespaceLines = /^\s*$/v;
+const atLeastTwoLinesWhitespace = /^[ \t]*\n[ \t]*\n\s*$/v;
+
+export default iterateJsdoc(({
+  jsdoc,
+  utils,
+}) => {
+  const {
+    description,
+    descriptions,
+    lastDescriptionLine,
+  } = utils.getDescription();
+
+  const regex = jsdoc.tags.length ?
+    anyWhitespaceLines :
+    atLeastTwoLinesWhitespace;
+
+  if (descriptions.length && regex.test(description)) {
+    if (jsdoc.tags.length) {
+      utils.reportJSDoc(
+        'There should be no blank lines in block descriptions followed by tags.',
+        {
+          line: lastDescriptionLine,
+        },
+        () => {
+          utils.setBlockDescription(() => {
+            // Remove all lines
+            return [];
+          });
+        },
+      );
+    } else {
+      utils.reportJSDoc(
+        'There should be no extra blank lines in block descriptions not followed by tags.',
+        {
+          line: lastDescriptionLine,
+        },
+        () => {
+          utils.setBlockDescription((info, seedTokens) => {
+            return [
+              // Keep the starting line
+              {
+                number: 0,
+                source: '',
+                tokens: seedTokens({
+                  ...info,
+                  description: '',
+                }),
+              },
+            ];
+          });
+        },
+      );
+    }
+  }
+}, {
+  iterateAllJsdocs: true,
+  meta: {
+    docs: {
+      description: 'Detects and removes extra lines of a blank block description',
+      url: 'https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/no-blank-block-descriptions.md#repos-sticky-header',
+    },
+    fixable: 'whitespace',
+    schema: [],
+    type: 'layout',
+  },
+});