eslint-plugin-jsdoc 47.0.2 → 48.0.1

package/src/rules/checkValues.js

@@ -0,0 +1,220 @@
+import iterateJsdoc from '../iterateJsdoc.js';
+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(({
+  utils,
+  report,
+  context,
+}) => {
+  const options = context.options[0] || {};
+  const {
+    allowedLicenses = null,
+    allowedAuthors = null,
+    numericOnlyVariation = false,
+    licensePattern = '/([^\n\r]*)/gu',
+  } = 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,
+          );
+        }
+      }
+    }
+  });
+
+  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/emptyTags.js

@@ -0,0 +1,88 @@
+import iterateJsdoc from '../iterateJsdoc.js';
+
+const defaultEmptyTags = new Set([
+  'abstract', 'async', 'generator', 'global', 'hideconstructor',
+  'ignore', 'inner', 'instance', 'override', 'readonly',
+
+  // jsdoc doesn't use this form in its docs, but allow for compatibility with
+  //  TypeScript which allows and Closure which requires
+  'inheritDoc',
+
+  // jsdoc doesn't use but allow for TypeScript
+  'internal',
+  'overload',
+]);
+
+const emptyIfNotClosure = new Set([
+  'package', 'private', 'protected', 'public', 'static',
+
+  // Closure doesn't allow with this casing
+  'inheritdoc',
+]);
+
+const emptyIfClosure = new Set([
+  'interface',
+]);
+
+export default iterateJsdoc(({
+  settings,
+  jsdoc,
+  utils,
+}) => {
+  const emptyTags = utils.filterTags(({
+    tag: tagName,
+  }) => {
+    return defaultEmptyTags.has(tagName) ||
+      utils.hasOptionTag(tagName) && jsdoc.tags.some(({
+        tag,
+      }) => {
+        return tag === tagName;
+      }) ||
+      settings.mode === 'closure' && emptyIfClosure.has(tagName) ||
+      settings.mode !== 'closure' && emptyIfNotClosure.has(tagName);
+  });
+
+  for (const tag of emptyTags) {
+    const content = tag.name || tag.description || tag.type;
+    if (content.trim()) {
+      const fix = () => {
+        // By time of call in fixer, `tag` will have `line` added
+        utils.setTag(
+          /**
+           * @type {import('comment-parser').Spec & {
+           *   line: import('../iterateJsdoc.js').Integer
+           * }}
+           */ (tag),
+        );
+      };
+
+      utils.reportJSDoc(`@${tag.tag} should be empty.`, tag, fix, true);
+    }
+  }
+}, {
+  checkInternal: true,
+  checkPrivate: true,
+  iterateAllJsdocs: true,
+  meta: {
+    docs: {
+      description: 'Expects specific tags to be empty of any content.',
+      url: 'https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/empty-tags.md#repos-sticky-header',
+    },
+    fixable: 'code',
+    schema: [
+      {
+        additionalProperties: false,
+        properties: {
+          tags: {
+            items: {
+              type: 'string',
+            },
+            type: 'array',
+          },
+        },
+        type: 'object',
+      },
+    ],
+    type: 'suggestion',
+  },
+});

package/src/rules/implementsOnClasses.js

@@ -0,0 +1,64 @@
+import iterateJsdoc from '../iterateJsdoc.js';
+
+export default iterateJsdoc(({
+  report,
+  utils,
+}) => {
+  const iteratingFunction = utils.isIteratingFunction();
+
+  if (iteratingFunction) {
+    if (utils.hasATag([
+      'class',
+      'constructor',
+    ]) ||
+      utils.isConstructor()
+    ) {
+      return;
+    }
+  } else if (!utils.isVirtualFunction()) {
+    return;
+  }
+
+  utils.forEachPreferredTag('implements', (tag) => {
+    report('@implements used on a non-constructor function', null, tag);
+  });
+}, {
+  contextDefaults: true,
+  meta: {
+    docs: {
+      description: 'Reports an issue with any non-constructor function using `@implements`.',
+      url: 'https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/implements-on-classes.md#repos-sticky-header',
+    },
+    schema: [
+      {
+        additionalProperties: false,
+        properties: {
+          contexts: {
+            items: {
+              anyOf: [
+                {
+                  type: 'string',
+                },
+                {
+                  additionalProperties: false,
+                  properties: {
+                    comment: {
+                      type: 'string',
+                    },
+                    context: {
+                      type: 'string',
+                    },
+                  },
+                  type: 'object',
+                },
+              ],
+            },
+            type: 'array',
+          },
+        },
+        type: 'object',
+      },
+    ],
+    type: 'suggestion',
+  },
+});

