eslint-plugin-jsdoc 52.0.4 → 53.0.1

package/src/rules/tagLines.js

@@ -1,359 +0,0 @@
-import iterateJsdoc from '../iterateJsdoc.js';
-
-export default iterateJsdoc(({
-  context,
-  jsdoc,
-  utils,
-}) => {
-  const [
-    alwaysNever = 'never',
-    {
-      applyToEndTag = true,
-      count = 1,
-      endLines = 0,
-      startLines = 0,
-      tags = {},
-    } = {},
-  ] = context.options;
-
-  // eslint-disable-next-line complexity -- Temporary
-  jsdoc.tags.some((tg, tagIdx) => {
-    let lastTag;
-
-    /**
-     * @type {null|import('../iterateJsdoc.js').Integer}
-     */
-    let lastEmpty = null;
-
-    /**
-     * @type {null|import('../iterateJsdoc.js').Integer}
-     */
-    let reportIndex = null;
-    let emptyLinesCount = 0;
-    for (const [
-      idx,
-      {
-        tokens: {
-          description,
-          end,
-          name,
-          tag,
-          type,
-        },
-      },
-    ] of tg.source.entries()) {
-      // May be text after a line break within a tag description
-      if (description) {
-        reportIndex = null;
-      }
-
-      if (lastTag && [
-        'always', 'any',
-      ].includes(tags[lastTag.slice(1)]?.lines)) {
-        continue;
-      }
-
-      const empty = !tag && !name && !type && !description;
-      if (
-        empty && !end &&
-        (alwaysNever === 'never' ||
-          lastTag && tags[lastTag.slice(1)]?.lines === 'never'
-        )
-      ) {
-        reportIndex = idx;
-
-        continue;
-      }
-
-      if (!end) {
-        if (empty) {
-          emptyLinesCount++;
-        } else {
-          emptyLinesCount = 0;
-        }
-
-        lastEmpty = empty ? idx : null;
-      }
-
-      lastTag = tag;
-    }
-
-    if (
-      typeof endLines === 'number' &&
-      lastEmpty !== null && tagIdx === jsdoc.tags.length - 1
-    ) {
-      const lineDiff = endLines - emptyLinesCount;
-
-      if (lineDiff < 0) {
-        const fixer = () => {
-          utils.removeTag(tagIdx, {
-            tagSourceOffset: /** @type {import('../iterateJsdoc.js').Integer} */ (
-              lastEmpty
-            ) + lineDiff + 1,
-          });
-        };
-
-        utils.reportJSDoc(
-          `Expected ${endLines} trailing lines`,
-          {
-            line: tg.source[lastEmpty].number + lineDiff + 1,
-          },
-          fixer,
-        );
-      } else if (lineDiff > 0) {
-        const fixer = () => {
-          utils.addLines(
-            tagIdx,
-            /** @type {import('../iterateJsdoc.js').Integer} */ (lastEmpty),
-            endLines - emptyLinesCount,
-          );
-        };
-
-        utils.reportJSDoc(
-          `Expected ${endLines} trailing lines`,
-          {
-            line: tg.source[lastEmpty].number,
-          },
-          fixer,
-        );
-      }
-
-      return true;
-    }
-
-    if (reportIndex !== null) {
-      const fixer = () => {
-        utils.removeTag(tagIdx, {
-          tagSourceOffset: /** @type {import('../iterateJsdoc.js').Integer} */ (
-            reportIndex
-          ),
-        });
-      };
-
-      utils.reportJSDoc(
-        'Expected no lines between tags',
-        {
-          line: tg.source[0].number + 1,
-        },
-        fixer,
-      );
-
-      return true;
-    }
-
-    return false;
-  });
-
-  (applyToEndTag ? jsdoc.tags : jsdoc.tags.slice(0, -1)).some((tg, tagIdx) => {
-    /**
-     * @type {{
-     *   idx: import('../iterateJsdoc.js').Integer,
-     *   number: import('../iterateJsdoc.js').Integer
-     * }[]}
-     */
-    const lines = [];
-
-    let currentTag;
-    let tagSourceIdx = 0;
-    for (const [
-      idx,
-      {
-        number,
-        tokens: {
-          description,
-          end,
-          name,
-          tag,
-          type,
-        },
-      },
-    ] of tg.source.entries()) {
-      if (description) {
-        lines.splice(0, lines.length);
-        tagSourceIdx = idx;
-      }
-
-      if (tag) {
-        currentTag = tag;
-      }
-
-      if (!tag && !name && !type && !description && !end) {
-        lines.push({
-          idx,
-          number,
-        });
-      }
-    }
-
-    const currentTg = currentTag && tags[currentTag.slice(1)];
-    const tagCount = currentTg?.count;
-
-    const defaultAlways = alwaysNever === 'always' && currentTg?.lines !== 'never' &&
-      currentTg?.lines !== 'any' && lines.length < count;
-
-    let overrideAlways;
-    let fixCount = count;
-    if (!defaultAlways) {
-      fixCount = typeof tagCount === 'number' ? tagCount : count;
-      overrideAlways = currentTg?.lines === 'always' &&
-        lines.length < fixCount;
-    }
-
-    if (defaultAlways || overrideAlways) {
-      const fixer = () => {
-        utils.addLines(tagIdx, lines[lines.length - 1]?.idx || tagSourceIdx + 1, fixCount - lines.length);
-      };
-
-      const line = lines[lines.length - 1]?.number || tg.source[tagSourceIdx].number;
-      utils.reportJSDoc(
-        `Expected ${fixCount} line${fixCount === 1 ? '' : 's'} between tags but found ${lines.length}`,
-        {
-          line,
-        },
-        fixer,
-      );
-
-      return true;
-    }
-
-    return false;
-  });
-
-  if (typeof startLines === 'number') {
-    if (!jsdoc.tags.length) {
-      return;
-    }
-
-    const {
-      description,
-      lastDescriptionLine,
-    } = utils.getDescription();
-    if (!(/\S/v).test(description)) {
-      return;
-    }
-
-    const trailingLines = description.match(/\n+$/v)?.[0]?.length;
-    const trailingDiff = (trailingLines ?? 0) - startLines;
-    if (trailingDiff > 0) {
-      utils.reportJSDoc(
-        `Expected only ${startLines} line after block description`,
-        {
-          line: lastDescriptionLine - trailingDiff,
-        },
-        () => {
-          utils.setBlockDescription((info, seedTokens, descLines) => {
-            return descLines.slice(0, -trailingDiff).map((desc) => {
-              return {
-                number: 0,
-                source: '',
-                tokens: seedTokens({
-                  ...info,
-                  description: desc,
-                  postDelimiter: desc.trim() ? info.postDelimiter : '',
-                }),
-              };
-            });
-          });
-        },
-      );
-    } else if (trailingDiff < 0) {
-      utils.reportJSDoc(
-        `Expected ${startLines} lines after block description`,
-        {
-          line: lastDescriptionLine,
-        },
-        () => {
-          utils.setBlockDescription((info, seedTokens, descLines) => {
-            return [
-              ...descLines,
-              ...Array.from({
-                length: -trailingDiff,
-              }, () => {
-                return '';
-              }),
-            ].map((desc) => {
-              return {
-                number: 0,
-                source: '',
-                tokens: seedTokens({
-                  ...info,
-                  description: desc,
-                  postDelimiter: desc.trim() ? info.postDelimiter : '',
-                }),
-              };
-            });
-          });
-        },
-      );
-    }
-  }
-}, {
-  iterateAllJsdocs: true,
-  meta: {
-    docs: {
-      description: 'Enforces lines (or no lines) between tags.',
-      url: 'https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/tag-lines.md#repos-sticky-header',
-    },
-    fixable: 'code',
-    schema: [
-      {
-        enum: [
-          'always', 'any', 'never',
-        ],
-        type: 'string',
-      },
-      {
-        additionalProperties: false,
-        properties: {
-          applyToEndTag: {
-            type: 'boolean',
-          },
-          count: {
-            type: 'integer',
-          },
-          endLines: {
-            anyOf: [
-              {
-                type: 'integer',
-              },
-              {
-                type: 'null',
-              },
-            ],
-          },
-          startLines: {
-            anyOf: [
-              {
-                type: 'integer',
-              },
-              {
-                type: 'null',
-              },
-            ],
-          },
-          tags: {
-            patternProperties: {
-              '.*': {
-                additionalProperties: false,
-                properties: {
-                  count: {
-                    type: 'integer',
-                  },
-                  lines: {
-                    enum: [
-                      'always', 'never', 'any',
-                    ],
-                    type: 'string',
-                  },
-                },
-              },
-            },
-            type: 'object',
-          },
-        },
-        type: 'object',
-      },
-    ],
-    type: 'suggestion',
-  },
-});

