eslint-plugin-jsdoc 52.0.4 → 53.0.0

package/src/rules/requireAsteriskPrefix.js

@@ -1,190 +0,0 @@
-import iterateJsdoc from '../iterateJsdoc.js';
-
-export default iterateJsdoc(({
-  context,
-  indent,
-  jsdoc,
-  utils,
-}) => {
-  const [
-    defaultRequireValue = 'always',
-    {
-      tags: tagMap = {},
-    } = {},
-  ] = context.options;
-
-  const {
-    source,
-  } = jsdoc;
-
-  const always = defaultRequireValue === 'always';
-  const never = defaultRequireValue === 'never';
-
-  /** @type {string} */
-  let currentTag;
-  source.some(({
-    number,
-    tokens,
-  }) => {
-    const {
-      delimiter,
-      description,
-      end,
-      tag,
-    } = tokens;
-
-    /**
-     * @returns {void}
-     */
-    const neverFix = () => {
-      tokens.delimiter = '';
-      tokens.postDelimiter = '';
-    };
-
-    /**
-     * @param {string} checkValue
-     * @returns {boolean}
-     */
-    const checkNever = (checkValue) => {
-      if (delimiter && delimiter !== '/**' && (
-        never && !tagMap.always?.includes(checkValue) ||
-        tagMap.never?.includes(checkValue)
-      )) {
-        utils.reportJSDoc('Expected JSDoc line to have no prefix.', {
-          column: 0,
-          line: number,
-        }, neverFix);
-
-        return true;
-      }
-
-      return false;
-    };
-
-    /**
-     * @returns {void}
-     */
-    const alwaysFix = () => {
-      if (!tokens.start) {
-        tokens.start = indent + ' ';
-      }
-
-      tokens.delimiter = '*';
-      tokens.postDelimiter = tag || description ? ' ' : '';
-    };
-
-    /**
-     * @param {string} checkValue
-     * @returns {boolean}
-     */
-    const checkAlways = (checkValue) => {
-      if (
-        !delimiter && (
-          always && !tagMap.never?.includes(checkValue) ||
-          tagMap.always?.includes(checkValue)
-        )
-      ) {
-        utils.reportJSDoc('Expected JSDoc line to have the prefix.', {
-          column: 0,
-          line: number,
-        }, alwaysFix);
-
-        return true;
-      }
-
-      return false;
-    };
-
-    if (tag) {
-      // Remove at sign
-      currentTag = tag.slice(1);
-    }
-
-    if (
-      // If this is the end but has a tag, the delimiter will also be
-      //  populated and will be safely ignored later
-      end && !tag
-    ) {
-      return false;
-    }
-
-    if (!currentTag) {
-      if (tagMap.any?.includes('*description')) {
-        return false;
-      }
-
-      if (checkNever('*description')) {
-        return true;
-      }
-
-      if (checkAlways('*description')) {
-        return true;
-      }
-
-      return false;
-    }
-
-    if (tagMap.any?.includes(currentTag)) {
-      return false;
-    }
-
-    if (checkNever(currentTag)) {
-      return true;
-    }
-
-    if (checkAlways(currentTag)) {
-      return true;
-    }
-
-    return false;
-  });
-}, {
-  iterateAllJsdocs: true,
-  meta: {
-    docs: {
-      description:
-        'Requires that each JSDoc line starts with an `*`.',
-      url: 'https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/require-asterisk-prefix.md#repos-sticky-header',
-    },
-    fixable: 'code',
-    schema: [
-      {
-        enum: [
-          'always', 'never', 'any',
-        ],
-        type: 'string',
-      },
-      {
-        additionalProperties: false,
-        properties: {
-          tags: {
-            additionalProperties: false,
-            properties: {
-              always: {
-                items: {
-                  type: 'string',
-                },
-                type: 'array',
-              },
-              any: {
-                items: {
-                  type: 'string',
-                },
-                type: 'array',
-              },
-              never: {
-                items: {
-                  type: 'string',
-                },
-                type: 'array',
-              },
-            },
-            type: 'object',
-          },
-        },
-        type: 'object',
-      },
-    ],
-    type: 'layout',
-  },
-});

