eslint-plugin-jsdoc 48.5.2 → 48.7.0

package/dist/rules/requireTemplate.cjs

@@ -0,0 +1,124 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.default = void 0;
+var _jsdoccomment = require("@es-joy/jsdoccomment");
+var _iterateJsdoc = _interopRequireDefault(require("../iterateJsdoc.cjs"));
+function _interopRequireDefault(e) { return e && e.__esModule ? e : { default: e }; }
+var _default = exports.default = (0, _iterateJsdoc.default)(({
+  context,
+  utils,
+  node,
+  settings,
+  report
+}) => {
+  const {
+    requireSeparateTemplates = false
+  } = context.options[0] || {};
+  const {
+    mode
+  } = settings;
+  const usedNames = new Set();
+  const templateTags = utils.getTags('template');
+  const templateNames = templateTags.flatMap(({
+    name
+  }) => {
+    return name.split(/,\s*/);
+  });
+  for (const tag of templateTags) {
+    const {
+      name
+    } = tag;
+    const names = name.split(/,\s*/);
+    if (requireSeparateTemplates && names.length > 1) {
+      report(`Missing separate @template for ${names[1]}`, null, tag);
+    }
+  }
+
+  /**
+   * @param {import('@typescript-eslint/types').TSESTree.TSTypeAliasDeclaration} aliasDeclaration
+   */
+  const checkParameters = aliasDeclaration => {
+    /* c8 ignore next -- Guard */
+    const {
+      params
+    } = aliasDeclaration.typeParameters ?? {
+      params: []
+    };
+    for (const {
+      name: {
+        name
+      }
+    } of params) {
+      usedNames.add(name);
+    }
+    for (const usedName of usedNames) {
+      if (!templateNames.includes(usedName)) {
+        report(`Missing @template ${usedName}`);
+      }
+    }
+  };
+  const handleTypeAliases = () => {
+    var _nde$declaration;
+    const nde = /** @type {import('@typescript-eslint/types').TSESTree.Node} */
+    node;
+    if (!nde) {
+      return;
+    }
+    switch (nde.type) {
+      case 'ExportNamedDeclaration':
+        if (((_nde$declaration = nde.declaration) === null || _nde$declaration === void 0 ? void 0 : _nde$declaration.type) === 'TSTypeAliasDeclaration') {
+          checkParameters(nde.declaration);
+        }
+        break;
+      case 'TSTypeAliasDeclaration':
+        checkParameters(nde);
+        break;
+    }
+  };
+  const typedefTags = utils.getTags('typedef');
+  if (!typedefTags.length || typedefTags.length >= 2) {
+    handleTypeAliases();
+    return;
+  }
+  const potentialType = typedefTags[0].type;
+  const parsedType = mode === 'permissive' ? (0, _jsdoccomment.tryParse)( /** @type {string} */potentialType) : (0, _jsdoccomment.parse)( /** @type {string} */potentialType, mode);
+  (0, _jsdoccomment.traverse)(parsedType, nde => {
+    const {
+      type,
+      value
+    } = /** @type {import('jsdoc-type-pratt-parser').NameResult} */nde;
+    if (type === 'JsdocTypeName' && /^[A-Z]$/.test(value)) {
+      usedNames.add(value);
+    }
+  });
+
+  // Could check against whitelist/blacklist
+  for (const usedName of usedNames) {
+    if (!templateNames.includes(usedName)) {
+      report(`Missing @template ${usedName}`, null, typedefTags[0]);
+    }
+  }
+}, {
+  iterateAllJsdocs: true,
+  meta: {
+    docs: {
+      description: 'Requires template tags for each generic type parameter',
+      url: 'https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/require-template.md#repos-sticky-header'
+    },
+    schema: [{
+      additionalProperties: false,
+      properties: {
+        requireSeparateTemplates: {
+          type: 'boolean'
+        }
+      },
+      type: 'object'
+    }],
+    type: 'suggestion'
+  }
+});
+module.exports = exports.default;
+//# sourceMappingURL=requireTemplate.cjs.map

