eslint-plugin-jsdoc 53.0.1 → 54.1.0

package/src/rules/checkTagNames.js

@@ -0,0 +1,314 @@
+import iterateJsdoc from '../iterateJsdoc.js';
+import escapeStringRegexp from 'escape-string-regexp';
+
+// https://babeljs.io/docs/en/babel-plugin-transform-react-jsx/
+const jsxTagNames = new Set([
+  'jsx',
+  'jsxFrag',
+  'jsxImportSource',
+  'jsxRuntime',
+]);
+
+const typedTagsAlwaysUnnecessary = new Set([
+  'augments',
+  'callback',
+  'class',
+  'enum',
+  'implements',
+  'private',
+  'property',
+  'protected',
+  'public',
+  'readonly',
+  'this',
+  'type',
+  'typedef',
+]);
+
+const typedTagsNeedingName = new Set([
+  'template',
+]);
+
+const typedTagsUnnecessaryOutsideDeclare = new Set([
+  'abstract',
+  'access',
+  'class',
+  'constant',
+  'constructs',
+  'default',
+  'enum',
+  'export',
+  'exports',
+  'function',
+  'global',
+  'inherits',
+  'instance',
+  'interface',
+  'member',
+  'memberof',
+  'memberOf',
+  'method',
+  'mixes',
+  'mixin',
+  'module',
+  'name',
+  'namespace',
+  'override',
+  'property',
+  'requires',
+  'static',
+  'this',
+]);
+
+export default iterateJsdoc(({
+  context,
+  jsdoc,
+  jsdocNode,
+  node,
+  report,
+  settings,
+  sourceCode,
+  utils,
+}) => {
+  const
+    /**
+     * @type {{
+     *   definedTags: string[],
+     *   enableFixer: boolean,
+     *   jsxTags: boolean,
+     *   typed: boolean
+     }} */ {
+      definedTags = [],
+      enableFixer = true,
+      jsxTags,
+      typed,
+    } = context.options[0] || {};
+
+  /** @type {(string|undefined)[]} */
+  let definedPreferredTags = [];
+  const {
+    structuredTags,
+    tagNamePreference,
+  } = settings;
+  const definedStructuredTags = Object.keys(structuredTags);
+  const definedNonPreferredTags = Object.keys(tagNamePreference);
+  if (definedNonPreferredTags.length) {
+    definedPreferredTags = Object.values(tagNamePreference).map((preferredTag) => {
+      if (typeof preferredTag === 'string') {
+        // May become an empty string but will be filtered out below
+        return preferredTag;
+      }
+
+      if (!preferredTag) {
+        return undefined;
+      }
+
+      if (typeof preferredTag !== 'object') {
+        utils.reportSettings(
+          'Invalid `settings.jsdoc.tagNamePreference`. Values must be falsy, a string, or an object.',
+        );
+      }
+
+      return preferredTag.replacement;
+    })
+      .filter(Boolean);
+  }
+
+  /**
+   * @param {import('eslint').Rule.Node} subNode
+   * @returns {boolean}
+   */
+  const isInAmbientContext = (subNode) => {
+    return subNode.type === 'Program' ?
+      context.getFilename().endsWith('.d.ts') :
+      Boolean(
+        /** @type {import('@typescript-eslint/types').TSESTree.VariableDeclaration} */ (
+          subNode
+        ).declare,
+      ) || isInAmbientContext(subNode.parent);
+  };
+
+  /**
+   * @param {import('comment-parser').Spec} jsdocTag
+   * @returns {boolean}
+   */
+  const tagIsRedundantWhenTyped = (jsdocTag) => {
+    if (!typedTagsUnnecessaryOutsideDeclare.has(jsdocTag.tag)) {
+      return false;
+    }
+
+    if (jsdocTag.tag === 'default') {
+      return false;
+    }
+
+    if (node === null) {
+      return false;
+    }
+
+    if (context.getFilename().endsWith('.d.ts') && [
+      null, 'Program', undefined,
+    ].includes(node?.parent?.type)) {
+      return false;
+    }
+
+    if (isInAmbientContext(/** @type {import('eslint').Rule.Node} */ (node))) {
+      return false;
+    }
+
+    return true;
+  };
+
+  /**
+   * @param {string} message
+   * @param {import('comment-parser').Spec} jsdocTag
+   * @param {import('../iterateJsdoc.js').Integer} tagIndex
+   * @param {Partial<import('comment-parser').Tokens>} [additionalTagChanges]
+   * @returns {void}
+   */
+  const reportWithTagRemovalFixer = (message, jsdocTag, tagIndex, additionalTagChanges) => {
+    utils.reportJSDoc(message, jsdocTag, enableFixer ? () => {
+      if (jsdocTag.description.trim()) {
+        utils.changeTag(jsdocTag, {
+          postType: '',
+          type: '',
+          ...additionalTagChanges,
+        });
+      } else {
+        utils.removeTag(tagIndex, {
+          removeEmptyBlock: true,
+        });
+      }
+    } : null, true);
+  };
+
+  /**
+   * @param {import('comment-parser').Spec} jsdocTag
+   * @param {import('../iterateJsdoc.js').Integer} tagIndex
+   * @returns {boolean}
+   */
+  const checkTagForTypedValidity = (jsdocTag, tagIndex) => {
+    if (typedTagsAlwaysUnnecessary.has(jsdocTag.tag)) {
+      reportWithTagRemovalFixer(
+        `'@${jsdocTag.tag}' is redundant when using a type system.`,
+        jsdocTag,
+        tagIndex,
+        {
+          postTag: '',
+          tag: '',
+        },
+      );
+      return true;
+    }
+
+    if (tagIsRedundantWhenTyped(jsdocTag)) {
+      reportWithTagRemovalFixer(
+        `'@${jsdocTag.tag}' is redundant outside of ambient (\`declare\`/\`.d.ts\`) contexts when using a type system.`,
+        jsdocTag,
+        tagIndex,
+      );
+      return true;
+    }
+
+    if (typedTagsNeedingName.has(jsdocTag.tag) && !jsdocTag.name) {
+      reportWithTagRemovalFixer(
+        `'@${jsdocTag.tag}' without a name is redundant when using a type system.`,
+        jsdocTag,
+        tagIndex,
+      );
+      return true;
+    }
+
+    return false;
+  };
+
+  for (let tagIndex = 0; tagIndex < jsdoc.tags.length; tagIndex += 1) {
+    const jsdocTag = jsdoc.tags[tagIndex];
+    const tagName = jsdocTag.tag;
+    if (jsxTags && jsxTagNames.has(tagName)) {
+      continue;
+    }
+
+    if (typed && checkTagForTypedValidity(jsdocTag, tagIndex)) {
+      continue;
+    }
+
+    const validTags = [
+      ...definedTags,
+      ...(/** @type {string[]} */ (definedPreferredTags)),
+      ...definedNonPreferredTags,
+      ...definedStructuredTags,
+      ...typed ? typedTagsNeedingName : [],
+    ];
+
+    if (utils.isValidTag(tagName, validTags)) {
+      let preferredTagName = utils.getPreferredTagName({
+        allowObjectReturn: true,
+        defaultMessage: `Blacklisted tag found (\`@${tagName}\`)`,
+        tagName,
+      });
+      if (!preferredTagName) {
+        continue;
+      }
+
+      let message;
+      if (typeof preferredTagName === 'object') {
+        ({
+          message,
+          replacement: preferredTagName,
+        } = /** @type {{message: string; replacement?: string | undefined;}} */ (
+          preferredTagName
+        ));
+      }
+
+      if (!message) {
+        message = `Invalid JSDoc tag (preference). Replace "${tagName}" JSDoc tag with "${preferredTagName}".`;
+      }
+
+      if (preferredTagName !== tagName) {
+        report(message, (fixer) => {
+          const replacement = sourceCode.getText(jsdocNode).replace(
+            new RegExp(`@${escapeStringRegexp(tagName)}\\b`, 'v'),
+            `@${preferredTagName}`,
+          );
+
+          return fixer.replaceText(jsdocNode, replacement);
+        }, jsdocTag);
+      }
+    } else {
+      report(`Invalid JSDoc tag name "${tagName}".`, null, jsdocTag);
+    }
+  }
+}, {
+  iterateAllJsdocs: true,
+  meta: {
+    docs: {
+      description: 'Reports invalid block tag names.',
+      url: 'https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/check-tag-names.md#repos-sticky-header',
+    },
+    fixable: 'code',
+    schema: [
+      {
+        additionalProperties: false,
+        properties: {
+          definedTags: {
+            items: {
+              type: 'string',
+            },
+            type: 'array',
+          },
+          enableFixer: {
+            type: 'boolean',
+          },
+          jsxTags: {
+            type: 'boolean',
+          },
+          typed: {
+            type: 'boolean',
+          },
+        },
+        type: 'object',
+      },
+    ],
+    type: 'suggestion',
+  },
+});

