eslint-plugin-jsdoc 52.0.4 → 53.0.0

package/src/rules/checkTagNames.js

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

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