eslint-plugin-jsdoc 64.3.0 → 64.3.2

package/README.md

@@ -512,7 +512,7 @@ non-default-recommended fixer).
 ||| [no-restricted-syntax](./docs/rules/no-restricted-syntax.md#readme) | Reports when certain comment structures are present. |
 |On in TS; Off in TS flavor|:wrench:| [no-types](./docs/rules/no-types.md#readme) | This rule reports types being used on `@param` or `@returns` (redundant with TypeScript). |
 |:heavy_check_mark: (Off in TS; Off in TS flavor)|| [no-undefined-types](./docs/rules/no-undefined-types.md#readme) | Besides some expected built-in types, prohibits any types not specified as globals or within `@typedef`. |
-||| [no-unnecessary-type-assertion](./docs/rules/no-unnecessary-type-assertion.md#readme) | Reports redundant @type tags that match or broaden the naturally inferred TypeScript type. |
+||:wrench:| [no-unnecessary-type-assertion](./docs/rules/no-unnecessary-type-assertion.md#readme) | Reports redundant @type tags that match or broaden the naturally inferred TypeScript type. |
 ||:wrench:| [normalize-see-links](./docs/rules/normalize-see-links.md#readme) | Normalizes labeled links in `@see` tags to a canonical `{@link}` form. |
 ||:wrench:| [prefer-import-tag](./docs/rules/prefer-import-tag.md#readme) | Prefer `@import` tags to inline `import()` statements. |
 |:heavy_check_mark:|| [reject-any-type](./docs/rules/reject-any-type.md#readme) | Reports use of `any` or `*` type |

package/dist/getJsdocProcessorPlugin.d.ts

@@ -1,5 +1,4 @@
 export function getJsdocProcessorPlugin(options?: JsdocProcessorOptions): ESLint.Plugin;
-export type Integer = number;
 export type JsdocProcessorOptions = {
     /**
      * Require captions for example tags

package/dist/index.d.ts

@@ -86,13 +86,16 @@ export type ConfigGroups = "recommended" | "stylistic" | "contents" | "logical"
 export type ConfigVariants = "" | "-typescript" | "-typescript-flavor";
 export type ErrorLevelVariants = "" | "-error";
 export type FlatConfigNames = `flat/${ConfigGroups}${ConfigVariants}${ErrorLevelVariants}` | "flat/recommended-tsdoc" | "flat/recommended-tsdoc-error";
+export type JsdocPlugin = import("eslint").ESLint.Plugin & {
+    configs: Record<FlatConfigNames, import("eslint").Linter.Config> & Record<"examples" | "default-expressions" | "examples-and-default-expressions", import("eslint").Linter.Config[]> & Record<"flat/recommended-mixed", import("eslint").Linter.Config[]>;
+};
 /**
  * @typedef {"recommended" | "stylistic" | "contents" | "logical" | "requirements"} ConfigGroups
  * @typedef {"" | "-typescript" | "-typescript-flavor"} ConfigVariants
  * @typedef {"" | "-error"} ErrorLevelVariants
  * @typedef {`flat/${ConfigGroups}${ConfigVariants}${ErrorLevelVariants}` |
  *   "flat/recommended-tsdoc" | "flat/recommended-tsdoc-error"} FlatConfigNames
- * @type {import('eslint').ESLint.Plugin & {
+ * @typedef {import('eslint').ESLint.Plugin & {
  *   configs: Record<
  *      FlatConfigNames,
  *       import('eslint').Linter.Config
@@ -102,9 +105,7 @@ export type FlatConfigNames = `flat/${ConfigGroups}${ConfigVariants}${ErrorLevel
  *       import('eslint').Linter.Config[]
  *     > &
  *     Record<"flat/recommended-mixed", import('eslint').Linter.Config[]>
- * }}
+ * }} JsdocPlugin
  */
-declare const index: import("eslint").ESLint.Plugin & {
-    configs: Record<FlatConfigNames, import("eslint").Linter.Config> & Record<"examples" | "default-expressions" | "examples-and-default-expressions", import("eslint").Linter.Config[]> & Record<"flat/recommended-mixed", import("eslint").Linter.Config[]>;
-};
+declare const index: JsdocPlugin;
 //# sourceMappingURL=index.d.ts.map

package/dist/rules.d.ts

@@ -1320,6 +1320,10 @@ export interface Rules {
            * Whether to check `const` type assertions as redundant
            */
           checkLiteralConstAssertions?: boolean;
+          /**
+           * Whether to enable the fixer that removes the redundant `@type` tag (and the JSDoc block if it becomes empty). Defaults to `true`.
+           */
+          enableFixer?: boolean;
           /**
            * Whether to treat `any` type casts as redundant
            */

package/package.json

@@ -69,7 +69,7 @@
     "semantic-release": "^25.0.9",
     "sinon": "^22.1.0",
     "ts-api-utils": "^2.5.0",
-    "typescript": "5.9.3",
+    "typescript": "6.0.3",
     "typescript-eslint": "8.67.0"
   },
   "engines": {
@@ -139,6 +139,7 @@
   "scripts": {
     "ruleTypes": "node ./src/bin/generateRuleTypes.js",
     "tsc": "tsc",
+    "tsc:ts7": "npx -y -p typescript@^7 -c \"tsc\"",
     "tsc-build": "tsc -p tsconfig-prod.json",
     "build": "rimraf ./dist && mkdir dist && pnpm tsc-build && cp src/rules.d.ts dist/rules.d.ts",
     "attw": "attw --profile esm-only --pack .",
@@ -156,5 +157,5 @@
     "test-cov": "TIMING=1 c8 --reporter text pnpm run test-no-cov",
     "test-index": "pnpm run test-no-cov test/rules/index.js"
   },
-  "version": "64.3.0"
+  "version": "64.3.2"
 }

package/src/getJsdocProcessorPlugin.js

@@ -80,9 +80,6 @@ const getLinesCols = (text) => {
   ];
 };
 
-/**
- * @typedef {number} Integer
- */
 /**
  * @typedef {object} JsdocProcessorOptions
  * @property {boolean} [captionRequired] Require captions for example tags

package/src/index.js

@@ -89,7 +89,7 @@ import semver from 'semver';
  * @typedef {"" | "-error"} ErrorLevelVariants
  * @typedef {`flat/${ConfigGroups}${ConfigVariants}${ErrorLevelVariants}` |
  *   "flat/recommended-tsdoc" | "flat/recommended-tsdoc-error"} FlatConfigNames
- * @type {import('eslint').ESLint.Plugin & {
+ * @typedef {import('eslint').ESLint.Plugin & {
  *   configs: Record<
  *      FlatConfigNames,
  *       import('eslint').Linter.Config
@@ -99,10 +99,10 @@ import semver from 'semver';
  *       import('eslint').Linter.Config[]
  *     > &
  *     Record<"flat/recommended-mixed", import('eslint').Linter.Config[]>
- * }}
+ * }} JsdocPlugin
  */
-const index = {};
-index.configs = {};
+const index = /** @type {JsdocPlugin} */ ({});
+index.configs = /** @type {typeof index.configs} */ ({});
 index.rules = {
   'check-access': checkAccess,
   'check-alignment': checkAlignment,

package/src/iterateJsdoc.js

@@ -192,10 +192,10 @@ import esquery from 'esquery';
  */
 
 /**
- * @callback ChangeTag
- * @param {import('comment-parser').Spec} tag
- * @param {...Partial<import('comment-parser').Tokens>} tokens
- * @returns {void}
+ * @typedef {(
+ *   tag: import('comment-parser').Spec,
+ *   ...tokens: Partial<import('comment-parser').Tokens>[]
+ * ) => void} ChangeTag
  */
 
 /**
@@ -624,8 +624,7 @@ const getBasicUtils = (context, {
   mode,
   tagNamePreference,
 }) => {
-  /** @type {BasicUtils} */
-  const utils = {};
+  const utils = /** @type {BasicUtils} */ ({});
 
   for (const method of [
     'isNameOrNamepathDefiningTag',

package/src/jsdocUtils.js

@@ -368,9 +368,7 @@ const getFunctionParameterNames = (
                   /** @type {import('estree').Identifier} */ (
                     param.key
                   ).name,
-                  /** @type {import('estree').AssignmentPattern} */ (
-                    param.value
-                  ).right.properties.map((prop) => {
+                  param.value.right.properties.map((prop) => {
                     return /** @type {string} */ (getParamName(
                       /** @type {import('estree').Property} */
                       (prop),

package/src/rules/checkTypes.js

@@ -44,9 +44,14 @@ const checkNativeTypes = (preferredTypes, typeNodeName, preferred, parentNode, i
             parentNode
           )?.left?.type === 'JsdocTypeName' &&
           /**
-           * @type {import('jsdoc-type-pratt-parser').GenericResult}
+           * @type {import('jsdoc-type-pratt-parser').NameResult}
            */
-          (parentNode)?.left?.value === 'Object'
+          (
+            /**
+             * @type {import('jsdoc-type-pratt-parser').GenericResult}
+             */
+            (parentNode)?.left
+          )?.value === 'Object'
         )
       )
     ) {

package/src/rules/noUnnecessaryTypeAssertion.js

@@ -1,9 +1,12 @@
+/* eslint-disable no-bitwise -- Convenient */
 /* eslint-disable jsdoc/reject-any-type -- TypeScript types need not be installed */
 import iterateJsdoc from '../iterateJsdoc.js';
 import {
   createRequire,
 } from 'module';
 
+let warned = false;
+
 /** @type {any} */
 let ts;
 
@@ -37,7 +40,7 @@ const isLiteralType = (type) => {
   }
 
   // Check using TypeFlags for specific edge cases like boolean or template literals
-  // eslint-disable-next-line no-bitwise -- Convenient
+
   if (type.flags & (ts.TypeFlags.BooleanLiteral | ts.TypeFlags.TemplateLiteral)) {
     return true;
   }
@@ -59,9 +62,13 @@ const isLiteralType = (type) => {
 
 export default iterateJsdoc(({
   context,
+  jsdoc,
+  jsdocNode,
   node: nde,
   report,
+  sourceCode,
   utils,
+// eslint-disable-next-line complexity -- Numerous type/option permutations
 }) => {
   /* c8 ignore next 4 -- Guard */
   // Already handled
@@ -79,10 +86,41 @@ export default iterateJsdoc(({
   const {
     // https://typescript-eslint.io/rules/no-unnecessary-type-assertion/
     checkLiteralConstAssertions = false,
+    enableFixer = true,
     treatAnyAsRedundant = false,
     typesToIgnore = [],
   } = context.options[0] ?? {};
 
+  /**
+   * Removes the redundant `@type` tag, deleting the whole JSDoc block if it
+   * is left empty.
+   * @returns {void}
+   */
+  const removeType = () => {
+    utils.removeTag(jsdoc.tags.indexOf(/** @type {any} */ (types[0])), {
+      removeEmptyBlock: true,
+    });
+
+    // `removeTag` only drops the enclosing block for a single-line comment; for
+    // a multi-line block whose sole content was the `@type` tag, clear what is
+    // left (only the delimiter lines) so the now-empty comment is removed too.
+    const blockIsEmpty = jsdoc.source.every(({
+      tokens: {
+        description,
+        name,
+        tag,
+        type,
+      },
+    }) => {
+      return !tag && !type && !name && !description.trim();
+    });
+    if (blockIsEmpty) {
+      jsdoc.source.splice(0);
+    }
+  };
+
+  const fixer = enableFixer ? removeType : null;
+
   const node =
     /**
      * @type {import('@typescript-eslint/utils').TSESTree.Node}
@@ -94,11 +132,15 @@ export default iterateJsdoc(({
      * @type {import('@typescript-eslint/utils').ParserServices}
      */ (context.sourceCode.parserServices);
 
-  /* c8 ignore next 6 -- Guard */
+  /* c8 ignore next 10 -- Guard */
   if (!services || !services.program) {
-    // Cannot proceed without type-aware linting enabled
-    // eslint-disable-next-line no-console -- Feedback
-    console.warn('⚠️ You must point ESLint to the `typescript-eslint` parser using `languageOptions`. See the documentation for `jsdoc/no-unnecessary-type-assertion`.');
+    if (!warned) {
+      // Cannot proceed without type-aware linting enabled
+      // eslint-disable-next-line no-console -- Feedback
+      console.warn('⚠️ You must point ESLint to the `typescript-eslint` parser using `languageOptions`. See the documentation for `jsdoc/no-unnecessary-type-assertion`.');
+      warned = true;
+    }
+
     return;
   }
 
@@ -106,37 +148,201 @@ export default iterateJsdoc(({
   // const services = ESLintUtils.getParserServices(context);
   const checker = services.program.getTypeChecker();
 
+  const assertedTypeStr = types[0].type;
+
+  const message = assertedTypeStr === 'const' ?
+    'The @type tag declaring "{{ type }}" is redundant as TypeScript infers it automatically for literals.' :
+    'The @type tag declaring "{{ type }}" is redundant as TypeScript infers it automatically.';
+
   /**
-   * @param {string} typeStr
-   * @returns {any} `ts.Type`
+   * Whether `inferredType` is a generic reference carrying `any` type arguments
+   * that `assertedType` replaces with concrete ones (e.g. an untyped
+   * `document.querySelectorAll(sel)` giving `NodeListOf<any>`, asserted as
+   * `NodeListOf<HTMLElement>`, or `new Map()` giving `Map<any, any>`). Such an
+   * assertion supplies real type information, so it is not redundant even though
+   * `any` leaves the two types mutually assignable.
+   * @param {any} inferredType `ts.Type`
+   * @param {any} assertedType `ts.Type`
+   * @returns {boolean}
    */
-  const getTypeFromString = (typeStr) => {
-    // 2. Parse the type string into a virtual TypeScript SourceFile
-    const virtualSourceFile = ts.createSourceFile(
-      'inline-type-eval.ts',
-      `type __TargetType = ${typeStr};`,
-      ts.ScriptTarget.Latest,
-      true,
-    );
+  const tightensAnyTypeArgument = (inferredType, assertedType) => {
+    // Only ever called for an object type, which always carries `objectFlags`.
+    if ((inferredType.objectFlags & ts.ObjectFlags.Reference) === 0) {
+      return false;
+    }
+
+    const assertedTypeArguments = checker.getTypeArguments(assertedType);
+
+    return checker.getTypeArguments(inferredType).some((inferredTypeArgument, index) => {
+      return (inferredTypeArgument.flags & ts.TypeFlags.Any) !== 0 &&
+        assertedTypeArguments[index] !== undefined &&
+        (assertedTypeArguments[index].flags & ts.TypeFlags.Any) === 0;
+    });
+  };
+
+  /**
+   * A generic call/`new` expression takes its type arguments partly from the
+   * surrounding contextual type, which under a `@type` (a cast, or a
+   * declaration) is the asserted type itself. `getTypeAtLocation` then just
+   * echoes the asserted type back, so a genuine tightening looks redundant
+   * (`document.querySelectorAll(sel)` is really `NodeListOf<Element>`, not the
+   * asserted `NodeListOf<HTMLElement>`). The uncontaminated type cannot be
+   * recovered here, so such expressions are left alone.
+   * @param {any} tsExpression `ts.Node`
+   * @returns {boolean}
+   */
+  const isGenericCall = (tsExpression) => {
+    if (!ts.isCallExpression(tsExpression) && !ts.isNewExpression(tsExpression)) {
+      return false;
+    }
 
-    // 3. Find the TypeNode in the AST (type __TargetType = <TypeNode>;)
-    // Type `ts.TypeAliasDeclaration`
-    const typeAlias = /** @type {any} */ (
-      virtualSourceFile.statements[0]
+    const signature = /** @type {any} */ (
+      checker.getResolvedSignature(tsExpression)
     );
-    const typeNode = typeAlias.type;
+    return Boolean(
+      signature &&
+      (signature.typeParameters ?? signature.target?.typeParameters)?.length,
+    );
+  };
+
+  /**
+   * A template literal with interpolations widens to `string` on its own, but a
+   * surrounding `@type` (a cast, or a declaration) contextually narrows it to a
+   * template-literal type, so `getTypeAtLocation` echoes the asserted literal
+   * back and a genuine narrowing (`\`${x}Reference\`` really being `string`,
+   * asserted as `AvailableType`) looks redundant.
+   * @param {any} estreeExpression
+   * @returns {boolean}
+   */
+  const isInterpolatedTemplateLiteral = (estreeExpression) => {
+    return estreeExpression?.type === 'TemplateLiteral' &&
+      estreeExpression.expressions.length > 0;
+  };
+
+  /**
+   * Whether `type` carries no real structure to compare against — `any`,
+   * `never`, `null`, `undefined`, an empty array (`[]` -> `never[]`), an empty
+   * object (`{}`), or an array whose element type is itself such a placeholder
+   * (`any[]`). An assertion onto a placeholder is always supplying real type
+   * information, so it is not redundant.
+   * @param {any} type `ts.Type`
+   * @returns {boolean}
+   */
+  const isPlaceholderType = (type) => {
+    if ((type.flags & (
+      ts.TypeFlags.Any | ts.TypeFlags.Never |
+      ts.TypeFlags.Null | ts.TypeFlags.Undefined
+    )) !== 0) {
+      return true;
+    }
+
+    if ((type.flags & ts.TypeFlags.Object) === 0) {
+      return false;
+    }
+
+    if (checker.isArrayType(type)) {
+      const [
+        elementType,
+      ] = checker.getTypeArguments(/** @type {import('typescript').TypeReference} */ (
+        type
+      ));
+      return !elementType || (elementType.flags & (
+        ts.TypeFlags.Never | ts.TypeFlags.Undefined | ts.TypeFlags.Any
+      )) !== 0;
+    }
+
+    const {
+      objectFlags,
+    } = /** @type {import('typescript').ObjectType} */ (type);
+    return (objectFlags & ts.ObjectFlags.EmptyObjectLiteral) !== 0 ||
+      checker.getPropertiesOfType(type).length === 0;
+  };
+
+  /**
+   * Whether the JSDoc-asserted type adds nothing over the type TypeScript
+   * already infers for the expression it is attached to.
+   * @param {any} rawInferredType `ts.Type`
+   * @param {any} rawAssertedType `ts.Type`
+   * @returns {boolean}
+   */
+  const isRedundantAssertion = (rawInferredType, rawAssertedType) => {
+    if (assertedTypeStr === 'const') {
+      return checkLiteralConstAssertions && isLiteralType(rawInferredType);
+    }
+
+    if (!treatAnyAsRedundant && assertedTypeStr === 'any') {
+      return false;
+    }
+
+    if (typesToIgnore.includes(assertedTypeStr)) {
+      return false;
+    }
+
+    // An `any` expression (e.g. a property of `JSON.parse(s)`) is assignable to
+    // everything, so a concrete assertion on it is genuinely narrowing rather
+    // than redundant. (`@type {any}` on `any` still falls through to the
+    // `treatAnyAsRedundant` handling above/below.)
+    if (
+      (rawInferredType.flags & ts.TypeFlags.Any) !== 0 &&
+      (rawAssertedType.flags & ts.TypeFlags.Any) === 0
+    ) {
+      return false;
+    }
+
+    // A union such as `never[] | {}` (from `cond ? [] : {}`) reaches the
+    // primitive path below; if every constituent is a structureless placeholder
+    // the assertion is supplying the real shape, so it is not redundant.
+    if (rawInferredType.isUnion() && rawInferredType.types.every(isPlaceholderType)) {
+      return false;
+    }
+
+    const isObjectOrArray = (rawInferredType.flags & ts.TypeFlags.Object) !== 0;
+
+    if (!isObjectOrArray) {
+      // Primitives and individual literal values ("text" -> string) use unidirectional verification
+      return checker.isTypeAssignableTo(rawInferredType, rawAssertedType);
+    }
+
+    if (isPlaceholderType(rawInferredType)) {
+      return false;
+    }
+
+    if (checker.isArrayType(rawInferredType)) {
+      // Arrays: standard structural bidirectional assignment matches string[] vs string[]
+      return checker.isTypeAssignableTo(rawInferredType, rawAssertedType) &&
+        checker.isTypeAssignableTo(rawAssertedType, rawInferredType);
+    }
+
+    if (tightensAnyTypeArgument(rawInferredType, rawAssertedType)) {
+      return false;
+    }
 
-    // 4. Resolve the type using the TypeChecker
-    // Note: If the type string references external symbols or types from your
-    // actual codebase, the checker may require a complete program context to resolve them.
-    return checker.getTypeFromTypeNode(typeNode);
+    // Objects: strip the literal-initialization flags, then require structural
+    // equivalence in both directions, so `{prop: string}` vs `{prop: string}` is
+    // redundant while `{prop?: string}` vs `{prop: string}` fails backward.
+    const inferredBaseType = checker.getBaseTypeOfLiteralType(rawInferredType);
+    const assertedBaseType = checker.getBaseTypeOfLiteralType(rawAssertedType);
+
+    return checker.isTypeAssignableTo(inferredBaseType, assertedBaseType) &&
+      checker.isTypeAssignableTo(assertedBaseType, inferredBaseType);
   };
 
-  // Todo: Support more than just VariableDeclaration!
+  // Positions where a bare expression of any precedence is valid and equivalent
+  // to the parenthesized form, so a redundant `/** @type {T} */ (expr)` cast can
+  // be unwrapped to `expr` without changing meaning.
+  const unwrappableParentTypes = new Set([
+    'ArrayExpression',
+    'AssignmentExpression',
+    'ReturnStatement',
+    'ThrowStatement',
+    'VariableDeclarator',
+  ]);
 
-  // 3. For this example, let's assume we are checking VariableDeclarators
-  // e.g., `/** @type {number} */ const x = 5;`
+  // 3. `/** @type {T} */ const x = 5;`
   if (node?.type === 'VariableDeclaration') {
+    // A leading `@type` tag only influences the first declarator (TypeScript
+    // leaves the rest to their own inferred types), so checking `[0]` fully
+    // determines whether the tag is redundant even for `const a = 1, b = 2;`.
     const decl = node.declarations[0];
 
     /* c8 ignore next 4 -- How to cover? */
@@ -145,59 +351,146 @@ export default iterateJsdoc(({
       return;
     }
 
-    // 4. Map the ESLint AST nodes to TypeScript AST nodes
-    // const tsNode = services.esTreeNodeToTSNodeMap.get(decl.id);
-    const tsInit = services.esTreeNodeToTSNodeMap.get(decl.init);
+    // Resolve the `@type` tag through the real TypeNode that TypeScript already
+    // parsed and bound as part of the program. Re-parsing the type string into
+    // a detached virtual source file (as an earlier approach did) leaves object
+    // type literals unbound, so `{prop: string}` collapses to `{}`.
+    const jsdocTypeNode = ts.getJSDocType(
+      services.esTreeNodeToTSNodeMap.get(decl),
+    );
 
-    // 5. Get the types
-    // tsNode type includes the JSDoc explicit type
-    // tsInit type is the purely inferred type from the right-hand side
-    const inferredType = checker.getTypeAtLocation(tsInit);
+    /* c8 ignore next 3 -- Every `@type` tag reaching here has a bound TypeNode */
+    if (!jsdocTypeNode) {
+      return;
+    }
 
-    // 6. Compare the types.
-    const declaredTypeStr = types[0].type;
-    const declaredType = getTypeFromString(declaredTypeStr);
+    const declInitTsNode = services.esTreeNodeToTSNodeMap.get(decl.init);
+    if (isGenericCall(declInitTsNode) || isInterpolatedTemplateLiteral(decl.init)) {
+      return;
+    }
 
-    const isRedundantType = checker.isTypeAssignableTo(
-      inferredType,
-      declaredType,
-    );
+    const declInferredType = checker.getTypeAtLocation(declInitTsNode);
+    const declAssertedType = checker.getTypeFromTypeNode(jsdocTypeNode);
 
-    if (declaredTypeStr === 'const') {
-      if (checkLiteralConstAssertions && isLiteralType(inferredType)) {
-        report(
-          'The @type tag declaring "{{ type }}" is redundant as TypeScript infers it automatically for literals.',
-          null,
-          types[0],
-          {
-            type: declaredTypeStr,
-          },
-        );
-      }
+    if (isRedundantAssertion(declInferredType, declAssertedType)) {
+      utils.reportJSDoc(message, types[0], fixer, true, {
+        type: assertedTypeStr,
+      });
+    }
+
+    return;
+  }
+
+  // 4. Inline cast: `/** @type {T} */ (expr)` (TypeScript's JSDoc assertion).
+  const exprTsNode = services.esTreeNodeToTSNodeMap.get(node);
+  const paren = exprTsNode?.parent;
+  if (!paren || !ts.isParenthesizedExpression(paren)) {
+    return;
+  }
 
+  const typeTag = ts.getJSDocTypeTag(paren);
+
+  /* c8 ignore next 4 -- Defensive: `getJSDocTypeTag` can also surface a `@type`
+     inherited from an enclosing statement, whose position precedes the paren */
+  if (!typeTag || typeTag.pos < paren.pos) {
+    return;
+  }
+
+  // The `@type` TypeScript resolves for `paren` must be the very comment being
+  // iterated. When the comment actually sits on an inner parenthesized
+  // sub-expression that is then a member/argument of the paren's operand
+  // (`/** @type {DOMException} */ (reader.error).message`), `paren` is a
+  // different, outer cast carrying a different comment, so measuring or fixing
+  // against it would target the wrong expression (and drop the inner cast).
+  if (typeTag.parent.end !== jsdocNode.range[1]) {
+    return;
+  }
+
+  if (isGenericCall(exprTsNode) || isInterpolatedTemplateLiteral(node)) {
+    return;
+  }
+
+  // The `unknown` half of a "cast through `unknown`"
+  // (`/** @type {T} */ (/** @type {unknown} */ (x))`) is the load-bearing
+  // bridge that lets the outer assertion reach an otherwise-incompatible type;
+  // it is never redundant, even though `unknown` is broader than everything.
+  if (assertedTypeStr === 'unknown' && ts.isParenthesizedExpression(paren.parent)) {
+    const outerTypeTag = ts.getJSDocTypeTag(paren.parent);
+    if (outerTypeTag && outerTypeTag.pos >= paren.parent.pos) {
       return;
     }
+  }
 
-    if (
-      isRedundantType && (treatAnyAsRedundant || declaredTypeStr !== 'any') &&
-      !typesToIgnore.includes(declaredTypeStr)
-    ) {
-      report(
-        'The @type tag declaring "{{ type }}" is redundant as TypeScript infers it automatically.',
-        null,
-        types[0],
-        {
-          type: declaredTypeStr,
-        },
-      );
-    }
+  const parent = /** @type {any} */ (node.parent);
+  const declaration = parent.type === 'VariableDeclarator' ? parent.parent : null;
+
+  // A `/** @type {const} */` cast only fails to do real work on a `const`
+  // declarator, which already infers the literal type. Anywhere else (`let`, a
+  // return, an object-property value, some generic call arguments, …) it
+  // suppresses widening, so it is not redundant.
+  if (assertedTypeStr === 'const' && declaration?.kind !== 'const') {
+    return;
   }
+
+  // For a mutable binding (`let`/`var`) TypeScript widens the initializer, so a
+  // narrowing cast such as `/** @type {5} */` is doing real work; widen the
+  // uncast type to match before judging redundancy.
+  const mutableBinding = Boolean(declaration) && declaration.kind !== 'const';
+  const castInferredType = mutableBinding ?
+    checker.getBaseTypeOfLiteralType(checker.getTypeAtLocation(exprTsNode)) :
+    checker.getTypeAtLocation(exprTsNode);
+  const castAssertedType = checker.getTypeFromTypeNode(typeTag.typeExpression.type);
+
+  if (!isRedundantAssertion(castInferredType, castAssertedType)) {
+    return;
+  }
+
+  const canUnwrap = enableFixer && (
+    unwrappableParentTypes.has(parent.type) ||
+    (parent.type === 'ConditionalExpression' && parent.test !== node) ||
+    ((parent.type === 'CallExpression' || parent.type === 'NewExpression') &&
+      parent.callee !== node)
+  );
+
+  report(
+    message,
+    canUnwrap ?
+      /**
+       * @param {import('eslint').Rule.RuleFixer} ruleFixer
+       * @returns {import('eslint').Rule.Fix}
+       */
+      (ruleFixer) => {
+        const closeParen = /** @type {import('eslint').AST.Token} */ (
+          sourceCode.getTokenAfter(/** @type {any} */ (node), {
+            filter: ({
+              type,
+              value,
+            }) => {
+              return type === 'Punctuator' && value === ')';
+            },
+          })
+        );
+
+        return ruleFixer.replaceTextRange(
+          [
+            jsdocNode.range[0], closeParen.range[1],
+          ],
+          sourceCode.getText(/** @type {any} */ (node)),
+        );
+      } :
+      null,
+    types[0],
+    {
+      type: assertedTypeStr,
+    },
+  );
 }, {
   iterateAllJsdocs: true,
   meta: {
     docs: {
       description: 'Reports redundant @type tags that match or broaden the naturally inferred TypeScript type.',
     },
+    fixable: 'code',
     schema: [
       {
         additionalProperties: false,
@@ -206,6 +499,10 @@ export default iterateJsdoc(({
             description: 'Whether to check `const` type assertions as redundant',
             type: 'boolean',
           },
+          enableFixer: {
+            description: 'Whether to enable the fixer that removes the redundant `@type` tag (and the JSDoc block if it becomes empty). Defaults to `true`.',
+            type: 'boolean',
+          },
           treatAnyAsRedundant: {
             description: 'Whether to treat `any` type casts as redundant',
             type: 'boolean',

package/src/rules/preferImportTag.js

@@ -152,6 +152,7 @@ export default iterateJsdoc(({
         return;
       }
 
+      /** @type {import('jsdoc-type-pratt-parser').NonRootResult} */
       let currentNode = nde;
 
       /** @type {string[]} */

package/src/rules.d.ts

@@ -1320,6 +1320,10 @@ export interface Rules {
            * Whether to check `const` type assertions as redundant
            */
           checkLiteralConstAssertions?: boolean;
+          /**
+           * Whether to enable the fixer that removes the redundant `@type` tag (and the JSDoc block if it becomes empty). Defaults to `true`.
+           */
+          enableFixer?: boolean;
           /**
            * Whether to treat `any` type casts as redundant
            */