package/src/rules/textEscaping.js

@@ -1,154 +0,0 @@
-import iterateJsdoc from '../iterateJsdoc.js';
-
-// We could disallow raw gt, quot, and apos, but allow for parity; but we do
-//  not allow hex or decimal character references
-const htmlRegex = /(<|&(?!(?:amp|lt|gt|quot|apos);))(?=\S)/v;
-const markdownRegex = /(?<!\\)(`+)([^`]+)\1(?!`)/v;
-
-/**
- * @param {string} desc
- * @returns {string}
- */
-const htmlReplacer = (desc) => {
-  return desc.replaceAll(new RegExp(htmlRegex, 'gv'), (_) => {
-    if (_ === '<') {
-      return '&lt;';
-    }
-
-    return '&amp;';
-  });
-};
-
-/**
- * @param {string} desc
- * @returns {string}
- */
-const markdownReplacer = (desc) => {
-  return desc.replaceAll(new RegExp(markdownRegex, 'gv'), (_, backticks, encapsed) => {
-    const bookend = '`'.repeat(backticks.length);
-    return `\\${bookend}${encapsed}${bookend}`;
-  });
-};
-
-export default iterateJsdoc(({
-  context,
-  jsdoc,
-  utils,
-}) => {
-  const {
-    escapeHTML,
-    escapeMarkdown,
-  } = context.options[0] || {};
-
-  if (!escapeHTML && !escapeMarkdown) {
-    context.report({
-      loc: {
-        end: {
-          column: 1,
-          line: 1,
-        },
-        start: {
-          column: 1,
-          line: 1,
-        },
-      },
-      message: 'You must include either `escapeHTML` or `escapeMarkdown`',
-    });
-    return;
-  }
-
-  const {
-    descriptions,
-  } = utils.getDescription();
-
-  if (escapeHTML) {
-    if (descriptions.some((desc) => {
-      return htmlRegex.test(desc);
-    })) {
-      const line = utils.setDescriptionLines(htmlRegex, htmlReplacer);
-      utils.reportJSDoc('You have unescaped HTML characters < or &', {
-        line,
-      }, () => {}, true);
-      return;
-    }
-
-    for (const tag of jsdoc.tags) {
-      if (tag.tag === 'example') {
-        continue;
-      }
-
-      if (/** @type {string[]} */ (
-        utils.getTagDescription(tag, true)
-      ).some((desc) => {
-        return htmlRegex.test(desc);
-      })) {
-        const line = utils.setTagDescription(tag, htmlRegex, htmlReplacer) +
-          tag.source[0].number;
-        utils.reportJSDoc('You have unescaped HTML characters < or & in a tag', {
-          line,
-        }, () => {}, true);
-      }
-    }
-
-    return;
-  }
-
-  if (descriptions.some((desc) => {
-    return markdownRegex.test(desc);
-  })) {
-    const line = utils.setDescriptionLines(markdownRegex, markdownReplacer);
-    utils.reportJSDoc('You have unescaped Markdown backtick sequences', {
-      line,
-    }, () => {}, true);
-    return;
-  }
-
-  for (const tag of jsdoc.tags) {
-    if (tag.tag === 'example') {
-      continue;
-    }
-
-    if (/** @type {string[]} */ (
-      utils.getTagDescription(tag, true)
-    ).some((desc) => {
-      return markdownRegex.test(desc);
-    })) {
-      const line = utils.setTagDescription(
-        tag, markdownRegex, markdownReplacer,
-      ) + tag.source[0].number;
-      utils.reportJSDoc(
-        'You have unescaped Markdown backtick sequences in a tag',
-        {
-          line,
-        },
-        () => {},
-        true,
-      );
-    }
-  }
-}, {
-  iterateAllJsdocs: true,
-  meta: {
-    docs: {
-      description: 'Auto-escape certain characters that are input within block and tag descriptions.',
-      url: 'https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/text-escaping.md#repos-sticky-header',
-    },
-    fixable: 'code',
-    schema: [
-      {
-        additionalProperties: false,
-        properties: {
-          // Option properties here (or remove the object)
-          escapeHTML: {
-            type: 'boolean',
-          },
-          escapeMarkdown: {
-            type: 'boolean',
-          },
-        },
-        type: 'object',
-      },
-    ],
-    type: 'suggestion',
-  },
-});