@depup/eslint-plugin-jsdoc 64.3.4-depup.0 → 64.3.6-depup.0

package/README.md

@@ -13,17 +13,10 @@ npm install @depup/eslint-plugin-jsdoc
 
 | Field | Value |
 |-------|-------|
-| Original | [eslint-plugin-jsdoc](https://www.npmjs.com/package/eslint-plugin-jsdoc) @ 64.3.4 |
-| Processed | 2026-09-02 |
+| Original | [eslint-plugin-jsdoc](https://www.npmjs.com/package/eslint-plugin-jsdoc) @ 64.3.6 |
+| Processed | 2026-09-06 |
 | Smoke test | passed |
-| Deps updated | 2 |
-
-## Dependency Changes
-
-| Dependency | From | To |
-|------------|------|-----|
-| @es-joy/jsdoccomment | ~0.95.1 | ^0.96.0 |
-| @typescript-eslint/utils | ^8.68.0 | ^8.69.0 |
+| Deps updated | 0 |
 
 ---
 

package/changes.json

@@ -1,14 +1,5 @@
 {
-  "bumped": {
-    "@es-joy/jsdoccomment": {
-      "from": "~0.95.1",
-      "to": "^0.96.0"
-    },
-    "@typescript-eslint/utils": {
-      "from": "^8.68.0",
-      "to": "^8.69.0"
-    }
-  },
-  "timestamp": "2026-09-02T00:33:20.653Z",
-  "totalUpdated": 2
+  "bumped": {},
+  "timestamp": "2026-09-06T00:59:03.732Z",
+  "totalUpdated": 0
 }

package/dist/rules.d.ts

@@ -1324,6 +1324,10 @@ export interface Rules {
            * 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 report a non-`const` literal-tuple assertion on an array literal (e.g. `/** @type {['foo']} * / (['foo'])`) and fix it to the equivalent, more concise `/** @type {const} * /` assertion. Defaults to `false`.
+           */
+          preferConstToLiteralTuples?: boolean;
           /**
            * Whether to treat `any` type casts as redundant
            */

package/package.json

@@ -5,7 +5,7 @@
     "url": "http://gajus.com"
   },
   "dependencies": {
-    "@es-joy/jsdoccomment": "^0.96.0",
+    "@es-joy/jsdoccomment": "~0.97.0",
     "@es-joy/resolve.exports": "1.2.0",
     "@typescript-eslint/utils": "^8.69.0",
     "are-docs-informative": "^0.1.1",
@@ -41,36 +41,36 @@
     "@types/estree": "^1.0.9",
     "@types/json-schema": "^7.0.15",
     "@types/mocha": "^10.0.10",
-    "@types/node": "^26.2.0",
+    "@types/node": "^26.4.1",
     "@types/semver": "^7.8.0",
     "@types/spdx-expression-parse": "^4.0.0",
-    "@typescript-eslint/types": "8.67.0",
+    "@typescript-eslint/types": "8.69.0",
     "babel-plugin-add-module-exports": "^1.0.4",
     "babel-plugin-transform-import-meta": "^3.0.0",
     "c8": "^12.0.0",
     "camelcase": "^9.0.0",
     "chai": "^6.2.2",
     "decamelize": "^6.0.1",
-    "eslint": "10.8.1",
+    "eslint": "10.10.0",
     "eslint-config-canonical": "^47.4.2",
     "gitdown": "^4.1.1",
     "glob": "^13.0.6",
-    "globals": "^17.11.0",
+    "globals": "^17.12.0",
     "husky": "^9.1.7",
-    "jsdoc-type-pratt-parser": "^9.1.2",
+    "jsdoc-type-pratt-parser": "^9.2.1",
     "json-schema": "^0.4.0",
-    "json-schema-to-typescript": "^15.0.4",
-    "lint-staged": "^17.3.0",
-    "mocha": "^11.8.0",
+    "json-schema-to-typescript": "^16.0.0",
+    "lint-staged": "^17.5.0",
+    "mocha": "^12.0.0",
     "open-editor": "^6.0.0",
-    "playwright": "^1.62.1",
+    "playwright": "^1.63.0",
     "replace": "^1.2.2",
     "rimraf": "^6.1.3",
     "semantic-release": "^25.0.9",
     "sinon": "^22.1.0",
     "ts-api-utils": "^2.5.0",
     "typescript": "6.0.3",
-    "typescript-eslint": "8.67.0"
+    "typescript-eslint": "8.69.0"
   },
   "engines": {
     "node": "^22.22.2 || >=24.15.0"
@@ -162,22 +162,13 @@
     "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.4-depup.0",
+  "version": "64.3.6-depup.0",
   "depup": {
-    "changes": {
-      "@es-joy/jsdoccomment": {
-        "from": "~0.95.1",
-        "to": "^0.96.0"
-      },
-      "@typescript-eslint/utils": {
-        "from": "^8.68.0",
-        "to": "^8.69.0"
-      }
-    },
-    "depsUpdated": 2,
+    "changes": {},
+    "depsUpdated": 0,
     "originalPackage": "eslint-plugin-jsdoc",
-    "originalVersion": "64.3.4",
-    "processedAt": "2026-09-02T00:33:49.226Z",
+    "originalVersion": "64.3.6",
+    "processedAt": "2026-09-06T00:59:25.028Z",
     "smokeTest": "passed"
   }
 }

package/src/rules/noUnnecessaryTypeAssertion.js

@@ -87,6 +87,7 @@ export default iterateJsdoc(({
     // https://typescript-eslint.io/rules/no-unnecessary-type-assertion/
     checkLiteralConstAssertions = false,
     enableFixer = true,
+    preferConstToLiteralTuples = false,
     treatAnyAsRedundant = false,
     typesToIgnore = [],
   } = context.options[0] ?? {};
@@ -154,6 +155,24 @@ export default iterateJsdoc(({
     '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.';
 
+  const preferConstMessage =
+    'The @type tag declaring "{{ type }}" is better written as the "const" assertion `/** @type {const} */` (TypeScript 4.5+).';
+
+  /**
+   * Rewrites the reported `@type` tag's type to `const`.
+   * @returns {void}
+   */
+  const convertToConst = () => {
+    for (const {
+      tokens,
+    } of /** @type {import('comment-parser').Spec} */ (types[0]).source) {
+      if (tokens.type) {
+        tokens.type = '{const}';
+        break;
+      }
+    }
+  };
+
   /**
    * Whether `inferredType` is a generic reference carrying `any` type arguments
    * that `assertedType` replaces with concrete ones (e.g. an untyped
@@ -327,6 +346,97 @@ export default iterateJsdoc(({
       checker.isTypeAssignableTo(assertedBaseType, inferredBaseType);
   };
 
+  /**
+   * A non-`const` tuple type annotation on an array literal (asserting `['foo']`
+   * onto `['foo']`) turns the literal's inferred `T[]` into a tuple; since the
+   * literal only takes that tuple type *from* the assertion, the assertion is
+   * never genuinely redundant even though the contextually-typed expression
+   * echoes the asserted tuple straight back. It is the pre-TypeScript-4.5
+   * stand-in for a `const` assertion.
+   * @param {any} assertedType `ts.Type`
+   * @param {import('@typescript-eslint/utils').TSESTree.Node | null | undefined} operand
+   * @returns {boolean}
+   */
+  const isTupleConversionIdiom = (assertedType, operand) => {
+    return assertedTypeStr !== 'const' &&
+      operand?.type === 'ArrayExpression' &&
+      checker.isTupleType(assertedType);
+  };
+
+  /**
+   * An array-literal annotation whose element type is a literal (or union of
+   * literals) — `type {ViewType[]}` on `['single-panel', 'user']` —
+   * narrows the element type that the bare literal would widen (`string[]` ->
+   * `ViewType[]`). Like the tuple idiom, the literal takes that element type
+   * only *from* the annotation, so the contextually-typed initializer echoes
+   * the asserted array straight back and the genuine narrowing looks redundant.
+   * @param {any} assertedType `ts.Type`
+   * @param {import('@typescript-eslint/utils').TSESTree.Node | null | undefined} operand
+   * @returns {boolean}
+   */
+  const narrowsArrayLiteralElement = (assertedType, operand) => {
+    if (operand?.type !== 'ArrayExpression' || !checker.isArrayType(assertedType)) {
+      return false;
+    }
+
+    const [
+      elementType,
+    ] = checker.getTypeArguments(assertedType);
+    return isLiteralType(elementType);
+  };
+
+  /**
+   * Whether `operand` is an object literal carrying a method or function-valued
+   * property. Under a surrounding `@type` object annotation such a function is
+   * contextually typed by the annotation — its otherwise-implicit-`any`
+   * parameters (and hence its signature) come straight from it — so
+   * `getTypeAtLocation` echoes the asserted object shape back and a genuine
+   * typing looks redundant. As elsewhere in this rule the uncontaminated type
+   * cannot be recovered here, so such literals are left alone (at the cost of
+   * missing the rare object annotation that only restates a fully
+   * self-evident method signature).
+   * @param {import('@typescript-eslint/utils').TSESTree.Node | null | undefined} operand
+   * @returns {boolean}
+   */
+  const hasContextuallyTypedFunctionMember = (operand) => {
+    return operand?.type === 'ObjectExpression' &&
+      operand.properties.some((property) => {
+        return property.type === 'Property' && (
+          property.value.type === 'FunctionExpression' ||
+          property.value.type === 'ArrowFunctionExpression'
+        );
+      });
+  };
+
+  /**
+   * Whether every element of `tupleType` is a literal type, so a `const`
+   * assertion would reproduce the same element types (`['foo', 1]` but not
+   * `[string]`).
+   * @param {any} tupleType `ts.Type`
+   * @returns {boolean}
+   */
+  const tupleElementsAllLiteral = (tupleType) => {
+    const elements = checker.getTypeArguments(tupleType);
+    return elements.length > 0 && elements.every(isLiteralType);
+  };
+
+  /**
+   * Reports an array-literal tuple assertion, offering (under `enableFixer`) a
+   * rewrite to the equivalent, more concise `const` assertion.
+   * @returns {void}
+   */
+  const reportPreferConst = () => {
+    utils.reportJSDoc(
+      preferConstMessage,
+      types[0],
+      enableFixer ? convertToConst : null,
+      false,
+      {
+        type: assertedTypeStr,
+      },
+    );
+  };
+
   // 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.
@@ -372,6 +482,21 @@ export default iterateJsdoc(({
     const declInferredType = checker.getTypeAtLocation(declInitTsNode);
     const declAssertedType = checker.getTypeFromTypeNode(jsdocTypeNode);
 
+    if (isTupleConversionIdiom(declAssertedType, decl.init)) {
+      if (preferConstToLiteralTuples && tupleElementsAllLiteral(declAssertedType)) {
+        reportPreferConst();
+      }
+
+      return;
+    }
+
+    if (
+      narrowsArrayLiteralElement(declAssertedType, decl.init) ||
+      hasContextuallyTypedFunctionMember(decl.init)
+    ) {
+      return;
+    }
+
     if (isRedundantAssertion(declInferredType, declAssertedType)) {
       utils.reportJSDoc(message, types[0], fixer, true, {
         type: assertedTypeStr,
@@ -441,6 +566,21 @@ export default iterateJsdoc(({
     checker.getTypeAtLocation(exprTsNode);
   const castAssertedType = checker.getTypeFromTypeNode(typeTag.typeExpression.type);
 
+  if (isTupleConversionIdiom(castAssertedType, node)) {
+    if (preferConstToLiteralTuples && tupleElementsAllLiteral(castAssertedType)) {
+      reportPreferConst();
+    }
+
+    return;
+  }
+
+  if (
+    narrowsArrayLiteralElement(castAssertedType, node) ||
+    hasContextuallyTypedFunctionMember(node)
+  ) {
+    return;
+  }
+
   if (!isRedundantAssertion(castInferredType, castAssertedType)) {
     return;
   }
@@ -503,6 +643,10 @@ export default iterateJsdoc(({
             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',
           },
+          preferConstToLiteralTuples: {
+            description: 'Whether to report a non-`const` literal-tuple assertion on an array literal (e.g. `/** @type {[\'foo\']} */ ([\'foo\'])`) and fix it to the equivalent, more concise `/** @type {const} */` assertion. Defaults to `false`.',
+            type: 'boolean',
+          },
           treatAnyAsRedundant: {
             description: 'Whether to treat `any` type casts as redundant',
             type: 'boolean',

package/src/rules/requireJsdoc.js

@@ -34,7 +34,6 @@ import {
 /** @type {import('json-schema').JSONSchema4} */
 const OPTIONS_SCHEMA = {
   additionalProperties: false,
-  description: 'Has the following optional keys.\n',
   properties: {
     checkAllFunctionExpressions: {
       default: false,

package/src/rules.d.ts

@@ -1324,6 +1324,10 @@ export interface Rules {
            * 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 report a non-`const` literal-tuple assertion on an array literal (e.g. `/** @type {['foo']} * / (['foo'])`) and fix it to the equivalent, more concise `/** @type {const} * /` assertion. Defaults to `false`.
+           */
+          preferConstToLiteralTuples?: boolean;
           /**
            * Whether to treat `any` type casts as redundant
            */