package/src/rules/checkTemplateNames.js

@@ -0,0 +1,204 @@
+import iterateJsdoc, {
+  parseComment,
+} from '../iterateJsdoc.js';
+import {
+  getTags,
+} from '../jsdocUtils.js';
+import {
+  getJSDocComment,
+  parse as parseType,
+  traverse,
+  tryParse as tryParseType,
+} from '@es-joy/jsdoccomment';
+
+export default iterateJsdoc(({
+  jsdoc,
+  node,
+  report,
+  settings,
+  sourceCode,
+  utils,
+}) => {
+  const {
+    mode,
+  } = settings;
+
+  const templateTags = utils.getTags('template');
+
+  const usedNames = new Set();
+  /**
+   * @param {string} potentialType
+   */
+  const checkForUsedTypes = (potentialType) => {
+    let parsedType;
+    try {
+      parsedType = mode === 'permissive' ?
+        tryParseType(/** @type {string} */ (potentialType)) :
+        parseType(/** @type {string} */ (potentialType), mode);
+    } catch {
+      return;
+    }
+
+    traverse(parsedType, (nde) => {
+      const {
+        type,
+        value,
+      } = /** @type {import('jsdoc-type-pratt-parser').NameResult} */ (nde);
+      if (type === 'JsdocTypeName') {
+        usedNames.add(value);
+      }
+    });
+  };
+
+  const checkParamsAndReturnsTags = (jsdc = jsdoc) => {
+    const paramName = /** @type {string} */ (utils.getPreferredTagName({
+      tagName: 'param',
+    }));
+    const paramTags = getTags(jsdc, paramName);
+    for (const paramTag of paramTags) {
+      checkForUsedTypes(paramTag.type);
+    }
+
+    const returnsName = /** @type {string} */ (utils.getPreferredTagName({
+      tagName: 'returns',
+    }));
+    const returnsTags = getTags(jsdc, returnsName);
+    for (const returnsTag of returnsTags) {
+      checkForUsedTypes(returnsTag.type);
+    }
+  };
+
+  const checkTemplateTags = () => {
+    for (const tag of templateTags) {
+      const {
+        name,
+      } = tag;
+      const names = name.split(/,\s*/v);
+      for (const nme of names) {
+        if (!usedNames.has(nme)) {
+          report(`@template ${nme} not in use`, null, tag);
+        }
+      }
+    }
+  };
+
+  /**
+   * @param {import('@typescript-eslint/types').TSESTree.FunctionDeclaration|
+   *   import('@typescript-eslint/types').TSESTree.ClassDeclaration|
+   *   import('@typescript-eslint/types').TSESTree.TSInterfaceDeclaration|
+   *   import('@typescript-eslint/types').TSESTree.TSTypeAliasDeclaration} aliasDeclaration
+   * @param {boolean} [checkParamsAndReturns]
+   */
+  const checkParameters = (aliasDeclaration, checkParamsAndReturns) => {
+    /* c8 ignore next -- Guard */
+    const {
+      params,
+    } = aliasDeclaration.typeParameters ?? {
+      params: [],
+    };
+    for (const {
+      name: {
+        name,
+      },
+    } of params) {
+      usedNames.add(name);
+    }
+
+    if (checkParamsAndReturns) {
+      checkParamsAndReturnsTags();
+    } else if (aliasDeclaration.type === 'ClassDeclaration') {
+      /* c8 ignore next -- TS */
+      for (const nde of aliasDeclaration?.body?.body ?? []) {
+        // @ts-expect-error Should be ok
+        const commentNode = getJSDocComment(sourceCode, nde, settings);
+        if (!commentNode) {
+          continue;
+        }
+
+        const innerJsdoc = parseComment(commentNode, '');
+        checkParamsAndReturnsTags(innerJsdoc);
+
+        const typeName = /** @type {string} */ (utils.getPreferredTagName({
+          tagName: 'type',
+        }));
+        const typeTags = getTags(innerJsdoc, typeName);
+        for (const typeTag of typeTags) {
+          checkForUsedTypes(typeTag.type);
+        }
+      }
+    }
+
+    checkTemplateTags();
+  };
+
+  const handleTypeAliases = () => {
+    const nde = /** @type {import('@typescript-eslint/types').TSESTree.Node} */ (
+      node
+    );
+    if (!nde) {
+      return;
+    }
+
+    switch (nde.type) {
+      case 'ClassDeclaration':
+      case 'TSInterfaceDeclaration':
+      case 'TSTypeAliasDeclaration':
+        checkParameters(nde);
+        break;
+      case 'ExportDefaultDeclaration':
+      case 'ExportNamedDeclaration':
+        switch (nde.declaration?.type) {
+          case 'ClassDeclaration':
+          case 'TSInterfaceDeclaration':
+          case 'TSTypeAliasDeclaration':
+            checkParameters(nde.declaration);
+            break;
+          case 'FunctionDeclaration':
+            checkParameters(nde.declaration, true);
+            break;
+        }
+
+        break;
+      case 'FunctionDeclaration':
+        checkParameters(nde, true);
+        break;
+    }
+  };
+
+  const callbackTags = utils.getTags('callback');
+  const functionTags = utils.getTags('function');
+  if (callbackTags.length || functionTags.length) {
+    checkParamsAndReturnsTags();
+    checkTemplateTags();
+    return;
+  }
+
+  const typedefTags = utils.getTags('typedef');
+  if (!typedefTags.length || typedefTags.length >= 2) {
+    handleTypeAliases();
+    return;
+  }
+
+  const potentialTypedefType = typedefTags[0].type;
+  checkForUsedTypes(potentialTypedefType);
+
+  const propertyName = /** @type {string} */ (utils.getPreferredTagName({
+    tagName: 'property',
+  }));
+  const propertyTags = utils.getTags(propertyName);
+  for (const propertyTag of propertyTags) {
+    checkForUsedTypes(propertyTag.type);
+  }
+
+  checkTemplateTags();
+}, {
+  iterateAllJsdocs: true,
+  meta: {
+    docs: {
+      description: 'Checks that any `@template` names are actually used in the connected `@typedef` or type alias.',
+      url: 'https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/check-template-names.md#repos-sticky-header',
+    },
+    schema: [],
+    type: 'suggestion',
+  },
+});