package/dist/rules/requireTemplate.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"requireTemplate.cjs","names":["_jsdoccomment","require","_iterateJsdoc","_interopRequireDefault","e","__esModule","default","_default","exports","iterateJsdoc","context","utils","node","settings","report","requireSeparateTemplates","options","mode","usedNames","Set","templateTags","getTags","templateNames","flatMap","name","split","tag","names","length","checkParameters","aliasDeclaration","params","typeParameters","add","usedName","includes","handleTypeAliases","_nde$declaration","nde","type","declaration","typedefTags","potentialType","parsedType","tryParseType","parseType","traverse","value","test","iterateAllJsdocs","meta","docs","description","url","schema","additionalProperties","properties","module"],"sources":["../../src/rules/requireTemplate.js"],"sourcesContent":["import {\n  parse as parseType,\n  traverse,\n  tryParse as tryParseType,\n} from '@es-joy/jsdoccomment';\nimport iterateJsdoc from '../iterateJsdoc.js';\n\nexport default iterateJsdoc(({\n  context,\n  utils,\n  node,\n  settings,\n  report,\n}) => {\n  const {\n    requireSeparateTemplates = false,\n  } = context.options[0] || {};\n\n  const {\n    mode\n  } = settings;\n\n  const usedNames = new Set();\n  const templateTags = utils.getTags('template');\n  const templateNames = templateTags.flatMap(({name}) => {\n    return name.split(/,\\s*/);\n  });\n\n  for (const tag of templateTags) {\n    const {name} = tag;\n    const names = name.split(/,\\s*/);\n    if (requireSeparateTemplates && names.length > 1) {\n      report(`Missing separate @template for ${names[1]}`, null, tag);\n    }\n  }\n\n  /**\n   * @param {import('@typescript-eslint/types').TSESTree.TSTypeAliasDeclaration} aliasDeclaration\n   */\n  const checkParameters = (aliasDeclaration) => {\n    /* c8 ignore next -- Guard */\n    const {params} = aliasDeclaration.typeParameters ?? {params: []};\n    for (const {name: {name}} of params) {\n      usedNames.add(name);\n    }\n    for (const usedName of usedNames) {\n      if (!templateNames.includes(usedName)) {\n        report(`Missing @template ${usedName}`);\n      }\n    }\n  };\n\n  const handleTypeAliases = () => {\n    const nde = /** @type {import('@typescript-eslint/types').TSESTree.Node} */ (\n      node\n    );\n    if (!nde) {\n      return;\n    }\n    switch (nde.type) {\n    case 'ExportNamedDeclaration':\n      if (nde.declaration?.type === 'TSTypeAliasDeclaration') {\n        checkParameters(nde.declaration);\n      }\n      break;\n    case 'TSTypeAliasDeclaration':\n      checkParameters(nde);\n      break;\n    }\n  };\n\n  const typedefTags = utils.getTags('typedef');\n  if (!typedefTags.length || typedefTags.length >= 2) {\n    handleTypeAliases();\n    return;\n  }\n\n  const potentialType = typedefTags[0].type;\n  const parsedType = mode === 'permissive' ?\n    tryParseType(/** @type {string} */ (potentialType)) :\n    parseType(/** @type {string} */ (potentialType), mode)\n\n  traverse(parsedType, (nde) => {\n    const {\n      type,\n      value,\n    } = /** @type {import('jsdoc-type-pratt-parser').NameResult} */ (nde);\n    if (type === 'JsdocTypeName' && (/^[A-Z]$/).test(value)) {\n      usedNames.add(value);\n    }\n  });\n\n  // Could check against whitelist/blacklist\n  for (const usedName of usedNames) {\n    if (!templateNames.includes(usedName)) {\n      report(`Missing @template ${usedName}`, null, typedefTags[0]);\n    }\n  }\n}, {\n  iterateAllJsdocs: true,\n  meta: {\n    docs: {\n      description: 'Requires template tags for each generic type parameter',\n      url: 'https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/require-template.md#repos-sticky-header',\n    },\n    schema: [\n      {\n        additionalProperties: false,\n        properties: {\n          requireSeparateTemplates: {\n            type: 'boolean'\n          }\n        },\n        type: 'object',\n      },\n    ],\n    type: 'suggestion',\n  },\n});\n"],"mappings":"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","ignoreList":[]}

