eslint-plugin-jsdoc 53.0.1 → 54.1.0

package/src/rules/checkValues.js

@@ -0,0 +1,248 @@
+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

@@ -0,0 +1,398 @@
+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',
+  },
+};