eslint-plugin-jsdoc 64.2.1 → 64.3.0

package/README.md

@@ -512,6 +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:| [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/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,26 @@ 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 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.95.1",
     "@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",
@@ -155,5 +156,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.2.1"
+  "version": "64.3.0"
 }

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';
@@ -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/rules/noUnnecessaryTypeAssertion.js

@@ -0,0 +1,226 @@
+/* eslint-disable jsdoc/reject-any-type -- TypeScript types need not be installed */
+import iterateJsdoc from '../iterateJsdoc.js';
+import {
+  createRequire,
+} from 'module';
+
+/** @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
+  // eslint-disable-next-line no-bitwise -- Convenient
+  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,
+  node: nde,
+  report,
+  utils,
+}) => {
+  /* 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,
+    treatAnyAsRedundant = false,
+    typesToIgnore = [],
+  } = context.options[0] ?? {};
+
+  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 6 -- 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`.');
+    return;
+  }
+
+  // 1. Grab the parser services and the active TypeChecker
+  // const services = ESLintUtils.getParserServices(context);
+  const checker = services.program.getTypeChecker();
+
+  /**
+   * @param {string} typeStr
+   * @returns {any} `ts.Type`
+   */
+  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,
+    );
+
+    // 3. Find the TypeNode in the AST (type __TargetType = <TypeNode>;)
+    // Type `ts.TypeAliasDeclaration`
+    const typeAlias = /** @type {any} */ (
+      virtualSourceFile.statements[0]
+    );
+    const typeNode = typeAlias.type;
+
+    // 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);
+  };
+
+  // Todo: Support more than just VariableDeclaration!
+
+  // 3. For this example, let's assume we are checking VariableDeclarators
+  // e.g., `/** @type {number} */ const x = 5;`
+  if (node?.type === 'VariableDeclaration') {
+    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;
+    }
+
+    // 4. Map the ESLint AST nodes to TypeScript AST nodes
+    // const tsNode = services.esTreeNodeToTSNodeMap.get(decl.id);
+    const tsInit = services.esTreeNodeToTSNodeMap.get(decl.init);
+
+    // 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);
+
+    // 6. Compare the types.
+    const declaredTypeStr = types[0].type;
+    const declaredType = getTypeFromString(declaredTypeStr);
+
+    const isRedundantType = checker.isTypeAssignableTo(
+      inferredType,
+      declaredType,
+    );
+
+    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,
+          },
+        );
+      }
+
+      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,
+        },
+      );
+    }
+  }
+}, {
+  iterateAllJsdocs: true,
+  meta: {
+    docs: {
+      description: 'Reports redundant @type tags that match or broaden the naturally inferred TypeScript type.',
+    },
+    schema: [
+      {
+        additionalProperties: false,
+        properties: {
+          checkLiteralConstAssertions: {
+            description: 'Whether to check `const` type assertions as redundant',
+            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.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,26 @@ 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 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": 
     | []