@depup/eslint-plugin-jsdoc 64.2.1-depup.1 → 64.3.2-depup.0

package/README.md

@@ -13,8 +13,8 @@ npm install @depup/eslint-plugin-jsdoc
 
 | Field | Value |
 |-------|-------|
-| Original | [eslint-plugin-jsdoc](https://www.npmjs.com/package/eslint-plugin-jsdoc) @ 64.2.1 |
-| Processed | 2026-08-24 |
+| Original | [eslint-plugin-jsdoc](https://www.npmjs.com/package/eslint-plugin-jsdoc) @ 64.3.2 |
+| Processed | 2026-08-31 |
 | Smoke test | passed |
 | Deps updated | 1 |
 

package/changes.json

@@ -5,6 +5,6 @@
       "to": "^0.96.0"
     }
   },
-  "timestamp": "2026-08-24T08:17:04.824Z",
+  "timestamp": "2026-08-31T00:36:03.183Z",
   "totalUpdated": 1
 }

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/noUnnecessaryTypeAssertion.d.ts

@@ -0,0 +1,3 @@
+declare const _default: import("eslint").Rule.RuleModule;
+export default _default;
+//# sourceMappingURL=noUnnecessaryTypeAssertion.d.ts.map

package/dist/rules.d.ts

@@ -144,8 +144,8 @@ export interface Rules {
            */
           allowExtraTrailingParamDocs?: boolean;
           /**
-           * Whether to offer a suggestion to rename a mismatched `@param` to the
-           * corresponding function parameter name. Defaults to `false`.
+           * Whether to auto-fix a mismatched `@param` name to the corresponding
+           * function parameter name. A suggestion is always offered. Defaults to `false`.
            */
           badParamNames?: boolean;
           /**
@@ -229,8 +229,8 @@ export interface Rules {
            */
           enableFixer?: boolean;
           /**
-           * Whether to offer a suggestion to remove an `@param` that has no
-           * corresponding function parameter. Defaults to `false`.
+           * Whether to auto-remove an `@param` that has no corresponding function
+           * parameter. A suggestion is always offered. Defaults to `false`.
            */
           extraParams?: boolean;
           /**
@@ -1311,6 +1311,30 @@ export interface Rules {
         }
       ];
 
+  /** Reports redundant @type tags that match or broaden the naturally inferred TypeScript type. */
+  "jsdoc/no-unnecessary-type-assertion": 
+    | []
+    | [
+        {
+          /**
+           * 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
+           */
+          treatAnyAsRedundant?: boolean;
+          /**
+           * An array list of types to ignore
+           */
+          typesToIgnore?: string[];
+        }
+      ];
+
   /** Normalizes labeled links in `@see` tags to a canonical `{@link}` form. */
   "jsdoc/normalize-see-links": 
     | []

package/package.json

@@ -7,6 +7,7 @@
   "dependencies": {
     "@es-joy/jsdoccomment": "^0.96.0",
     "@es-joy/resolve.exports": "1.2.0",
+    "@typescript-eslint/utils": "^8.68.0",
     "are-docs-informative": "^0.1.1",
     "comment-parser": "1.4.8",
     "debug": "^4.4.3",
@@ -68,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": {
@@ -144,6 +145,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 .",
@@ -160,7 +162,7 @@
     "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.2.1-depup.1",
+  "version": "64.3.2-depup.0",
   "depup": {
     "changes": {
       "@es-joy/jsdoccomment": {
@@ -170,8 +172,8 @@
     },
     "depsUpdated": 1,
     "originalPackage": "eslint-plugin-jsdoc",
-    "originalVersion": "64.2.1",
-    "processedAt": "2026-08-24T08:17:27.573Z",
+    "originalVersion": "64.3.2",
+    "processedAt": "2026-08-31T00:36:26.963Z",
     "smokeTest": "passed"
   }
 }

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

@@ -39,6 +39,7 @@ import noRestrictedSyntax from './rules/noRestrictedSyntax.js';
 import normalizeSeeLinks from './rules/normalizeSeeLinks.js';
 import noTypes from './rules/noTypes.js';
 import noUndefinedTypes from './rules/noUndefinedTypes.js';
+import noUnnecessaryTypeAssertion from './rules/noUnnecessaryTypeAssertion.js';
 import preferImportTag from './rules/preferImportTag.js';
 import requireAsteriskPrefix from './rules/requireAsteriskPrefix.js';
 import requireDescription from './rules/requireDescription.js';
@@ -88,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
@@ -98,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,
@@ -134,6 +135,7 @@ index.rules = {
   'no-restricted-syntax': noRestrictedSyntax,
   'no-types': noTypes,
   'no-undefined-types': noUndefinedTypes,
+  'no-unnecessary-type-assertion': noUnnecessaryTypeAssertion,
   'normalize-see-links': normalizeSeeLinks,
   'prefer-import-tag': preferImportTag,
   'reject-any-type': buildRejectOrPreferRuleDefinition({
@@ -325,6 +327,7 @@ const createRecommendedRuleset = (warnOrError, flatName) => {
       'jsdoc/no-restricted-syntax': 'off',
       'jsdoc/no-types': 'off',
       'jsdoc/no-undefined-types': warnOrError,
+      'jsdoc/no-unnecessary-type-assertion': 'off',
       'jsdoc/normalize-see-links': 'off',
       'jsdoc/prefer-import-tag': 'off',
       'jsdoc/reject-any-type': warnOrError,

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

@@ -0,0 +1,523 @@
+/* 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;
+
+// 1. Create a require function bound to the current file's URL
+const require = createRequire(import.meta.url);
+
+try {
+  // 2. Attempt to import the package synchronously
+  ts = require('typescript');
+/* c8 ignore next 10 -- Guard */
+} catch (error) {
+  // 3. Fall back gracefully if it is not installed
+  if (/** @type {{code?: string}} */ (error).code !== 'MODULE_NOT_FOUND') {
+    // Re-throw if it's a different error (e.g., syntax error inside the package)
+    throw error;
+  }
+
+  // eslint-disable-next-line no-console -- Warning user
+  console.warn('⚠️ typescript is not installed. `jsdoc/no-unnecessary-type-assertion` will not work. To disable this warning, you must disable the rule.');
+}
+
+// Helper to check for standard literals and boolean/enum/template literals
+/**
+ * @param {any} type The type is `ts.Type`
+ * @returns {boolean}
+ */
+const isLiteralType = (type) => {
+  // Standard primitive literals (string, number, bigint, boolean literal flags)
+  if (type.isLiteral()) {
+    return true;
+  }
+
+  // Check using TypeFlags for specific edge cases like boolean or template literals
+
+  if (type.flags & (ts.TypeFlags.BooleanLiteral | ts.TypeFlags.TemplateLiteral)) {
+    return true;
+  }
+
+  // If dealing with a union (e.g. 'a' | 'b'), you can check if all constituents are literals
+  if (type.isUnion()) {
+    return type.types.every(
+      /**
+       * @param {any} typ
+       */
+      (typ) => {
+        return isLiteralType(typ);
+      },
+    );
+  }
+
+  return false;
+};
+
+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
+  if (!ts) {
+    return;
+  }
+
+  const types = utils.getTags('type');
+
+  // 1. Only proceed if there is a @type tag
+  if (!types.length) {
+    return;
+  }
+
+  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}
+     */ (nde);
+
+  // 2. Safely get TypeScript parser services and TypeChecker
+  const services =
+    /**
+     * @type {import('@typescript-eslint/utils').ParserServices}
+     */ (context.sourceCode.parserServices);
+
+  /* c8 ignore next 10 -- Guard */
+  if (!services || !services.program) {
+    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;
+  }
+
+  // 1. Grab the parser services and the active TypeChecker
+  // 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.';
+
+  /**
+   * 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 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;
+    }
+
+    const signature = /** @type {any} */ (
+      checker.getResolvedSignature(tsExpression)
+    );
+    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;
+    }
+
+    // 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);
+  };
+
+  // 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. `/** @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? */
+    if (!decl.init) {
+      // No initializer, type is likely `any`, so @type isn't redundant
+      return;
+    }
+
+    // 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),
+    );
+
+    /* c8 ignore next 3 -- Every `@type` tag reaching here has a bound TypeNode */
+    if (!jsdocTypeNode) {
+      return;
+    }
+
+    const declInitTsNode = services.esTreeNodeToTSNodeMap.get(decl.init);
+    if (isGenericCall(declInitTsNode) || isInterpolatedTemplateLiteral(decl.init)) {
+      return;
+    }
+
+    const declInferredType = checker.getTypeAtLocation(declInitTsNode);
+    const declAssertedType = checker.getTypeFromTypeNode(jsdocTypeNode);
+
+    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;
+    }
+  }
+
+  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,
+        properties: {
+          checkLiteralConstAssertions: {
+            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',
+          },
+          typesToIgnore: {
+            description: 'An array list of types to ignore',
+            items: {
+              type: 'string',
+            },
+            type: 'array',
+          },
+        },
+        type: 'object',
+      },
+    ],
+    type: 'suggestion',
+  },
+});

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