package/package.json

@@ -5,13 +5,13 @@
     "url": "http://gajus.com"
   },
   "dependencies": {
-    "@es-joy/jsdoccomment": "~0.43.1",
+    "@es-joy/jsdoccomment": "~0.46.0",
     "are-docs-informative": "^0.0.2",
     "comment-parser": "1.4.1",
     "debug": "^4.3.5",
     "escape-string-regexp": "^4.0.0",
-    "esquery": "^1.5.0",
-    "parse-imports": "^2.1.0",
+    "esquery": "^1.6.0",
+    "parse-imports": "^2.1.1",
     "semver": "^7.6.2",
     "spdx-expression-parse": "^4.0.0",
     "synckit": "^0.9.0"
@@ -29,7 +29,7 @@
     "@es-joy/jsdoc-eslint-parser": "^0.21.1",
     "@hkdobrev/run-if-changed": "^0.3.1",
     "@semantic-release/commit-analyzer": "^13.0.0",
-    "@semantic-release/github": "^10.0.6",
+    "@semantic-release/github": "^10.1.0",
     "@semantic-release/npm": "^12.0.1",
     "@types/chai": "^4.3.16",
     "@types/debug": "^4.1.12",
@@ -39,35 +39,35 @@
     "@types/json-schema": "^7.0.15",
     "@types/lodash.defaultsdeep": "^4.6.9",
     "@types/mocha": "^10.0.7",
-    "@types/node": "^20.14.9",
+    "@types/node": "^20.14.10",
     "@types/semver": "^7.5.8",
     "@types/spdx-expression-parse": "^3.0.5",
-    "@typescript-eslint/types": "^7.14.1",
+    "@typescript-eslint/types": "^7.16.0",
     "babel-plugin-add-module-exports": "^1.0.4",
-    "babel-plugin-istanbul": "^6.1.1",
+    "babel-plugin-istanbul": "^7.0.0",
     "babel-plugin-transform-import-meta": "^2.2.1",
     "c8": "^10.1.2",
-    "camelcase": "^6.3.0",
-    "chai": "^4.3.10",
+    "camelcase": "^8.0.0",
+    "chai": "^5.1.1",
     "cross-env": "^7.0.3",
-    "decamelize": "^5.0.1",
-    "eslint": "9.5.0",
+    "decamelize": "^6.0.0",
+    "eslint": "9.6.0",
     "eslint-config-canonical": "~43.0.13",
     "espree": "^10.1.0",
-    "gitdown": "^3.1.5",
+    "gitdown": "^4.0.0",
     "glob": "^10.4.2",
-    "globals": "^15.6.0",
+    "globals": "^15.8.0",
     "husky": "^9.0.11",
     "jsdoc-type-pratt-parser": "^4.0.0",
     "json-schema": "^0.4.0",
     "lint-staged": "^15.2.7",
     "lodash.defaultsdeep": "^4.6.1",
-    "mocha": "^10.5.2",
-    "open-editor": "^3.0.0",
+    "mocha": "^10.6.0",
+    "open-editor": "^4.1.1",
     "replace": "^1.2.2",
     "rimraf": "^5.0.7",
     "semantic-release": "^24.0.0",
-    "typescript": "5.3.x",
+    "typescript": "5.5.x",
     "typescript-eslint": "^8.0.0-alpha.34"
   },
   "engines": {
@@ -144,5 +144,5 @@
     "test-cov": "cross-env TIMING=1 c8 --reporter text npm run test-no-cov",
     "test-index": "npm run test-no-cov -- test/rules/index.js"
   },
-  "version": "48.5.2"
+  "version": "48.7.0"
 }

package/src/index.js