package/src/rules/importsAsDependencies.js

@@ -0,0 +1,131 @@
+import iterateJsdoc from '../iterateJsdoc.js';
+import {
+  parse,
+  traverse,
+  tryParse,
+} from '@es-joy/jsdoccomment';
+import {
+  readFileSync,
+} from 'fs';
+import isBuiltinModule from 'is-builtin-module';
+import {
+  join,
+} from 'path';
+
+/**
+ * @type {Set<string>|null}
+ */
+let deps;
+
+const setDeps = function () {
+  try {
+    const pkg = JSON.parse(
+      // @ts-expect-error It's ok
+      readFileSync(join(process.cwd(), './package.json')),
+    );
+    deps = new Set([
+      ...(pkg.dependencies ?
+        /* c8 ignore next 2 */
+        Object.keys(pkg.dependencies) :
+        []),
+      ...(pkg.devDependencies ?
+        /* c8 ignore next 2 */
+        Object.keys(pkg.devDependencies) :
+        []),
+    ]);
+  /* c8 ignore next -- our package.json exists */
+  } catch (error) {
+    /* c8 ignore next -- our package.json exists */
+    deps = null;
+    /* c8 ignore next 4 -- our package.json exists */
+    /* eslint-disable no-console -- Inform user */
+    console.log(error);
+    /* eslint-enable no-console -- Inform user */
+  }
+};
+
+const moduleCheck = new Map();
+
+export default iterateJsdoc(({
+  jsdoc,
+  settings,
+  utils,
+}) => {
+  if (deps === undefined) {
+    setDeps();
+  }
+
+  /* c8 ignore next 3 -- our package.json exists */
+  if (deps === null) {
+    return;
+  }
+
+  const {
+    mode,
+  } = settings;
+
+  for (const tag of jsdoc.tags) {
+    let typeAst;
+    try {
+      typeAst = mode === 'permissive' ? tryParse(tag.type) : parse(tag.type, mode);
+    } catch {
+      continue;
+    }
+
+    // eslint-disable-next-line no-loop-func -- Safe
+    traverse(typeAst, (nde) => {
+      /* c8 ignore next 3 -- TS guard */
+      if (deps === null) {
+        return;
+      }
+
+      if (nde.type === 'JsdocTypeImport') {
+        let mod = nde.element.value.replace(
+          /^(@[^/]+\/[^/]+|[^/]+).*$/u, '$1',
+        );
+
+        if ((/^[./]/u).test(mod)) {
+          return;
+        }
+
+        if (isBuiltinModule(mod)) {
+          // mod = '@types/node';
+          // moduleCheck.set(mod, !deps.has(mod));
+          return;
+        } else if (!moduleCheck.has(mod)) {
+          let pkg;
+          try {
+            pkg = JSON.parse(
+              // @ts-expect-error It's ok
+              readFileSync(join(process.cwd(), 'node_modules', mod, './package.json')),
+            );
+          } catch {
+            // Ignore
+          }
+
+          if (!pkg || (!pkg.types && !pkg.typings)) {
+            mod = `@types/${mod}`;
+          }
+
+          moduleCheck.set(mod, !deps.has(mod));
+        }
+
+        if (moduleCheck.get(mod)) {
+          utils.reportJSDoc(
+            'import points to package which is not found in dependencies',
+            tag,
+          );
+        }
+      }
+    });
+  }
+}, {
+  iterateAllJsdocs: true,
+  meta: {
+    docs: {
+      description: 'Reports if JSDoc `import()` statements point to a package which is not listed in `dependencies` or `devDependencies`',
+      url: 'https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/imports-as-dependencies.md#repos-sticky-header',
+    },
+    type: 'suggestion',
+  },
+});

package/src/rules/informativeDocs.js

