eslint-plugin-jsdoc 62.6.1 → 62.7.1

package/package.json

@@ -16,7 +16,7 @@
     "html-entities": "^2.6.0",
     "object-deep-merge": "^2.0.0",
     "parse-imports-exports": "^0.2.4",
-    "semver": "^7.7.3",
+    "semver": "^7.7.4",
     "spdx-expression-parse": "^4.0.0",
     "to-valid-identifier": "^1.0.0"
   },
@@ -24,19 +24,18 @@
   "devDependencies": {
     "@arethetypeswrong/cli": "^0.18.2",
     "@babel/cli": "^7.28.6",
-    "@babel/core": "^7.29.0",
-    "@babel/eslint-parser": "^7.28.6",
-    "@babel/plugin-syntax-class-properties": "^7.12.13",
-    "@babel/plugin-transform-flow-strip-types": "^7.27.1",
-    "@babel/preset-env": "^7.29.0",
+    "@babel/core": "8.0.0-rc.1",
+    "@babel/eslint-parser": "8.0.0-rc.1",
+    "@babel/plugin-transform-flow-strip-types": "8.0.0-rc.1",
+    "@babel/preset-env": "8.0.0-rc.1",
     "@es-joy/escodegen": "^4.2.0",
     "@es-joy/jsdoc-eslint-parser": "^0.27.0",
     "@eslint/core": "^1.1.0",
     "@hkdobrev/run-if-changed": "^0.6.3",
     "@rollup/plugin-node-resolve": "^16.0.3",
     "@semantic-release/commit-analyzer": "^13.0.1",
-    "@semantic-release/github": "^12.0.3",
-    "@semantic-release/npm": "^13.1.3",
+    "@semantic-release/github": "^12.0.6",
+    "@semantic-release/npm": "^13.1.4",
     "@types/chai": "^5.2.3",
     "@types/debug": "^4.1.12",
     "@types/espree": "^10.1.0",
@@ -44,10 +43,10 @@
     "@types/estree": "^1.0.8",
     "@types/json-schema": "^7.0.15",
     "@types/mocha": "^10.0.10",
-    "@types/node": "^25.2.0",
+    "@types/node": "^25.3.0",
     "@types/semver": "^7.7.1",
     "@types/spdx-expression-parse": "^3.0.5",
-    "@typescript-eslint/types": "^8.54.0",
+    "@typescript-eslint/types": "8.56.0",
     "babel-plugin-add-module-exports": "^1.0.4",
     "babel-plugin-istanbul": "^7.0.1",
     "babel-plugin-transform-import-meta": "^2.3.3",
@@ -55,10 +54,10 @@
     "camelcase": "^9.0.0",
     "chai": "^6.2.2",
     "decamelize": "^6.0.1",
-    "eslint": "9.39.2",
+    "eslint": "10.0.0",
     "eslint-config-canonical": "^47.4.2",
     "gitdown": "^4.1.1",
-    "glob": "^13.0.1",
+    "glob": "^13.0.5",
     "globals": "^17.3.0",
     "husky": "^9.1.7",
     "jsdoc-type-pratt-parser": "^7.1.1",
@@ -67,15 +66,15 @@
     "lint-staged": "^16.2.7",
     "mocha": "^11.7.5",
     "open-editor": "^6.0.0",
-    "playwright": "^1.58.1",
+    "playwright": "^1.58.2",
     "replace": "^1.2.2",
-    "rimraf": "^6.1.2",
+    "rimraf": "^6.1.3",
     "rollup": "^4.57.1",
     "semantic-release": "^25.0.3",
     "sinon": "^21.0.1",
     "ts-api-utils": "^2.4.0",
     "typescript": "5.9.3",
-    "typescript-eslint": "^8.54.0"
+    "typescript-eslint": "8.56.0"
   },
   "engines": {
     "node": "^20.19.0 || ^22.13.0 || >=24"
@@ -147,7 +146,7 @@
     "statements": 100
   },
   "peerDependencies": {
-    "eslint": "^7.0.0 || ^8.0.0 || ^9.0.0"
+    "eslint": "^7.0.0 || ^8.0.0 || ^9.0.0 || ^10.0.0"
   },
   "repository": {
     "type": "git",
@@ -162,7 +161,8 @@
   },
   "pnpm": {
     "overrides": {
-      "@types/eslint": "0.0.0-interferes-with-eslint-now"
+      "@types/eslint": "0.0.0-interferes-with-eslint-now",
+      "eslint-scope": "9.1.0"
     },
     "ignoredBuiltDependencies": [
       "core-js",
@@ -177,7 +177,7 @@
     "tsc-build": "tsc -p tsconfig-prod.json",
     "tsc-cjs": "tsc -p tsconfig-cjs.json",
     "rollup": "rollup -c",
-    "build": "node ./src/bin/buildEntryFileForTS.js && rimraf ./dist && pnpm rollup && NODE_ENV=production babel ./src --out-file-extension .cjs --out-dir ./dist --copy-files --source-maps --ignore ./src/bin/*.js --no-copy-ignored && replace 'to-valid-identifier' '../to-valid-identifier.cjs' 'dist' -r --include=\"*.cjs\" && replace 'require\\(\"\\.(.*?)\\.[^.]*?\"\\)' 'require(\".$1.cjs\")' 'dist' -r --include=\"*.cjs\" && pnpm tsc-build && pnpm tsc-cjs",
+    "build": "node ./src/bin/buildEntryFileForTS.js && rimraf ./dist && mkdir dist && pnpm rollup && NODE_ENV=production babel ./src --out-file-extension .cjs --out-dir ./dist --copy-files --source-maps --ignore ./src/bin/*.js --no-copy-ignored && replace 'to-valid-identifier' '../to-valid-identifier.cjs' 'dist' -r --include=\"*.cjs\" && replace 'require\\(\"\\.(.*?)\\.[^.]*?\"\\)' 'require(\".$1.cjs\")' 'dist' -r --include=\"*.cjs\" && pnpm tsc-build && pnpm tsc-cjs",
     "attw": "attw --pack .",
     "check-docs": "node ./src/bin/generateDocs.js --check",
     "create-docs": "pnpm run create-options && node ./src/bin/generateDocs.js && pnpm ruleTypes",
@@ -192,5 +192,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": "62.6.1"
+  "version": "62.7.1"
 }

package/src/iterateJsdoc.js

@@ -739,6 +739,7 @@ const getUtils = (
 
   /* c8 ignore next -- Fallback to deprecated method */
   const {
+    // @ts-expect-error ESLint < 10
     sourceCode = context.getSourceCode(),
   } = context;
 
@@ -2188,6 +2189,7 @@ const iterateAllJsdocs = (iterator, ruleConfig, contexts, additiveCommentContext
   const callIterator = (context, node, jsdocNodes, state, lastCall) => {
     /* c8 ignore next -- Fallback to deprecated method */
     const {
+      // @ts-expect-error ESLint < 10
       sourceCode = context.getSourceCode(),
     } = context;
     const {
@@ -2301,6 +2303,7 @@ const iterateAllJsdocs = (iterator, ruleConfig, contexts, additiveCommentContext
     create (context) {
       /* c8 ignore next -- Fallback to deprecated method */
       const {
+        // @ts-expect-error ESLint < 10
         sourceCode = context.getSourceCode(),
       } = context;
       settings = getSettings(context);
@@ -2349,7 +2352,9 @@ const iterateAllJsdocs = (iterator, ruleConfig, contexts, additiveCommentContext
           ], /** @type {StateObject} */ (state));
         },
         'Program:exit' () {
-          const allComments = sourceCode.getAllComments();
+          const allComments = /** @type {import('estree').Comment[]} */ (
+            sourceCode.getAllComments()
+          );
           const untrackedJSdoc = allComments.filter((node) => {
             return !trackedJsdocs.has(node);
           });
@@ -2381,6 +2386,7 @@ const checkFile = (iterator, ruleConfig) => {
     create (context) {
       /* c8 ignore next -- Fallback to deprecated method */
       const {
+        // @ts-expect-error ESLint < 10
         sourceCode = context.getSourceCode(),
       } = context;
       const settings = getSettings(context);
@@ -2504,6 +2510,7 @@ export default function iterateJsdoc (iterator, ruleConfig) {
 
       /* c8 ignore next -- Fallback to deprecated method */
       const {
+        // @ts-expect-error ESLint < 10
         sourceCode = context.getSourceCode(),
       } = context;
       const {

package/src/rules/checkExamples.js

@@ -366,6 +366,7 @@ export default iterateJsdoc(({
   const getFilenameInfo = (filename, ext = 'md/*.js') => {
     let defaultFileName;
     if (!filename) {
+      // @ts-expect-error ESLint < 10
       const jsFileName = context.getFilename();
       if (typeof jsFileName === 'string' && jsFileName.includes('.')) {
         defaultFileName = jsFileName.replace(/\.[^.]*$/v, `.${ext}`);

package/src/rules/checkTagNames.js

@@ -130,7 +130,8 @@ export default iterateJsdoc(({
    */
   const isInAmbientContext = (subNode) => {
     return subNode.type === 'Program' ?
-      /* c8 ignore next -- Support old ESLint */
+      /* c8 ignore next 2 -- Support old ESLint */
+      // @ts-expect-error ESLint < 10
       (context.filename ?? context.getFilename()).endsWith('.d.ts') :
       Boolean(
         /** @type {import('@typescript-eslint/types').TSESTree.VariableDeclaration} */ (
@@ -156,7 +157,8 @@ export default iterateJsdoc(({
       return false;
     }
 
-    /* c8 ignore next -- Support old ESLint */
+    /* c8 ignore next 2 -- Support old ESLint */
+    // @ts-expect-error ESLint < 10
     if ((context.filename ?? context.getFilename()).endsWith('.d.ts') && [
       null, 'Program', undefined,
     ].includes(node?.parent?.type)) {

package/src/rules/convertToJsdocComments.js

@@ -35,6 +35,7 @@ export default {
 
     /* c8 ignore next -- Fallback to deprecated method */
     const {
+      // @ts-expect-error ESLint < 10
       sourceCode = context.getSourceCode(),
     } = context;
     const settings = getSettings(context);

package/src/rules/preferImportTag.js

@@ -10,9 +10,13 @@ import {
   traverse,
   tryParse as tryParseType,
 } from '@es-joy/jsdoccomment';
+import {
+  Linter,
+} from 'eslint';
 import {
   parseImportsExports,
 } from 'parse-imports-exports';
+import semver from 'semver';
 import toValidIdentifier from 'to-valid-identifier';
 
 export default iterateJsdoc(({
@@ -66,6 +70,60 @@ export default iterateJsdoc(({
       return tag;
     });
 
+  /**
+   * Helper to insert an import statement at the top of the file.
+   * @param {string} importText - The import statement text (without newline)
+   * @returns {((fixer: import('eslint').Rule.RuleFixer) => import('eslint').Rule.Fix|void)} - Fixer function for ESLint
+   */
+  const createImportInserter = (importText) => {
+    return (fixer) => {
+      const programNode = sourceCode.ast;
+      const commentNodes = sourceCode.getCommentsBefore(programNode);
+
+      /* c8 ignore start -- ESLint < 10 */
+      if (commentNodes[0]) {
+        return fixer.insertTextBefore(
+          // @ts-expect-error - Comment is compatible with Node in practice
+          commentNodes[0],
+          `${importText}\n${indent}`,
+        );
+      }
+
+      // For ESLint < 10, use the simple approach of inserting before programNode
+      if (semver.lt(Linter.version, '10.0.0')) {
+        return fixer.insertTextBefore(
+          programNode,
+          importText,
+        );
+      }
+
+      // For ESLint 10+, handle the changed Program node range
+      const sourceText = sourceCode.getText();
+      const hasCode = programNode.body && programNode.body.length > 0;
+      const leadingMatch = hasCode ? sourceText.match(/^(\n[ \t]*)/v) : null;
+      if (leadingMatch) {
+        const leading = leadingMatch[1];
+        return fixer.replaceTextRange(
+          [
+            leading.length, leading.length,
+          ],
+          `${importText}\n${leading.slice(1)}`,
+        );
+      }
+
+      const startsWithNewline = sourceText[0] === '\n';
+      return fixer.replaceTextRange(
+        startsWithNewline ? [
+          0, 1,
+        ] : [
+          0, 0,
+        ],
+        `${importText}\n`,
+      );
+      /* c8 ignore end -- ESLint < 10 */
+    };
+  };
+
   /**
    * @param {import('@es-joy/jsdoccomment').JsdocTagWithInline} tag
    */
@@ -365,16 +423,9 @@ export default iterateJsdoc(({
           tag,
           enableFixer ? (fixer) => {
             getFixer(element.value, [])();
-
-            const programNode = sourceCode.ast;
-            const commentNodes = sourceCode.getCommentsBefore(programNode);
-            return fixer.insertTextBefore(
-              // @ts-expect-error Ok
-              commentNodes[0] ?? programNode,
-              `/** @import * as ${toValidIdentifier(element.value)} from '${element.value}'; */${
-                commentNodes[0] ? '\n' + indent : ''
-              }`,
-            );
+            return createImportInserter(
+              `/** @import * as ${toValidIdentifier(element.value)} from '${element.value}'; */`,
+            )(fixer);
           } : null,
         );
         return;
@@ -387,17 +438,9 @@ export default iterateJsdoc(({
           tag,
           enableFixer ? (fixer) => {
             getFixer(element.value, [])();
-
-            const programNode = sourceCode.ast;
-            const commentNodes = sourceCode.getCommentsBefore(programNode);
-
-            return fixer.insertTextBefore(
-              // @ts-expect-error Ok
-              commentNodes[0] ?? programNode,
-              `/** @import ${element.value} from '${element.value}'; */${
-                commentNodes[0] ? '\n' + indent : ''
-              }`,
-            );
+            return createImportInserter(
+              `/** @import ${element.value} from '${element.value}'; */`,
+            )(fixer);
           } : null,
         );
         return;
@@ -418,22 +461,14 @@ export default iterateJsdoc(({
             )();
           }
 
-          const programNode = sourceCode.ast;
-          const commentNodes = sourceCode.getCommentsBefore(programNode);
-          return fixer.insertTextBefore(
-            // @ts-expect-error Ok
-            commentNodes[0] ?? programNode,
-            outputType === 'namespaced-import' ?
-              `/** @import * as ${toValidIdentifier(element.value)} from '${element.value}'; */${
-                commentNodes[0] ? '\n' + indent : ''
-              }` :
-              `/** @import { ${toValidIdentifier(
-                /* c8 ignore next -- TS */
-                pathSegments.at(-1) ?? '',
-              )} } from '${element.value}'; */${
-                commentNodes[0] ? '\n' + indent : ''
-              }`,
-          );
+          const importText = outputType === 'namespaced-import' ?
+            `/** @import * as ${toValidIdentifier(element.value)} from '${element.value}'; */` :
+            `/** @import { ${toValidIdentifier(
+              /* c8 ignore next -- TS */
+              pathSegments.at(-1) ?? '',
+            )} } from '${element.value}'; */`;
+
+          return createImportInserter(importText)(fixer);
         } : null,
       );
     });

package/src/rules/requireJsdoc.js

@@ -536,6 +536,7 @@ export default {
   create (context) {
     /* c8 ignore next -- Fallback to deprecated method */
     const {
+      // @ts-expect-error ESLint < 10
       sourceCode = context.getSourceCode(),
     } = context;
     const settings = getSettings(context);
@@ -876,7 +877,6 @@ export default {
   },
   meta: {
     docs: {
-      category: 'Stylistic Issues',
       description: 'Checks for presence of JSDoc comments, on functions and potentially other contexts (optionally limited to exports).',
       recommended: true,
       url: 'https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/require-jsdoc.md#repos-sticky-header',

package/src/rules/requireProperty.js

@@ -1,6 +1,7 @@
 import iterateJsdoc from '../iterateJsdoc.js';
 
 export default iterateJsdoc(({
+  context,
   utils,
 }) => {
   const propertyAssociatedTags = utils.filterTags(({
@@ -18,6 +19,23 @@ export default iterateJsdoc(({
     tagName: 'property',
   }));
 
+  if (!targetTagName) {
+    context.report({
+      loc: {
+        end: {
+          column: 1,
+          line: 1,
+        },
+        start: {
+          column: 1,
+          line: 1,
+        },
+      },
+      message: 'Cannot prohibit `@property` in the `tagNamePreference` setting while using the `require-property` rule.',
+    });
+    return;
+  }
+
   if (utils.hasATag([
     targetTagName,
   ])) {

package/src/rules/requireReturns.js

@@ -106,6 +106,7 @@ export default iterateJsdoc(({
       };
       /* c8 ignore next -- Fallback to deprecated method */
       const {
+        // @ts-expect-error ESLint < 10
         sourceCode = context.getSourceCode(),
       } = context;
       const exported = exportParser.isUncommentedExport(