@@ -9,6 +9,7 @@ import checkSyntax from './rules/checkSyntax.js';
 import checkTagNames from './rules/checkTagNames.js';
 import checkTypes from './rules/checkTypes.js';
 import checkValues from './rules/checkValues.js';
+import convertToJsdocComments from './rules/convertToJsdocComments.js';
 import emptyTags from './rules/emptyTags.js';
 import implementsOnClasses from './rules/implementsOnClasses.js';
 import importsAsDependencies from './rules/importsAsDependencies.js';
@@ -44,6 +45,7 @@ import requireReturns from './rules/requireReturns.js';
 import requireReturnsCheck from './rules/requireReturnsCheck.js';
 import requireReturnsDescription from './rules/requireReturnsDescription.js';
 import requireReturnsType from './rules/requireReturnsType.js';
+import requireTemplate from './rules/requireTemplate.js';
 import requireThrows from './rules/requireThrows.js';
 import requireYields from './rules/requireYields.js';
 import requireYieldsCheck from './rules/requireYieldsCheck.js';
@@ -81,6 +83,7 @@ const index = {
     'check-tag-names': checkTagNames,
     'check-types': checkTypes,
     'check-values': checkValues,
+    'convert-to-jsdoc-comments': convertToJsdocComments,
     'empty-tags': emptyTags,
     'implements-on-classes': implementsOnClasses,
     'imports-as-dependencies': importsAsDependencies,
@@ -116,6 +119,7 @@ const index = {
     'require-returns-check': requireReturnsCheck,
     'require-returns-description': requireReturnsDescription,
     'require-returns-type': requireReturnsType,
+    'require-template': requireTemplate,
     'require-throws': requireThrows,
     'require-yields': requireYields,
     'require-yields-check': requireYieldsCheck,
@@ -153,6 +157,7 @@ const createRecommendedRuleset = (warnOrError, flatName) => {
       'jsdoc/check-tag-names': warnOrError,
       'jsdoc/check-types': warnOrError,
       'jsdoc/check-values': warnOrError,
+      'jsdoc/convert-to-jsdoc-comments': 'off',
       'jsdoc/empty-tags': warnOrError,
       'jsdoc/implements-on-classes': warnOrError,
       'jsdoc/imports-as-dependencies': 'off',
@@ -188,6 +193,7 @@ const createRecommendedRuleset = (warnOrError, flatName) => {
       'jsdoc/require-returns-check': warnOrError,
       'jsdoc/require-returns-description': warnOrError,
       'jsdoc/require-returns-type': warnOrError,
+      'jsdoc/require-template': 'off',
       'jsdoc/require-throws': 'off',
       'jsdoc/require-yields': warnOrError,
       'jsdoc/require-yields-check': warnOrError,

package/src/jsdocUtils.js

@@ -1321,7 +1321,7 @@ const parseClosureTemplateTag = (tag) => {
  * @param {{
  *   contexts?: import('./iterateJsdoc.js').Context[]
  * }} settings
- * @returns {string[]}
+ * @returns {(string|import('./iterateJsdoc.js').ContextObject)[]}
  */
 const enforcedContexts = (context, defaultContexts, settings) => {
   const contexts = context.options[0]?.contexts || settings.contexts || (defaultContexts === true ? [

package/src/rules/convertToJsdocComments.js

@@ -0,0 +1,384 @@
+import iterateJsdoc from '../iterateJsdoc.js';
+import {
+  getSettings,
+} from '../iterateJsdoc.js';
+import jsdocUtils from '../jsdocUtils.js';
+import {
+  getNonJsdocComment,
+  getDecorator,
+  getReducedASTNode,
+  getFollowingComment,
+} from '@es-joy/jsdoccomment';
+
+/** @type {import('eslint').Rule.RuleModule} */
+export default {
+  create (context) {
+    /**
+     * @typedef {import('eslint').AST.Token | import('estree').Comment | {
+     *   type: import('eslint').AST.TokenType|"Line"|"Block"|"Shebang",
+     *   range: [number, number],
+     *   value: string
+     * }} Token
+     */
+
+    /**
+     * @callback AddComment
+     * @param {boolean|undefined} inlineCommentBlock
+     * @param {Token} comment
+     * @param {string} indent
+     * @param {number} lines
+     * @param {import('eslint').Rule.RuleFixer} fixer
+     */
+
+    /* c8 ignore next -- Fallback to deprecated method */
+    const {
+      sourceCode = context.getSourceCode(),
+    } = context;
+    const settings = getSettings(context);
+    if (!settings) {
+      return {};
+    }
+
+    const {
+      contexts = settings.contexts || [],
+      contextsAfter = /** @type {string[]} */ ([]),
+      contextsBeforeAndAfter = [
+        'VariableDeclarator', 'TSPropertySignature', 'PropertyDefinition'
+      ],
+      enableFixer = true,
+      enforceJsdocLineStyle = 'multi',
+      lineOrBlockStyle = 'both',
+      allowedPrefixes = ['@ts-', 'istanbul ', 'c8 ', 'v8 ', 'eslint', 'prettier-']
+    } = context.options[0] ?? {};
+
+    let reportingNonJsdoc = false;
+
+    /**
+     * @param {string} messageId
+     * @param {import('estree').Comment|Token} comment
+     * @param {import('eslint').Rule.Node} node
+     * @param {import('eslint').Rule.ReportFixer} fixer
+     */
+    const report = (messageId, comment, node, fixer) => {
+      const loc = {
+        end: {
+          column: 0,
+          /* c8 ignore next 2 -- Guard */
+          // @ts-expect-error Ok
+          line: (comment.loc?.start?.line ?? 1),
+        },
+        start: {
+          column: 0,
+          /* c8 ignore next 2 -- Guard */
+          // @ts-expect-error Ok
+          line: (comment.loc?.start?.line ?? 1)
+        },
+      };
+
+      context.report({
+        fix: enableFixer ? fixer : null,
+        loc,
+        messageId,
+        node,
+      });
+    };
+
+    /**
+     * @param {import('eslint').Rule.Node} node
+     * @param {import('eslint').AST.Token | import('estree').Comment | {
+     *   type: import('eslint').AST.TokenType|"Line"|"Block"|"Shebang",
+     *   range: [number, number],
+     *   value: string
+     * }} comment
+     * @param {AddComment} addComment
+     * @param {import('../iterateJsdoc.js').Context[]} ctxts
+     */
+    const getFixer = (node, comment, addComment, ctxts) => {
+      return /** @type {import('eslint').Rule.ReportFixer} */ (fixer) => {
+        // Default to one line break if the `minLines`/`maxLines` settings allow
+        const lines = settings.minLines === 0 && settings.maxLines >= 1 ? 1 : settings.minLines;
+        let baseNode =
+          /**
+           * @type {import('@typescript-eslint/types').TSESTree.Node|import('eslint').Rule.Node}
+           */ (
+            getReducedASTNode(node, sourceCode)
+          );
+
+        const decorator = getDecorator(
+          /** @type {import('eslint').Rule.Node} */
+          (baseNode)
+        );
+        if (decorator) {
+          baseNode = /** @type {import('@typescript-eslint/types').TSESTree.Decorator} */ (
+            decorator
+          );
+        }
+
+        const indent = jsdocUtils.getIndent({
+          text: sourceCode.getText(
+            /** @type {import('eslint').Rule.Node} */ (baseNode),
+            /** @type {import('eslint').AST.SourceLocation} */
+            (
+              /** @type {import('eslint').Rule.Node} */ (baseNode).loc
+            ).start.column,
+          ),
+        });
+
+        const {
+          inlineCommentBlock,
+        } =
+          /**
+           * @type {{
+           *     context: string,
+           *     inlineCommentBlock: boolean,
+           *     minLineCount: import('../iterateJsdoc.js').Integer
+           *   }[]}
+           */ (ctxts).find((contxt) => {
+            if (typeof contxt === 'string') {
+              return false;
+            }
+
+            const {
+              context: ctxt,
+            } = contxt;
+            return ctxt === node.type;
+          }) || {};
+
+        return addComment(inlineCommentBlock, comment, indent, lines, fixer);
+      };
+    };
+
+    /**
+     * @param {import('eslint').AST.Token | import('estree').Comment | {
+     *   type: import('eslint').AST.TokenType|"Line"|"Block"|"Shebang",
+     *   range: [number, number],
+     *   value: string
+     * }} comment
+     * @param {import('eslint').Rule.Node} node
+     * @param {AddComment} addComment
+     * @param {import('../iterateJsdoc.js').Context[]} ctxts
+     */
+    const reportings = (comment, node, addComment, ctxts) => {
+      const fixer = getFixer(node, comment, addComment, ctxts);
+
+      if (comment.type === 'Block') {
+        if (lineOrBlockStyle === 'line') {
+          return;
+        }
+        report('blockCommentsJsdocStyle', comment, node, fixer);
+        return;
+      }
+
+      if (comment.type === 'Line') {
+        if (lineOrBlockStyle === 'block') {
+          return;
+        }
+        report('lineCommentsJsdocStyle', comment, node, fixer);
+      }
+    };
+
+    /**
+     * @type {import('../iterateJsdoc.js').CheckJsdoc}
+     */
+    const checkNonJsdoc = (_info, _handler, node) => {
+      const comment = getNonJsdocComment(sourceCode, node, settings);
+
+      if (
+        !comment ||
+        /** @type {string[]} */
+        (allowedPrefixes).some((prefix) => {
+          return comment.value.trimStart().startsWith(prefix);
+        })
+      ) {
+        return;
+      }
+
+      reportingNonJsdoc = true;
+
+      /** @type {AddComment} */
+      const addComment = (inlineCommentBlock, comment, indent, lines, fixer) => {
+        const insertion = (
+          inlineCommentBlock || enforceJsdocLineStyle === 'single'
+            ? `/** ${comment.value.trim()} `
+            : `/**\n${indent}*${comment.value.trimEnd()}\n${indent}`
+        ) +
+            `*/${'\n'.repeat((lines || 1) - 1)}`;
+
+        return fixer.replaceText(
+          /** @type {import('eslint').AST.Token} */
+          (comment),
+          insertion,
+        );
+      };
+
+      reportings(comment, node, addComment, contexts);
+    };
+
+    /**
+     * @param {import('eslint').Rule.Node} node
+     * @param {import('../iterateJsdoc.js').Context[]} ctxts
+     */
+    const checkNonJsdocAfter = (node, ctxts) => {
+      const comment = getFollowingComment(sourceCode, node);
+
+      if (
+        !comment ||
+        comment.value.startsWith('*') ||
+        /** @type {string[]} */
+        (allowedPrefixes).some((prefix) => {
+          return comment.value.trimStart().startsWith(prefix);
+        })
+      ) {
+        return;
+      }
+
+      /** @type {AddComment} */
+      const addComment = (inlineCommentBlock, comment, indent, lines, fixer) => {
+        const insertion = (
+          inlineCommentBlock || enforceJsdocLineStyle === 'single'
+            ? `/** ${comment.value.trim()} `
+            : `/**\n${indent}*${comment.value.trimEnd()}\n${indent}`
+        ) +
+            `*/${'\n'.repeat((lines || 1) - 1)}${lines ? `\n${indent.slice(1)}` : ' '}`;
+
+        return [fixer.remove(
+          /** @type {import('eslint').AST.Token} */
+          (comment)
+        ), fixer.insertTextBefore(
+          node.type === 'VariableDeclarator' ? node.parent : node,
+          insertion,
+        )];
+      };
+
+      reportings(comment, node, addComment, ctxts);
+    };
+
+    // Todo: add contexts to check after (and handle if want both before and after)
+    return {
+      ...jsdocUtils.getContextObject(
+        jsdocUtils.enforcedContexts(context, true, settings),
+        checkNonJsdoc,
+      ),
+      ...jsdocUtils.getContextObject(
+        contextsAfter,
+        (_info, _handler, node) => {
+          checkNonJsdocAfter(node, contextsAfter);
+        },
+      ),
+      ...jsdocUtils.getContextObject(
+        contextsBeforeAndAfter,
+        (_info, _handler, node) => {
+          checkNonJsdoc({}, null, node);
+          if (!reportingNonJsdoc) {
+            checkNonJsdocAfter(node, contextsBeforeAndAfter);
+          }
+        }
+      )
+    };
+  },
+  meta: {
+    fixable: 'code',
+
+    messages: {
+      blockCommentsJsdocStyle: 'Block comments should be JSDoc-style.',
+      lineCommentsJsdocStyle: 'Line comments should be JSDoc-style.',
+    },
+
+    docs: {
+      description: 'Converts non-JSDoc comments preceding or following nodes into JSDoc ones',
+      url: 'https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/convert-to-jsdoc-comments.md#repos-sticky-header',
+    },
+    schema: [
+      {
+        additionalProperties: false,
+        properties: {
+          allowedPrefixes: {
+            type: 'array',
+            items: {
+              type: 'string'
+            }
+          },
+          contexts: {
+            items: {
+              anyOf: [
+                {
+                  type: 'string',
+                },
+                {
+                  additionalProperties: false,
+                  properties: {
+                    context: {
+                      type: 'string',
+                    },
+                    inlineCommentBlock: {
+                      type: 'boolean',
+                    },
+                  },
+                  type: 'object',
+                },
+              ],
+            },
+            type: 'array',
+          },
+          contextsAfter: {
+            items: {
+              anyOf: [
+                {
+                  type: 'string',
+                },
+                {
+                  additionalProperties: false,
+                  properties: {
+                    context: {
+                      type: 'string',
+                    },
+                    inlineCommentBlock: {
+                      type: 'boolean',
+                    },
+                  },
+                  type: 'object',
+                },
+              ],
+            },
+            type: 'array',
+          },
+          contextsBeforeAndAfter: {
+            items: {
+              anyOf: [
+                {
+                  type: 'string',
+                },
+                {
+                  additionalProperties: false,
+                  properties: {
+                    context: {
+                      type: 'string',
+                    },
+                    inlineCommentBlock: {
+                      type: 'boolean',
+                    },
+                  },
+                  type: 'object',
+                },
+              ],
+            },
+            type: 'array',
+          },
+          enableFixer: {
+            type: 'boolean'
+          },
+          enforceJsdocLineStyle: {
+            type: 'string',
+            enum: ['multi', 'single']
+          },
+          lineOrBlockStyle: {
+            type: 'string',
+            enum: ['block', 'line', 'both']
+          },
+        },
+        type: 'object',
+      },
+    ],
+    type: 'suggestion',
+  },
+};

package/src/rules/requireJsdoc.js

@@ -18,6 +18,11 @@ import {
  * }} RequireJsdocOpts
  */
 
+/**
+ * @typedef {import('eslint').Rule.Node|
+ *   import('@typescript-eslint/types').TSESTree.Node} ESLintOrTSNode
+ */
+
 /** @type {import('json-schema').JSONSchema4} */
 const OPTIONS_SCHEMA = {
   additionalProperties: false,
@@ -411,10 +416,13 @@ export default {
       const fix = /** @type {import('eslint').Rule.ReportFixer} */ (fixer) => {
         // Default to one line break if the `minLines`/`maxLines` settings allow
         const lines = settings.minLines === 0 && settings.maxLines >= 1 ? 1 : settings.minLines;
-        /** @type {import('eslint').Rule.Node|import('@typescript-eslint/types').TSESTree.Decorator} */
+        /** @type {ESLintOrTSNode|import('@typescript-eslint/types').TSESTree.Decorator} */
         let baseNode = getReducedASTNode(node, sourceCode);
 
-        const decorator = getDecorator(baseNode);
+        const decorator = getDecorator(
+          /** @type {import('eslint').Rule.Node} */
+          (baseNode)
+        );
         if (decorator) {
           baseNode = decorator;
         }