package/src/rules/requireDescription.js

@@ -1,161 +0,0 @@
-import iterateJsdoc from '../iterateJsdoc.js';
-
-/**
- * @param {string} description
- * @returns {import('../iterateJsdoc.js').Integer}
- */
-const checkDescription = (description) => {
-  return description
-    .trim()
-    .split('\n')
-    .filter(Boolean)
-    .length;
-};
-
-export default iterateJsdoc(({
-  context,
-  jsdoc,
-  report,
-  utils,
-}) => {
-  if (utils.avoidDocs()) {
-    return;
-  }
-
-  const {
-    descriptionStyle = 'body',
-  } = context.options[0] || {};
-
-  let targetTagName = utils.getPreferredTagName({
-    // We skip reporting except when `@description` is essential to the rule,
-    //  so user can block the tag and still meaningfully use this rule
-    //  even if the tag is present (and `check-tag-names` is the one to
-    //  normally report the fact that it is blocked but present)
-    skipReportingBlockedTag: descriptionStyle !== 'tag',
-    tagName: 'description',
-  });
-  if (!targetTagName) {
-    return;
-  }
-
-  const isBlocked = typeof targetTagName === 'object' && 'blocked' in targetTagName && targetTagName.blocked;
-  if (isBlocked) {
-    targetTagName = /** @type {{blocked: true; tagName: string;}} */ (
-      targetTagName
-    ).tagName;
-  }
-
-  if (descriptionStyle !== 'tag') {
-    const {
-      description,
-    } = utils.getDescription();
-    if (checkDescription(description || '')) {
-      return;
-    }
-
-    if (descriptionStyle === 'body') {
-      const descTags = utils.getPresentTags([
-        'desc', 'description',
-      ]);
-      if (descTags.length) {
-        const [
-          {
-            tag: tagName,
-          },
-        ] = descTags;
-        report(`Remove the @${tagName} tag to leave a plain block description or add additional description text above the @${tagName} line.`);
-      } else {
-        report('Missing JSDoc block description.');
-      }
-
-      return;
-    }
-  }
-
-  const functionExamples = isBlocked ?
-    [] :
-    jsdoc.tags.filter(({
-      tag,
-    }) => {
-      return tag === targetTagName;
-    });
-
-  if (!functionExamples.length) {
-    report(
-      descriptionStyle === 'any' ?
-        `Missing JSDoc block description or @${targetTagName} declaration.` :
-        `Missing JSDoc @${targetTagName} declaration.`,
-    );
-
-    return;
-  }
-
-  for (const example of functionExamples) {
-    if (!checkDescription(`${example.name} ${utils.getTagDescription(example)}`)) {
-      report(`Missing JSDoc @${targetTagName} description.`, null, example);
-    }
-  }
-}, {
-  contextDefaults: true,
-  meta: {
-    docs: {
-      description: 'Requires that all functions have a description.',
-      url: 'https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/require-description.md#repos-sticky-header',
-    },
-    schema: [
-      {
-        additionalProperties: false,
-        properties: {
-          checkConstructors: {
-            default: true,
-            type: 'boolean',
-          },
-          checkGetters: {
-            default: true,
-            type: 'boolean',
-          },
-          checkSetters: {
-            default: true,
-            type: 'boolean',
-          },
-          contexts: {
-            items: {
-              anyOf: [
-                {
-                  type: 'string',
-                },
-                {
-                  additionalProperties: false,
-                  properties: {
-                    comment: {
-                      type: 'string',
-                    },
-                    context: {
-                      type: 'string',
-                    },
-                  },
-                  type: 'object',
-                },
-              ],
-            },
-            type: 'array',
-          },
-          descriptionStyle: {
-            enum: [
-              'body', 'tag', 'any',
-            ],
-            type: 'string',
-          },
-          exemptedBy: {
-            items: {
-              type: 'string',
-            },
-            type: 'array',
-          },
-        },
-        type: 'object',
-      },
-    ],
-    type: 'suggestion',
-  },
-});

