eslint-plugin-jsdoc 52.0.1 → 52.0.3

package/src/rules/checkValues.js

@@ -1,248 +0,0 @@
-import iterateJsdoc from '../iterateJsdoc.js';
-import {
-  parseImportsExports,
-} from 'parse-imports-exports';
-import semver from 'semver';
-import spdxExpressionParse from 'spdx-expression-parse';
-
-const allowedKinds = new Set([
-  'class',
-  'constant',
-  'event',
-  'external',
-  'file',
-  'function',
-  'member',
-  'mixin',
-  'module',
-  'namespace',
-  'typedef',
-]);
-
-export default iterateJsdoc(({
-  context,
-  report,
-  settings,
-  utils,
-}) => {
-  const options = context.options[0] || {};
-  const {
-    allowedAuthors = null,
-    allowedLicenses = null,
-    licensePattern = '/([^\n\r]*)/gv',
-    numericOnlyVariation = false,
-  } = options;
-
-  utils.forEachPreferredTag('version', (jsdocParameter, targetTagName) => {
-    const version = /** @type {string} */ (
-      utils.getTagDescription(jsdocParameter)
-    ).trim();
-    if (!version) {
-      report(
-        `Missing JSDoc @${targetTagName} value.`,
-        null,
-        jsdocParameter,
-      );
-    } else if (!semver.valid(version)) {
-      report(
-        `Invalid JSDoc @${targetTagName}: "${utils.getTagDescription(jsdocParameter)}".`,
-        null,
-        jsdocParameter,
-      );
-    }
-  });
-
-  utils.forEachPreferredTag('kind', (jsdocParameter, targetTagName) => {
-    const kind = /** @type {string} */ (
-      utils.getTagDescription(jsdocParameter)
-    ).trim();
-    if (!kind) {
-      report(
-        `Missing JSDoc @${targetTagName} value.`,
-        null,
-        jsdocParameter,
-      );
-    } else if (!allowedKinds.has(kind)) {
-      report(
-        `Invalid JSDoc @${targetTagName}: "${utils.getTagDescription(jsdocParameter)}"; ` +
-        `must be one of: ${[
-          ...allowedKinds,
-        ].join(', ')}.`,
-        null,
-        jsdocParameter,
-      );
-    }
-  });
-
-  if (numericOnlyVariation) {
-    utils.forEachPreferredTag('variation', (jsdocParameter, targetTagName) => {
-      const variation = /** @type {string} */ (
-        utils.getTagDescription(jsdocParameter)
-      ).trim();
-      if (!variation) {
-        report(
-          `Missing JSDoc @${targetTagName} value.`,
-          null,
-          jsdocParameter,
-        );
-      } else if (
-        !Number.isInteger(Number(variation)) ||
-        Number(variation) <= 0
-      ) {
-        report(
-          `Invalid JSDoc @${targetTagName}: "${utils.getTagDescription(jsdocParameter)}".`,
-          null,
-          jsdocParameter,
-        );
-      }
-    });
-  }
-
-  utils.forEachPreferredTag('since', (jsdocParameter, targetTagName) => {
-    const version = /** @type {string} */ (
-      utils.getTagDescription(jsdocParameter)
-    ).trim();
-    if (!version) {
-      report(
-        `Missing JSDoc @${targetTagName} value.`,
-        null,
-        jsdocParameter,
-      );
-    } else if (!semver.valid(version)) {
-      report(
-        `Invalid JSDoc @${targetTagName}: "${utils.getTagDescription(jsdocParameter)}".`,
-        null,
-        jsdocParameter,
-      );
-    }
-  });
-  utils.forEachPreferredTag('license', (jsdocParameter, targetTagName) => {
-    const licenseRegex = utils.getRegexFromString(licensePattern, 'g');
-    const matches = /** @type {string} */ (
-      utils.getTagDescription(jsdocParameter)
-    ).matchAll(licenseRegex);
-    let positiveMatch = false;
-    for (const match of matches) {
-      const license = match[1] || match[0];
-      if (license) {
-        positiveMatch = true;
-      }
-
-      if (!license.trim()) {
-        // Avoid reporting again as empty match
-        if (positiveMatch) {
-          return;
-        }
-
-        report(
-          `Missing JSDoc @${targetTagName} value.`,
-          null,
-          jsdocParameter,
-        );
-      } else if (allowedLicenses) {
-        if (allowedLicenses !== true && !allowedLicenses.includes(license)) {
-          report(
-            `Invalid JSDoc @${targetTagName}: "${license}"; expected one of ${allowedLicenses.join(', ')}.`,
-            null,
-            jsdocParameter,
-          );
-        }
-      } else {
-        try {
-          spdxExpressionParse(license);
-        } catch {
-          report(
-            `Invalid JSDoc @${targetTagName}: "${license}"; expected SPDX expression: https://spdx.org/licenses/.`,
-            null,
-            jsdocParameter,
-          );
-        }
-      }
-    }
-  });
-
-  if (settings.mode === 'typescript') {
-    utils.forEachPreferredTag('import', (tag) => {
-      const {
-        description,
-        name,
-        type,
-      } = tag;
-      const typePart = type ? `{${type}} ` : '';
-      const imprt = 'import ' + (description ?
-        `${typePart}${name} ${description}` :
-        `${typePart}${name}`);
-
-      const importsExports = parseImportsExports(imprt.trim());
-
-      if (importsExports.errors) {
-        report(
-          'Bad @import tag',
-          null,
-          tag,
-        );
-      }
-    });
-  }
-
-  utils.forEachPreferredTag('author', (jsdocParameter, targetTagName) => {
-    const author = /** @type {string} */ (
-      utils.getTagDescription(jsdocParameter)
-    ).trim();
-    if (!author) {
-      report(
-        `Missing JSDoc @${targetTagName} value.`,
-        null,
-        jsdocParameter,
-      );
-    } else if (allowedAuthors && !allowedAuthors.includes(author)) {
-      report(
-        `Invalid JSDoc @${targetTagName}: "${utils.getTagDescription(jsdocParameter)}"; expected one of ${allowedAuthors.join(', ')}.`,
-        null,
-        jsdocParameter,
-      );
-    }
-  });
-}, {
-  iterateAllJsdocs: true,
-  meta: {
-    docs: {
-      description: 'This rule checks the values for a handful of tags: `@version`, `@since`, `@license` and `@author`.',
-      url: 'https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/check-values.md#repos-sticky-header',
-    },
-    schema: [
-      {
-        additionalProperties: false,
-        properties: {
-          allowedAuthors: {
-            items: {
-              type: 'string',
-            },
-            type: 'array',
-          },
-          allowedLicenses: {
-            anyOf: [
-              {
-                items: {
-                  type: 'string',
-                },
-                type: 'array',
-              },
-              {
-                type: 'boolean',
-              },
-            ],
-          },
-          licensePattern: {
-            type: 'string',
-          },
-          numericOnlyVariation: {
-            type: 'boolean',
-          },
-        },
-        type: 'object',
-      },
-    ],
-    type: 'suggestion',
-  },
-});