@@ -144,8 +144,8 @@ export interface Rules {
            */
           allowExtraTrailingParamDocs?: boolean;
           /**
-           * Whether to offer a suggestion to rename a mismatched `@param` to the
-           * corresponding function parameter name. Defaults to `false`.
+           * Whether to auto-fix a mismatched `@param` name to the corresponding
+           * function parameter name. A suggestion is always offered. Defaults to `false`.
            */
           badParamNames?: boolean;
           /**
@@ -229,8 +229,8 @@ export interface Rules {
            */
           enableFixer?: boolean;
           /**
-           * Whether to offer a suggestion to remove an `@param` that has no
-           * corresponding function parameter. Defaults to `false`.
+           * Whether to auto-remove an `@param` that has no corresponding function
+           * parameter. A suggestion is always offered. Defaults to `false`.
            */
           extraParams?: boolean;
           /**
@@ -1311,6 +1311,30 @@ export interface Rules {
         }
       ];
 
+  /** Reports redundant @type tags that match or broaden the naturally inferred TypeScript type. */
+  "jsdoc/no-unnecessary-type-assertion": 
+    | []
+    | [
+        {
+          /**
+           * 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
+           */
+          treatAnyAsRedundant?: boolean;
+          /**
+           * An array list of types to ignore
+           */
+          typesToIgnore?: string[];
+        }
+      ];
+
   /** Normalizes labeled links in `@see` tags to a canonical `{@link}` form. */
   "jsdoc/normalize-see-links": 
     | []