package/src/rules/requireDescriptionCompleteSentence.js

@@ -1,335 +0,0 @@
-import iterateJsdoc from '../iterateJsdoc.js';
-import escapeStringRegexp from 'escape-string-regexp';
-
-const otherDescriptiveTags = new Set([
-  'classdesc', 'deprecated', 'exception', 'file', 'fileoverview', 'overview',
-  // 'copyright' and 'see' might be good addition, but as the former may be
-  //   sensitive text, and the latter may have just a link, they are not
-  //   included by default
-  'summary', 'throws', 'todo', 'yield', 'yields',
-]);
-
-/**
- * @param {string} text
- * @returns {string[]}
- */
-const extractParagraphs = (text) => {
-  return text.split(/(?<![;:])\n\n+/v);
-};
-
-/**
- * @param {string} text
- * @param {string|RegExp} abbreviationsRegex
- * @returns {string[]}
- */
-const extractSentences = (text, abbreviationsRegex) => {
-  const txt = text
-    // Remove all {} tags.
-    .replaceAll(/(?<!^)\{[\s\S]*?\}\s*/gv, '')
-
-    // Remove custom abbreviations
-    .replace(abbreviationsRegex, '');
-
-  const sentenceEndGrouping = /([.?!])(?:\s+|$)/gv;
-
-  const puncts = [
-    ...txt.matchAll(sentenceEndGrouping),
-  ].map((sentEnd) => {
-    return sentEnd[0];
-  });
-
-  return txt
-    .split(/[.?!](?:\s+|$)/v)
-
-    // Re-add the dot.
-    .map((sentence, idx) => {
-      return !puncts[idx] && /^\s*$/v.test(sentence) ? sentence : `${sentence}${puncts[idx] || ''}`;
-    });
-};
-
-/**
- * @param {string} text
- * @returns {boolean}
- */
-const isNewLinePrecededByAPeriod = (text) => {
-  /** @type {boolean} */
-  let lastLineEndsSentence;
-
-  const lines = text.split('\n');
-
-  return !lines.some((line) => {
-    if (lastLineEndsSentence === false && /^[A-Z][a-z]/v.test(line)) {
-      return true;
-    }
-
-    lastLineEndsSentence = /[.:?!\|]$/v.test(line);
-
-    return false;
-  });
-};
-
-/**
- * @param {string} str
- * @returns {boolean}
- */
-const isCapitalized = (str) => {
-  return str[0] === str[0].toUpperCase();
-};
-
-/**
- * @param {string} str
- * @returns {boolean}
- */
-const isTable = (str) => {
-  return str.charAt(0) === '|';
-};
-
-/**
- * @param {string} str
- * @returns {string}
- */
-const capitalize = (str) => {
-  return str.charAt(0).toUpperCase() + str.slice(1);
-};
-
-/**
- * @param {string} description
- * @param {import('../iterateJsdoc.js').Report} reportOrig
- * @param {import('eslint').Rule.Node} jsdocNode
- * @param {string|RegExp} abbreviationsRegex
- * @param {import('eslint').SourceCode} sourceCode
- * @param {import('comment-parser').Spec|{
- *   line: import('../iterateJsdoc.js').Integer
- * }} tag
- * @param {boolean} newlineBeforeCapsAssumesBadSentenceEnd
- * @returns {boolean}
- */
-const validateDescription = (
-  description, reportOrig, jsdocNode, abbreviationsRegex,
-  sourceCode, tag, newlineBeforeCapsAssumesBadSentenceEnd,
-) => {
-  if (!description || (/^\n+$/v).test(description)) {
-    return false;
-  }
-
-  const descriptionNoHeadings = description.replaceAll(/^\s*#[^\n]*(\n|$)/gmv, '');
-
-  const paragraphs = extractParagraphs(descriptionNoHeadings).filter(Boolean);
-
-  return paragraphs.some((paragraph, parIdx) => {
-    const sentences = extractSentences(paragraph, abbreviationsRegex);
-
-    const fix = /** @type {import('eslint').Rule.ReportFixer} */ (fixer) => {
-      let text = sourceCode.getText(jsdocNode);
-
-      if (!/[.:?!]$/v.test(paragraph)) {
-        const line = paragraph.split('\n').findLast(Boolean);
-        text = text.replace(new RegExp(`${escapeStringRegexp(
-          /** @type {string} */
-          (line),
-        )}$`, 'mv'), `${line}.`);
-      }
-
-      for (const sentence of sentences.filter((sentence_) => {
-        return !(/^\s*$/v).test(sentence_) && !isCapitalized(sentence_) &&
-          !isTable(sentence_);
-      })) {
-        const beginning = sentence.split('\n')[0];
-
-        if ('tag' in tag && tag.tag) {
-          const reg = new RegExp(`(@${escapeStringRegexp(tag.tag)}.*)${escapeStringRegexp(beginning)}`, 'v');
-
-          text = text.replace(reg, (_$0, $1) => {
-            return $1 + capitalize(beginning);
-          });
-        } else {
-          text = text.replace(new RegExp('((?:[.?!]|\\*|\\})\\s*)' + escapeStringRegexp(beginning), 'v'), '$1' + capitalize(beginning));
-        }
-      }
-
-      return fixer.replaceText(jsdocNode, text);
-    };
-
-    /**
-     * @param {string} msg
-     * @param {import('eslint').Rule.ReportFixer | null | undefined} fixer
-     * @param {{
-     *   line?: number | undefined;
-     *   column?: number | undefined;
-     * } | (import('comment-parser').Spec & {
-     *   line?: number | undefined;
-     *   column?: number | undefined;
-     * })} tagObj
-     * @returns {void}
-     */
-    const report = (msg, fixer, tagObj) => {
-      if ('line' in tagObj) {
-        /**
-         * @type {{
-         *   line: number;
-         * }}
-         */ (tagObj).line += parIdx * 2;
-      } else {
-        /** @type {import('comment-parser').Spec} */ (
-          tagObj
-        ).source[0].number += parIdx * 2;
-      }
-
-      // Avoid errors if old column doesn't exist here
-      tagObj.column = 0;
-      reportOrig(msg, fixer, tagObj);
-    };
-
-    if (sentences.some((sentence) => {
-      return (/^[.?!]$/v).test(sentence);
-    })) {
-      report('Sentences must be more than punctuation.', null, tag);
-    }
-
-    if (sentences.some((sentence) => {
-      return !(/^\s*$/v).test(sentence) && !isCapitalized(sentence) && !isTable(sentence);
-    })) {
-      report('Sentences should start with an uppercase character.', fix, tag);
-    }
-
-    const paragraphNoAbbreviations = paragraph.replace(abbreviationsRegex, '');
-
-    if (!/(?:[.?!\|]|```)\s*$/v.test(paragraphNoAbbreviations)) {
-      report('Sentences must end with a period.', fix, tag);
-      return true;
-    }
-
-    if (newlineBeforeCapsAssumesBadSentenceEnd && !isNewLinePrecededByAPeriod(paragraphNoAbbreviations)) {
-      report('A line of text is started with an uppercase character, but the preceding line does not end the sentence.', null, tag);
-
-      return true;
-    }
-
-    return false;
-  });
-};
-
-export default iterateJsdoc(({
-  context,
-  jsdoc,
-  jsdocNode,
-  report,
-  sourceCode,
-  utils,
-}) => {
-  const /** @type {{abbreviations: string[], newlineBeforeCapsAssumesBadSentenceEnd: boolean}} */ {
-    abbreviations = [],
-    newlineBeforeCapsAssumesBadSentenceEnd = false,
-  } = context.options[0] || {};
-
-  const abbreviationsRegex = abbreviations.length ?
-    new RegExp('\\b' + abbreviations.map((abbreviation) => {
-      return escapeStringRegexp(abbreviation.replaceAll(/\.$/gv, '') + '.');
-    }).join('|') + '(?:$|\\s)', 'gv') :
-    '';
-
-  let {
-    description,
-  } = utils.getDescription();
-
-  const indices = [
-    ...description.matchAll(/```[\s\S]*```/gv),
-  ].map((match) => {
-    const {
-      index,
-    } = match;
-    const [
-      {
-        length,
-      },
-    ] = match;
-    return {
-      index,
-      length,
-    };
-  }).reverse();
-
-  for (const {
-    index,
-    length,
-  } of indices) {
-    description = description.slice(0, index) +
-      description.slice(/** @type {import('../iterateJsdoc.js').Integer} */ (
-        index
-      ) + length);
-  }
-
-  if (validateDescription(description, report, jsdocNode, abbreviationsRegex, sourceCode, {
-    line: jsdoc.source[0].number + 1,
-  }, newlineBeforeCapsAssumesBadSentenceEnd)) {
-    return;
-  }
-
-  utils.forEachPreferredTag('description', (matchingJsdocTag) => {
-    const desc = `${matchingJsdocTag.name} ${utils.getTagDescription(matchingJsdocTag)}`.trim();
-    validateDescription(desc, report, jsdocNode, abbreviationsRegex, sourceCode, matchingJsdocTag, newlineBeforeCapsAssumesBadSentenceEnd);
-  }, true);
-
-  const {
-    tagsWithNames,
-  } = utils.getTagsByType(jsdoc.tags);
-  const tagsWithoutNames = utils.filterTags(({
-    tag: tagName,
-  }) => {
-    return otherDescriptiveTags.has(tagName) ||
-      utils.hasOptionTag(tagName) && !tagsWithNames.some(({
-        tag,
-      }) => {
-        // If user accidentally adds tags with names (or like `returns`
-        //  get parsed as having names), do not add to this list
-        return tag === tagName;
-      });
-  });
-
-  tagsWithNames.some((tag) => {
-    const desc = /** @type {string} */ (
-      utils.getTagDescription(tag)
-    ).replace(/^- /v, '').trimEnd();
-
-    return validateDescription(desc, report, jsdocNode, abbreviationsRegex, sourceCode, tag, newlineBeforeCapsAssumesBadSentenceEnd);
-  });
-
-  tagsWithoutNames.some((tag) => {
-    const desc = `${tag.name} ${utils.getTagDescription(tag)}`.trim();
-
-    return validateDescription(desc, report, jsdocNode, abbreviationsRegex, sourceCode, tag, newlineBeforeCapsAssumesBadSentenceEnd);
-  });
-}, {
-  iterateAllJsdocs: true,
-  meta: {
-    docs: {
-      description: 'Requires that block description, explicit `@description`, and `@param`/`@returns` tag descriptions are written in complete sentences.',
-      url: 'https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/require-description-complete-sentence.md#repos-sticky-header',
-    },
-    fixable: 'code',
-    schema: [
-      {
-        additionalProperties: false,
-        properties: {
-          abbreviations: {
-            items: {
-              type: 'string',
-            },
-            type: 'array',
-          },
-          newlineBeforeCapsAssumesBadSentenceEnd: {
-            type: 'boolean',
-          },
-          tags: {
-            items: {
-              type: 'string',
-            },
-            type: 'array',
-          },
-        },
-        type: 'object',
-      },
-    ],
-    type: 'suggestion',
-  },
-});