package/src/rules/convertToJsdocComments.js

@@ -1,398 +0,0 @@
-import {
-  getSettings,
-} from '../iterateJsdoc.js';
-import {
-  enforcedContexts,
-  getContextObject,
-  getIndent,
-} from '../jsdocUtils.js';
-import {
-  getDecorator,
-  getFollowingComment,
-  getNonJsdocComment,
-  getReducedASTNode,
-} from '@es-joy/jsdoccomment';
-
-/** @type {import('eslint').Rule.RuleModule} */
-export default {
-  create (context) {
-    /**
-     * @typedef {import('eslint').AST.Token | import('estree').Comment | {
-     *   type: import('eslint').AST.TokenType|"Line"|"Block"|"Shebang",
-     *   range: [number, number],
-     *   value: string
-     * }} Token
-     */
-
-    /**
-     * @callback AddComment
-     * @param {boolean|undefined} inlineCommentBlock
-     * @param {Token} comment
-     * @param {string} indent
-     * @param {number} lines
-     * @param {import('eslint').Rule.RuleFixer} fixer
-     */
-
-    /* c8 ignore next -- Fallback to deprecated method */
-    const {
-      sourceCode = context.getSourceCode(),
-    } = context;
-    const settings = getSettings(context);
-    if (!settings) {
-      return {};
-    }
-
-    const {
-      allowedPrefixes = [
-        '@ts-', 'istanbul ', 'c8 ', 'v8 ', 'eslint', 'prettier-',
-      ],
-      contexts = settings.contexts || [],
-      contextsAfter = /** @type {string[]} */ ([]),
-      contextsBeforeAndAfter = [
-        'VariableDeclarator', 'TSPropertySignature', 'PropertyDefinition',
-      ],
-      enableFixer = true,
-      enforceJsdocLineStyle = 'multi',
-      lineOrBlockStyle = 'both',
-    } = context.options[0] ?? {};
-
-    let reportingNonJsdoc = false;
-
-    /**
-     * @param {string} messageId
-     * @param {import('estree').Comment|Token} comment
-     * @param {import('eslint').Rule.Node} node
-     * @param {import('eslint').Rule.ReportFixer} fixer
-     */
-    const report = (messageId, comment, node, fixer) => {
-      const loc = {
-        end: {
-          column: 0,
-          /* c8 ignore next 2 -- Guard */
-          // @ts-expect-error Ok
-          line: (comment.loc?.start?.line ?? 1),
-        },
-        start: {
-          column: 0,
-          /* c8 ignore next 2 -- Guard */
-          // @ts-expect-error Ok
-          line: (comment.loc?.start?.line ?? 1),
-        },
-      };
-
-      context.report({
-        fix: enableFixer ? fixer : null,
-        loc,
-        messageId,
-        node,
-      });
-    };
-
-    /**
-     * @param {import('eslint').Rule.Node} node
-     * @param {import('eslint').AST.Token | import('estree').Comment | {
-     *   type: import('eslint').AST.TokenType|"Line"|"Block"|"Shebang",
-     *   range: [number, number],
-     *   value: string
-     * }} comment
-     * @param {AddComment} addComment
-     * @param {import('../iterateJsdoc.js').Context[]} ctxts
-     */
-    const getFixer = (node, comment, addComment, ctxts) => {
-      return /** @type {import('eslint').Rule.ReportFixer} */ (fixer) => {
-        // Default to one line break if the `minLines`/`maxLines` settings allow
-        const lines = settings.minLines === 0 && settings.maxLines >= 1 ? 1 : settings.minLines;
-        let baseNode =
-          /**
-           * @type {import('@typescript-eslint/types').TSESTree.Node|import('eslint').Rule.Node}
-           */ (
-            getReducedASTNode(node, sourceCode)
-          );
-
-        const decorator = getDecorator(
-          /** @type {import('eslint').Rule.Node} */
-          (baseNode),
-        );
-        if (decorator) {
-          baseNode = /** @type {import('@typescript-eslint/types').TSESTree.Decorator} */ (
-            decorator
-          );
-        }
-
-        const indent = getIndent({
-          text: sourceCode.getText(
-            /** @type {import('eslint').Rule.Node} */ (baseNode),
-            /** @type {import('eslint').AST.SourceLocation} */
-            (
-              /** @type {import('eslint').Rule.Node} */ (baseNode).loc
-            ).start.column,
-          ),
-        });
-
-        const {
-          inlineCommentBlock,
-        } =
-          /**
-           * @type {{
-           *     context: string,
-           *     inlineCommentBlock: boolean,
-           *     minLineCount: import('../iterateJsdoc.js').Integer
-           *   }[]}
-           */ (ctxts).find((contxt) => {
-            if (typeof contxt === 'string') {
-              return false;
-            }
-
-            const {
-              context: ctxt,
-            } = contxt;
-            return ctxt === node.type;
-          }) || {};
-
-        return addComment(inlineCommentBlock, comment, indent, lines, fixer);
-      };
-    };
-
-    /**
-     * @param {import('eslint').AST.Token | import('estree').Comment | {
-     *   type: import('eslint').AST.TokenType|"Line"|"Block"|"Shebang",
-     *   range: [number, number],
-     *   value: string
-     * }} comment
-     * @param {import('eslint').Rule.Node} node
-     * @param {AddComment} addComment
-     * @param {import('../iterateJsdoc.js').Context[]} ctxts
-     */
-    const reportings = (comment, node, addComment, ctxts) => {
-      const fixer = getFixer(node, comment, addComment, ctxts);
-
-      if (comment.type === 'Block') {
-        if (lineOrBlockStyle === 'line') {
-          return;
-        }
-
-        report('blockCommentsJsdocStyle', comment, node, fixer);
-        return;
-      }
-
-      if (comment.type === 'Line') {
-        if (lineOrBlockStyle === 'block') {
-          return;
-        }
-
-        report('lineCommentsJsdocStyle', comment, node, fixer);
-      }
-    };
-
-    /**
-     * @type {import('../iterateJsdoc.js').CheckJsdoc}
-     */
-    const checkNonJsdoc = (_info, _handler, node) => {
-      const comment = getNonJsdocComment(sourceCode, node, settings);
-
-      if (
-        !comment ||
-        /** @type {string[]} */
-        (allowedPrefixes).some((prefix) => {
-          return comment.value.trimStart().startsWith(prefix);
-        })
-      ) {
-        return;
-      }
-
-      reportingNonJsdoc = true;
-
-      /** @type {AddComment} */
-      // eslint-disable-next-line unicorn/consistent-function-scoping -- Avoid conflicts
-      const addComment = (inlineCommentBlock, commentToAdd, indent, lines, fixer) => {
-        const insertion = (
-          inlineCommentBlock || enforceJsdocLineStyle === 'single' ?
-            `/** ${commentToAdd.value.trim()} ` :
-            `/**\n${indent}*${commentToAdd.value.trimEnd()}\n${indent}`
-        ) +
-            `*/${'\n'.repeat((lines || 1) - 1)}`;
-
-        return fixer.replaceText(
-          /** @type {import('eslint').AST.Token} */
-          (commentToAdd),
-          insertion,
-        );
-      };
-
-      reportings(comment, node, addComment, contexts);
-    };
-
-    /**
-     * @param {import('eslint').Rule.Node} node
-     * @param {import('../iterateJsdoc.js').Context[]} ctxts
-     */
-    const checkNonJsdocAfter = (node, ctxts) => {
-      const comment = getFollowingComment(sourceCode, node);
-
-      if (
-        !comment ||
-        comment.value.startsWith('*') ||
-        /** @type {string[]} */
-        (allowedPrefixes).some((prefix) => {
-          return comment.value.trimStart().startsWith(prefix);
-        })
-      ) {
-        return;
-      }
-
-      /** @type {AddComment} */
-      const addComment = (inlineCommentBlock, commentToAdd, indent, lines, fixer) => {
-        const insertion = (
-          inlineCommentBlock || enforceJsdocLineStyle === 'single' ?
-            `/** ${commentToAdd.value.trim()} ` :
-            `/**\n${indent}*${commentToAdd.value.trimEnd()}\n${indent}`
-        ) +
-            `*/${'\n'.repeat((lines || 1) - 1)}${lines ? `\n${indent.slice(1)}` : ' '}`;
-
-        return [
-          fixer.remove(
-          /** @type {import('eslint').AST.Token} */
-            (commentToAdd),
-          ), fixer.insertTextBefore(
-            node.type === 'VariableDeclarator' ? node.parent : node,
-            insertion,
-          ),
-        ];
-      };
-
-      reportings(comment, node, addComment, ctxts);
-    };
-
-    // Todo: add contexts to check after (and handle if want both before and after)
-    return {
-      ...getContextObject(
-        enforcedContexts(context, true, settings),
-        checkNonJsdoc,
-      ),
-      ...getContextObject(
-        contextsAfter,
-        (_info, _handler, node) => {
-          checkNonJsdocAfter(node, contextsAfter);
-        },
-      ),
-      ...getContextObject(
-        contextsBeforeAndAfter,
-        (_info, _handler, node) => {
-          checkNonJsdoc({}, null, node);
-          if (!reportingNonJsdoc) {
-            checkNonJsdocAfter(node, contextsBeforeAndAfter);
-          }
-        },
-      ),
-    };
-  },
-  meta: {
-    docs: {
-      description: 'Converts non-JSDoc comments preceding or following nodes into JSDoc ones',
-      url: 'https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/convert-to-jsdoc-comments.md#repos-sticky-header',
-    },
-
-    fixable: 'code',
-
-    messages: {
-      blockCommentsJsdocStyle: 'Block comments should be JSDoc-style.',
-      lineCommentsJsdocStyle: 'Line comments should be JSDoc-style.',
-    },
-    schema: [
-      {
-        additionalProperties: false,
-        properties: {
-          allowedPrefixes: {
-            items: {
-              type: 'string',
-            },
-            type: 'array',
-          },
-          contexts: {
-            items: {
-              anyOf: [
-                {
-                  type: 'string',
-                },
-                {
-                  additionalProperties: false,
-                  properties: {
-                    context: {
-                      type: 'string',
-                    },
-                    inlineCommentBlock: {
-                      type: 'boolean',
-                    },
-                  },
-                  type: 'object',
-                },
-              ],
-            },
-            type: 'array',
-          },
-          contextsAfter: {
-            items: {
-              anyOf: [
-                {
-                  type: 'string',
-                },
-                {
-                  additionalProperties: false,
-                  properties: {
-                    context: {
-                      type: 'string',
-                    },
-                    inlineCommentBlock: {
-                      type: 'boolean',
-                    },
-                  },
-                  type: 'object',
-                },
-              ],
-            },
-            type: 'array',
-          },
-          contextsBeforeAndAfter: {
-            items: {
-              anyOf: [
-                {
-                  type: 'string',
-                },
-                {
-                  additionalProperties: false,
-                  properties: {
-                    context: {
-                      type: 'string',
-                    },
-                    inlineCommentBlock: {
-                      type: 'boolean',
-                    },
-                  },
-                  type: 'object',
-                },
-              ],
-            },
-            type: 'array',
-          },
-          enableFixer: {
-            type: 'boolean',
-          },
-          enforceJsdocLineStyle: {
-            enum: [
-              'multi', 'single',
-            ],
-            type: 'string',
-          },
-          lineOrBlockStyle: {
-            enum: [
-              'block', 'line', 'both',
-            ],
-            type: 'string',
-          },
-        },
-        type: 'object',
-      },
-    ],
-    type: 'suggestion',
-  },
-};