eslint-plugin-jsdoc 47.0.2 → 48.0.1

package/src/rules/multilineBlocks.js

@@ -0,0 +1,333 @@
+import iterateJsdoc from '../iterateJsdoc.js';
+
+export default iterateJsdoc(({
+  context,
+  jsdoc,
+  utils,
+}) => {
+  const {
+    allowMultipleTags = true,
+    noFinalLineText = true,
+    noZeroLineText = true,
+    noSingleLineBlocks = false,
+    singleLineTags = [
+      'lends', 'type',
+    ],
+    noMultilineBlocks = false,
+    minimumLengthForMultiline = Number.POSITIVE_INFINITY,
+    multilineTags = [
+      '*',
+    ],
+  } = 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;
+  }
+
+  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,
+                tag: tg,
+                type: typ,
+                name: nme,
+                lineEnd,
+                postType,
+                postName,
+                postTag,
+              },
+            }) => {
+              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',
+          },
+          singleLineTags: {
+            items: {
+              type: 'string',
+            },
+            type: 'array',
+          },
+        },
+        type: 'object',
+      },
+    ],
+    type: 'suggestion',
+  },
+});

package/src/rules/noBadBlocks.js

@@ -0,0 +1,109 @@
+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 = /^\/\*(?!\*)/u;
+const extraAsteriskCommentRegexp = /^\/\*{3,}/u;
+
+export default iterateJsdoc(({
+  context,
+  sourceCode,
+  allComments,
+  makeReport,
+}) => {
+  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);
+    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*$/u;
+const atLeastTwoLinesWhitespace = /^[ \t]*\n[ \t]*\n\s*$/u;
+
+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',
+  },
+});

package/src/rules/noBlankBlocks.js

@@ -0,0 +1,53 @@
+import iterateJsdoc from '../iterateJsdoc.js';
+
+export default iterateJsdoc(({
+  context,
+  jsdoc,
+  utils,
+}) => {
+  if (jsdoc.tags.length) {
+    return;
+  }
+
+  const {
+    description,
+    lastDescriptionLine,
+  } = utils.getDescription();
+  if (description.trim()) {
+    return;
+  }
+
+  const {
+    enableFixer,
+  } = context.options[0] || {};
+
+  utils.reportJSDoc(
+    'No empty blocks',
+    {
+      line: lastDescriptionLine,
+    },
+    enableFixer ? () => {
+      jsdoc.source.splice(0, jsdoc.source.length);
+    } : null,
+  );
+}, {
+  iterateAllJsdocs: true,
+  meta: {
+    docs: {
+      description: 'Removes empty blocks with nothing but possibly line breaks',
+      url: 'https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/no-blank-blocks.md#repos-sticky-header',
+    },
+    fixable: 'code',
+    schema: [
+      {
+        additionalProperties: false,
+        properties: {
+          enableFixer: {
+            type: 'boolean',
+          },
+        },
+      },
+    ],
+    type: 'suggestion',
+  },
+});

package/src/rules/noDefaults.js

@@ -0,0 +1,85 @@
+import iterateJsdoc from '../iterateJsdoc.js';
+
+export default iterateJsdoc(({
+  context,
+  utils,
+}) => {
+  const {
+    noOptionalParamNames,
+  } = context.options[0] || {};
+  const paramTags = utils.getPresentTags([
+    'param', 'arg', 'argument',
+  ]);
+  for (const tag of paramTags) {
+    if (noOptionalParamNames && tag.optional) {
+      utils.reportJSDoc(`Optional param names are not permitted on @${tag.tag}.`, tag, () => {
+        utils.changeTag(tag, {
+          name: tag.name.replace(/([^=]*)(=.+)?/u, '$1'),
+        });
+      });
+    } else if (tag.default) {
+      utils.reportJSDoc(`Defaults are not permitted on @${tag.tag}.`, tag, () => {
+        utils.changeTag(tag, {
+          name: tag.name.replace(/([^=]*)(=.+)?/u, '[$1]'),
+        });
+      });
+    }
+  }
+
+  const defaultTags = utils.getPresentTags([
+    'default', 'defaultvalue',
+  ]);
+  for (const tag of defaultTags) {
+    if (tag.description.trim()) {
+      utils.reportJSDoc(`Default values are not permitted on @${tag.tag}.`, tag, () => {
+        utils.changeTag(tag, {
+          description: '',
+          postTag: '',
+        });
+      });
+    }
+  }
+}, {
+  contextDefaults: true,
+  meta: {
+    docs: {
+      description: 'This rule reports defaults being used on the relevant portion of `@param` or `@default`.',
+      url: 'https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/no-defaults.md#repos-sticky-header',
+    },
+    fixable: 'code',
+    schema: [
+      {
+        additionalProperties: false,
+        properties: {
+          contexts: {
+            items: {
+              anyOf: [
+                {
+                  type: 'string',
+                },
+                {
+                  additionalProperties: false,
+                  properties: {
+                    comment: {
+                      type: 'string',
+                    },
+                    context: {
+                      type: 'string',
+                    },
+                  },
+                  type: 'object',
+                },
+              ],
+            },
+            type: 'array',
+          },
+          noOptionalParamNames: {
+            type: 'boolean',
+          },
+        },
+        type: 'object',
+      },
+    ],
+    type: 'suggestion',
+  },
+});