@depup/eslint-plugin-jsdoc 62.8.0-depup.0

package/src/rules/tagLines.js

@@ -0,0 +1,486 @@
+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, postDelims) => {
+          const newPostDelims = [
+            ...postDelims.slice(0, excessIndexLine),
+            ...postDelims.slice(excessIndexLine + excessBlockLines - 1 - maxBlockLines),
+          ];
+          return [
+            ...descLines.slice(0, excessIndexLine),
+            ...descLines.slice(excessIndexLine + excessBlockLines - 1 - maxBlockLines),
+          ].map((desc, idx) => {
+            return {
+              number: 0,
+              source: '',
+              tokens: seedTokens({
+                ...info,
+                description: desc,
+                postDelimiter: newPostDelims[idx],
+              }),
+            };
+          });
+        });
+      },
+    );
+    return true;
+  }
+
+  return false;
+};
+
+export default iterateJsdoc(({
+  context,
+  jsdoc,
+  utils,
+}) => {
+  const [
+    alwaysNever = 'never',
+    {
+      applyToEndTag = true,
+      count = 1,
+      endLines = 0,
+      maxBlockLines = null,
+      startLines = 0,
+      startLinesWithNoTags = null,
+      tags = {},
+    } = {},
+  ] = context.options;
+
+  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);
+        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 (checkMaxBlockLines({
+    maxBlockLines,
+    startLines,
+    utils,
+  })) {
+    return;
+  }
+
+  if (typeof startLines === 'number' || typeof startLinesWithNoTags === 'number') {
+    const noTags = !jsdoc.tags.length;
+
+    if (noTags && startLinesWithNoTags === null) {
+      return;
+    }
+
+    const {
+      description,
+      lastDescriptionLine,
+    } = utils.getDescription();
+    if (!(/\S/v).test(description)) {
+      return;
+    }
+
+    const startingLines = noTags ? startLinesWithNoTags : startLines;
+
+    const trailingLines = description.match(/\n+$/v)?.[0]?.length;
+    const trailingDiff = (trailingLines ?? 0) - startingLines;
+    if (trailingDiff > 0) {
+      utils.reportJSDoc(
+        `Expected only ${startingLines} line${startingLines === 1 ? '' : 's'} after block description`,
+        {
+          line: lastDescriptionLine - trailingDiff,
+        },
+        () => {
+          utils.setBlockDescription((info, seedTokens, descLines, postDelims) => {
+            return descLines.slice(0, -trailingDiff).map((desc, idx) => {
+              return {
+                number: 0,
+                source: '',
+                tokens: seedTokens({
+                  ...info,
+                  description: desc,
+                  postDelimiter: postDelims[idx],
+                }),
+              };
+            });
+          });
+        },
+      );
+    } else if (trailingDiff < 0) {
+      utils.reportJSDoc(
+        `Expected ${startingLines} lines after block description`,
+        {
+          line: lastDescriptionLine,
+        },
+        () => {
+          utils.setBlockDescription((info, seedTokens, descLines, postDelims) => {
+            return [
+              ...descLines,
+              ...Array.from({
+                length: -trailingDiff,
+              }, () => {
+                return '';
+              }),
+            ].map((desc, idx) => {
+              return {
+                number: 0,
+                source: '',
+                tokens: seedTokens({
+                  ...info,
+                  description: desc,
+                  postDelimiter: desc.trim() ? postDelims[idx] : '',
+                }),
+              };
+            });
+          });
+        },
+      );
+    }
+  }
+}, {
+  iterateAllJsdocs: true,
+  meta: {
+    docs: {
+      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\`, \`startLinesWithNoTags\` \`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.`,
+        enum: [
+          'always', 'any', 'never',
+        ],
+        type: 'string',
+      },
+      {
+        additionalProperties: false,
+        properties: {
+          applyToEndTag: {
+            description: `Set to \`false\` and use with "always" to indicate the normal lines to be
+added after tags should not be added after the final tag.
+
+Defaults to \`true\`.`,
+            type: 'boolean',
+          },
+          count: {
+            description: `Use with "always" to indicate the number of lines to require be present.
+
+Defaults to 1.`,
+            type: 'integer',
+          },
+          endLines: {
+            anyOf: [
+              {
+                type: 'integer',
+              },
+              {
+                type: 'null',
+              },
+            ],
+            description: `If not set to \`null\`, will enforce end lines to the given count on the
+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: [
+              {
+                type: 'integer',
+              },
+              {
+                type: 'null',
+              },
+            ],
+            description: `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,
+a line count will not be enforced.
+
+Defaults to \`0\`.`,
+          },
+          startLinesWithNoTags: {
+            description: 'If set to a number, will enforce a starting lines count when there are no tags. Defaults to `undefined`.',
+            type: 'number',
+          },
+          tags: {
+            description: `Overrides the default behavior depending on specific tags.
+
+An object whose keys are tag names and whose values are objects with the
+following keys:
+
+1. \`lines\` - Set to \`always\`, \`never\`, or \`any\` to override.
+2. \`count\` - Overrides main \`count\` (for "always")
+
+Defaults to empty object.`,
+            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

@@ -0,0 +1,158 @@
+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: {
+          escapeHTML: {
+            description: `This option escapes all \`<\` and \`&\` characters (except those followed by
+whitespace which are treated as literals by Visual Studio Code). Defaults to
+\`false\`.`,
+            type: 'boolean',
+          },
+          escapeMarkdown: {
+            description: `This option escapes the first backtick (\`\` \` \`\`) in a paired sequence.
+Defaults to \`false\`.`,
+            type: 'boolean',
+          },
+        },
+        type: 'object',
+      },
+    ],
+    type: 'suggestion',
+  },
+});