@@ -0,0 +1,182 @@
+import iterateJsdoc from '../iterateJsdoc.js';
+import {
+  areDocsInformative,
+} from 'are-docs-informative';
+
+const defaultAliases = {
+  a: [
+    'an', 'our',
+  ],
+};
+
+const defaultUselessWords = [
+  'a', 'an', 'i', 'in', 'of', 's', 'the',
+];
+
+/* eslint-disable complexity -- Temporary */
+
+/**
+ * @param {import('eslint').Rule.Node|import('@typescript-eslint/types').TSESTree.Node|null|undefined} node
+ * @returns {string[]}
+ */
+const getNamesFromNode = (node) => {
+  switch (node?.type) {
+  case 'AccessorProperty':
+  case 'MethodDefinition':
+  case 'PropertyDefinition':
+  case 'TSAbstractAccessorProperty':
+  case 'TSAbstractMethodDefinition':
+  case 'TSAbstractPropertyDefinition':
+    return [
+      ...getNamesFromNode(
+        /** @type {import('@typescript-eslint/types').TSESTree.Node} */ (
+          node.parent
+        ).parent,
+      ),
+      ...getNamesFromNode(
+        /** @type {import('@typescript-eslint/types').TSESTree.Node} */
+        (node.key),
+      ),
+    ];
+  case 'ClassDeclaration':
+  case 'ClassExpression':
+  case 'FunctionDeclaration':
+  case 'FunctionExpression':
+  case 'TSModuleDeclaration':
+  case 'TSMethodSignature':
+  case 'TSDeclareFunction':
+  case 'TSEnumDeclaration':
+  case 'TSEnumMember':
+  case 'TSInterfaceDeclaration':
+  case 'TSTypeAliasDeclaration':
+    return getNamesFromNode(
+      /** @type {import('@typescript-eslint/types').TSESTree.ClassDeclaration} */
+      (node).id,
+    );
+  case 'Identifier':
+    return [
+      node.name,
+    ];
+  case 'Property':
+    return getNamesFromNode(
+      /** @type {import('@typescript-eslint/types').TSESTree.Node} */
+      (node.key),
+    );
+  case 'VariableDeclaration':
+    return getNamesFromNode(
+      /** @type {import('@typescript-eslint/types').TSESTree.Node} */
+      (node.declarations[0]),
+    );
+  case 'VariableDeclarator':
+    return [
+      ...getNamesFromNode(
+        /** @type {import('@typescript-eslint/types').TSESTree.Node} */
+        (node.id),
+      ),
+      ...getNamesFromNode(
+        /** @type {import('@typescript-eslint/types').TSESTree.Node} */
+        (node.init),
+      ),
+    ].filter(Boolean);
+  default:
+    return [];
+  }
+};
+/* eslint-enable complexity -- Temporary */
+
+export default iterateJsdoc(({
+  context,
+  jsdoc,
+  node,
+  report,
+  utils,
+}) => {
+  const /** @type {{aliases: {[key: string]: string[]}, excludedTags: string[], uselessWords: string[]}} */ {
+    aliases = defaultAliases,
+    excludedTags = [],
+    uselessWords = defaultUselessWords,
+  } = context.options[0] || {};
+  const nodeNames = getNamesFromNode(node);
+
+  /**
+   * @param {string} text
+   * @param {string} extraName
+   * @returns {boolean}
+   */
+  const descriptionIsRedundant = (text, extraName = '') => {
+    const textTrimmed = text.trim();
+    return Boolean(textTrimmed) && !areDocsInformative(textTrimmed, [
+      extraName, nodeNames,
+    ].filter(Boolean).join(' '), {
+      aliases,
+      uselessWords,
+    });
+  };
+
+  const {
+    description,
+    lastDescriptionLine,
+  } = utils.getDescription();
+  let descriptionReported = false;
+
+  for (const tag of jsdoc.tags) {
+    if (excludedTags.includes(tag.tag)) {
+      continue;
+    }
+
+    if (descriptionIsRedundant(tag.description, tag.name)) {
+      utils.reportJSDoc(
+        'This tag description only repeats the name it describes.',
+        tag,
+      );
+    }
+
+    descriptionReported ||= tag.description === description &&
+      /** @type {import('comment-parser').Spec & {line: import('../iterateJsdoc.js').Integer}} */
+      (tag).line === lastDescriptionLine;
+  }
+
+  if (!descriptionReported && descriptionIsRedundant(description)) {
+    report('This description only repeats the name it describes.');
+  }
+}, {
+  iterateAllJsdocs: true,
+  meta: {
+    docs: {
+      description:
+        'This rule reports doc comments that only restate their attached name.',
+      url: 'https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/informative-docs.md#repos-sticky-header',
+    },
+    schema: [
+      {
+        additionalProperties: false,
+        properties: {
+          aliases: {
+            patternProperties: {
+              '.*': {
+                items: {
+                  type: 'string',
+                },
+                type: 'array',
+              },
+            },
+          },
+          excludedTags: {
+            items: {
+              type: 'string',
+            },
+            type: 'array',
+          },
+          uselessWords: {
+            items: {
+              type: 'string',
+            },
+            type: 'array',
+          },
+        },
+        type: 'object',
+      },
+    ],
+    type: 'suggestion',
+  },
+});