eslint-plugin-jsdoc 44.2.3 → 44.2.5

package/dist/jsdocUtils.js

@@ -4,11 +4,11 @@ Object.defineProperty(exports, "__esModule", {
   value: true
 });
 exports.default = void 0;
-var _jsdoccomment = require("@es-joy/jsdoccomment");
-var _WarnSettings = _interopRequireDefault(require("./WarnSettings"));
 var _getDefaultTagStructureForMode = _interopRequireDefault(require("./getDefaultTagStructureForMode"));
 var _tagNames = require("./tagNames");
 var _hasReturnValue = require("./utils/hasReturnValue");
+var _WarnSettings = _interopRequireDefault(require("./WarnSettings"));
+var _jsdoccomment = require("@es-joy/jsdoccomment");
 function _interopRequireDefault(obj) { return obj && obj.__esModule ? obj : { default: obj }; }
 /**
  * @typedef {number} Integer
@@ -33,6 +33,25 @@ const setTagStructure = mode => {
   tagStructure = (0, _getDefaultTagStructureForMode.default)(mode);
 };
 
+/**
+ * @typedef {undefined|string|{
+ *   name: Integer,
+ *   restElement: boolean
+ * }|{
+ *   isRestProperty: boolean|undefined,
+ *   name: string,
+ *   restElement: boolean
+ * }|{
+ *   name: string,
+ *   restElement: boolean
+ * }} ParamCommon
+ */
+/**
+ * @typedef {ParamCommon|[string|undefined, (FlattendRootInfo & {
+ *   annotationParamName?: string,
+ * })]|NestedParamInfo} ParamNameInfo
+ */
+
 /**
  * @typedef {{
  *   hasPropertyRest: boolean,
@@ -41,15 +60,27 @@ const setTagStructure = mode => {
  *   rests: boolean[],
  * }} FlattendRootInfo
  */
+/**
+ * @typedef {[string, (string[]|ParamInfo[])]} NestedParamInfo
+ */
+/**
+ * @typedef {ParamCommon|
+ * [string|undefined, (FlattendRootInfo & {
+ *   annotationParamName?: string
+ * })]|
+ * NestedParamInfo} ParamInfo
+ */
 
 /**
  * Given a nested array of property names, reduce them to a single array,
- *   appending the name of the root element along the way if present.
- *
- * @param {} params
- * @param {string} root
+ * appending the name of the root element along the way if present.
+ * @callback FlattenRoots
+ * @param {ParamInfo[]} params
+ * @param {string} [root]
  * @returns {FlattendRootInfo}
  */
+
+/** @type {FlattenRoots} */
 const flattenRoots = (params, root = '') => {
   let hasRestElement = false;
   let hasPropertyRest = false;
@@ -58,7 +89,13 @@ const flattenRoots = (params, root = '') => {
    * @type {boolean[]}
    */
   const rests = [];
-  const names = params.reduce((acc, cur) => {
+  const names = params.reduce(
+  /**
+   * @param {string[]} acc
+   * @param {ParamInfo} cur
+   * @returns {string[]}
+   */
+  (acc, cur) => {
     if (Array.isArray(cur)) {
       let nms;
       if (Array.isArray(cur[1])) {
@@ -79,21 +116,21 @@ const flattenRoots = (params, root = '') => {
       if (flattened.hasPropertyRest) {
         hasPropertyRest = true;
       }
-      const inner = [root ? `${root}.${cur[0]}` : cur[0], ...flattened.names].filter(Boolean);
+      const inner = /** @type {string[]} */[root ? `${root}.${cur[0]}` : cur[0], ...flattened.names].filter(Boolean);
       rests.push(false, ...flattened.rests);
       return acc.concat(inner);
     }
     if (typeof cur === 'object') {
-      if (cur.isRestProperty) {
+      if ('isRestProperty' in cur && cur.isRestProperty) {
         hasPropertyRest = true;
         rests.push(true);
       } else {
         rests.push(false);
       }
-      if (cur.restElement) {
+      if ('restElement' in cur && cur.restElement) {
         hasRestElement = true;
       }
-      acc.push(root ? `${root}.${cur.name}` : cur.name);
+      acc.push(root ? `${root}.${String(cur.name)}` : String(cur.name));
     } else if (typeof cur !== 'undefined') {
       rests.push(false);
       acc.push(root ? `${root}.${cur}` : cur);
@@ -109,59 +146,72 @@ const flattenRoots = (params, root = '') => {
 };
 
 /**
- * @param {ESTreeOrTypeScriptNode} propSignature
- * @returns {undefined|Array|string}
+ * @param {import('@typescript-eslint/types').TSESTree.TSIndexSignature|
+ *  import('@typescript-eslint/types').TSESTree.TSConstructSignatureDeclaration|
+ *  import('@typescript-eslint/types').TSESTree.TSCallSignatureDeclaration|
+ *  import('@typescript-eslint/types').TSESTree.TSPropertySignature} propSignature
+ * @returns {undefined|string|[string, string[]]}
  */
 const getPropertiesFromPropertySignature = propSignature => {
   if (propSignature.type === 'TSIndexSignature' || propSignature.type === 'TSConstructSignatureDeclaration' || propSignature.type === 'TSCallSignatureDeclaration') {
     return undefined;
   }
   if (propSignature.typeAnnotation && propSignature.typeAnnotation.typeAnnotation.type === 'TSTypeLiteral') {
-    return [propSignature.key.name, propSignature.typeAnnotation.typeAnnotation.members.map(member => {
-      return getPropertiesFromPropertySignature(member);
+    return [/** @type {import('@typescript-eslint/types').TSESTree.Identifier} */propSignature.key.name, propSignature.typeAnnotation.typeAnnotation.members.map(member => {
+      return (/** @type {string} */
+        getPropertiesFromPropertySignature( /** @type {import('@typescript-eslint/types').TSESTree.TSPropertySignature} */
+        member)
+      );
     })];
   }
-  return propSignature.key.name;
+  return (/** @type {import('@typescript-eslint/types').TSESTree.Identifier} */propSignature.key.name
+  );
 };
 
 /**
- * @param {ESTreeOrTypeScriptNode} functionNode
+ * @param {ESTreeOrTypeScriptNode|null} functionNode
  * @param {boolean} [checkDefaultObjects]
- * @returns {Array}
+ * @throws {Error}
+ * @returns {ParamNameInfo[]}
  */
 const getFunctionParameterNames = (functionNode, checkDefaultObjects) => {
   var _functionNode$value;
   /* eslint-disable complexity -- Temporary */
   /**
-   * @param {} param
+   * @param {import('estree').Identifier|import('estree').AssignmentPattern|
+   *   import('estree').ObjectPattern|import('estree').Property|
+   *   import('estree').RestElement|import('estree').ArrayPattern|
+   *   import('@typescript-eslint/types').TSESTree.TSParameterProperty|
+   *   import('@typescript-eslint/types').TSESTree.Property|
+   *   import('@typescript-eslint/types').TSESTree.RestElement|
+   *   import('@typescript-eslint/types').TSESTree.Identifier|
+   *   import('@typescript-eslint/types').TSESTree.ObjectPattern|
+   *   import('@typescript-eslint/types').TSESTree.BindingName|
+   *   import('@typescript-eslint/types').TSESTree.Parameter
+   * } param
    * @param {boolean} [isProperty]
-   * @returns {undefined|{
-   *   isRestProperty: boolean|undefined,
-   *   name: string,
-   *   restElement: true
-   * }|[undefined|string, FlattendRootInfo|{
-   *   name: Integer,
-   *   restElement: boolean
-   * }[]]}
+   * @returns {ParamNameInfo|[string, ParamNameInfo[]]}
    */
   const getParamName = (param, isProperty) => {
-    var _param$left, _param$left3;
+    var _param$left2;
     /* eslint-enable complexity -- Temporary */
     const hasLeftTypeAnnotation = 'left' in param && 'typeAnnotation' in param.left;
     if ('typeAnnotation' in param || hasLeftTypeAnnotation) {
       var _typeAnnotation$typeA;
-      const typeAnnotation = hasLeftTypeAnnotation ? param.left.typeAnnotation : param.typeAnnotation;
+      const typeAnnotation = hasLeftTypeAnnotation ? /** @type {import('@typescript-eslint/types').TSESTree.Identifier} */param.left.typeAnnotation : /** @type {import('@typescript-eslint/types').TSESTree.Identifier|import('@typescript-eslint/types').TSESTree.ObjectPattern} */
+      param.typeAnnotation;
       if ((typeAnnotation === null || typeAnnotation === void 0 ? void 0 : (_typeAnnotation$typeA = typeAnnotation.typeAnnotation) === null || _typeAnnotation$typeA === void 0 ? void 0 : _typeAnnotation$typeA.type) === 'TSTypeLiteral') {
         const propertyNames = typeAnnotation.typeAnnotation.members.map(member => {
-          return getPropertiesFromPropertySignature(member);
+          return getPropertiesFromPropertySignature( /** @type {import('@typescript-eslint/types').TSESTree.TSPropertySignature} */
+          member);
         });
         const flattened = {
           ...flattenRoots(propertyNames),
-          annotationParamName: param.name
+          annotationParamName: 'name' in param ? param.name : undefined
         };
         const hasLeftName = 'left' in param && 'name' in param.left;
         if ('name' in param || hasLeftName) {
-          return [hasLeftName ? param.left.name : param.name, flattened];
+          return [hasLeftName ? /** @type {import('@typescript-eslint/types').TSESTree.Identifier} */param.left.name : /** @type {import('@typescript-eslint/types').TSESTree.Identifier} */param.name, flattened];
         }
         return [undefined, flattened];
       }
@@ -172,9 +222,9 @@ const getFunctionParameterNames = (functionNode, checkDefaultObjects) => {
     if ('left' in param && 'name' in param.left) {
       return param.left.name;
     }
-    if (param.type === 'ObjectPattern' || ((_param$left = param.left) === null || _param$left === void 0 ? void 0 : _param$left.type) === 'ObjectPattern') {
-      var _param$left2;
-      const properties = param.properties || ((_param$left2 = param.left) === null || _param$left2 === void 0 ? void 0 : _param$left2.properties);
+    if (param.type === 'ObjectPattern' || 'left' in param && param.left.type === 'ObjectPattern') {
+      var _param$left;
+      const properties = /** @type {import('@typescript-eslint/types').TSESTree.ObjectPattern} */param.properties || ( /** @type {import('estree').ObjectPattern} */(_param$left = /** @type {import('@typescript-eslint/types').TSESTree.AssignmentPattern} */param.left) === null || _param$left === void 0 ? void 0 : _param$left.properties);
       const roots = properties.map(prop => {
         return getParamName(prop, true);
       });
@@ -184,16 +234,22 @@ const getFunctionParameterNames = (functionNode, checkDefaultObjects) => {
       // eslint-disable-next-line default-case
       switch (param.value.type) {
         case 'ArrayPattern':
-          return [param.key.name, /** @type {import('estree').ArrayPattern} */param.value.elements.map((prop, idx) => {
-            return {
-              name: idx,
-              restElement: (prop === null || prop === void 0 ? void 0 : prop.type) === 'RestElement'
-            };
-          })];
+          {
+            return [/** @type {import('estree').Identifier} */
+            param.key.name, /** @type {import('estree').ArrayPattern} */param.value.elements.map((prop, idx) => {
+              return {
+                name: idx,
+                restElement: (prop === null || prop === void 0 ? void 0 : prop.type) === 'RestElement'
+              };
+            })];
+          }
         case 'ObjectPattern':
-          return [param.key.name, /** @type {import('estree').ObjectPattern} */param.value.properties.map(prop => {
-            return getParamName(prop, isProperty);
-          })];
+          {
+            return [/** @type {import('estree').Identifier} */param.key.name, /** @type {import('estree').ObjectPattern} */param.value.properties.map(prop => {
+              return (/** @type {string|[string, string[]]} */getParamName(prop, isProperty)
+              );
+            })];
+          }
         case 'AssignmentPattern':
           {
             // eslint-disable-next-line default-case
@@ -201,17 +257,21 @@ const getFunctionParameterNames = (functionNode, checkDefaultObjects) => {
               case 'Identifier':
                 // Default parameter
                 if (checkDefaultObjects && param.value.right.type === 'ObjectExpression') {
-                  return [param.key.name, /** @type {import('estree').AssignmentPattern} */param.value.right.properties.map(prop => {
-                    return getParamName(prop, isProperty);
+                  return [/** @type {import('estree').Identifier} */param.key.name, /** @type {import('estree').AssignmentPattern} */param.value.right.properties.map(prop => {
+                    return (/** @type {string} */getParamName( /** @type {import('estree').Property} */
+                      prop, isProperty)
+                    );
                   })];
                 }
                 break;
               case 'ObjectPattern':
-                return [param.key.name, /** @type {import('estree').ObjectPattern} */param.value.left.properties.map(prop => {
+                return [/** @type {import('estree').Identifier} */
+                param.key.name, /** @type {import('estree').ObjectPattern} */param.value.left.properties.map(prop => {
                   return getParamName(prop, isProperty);
                 })];
               case 'ArrayPattern':
-                return [param.key.name, /** @type {import('estree').ArrayPattern} */param.value.left.elements.map((prop, idx) => {
+                return [/** @type {import('estree').Identifier} */
+                param.key.name, /** @type {import('estree').ArrayPattern} */param.value.left.elements.map((prop, idx) => {
                   return {
                     name: idx,
                     restElement: (prop === null || prop === void 0 ? void 0 : prop.type) === 'RestElement'
@@ -226,9 +286,10 @@ const getFunctionParameterNames = (functionNode, checkDefaultObjects) => {
 
         // The key of an object could also be a string or number
         case 'Literal':
-          return param.key.raw ||
-          // istanbul ignore next -- `raw` may not be present in all parsers
-          param.key.value;
+          return (/** @type {string} */param.key.raw ||
+            // istanbul ignore next -- `raw` may not be present in all parsers
+            param.key.value
+          );
 
         // case 'MemberExpression':
         default:
@@ -239,9 +300,9 @@ const getFunctionParameterNames = (functionNode, checkDefaultObjects) => {
           return undefined;
       }
     }
-    if (param.type === 'ArrayPattern' || ((_param$left3 = param.left) === null || _param$left3 === void 0 ? void 0 : _param$left3.type) === 'ArrayPattern') {
-      var _param$left4;
-      const elements = /** @type {import('estree').ArrayPattern} */param.elements || ( /** @type {import('estree').ArrayPattern} */(_param$left4 = param.left) === null || _param$left4 === void 0 ? void 0 : _param$left4.elements);
+    if (param.type === 'ArrayPattern' || /** @type {import('estree').AssignmentPattern} */((_param$left2 = param.left) === null || _param$left2 === void 0 ? void 0 : _param$left2.type) === 'ArrayPattern') {
+      var _param$left3;
+      const elements = /** @type {import('estree').ArrayPattern} */param.elements || ( /** @type {import('estree').ArrayPattern} */(_param$left3 = /** @type {import('estree').AssignmentPattern} */param.left) === null || _param$left3 === void 0 ? void 0 : _param$left3.elements);
       const roots = elements.map((prop, idx) => {
         return {
           name: `"${idx}"`,
@@ -253,19 +314,20 @@ const getFunctionParameterNames = (functionNode, checkDefaultObjects) => {
     if (['RestElement', 'ExperimentalRestProperty'].includes(param.type)) {
       return {
         isRestProperty: isProperty,
-        name: param.argument.name,
+        name: /** @type {import('@typescript-eslint/types').TSESTree.Identifier} */ /** @type {import('@typescript-eslint/types').TSESTree.RestElement} */param.argument.name,
         restElement: true
       };
     }
     if (param.type === 'TSParameterProperty') {
-      return getParamName(param.parameter, true);
+      return getParamName( /** @type {import('@typescript-eslint/types').TSESTree.Identifier} */
+      /** @type {import('@typescript-eslint/types').TSESTree.TSParameterProperty} */param.parameter, true);
     }
     throw new Error(`Unsupported function signature format: \`${param.type}\`.`);
   };
   if (!functionNode) {
     return [];
   }
-  return (functionNode.params || ((_functionNode$value = functionNode.value) === null || _functionNode$value === void 0 ? void 0 : _functionNode$value.params) || []).map(param => {
+  return ( /** @type {import('@typescript-eslint/types').TSESTree.FunctionDeclaration} */functionNode.params || ( /** @type {import('@typescript-eslint/types').TSESTree.MethodDefinition} */(_functionNode$value = functionNode.value) === null || _functionNode$value === void 0 ? void 0 : _functionNode$value.params) || []).map(param => {
     return getParamName(param);
   });
 };
@@ -276,13 +338,13 @@ const getFunctionParameterNames = (functionNode, checkDefaultObjects) => {
  */
 const hasParams = functionNode => {
   // Should also check `functionNode.value.params` if supporting `MethodDefinition`
-  return functionNode.params.length;
+  return (/** @type {import('@typescript-eslint/types').TSESTree.FunctionDeclaration} */functionNode.params.length
+  );
 };
 
 /**
  * Gets all names of the target type, including those that refer to a path, e.g.
  * "@param foo; @param foo.bar".
- *
  * @param {import('comment-parser').Block} jsdoc
  * @param {string} targetTagName
  * @returns {{
@@ -312,7 +374,7 @@ const getJsdocTagsDeep = (jsdoc, targetTagName) => {
 const modeWarnSettings = (0, _WarnSettings.default)();
 
 /**
- * @param {ParserMode} mode
+ * @param {ParserMode|undefined} mode
  * @param {import('eslint').Rule.RuleContext} context
  * @returns {import('./tagNames.js').AliasedTags}
  */
@@ -329,6 +391,10 @@ const getTagNamesForMode = (mode, context) => {
       if (!modeWarnSettings.hasBeenWarned(context, 'mode')) {
         context.report({
           loc: {
+            end: {
+              column: 1,
+              line: 1
+            },
             start: {
               column: 1,
               line: 1
@@ -346,10 +412,10 @@ const getTagNamesForMode = (mode, context) => {
 
 /**
  * @param {import('eslint').Rule.RuleContext} context
- * @param {ParserMode} mode
+ * @param {ParserMode|undefined} mode
  * @param {string} name
  * @param {TagNamePreference} tagPreference
- * @returns {string|boolean|{
+ * @returns {string|false|{
  *   message: string;
  *   replacement?: string|undefined;
  * }}
@@ -385,10 +451,10 @@ const getPreferredTagName = (context, mode, name, tagPreference = {}) => {
 };
 
 /**
- * @param context
- * @param {ParserMode} mode
+ * @param {import('eslint').Rule.RuleContext} context
+ * @param {ParserMode|undefined} mode
  * @param {string} name
- * @param {Array} definedTags
+ * @param {string[]} definedTags
  * @returns {boolean}
  */
 const isValidTag = (context, mode, name, definedTags) => {
@@ -400,7 +466,7 @@ const isValidTag = (context, mode, name, definedTags) => {
 };
 
 /**
- * @param {object} jsdoc
+ * @param {import('./iterateJsdoc.js').JsdocBlockWithInline} jsdoc
  * @param {string} targetTagName
  * @returns {boolean}
  */
@@ -413,16 +479,12 @@ const hasTag = (jsdoc, targetTagName) => {
 
 /**
  * Get all tags, inline tags and inline tags in tags
- *
- * @param {import('comment-parser').Block & {
- *   inlineTags: import('@es-joy/jsdoccomment').JsdocInlineTagNoType[]
- * }} jsdoc
- * @param {boolean} includeInlineTags
+ * @param {import('./iterateJsdoc.js').JsdocBlockWithInline} jsdoc
  * @returns {(import('comment-parser').Spec|
  *   import('@es-joy/jsdoccomment').JsdocInlineTagNoType)[]}
  */
-const getAllTags = (jsdoc, includeInlineTags) => {
-  return includeInlineTags ? [...jsdoc.tags, ...jsdoc.inlineTags.map(inlineTag => {
+const getAllTags = jsdoc => {
+  return [...jsdoc.tags, ...jsdoc.inlineTags.map(inlineTag => {
     // Tags don't have source or line numbers, so add before returning
     let line = -1;
     for (const {
@@ -450,7 +512,8 @@ const getAllTags = (jsdoc, includeInlineTags) => {
       }
     }
     for (const inlineTag of tag.inlineTags) {
-      let line;
+      /** @type {import('./iterateJsdoc.js').Integer} */
+      let line = 0;
       for (const {
         number,
         tokens: {
@@ -472,11 +535,11 @@ const getAllTags = (jsdoc, includeInlineTags) => {
        */
       tag.inlineTags
     );
-  })] : jsdoc.tags;
+  })];
 };
 
 /**
- * @param {object} jsdoc
+ * @param {import('./iterateJsdoc.js').JsdocBlockWithInline} jsdoc
  * @param {string[]} targetTagNames
  * @returns {boolean}
  */
@@ -488,8 +551,7 @@ const hasATag = (jsdoc, targetTagNames) => {
 
 /**
  * Checks if the JSDoc comment has an undefined type.
- *
- * @param {import('comment-parser').Spec} tag
+ * @param {import('comment-parser').Spec|null|undefined} tag
  *   the tag which should be checked.
  * @param {ParserMode} mode
  * @returns {boolean}
@@ -529,7 +591,7 @@ const mayBeUndefinedTypeTag = (tag, mode) => {
 /**
  * @param {import('./getDefaultTagStructureForMode.js').TagStructure} map
  * @param {string} tag
- * @returns {Map<string, string | boolean>}
+ * @returns {Map<string, string|string[]|boolean|undefined>}
  */
 const ensureMap = (map, tag) => {
   if (!map.has(tag)) {
@@ -539,20 +601,8 @@ const ensureMap = (map, tag) => {
   );
 };
 
-/* eslint-disable jsdoc/valid-types -- Older non-TS version */
-/**
- * @typedef {{
- *   [tag: string]: {
- *     name: string|boolean,
- *     type: string[]|boolean,
- *     required: string[]
- *   }
- * }} StructuredTags
- */
-/* eslint-enable jsdoc/valid-types -- Older non-TS version */
-
 /**
- * @param {StructuredTags} structuredTags
+ * @param {import('./iterateJsdoc.js').StructuredTags} structuredTags
  * @param {import('./getDefaultTagStructureForMode.js').TagStructure} tagMap
  * @returns {void}
  */
@@ -588,7 +638,7 @@ const overrideTagStructure = (structuredTags, tagMap = tagStructure) => {
 
 /**
  * @param {ParserMode} mode
- * @param {StructuredTags} structuredTags
+ * @param {import('./iterateJsdoc.js').StructuredTags} structuredTags
  * @returns {import('./getDefaultTagStructureForMode.js').TagStructure}
  */
 const getTagStructureForMode = (mode, structuredTags) => {
@@ -634,11 +684,12 @@ const isNamepathOrUrlReferencingTag = (tag, tagMap = tagStructure) => {
 /**
  * @param {string} tag
  * @param {import('./getDefaultTagStructureForMode.js').TagStructure} tagMap
- * @returns {boolean}
+ * @returns {boolean|undefined}
  */
 const tagMustHaveTypePosition = (tag, tagMap = tagStructure) => {
   const tagStruct = ensureMap(tagMap, tag);
-  return tagStruct.get('typeRequired');
+  return (/** @type {boolean|undefined} */tagStruct.get('typeRequired')
+  );
 };
 
 /**
@@ -651,7 +702,7 @@ const tagMightHaveTypePosition = (tag, tagMap = tagStructure) => {
     return true;
   }
   const tagStruct = ensureMap(tagMap, tag);
-  const ret = tagStruct.get('typeAllowed');
+  const ret = /** @type {boolean|undefined} */tagStruct.get('typeAllowed');
   return ret === undefined ? true : ret;
 };
 const namepathTypes = new Set(['namepath-defining', 'namepath-referencing']);
@@ -674,42 +725,45 @@ const tagMightHaveNamePosition = (tag, tagMap = tagStructure) => {
  */
 const tagMightHaveNamepath = (tag, tagMap = tagStructure) => {
   const tagStruct = ensureMap(tagMap, tag);
-  return namepathTypes.has(tagStruct.get('namepathRole'));
+  const nampathRole = tagStruct.get('namepathRole');
+  return nampathRole !== false && namepathTypes.has( /** @type {string} */nampathRole);
 };
 
 /**
  * @param {string} tag
  * @param {import('./getDefaultTagStructureForMode.js').TagStructure} tagMap
- * @returns {boolean}
+ * @returns {boolean|undefined}
  */
 const tagMustHaveNamePosition = (tag, tagMap = tagStructure) => {
   const tagStruct = ensureMap(tagMap, tag);
-  return tagStruct.get('nameRequired');
+  return (/** @type {boolean|undefined} */tagStruct.get('nameRequired')
+  );
 };
 
 /**
- * @param tag
+ * @param {string} tag
  * @param {import('./getDefaultTagStructureForMode.js').TagStructure} tagMap
  * @returns {boolean}
  */
 const tagMightHaveEitherTypeOrNamePosition = (tag, tagMap) => {
-  return tagMightHaveTypePosition(tag, tagMap) || tagMightHaveNamepath(tag, tagMap);
+  return Boolean(tagMightHaveTypePosition(tag, tagMap)) || tagMightHaveNamepath(tag, tagMap);
 };
 
 /**
  * @param {string} tag
  * @param {import('./getDefaultTagStructureForMode.js').TagStructure} tagMap
- * @returns {boolean}
+ * @returns {boolean|undefined}
  */
 const tagMustHaveEitherTypeOrNamePosition = (tag, tagMap) => {
   const tagStruct = ensureMap(tagMap, tag);
-  return tagStruct.get('typeOrNameRequired');
+  return (/** @type {boolean} */tagStruct.get('typeOrNameRequired')
+  );
 };
 
 /**
- * @param tag
+ * @param {import('comment-parser').Spec} tag
  * @param {import('./getDefaultTagStructureForMode.js').TagStructure} tagMap
- * @returns {boolean}
+ * @returns {boolean|undefined}
  */
 const tagMissingRequiredTypeOrNamepath = (tag, tagMap = tagStructure) => {
   const mustHaveTypePosition = tagMustHaveTypePosition(tag.tag, tagMap);
@@ -723,7 +777,7 @@ const tagMissingRequiredTypeOrNamepath = (tag, tagMap = tagStructure) => {
 
 /* eslint-disable complexity -- Temporary */
 /**
- * @param {ESTreeOrTypeScriptNode} node
+ * @param {ESTreeOrTypeScriptNode|null|undefined} node
  * @param {boolean} [checkYieldReturnValue]
  * @returns {boolean}
  */
@@ -740,6 +794,7 @@ const hasNonFunctionYield = (node, checkYieldReturnValue) => {
         });
       }
 
+    // @ts-expect-error In Babel?
     // istanbul ignore next -- In Babel?
     case 'OptionalCallExpression':
     case 'CallExpression':
@@ -768,7 +823,8 @@ const hasNonFunctionYield = (node, checkYieldReturnValue) => {
       }
     case 'TryStatement':
       {
-        return hasNonFunctionYield(node.block, checkYieldReturnValue) || hasNonFunctionYield(node.handler && node.handler.body, checkYieldReturnValue) || hasNonFunctionYield(node.finalizer, checkYieldReturnValue);
+        return hasNonFunctionYield(node.block, checkYieldReturnValue) || hasNonFunctionYield(node.handler && node.handler.body, checkYieldReturnValue) || hasNonFunctionYield( /** @type {import('@typescript-eslint/types').TSESTree.BlockStatement} */
+        node.finalizer, checkYieldReturnValue);
       }
     case 'SwitchStatement':
       {
@@ -817,17 +873,23 @@ const hasNonFunctionYield = (node, checkYieldReturnValue) => {
     // istanbul ignore next -- In Babel?
     case 'PropertyDefinition':
     /* eslint-disable no-fallthrough */
+    // @ts-expect-error In Babel?
     // istanbul ignore next -- In Babel?
     case 'ObjectProperty':
+    // @ts-expect-error In Babel?
     // istanbul ignore next -- In Babel?
     case 'ClassProperty':
     case 'Property':
       /* eslint-enable no-fallthrough */
       return node.computed && hasNonFunctionYield(node.key, checkYieldReturnValue) || hasNonFunctionYield(node.value, checkYieldReturnValue);
+    // @ts-expect-error In Babel?
     // istanbul ignore next -- In Babel?
     case 'ObjectMethod':
+      // @ts-expect-error In Babel?
       // istanbul ignore next -- In Babel?
-      return node.computed && hasNonFunctionYield(node.key, checkYieldReturnValue) || node.arguments.some(nde => {
+      return node.computed && hasNonFunctionYield(node.key, checkYieldReturnValue) ||
+      // @ts-expect-error In Babel?
+      node.arguments.some(nde => {
         return hasNonFunctionYield(nde, checkYieldReturnValue);
       });
     case 'SpreadElement':
@@ -836,12 +898,14 @@ const hasNonFunctionYield = (node, checkYieldReturnValue) => {
     case 'TaggedTemplateExpression':
       return hasNonFunctionYield(node.quasi, checkYieldReturnValue);
 
+    // @ts-expect-error In Babel?
     // ?.
     // istanbul ignore next -- In Babel?
     case 'OptionalMemberExpression':
     case 'MemberExpression':
       return hasNonFunctionYield(node.object, checkYieldReturnValue) || hasNonFunctionYield(node.property, checkYieldReturnValue);
 
+    // @ts-expect-error In Babel?
     // istanbul ignore next -- In Babel?
     case 'Import':
     case 'ImportExpression':
@@ -856,7 +920,7 @@ const hasNonFunctionYield = (node, checkYieldReturnValue) => {
     case 'YieldExpression':
       {
         if (checkYieldReturnValue) {
-          if (node.parent.type === 'VariableDeclarator') {
+          if ( /** @type {import('eslint').Rule.Node} */node.parent.type === 'VariableDeclarator') {
             return true;
           }
           return false;
@@ -877,19 +941,19 @@ const hasNonFunctionYield = (node, checkYieldReturnValue) => {
 
 /**
  * Checks if a node has a return statement. Void return does not count.
- *
  * @param {ESTreeOrTypeScriptNode} node
  * @param {boolean} [checkYieldReturnValue]
  * @returns {boolean}
  */
 const hasYieldValue = (node, checkYieldReturnValue) => {
-  return node.generator && (node.expression || hasNonFunctionYield(node.body, checkYieldReturnValue));
+  return (/** @type {import('@typescript-eslint/types').TSESTree.FunctionDeclaration} */node.generator && ( /** @type {import('@typescript-eslint/types').TSESTree.FunctionDeclaration} */node.expression || hasNonFunctionYield( /** @type {import('@typescript-eslint/types').TSESTree.FunctionDeclaration} */
+    node.body, checkYieldReturnValue))
+  );
 };
 
 /**
  * Checks if a node has a throws statement.
- *
- * @param {ESTreeOrTypeScriptNode} node
+ * @param {ESTreeOrTypeScriptNode|null|undefined} node
  * @param {boolean} [innerFunction]
  * @returns {boolean}
  */
@@ -965,9 +1029,8 @@ const isInlineTag = (tag) => {
 
 /**
  * Parses GCC Generic/Template types
- *
- * @see {https://github.com/google/closure-compiler/wiki/Generic-Types}
- * @see {https://www.typescriptlang.org/docs/handbook/jsdoc-supported-types.html#template}
+ * @see {@link https://github.com/google/closure-compiler/wiki/Generic-Types}
+ * @see {@link https://www.typescriptlang.org/docs/handbook/jsdoc-supported-types.html#template}
  * @param {import('comment-parser').Spec} tag
  * @returns {string[]}
  */
@@ -983,12 +1046,13 @@ const parseClosureTemplateTag = tag => {
 
 /**
  * Checks user option for `contexts` array, defaulting to
- *   contexts designated by the rule. Returns an array of
- *   ESTree AST types, indicating allowable contexts.
- *
+ * contexts designated by the rule. Returns an array of
+ * ESTree AST types, indicating allowable contexts.
  * @param {import('eslint').Rule.RuleContext} context
- * @param {DefaultContexts} defaultContexts
- * @param settings
+ * @param {DefaultContexts|undefined} defaultContexts
+ * @param {{
+ *   contexts?: import('./iterateJsdoc.js').Context[]
+ * }} settings
  * @returns {string[]}
  */
 const enforcedContexts = (context, defaultContexts, settings) => {
@@ -998,14 +1062,19 @@ const enforcedContexts = (context, defaultContexts, settings) => {
 };
 
 /**
- * @param {string[]} contexts
- * @param {Function} checkJsdoc
- * @param {Function} handler
+ * @param {import('./iterateJsdoc.js').Context[]} contexts
+ * @param {import('./iterateJsdoc.js').CheckJsdoc} checkJsdoc
+ * @param {import('@es-joy/jsdoccomment').CommentHandler} [handler]
+ * @returns {import('eslint').Rule.RuleListener}
  */
 const getContextObject = (contexts, checkJsdoc, handler) => {
+  /** @type {import('eslint').Rule.RuleListener} */
   const properties = {};
   for (const [idx, prop] of contexts.entries()) {
+    /** @type {string} */
     let property;
+
+    /** @type {(node: import('eslint').Rule.Node) => void} */
     let value;
     if (typeof prop === 'object') {
       const selInfo = {
@@ -1013,13 +1082,18 @@ const getContextObject = (contexts, checkJsdoc, handler) => {
         selector: prop.context
       };
       if (prop.comment) {
-        property = prop.context;
+        property = /** @type {string} */prop.context;
         value = checkJsdoc.bind(null, {
           ...selInfo,
           comment: prop.comment
-        }, handler.bind(null, prop.comment));
+        },
+        /**
+         * @type {(jsdoc: import('@es-joy/jsdoccomment').JsdocBlockWithInline) => boolean}
+         */
+        /** @type {import('@es-joy/jsdoccomment').CommentHandler} */
+        handler.bind(null, prop.comment));
       } else {
-        property = prop.context;
+        property = /** @type {string} */prop.context;
         value = checkJsdoc.bind(null, selInfo, null);
       }
     } else {
@@ -1030,27 +1104,29 @@ const getContextObject = (contexts, checkJsdoc, handler) => {
       property = prop;
       value = checkJsdoc.bind(null, selInfo, null);
     }
-    const old = properties[property];
-    properties[property] = old ? function (...args) {
-      old(...args);
-      value(...args);
+    const old =
+    /**
+     * @type {((node: import('eslint').Rule.Node) => void)}
+     */
+    properties[property];
+    properties[property] = old ?
+    /**
+     * @type {((node: import('eslint').Rule.Node) => void)}
+     */
+    function (node) {
+      old(node);
+      value(node);
     } : value;
   }
   return properties;
 };
-const filterTags = (tags, filter) => {
-  return tags.filter(tag => {
-    return filter(tag);
-  });
-};
 const tagsWithNamesAndDescriptions = new Set(['param', 'arg', 'argument', 'property', 'prop', 'template',
 // These two are parsed by our custom parser as though having a `name`
 'returns', 'return']);
 
-/* eslint-disable jsdoc/valid-types -- Old version */
 /**
  * @typedef {{
- *   [key: string]: false|
+ *   [key: string]: false|string|
  *     {message: string, replacement?: string}
  * }} TagNamePreference
  */
@@ -1058,7 +1134,7 @@ const tagsWithNamesAndDescriptions = new Set(['param', 'arg', 'argument', 'prope
 
 /**
  * @param {import('eslint').Rule.RuleContext} context
- * @param {ParserMode} mode
+ * @param {ParserMode|undefined} mode
  * @param {import('comment-parser').Spec[]} tags
  * @param {TagNamePreference} tagPreference
  * @returns {{
@@ -1072,7 +1148,7 @@ const getTagsByType = (context, mode, tags, tagPreference) => {
    * @type {import('comment-parser').Spec[]}
    */
   const tagsWithoutNames = [];
-  const tagsWithNames = filterTags(tags, tag => {
+  const tagsWithNames = tags.filter(tag => {
     const {
       tag: tagName
     } = tag;
@@ -1089,7 +1165,9 @@ const getTagsByType = (context, mode, tags, tagPreference) => {
 };
 
 /**
- * @param {import('eslint').SourceCode} sourceCode
+ * @param {import('eslint').SourceCode|{
+ *   text: string
+ * }} sourceCode
  * @returns {string}
  */
 const getIndent = sourceCode => {
@@ -1098,64 +1176,87 @@ const getIndent = sourceCode => {
 };
 
 /**
- * @param {ESTreeOrTypeScriptNode} node
+ * @param {import('eslint').Rule.Node|null} node
  * @returns {boolean}
  */
 const isConstructor = node => {
   var _node$parent;
-  return (node === null || node === void 0 ? void 0 : node.type) === 'MethodDefinition' && node.kind === 'constructor' || (node === null || node === void 0 ? void 0 : (_node$parent = node.parent) === null || _node$parent === void 0 ? void 0 : _node$parent.kind) === 'constructor';
+  return (node === null || node === void 0 ? void 0 : node.type) === 'MethodDefinition' && node.kind === 'constructor' || /** @type {import('@typescript-eslint/types').TSESTree.MethodDefinition} */(node === null || node === void 0 ? void 0 : (_node$parent = node.parent) === null || _node$parent === void 0 ? void 0 : _node$parent.kind) === 'constructor';
 };
 
 /**
- * @param {ESTreeOrTypeScriptNode} node
+ * @param {import('eslint').Rule.Node|null} node
  * @returns {boolean}
  */
 const isGetter = node => {
   var _node$parent2;
-  return node && ((_node$parent2 = node.parent) === null || _node$parent2 === void 0 ? void 0 : _node$parent2.kind) === 'get';
+  return node !== null &&
+  /**
+   * @type {import('@typescript-eslint/types').TSESTree.MethodDefinition|
+   *   import('@typescript-eslint/types').TSESTree.Property}
+   */
+  ((_node$parent2 = node.parent) === null || _node$parent2 === void 0 ? void 0 : _node$parent2.kind) === 'get';
 };
 
 /**
- * @param {ESTreeOrTypeScriptNode} node
+ * @param {import('eslint').Rule.Node|null} node
  * @returns {boolean}
  */
 const isSetter = node => {
   var _node$parent3;
-  return node && ((_node$parent3 = node.parent) === null || _node$parent3 === void 0 ? void 0 : _node$parent3.kind) === 'set';
+  return node !== null &&
+  /**
+   * @type {import('@typescript-eslint/types').TSESTree.MethodDefinition|
+   *   import('@typescript-eslint/types').TSESTree.Property}
+   */
+  ((_node$parent3 = node.parent) === null || _node$parent3 === void 0 ? void 0 : _node$parent3.kind) === 'set';
 };
 
 /**
- * @param {ESTreeOrTypeScriptNode} node
+ * @param {import('eslint').Rule.Node} node
  * @returns {boolean}
  */
 const hasAccessorPair = node => {
   const {
     type,
     kind: sourceKind,
-    key: {
-      name: sourceName
-    }
-  } = node;
+    key
+  } =
+  /**
+   * @type {import('@typescript-eslint/types').TSESTree.MethodDefinition|
+   *   import('@typescript-eslint/types').TSESTree.Property}
+   */
+  node;
+  const sourceName = /** @type {import('@typescript-eslint/types').TSESTree.Identifier} */key.name;
   const oppositeKind = sourceKind === 'get' ? 'set' : 'get';
-  const children = type === 'MethodDefinition' ? 'body' : 'properties';
-  return node.parent[children].some(({
-    kind,
-    key: {
-      name
-    }
-  }) => {
+  const sibling = type === 'MethodDefinition' ? /** @type {import('@typescript-eslint/types').TSESTree.ClassBody} */node.parent.body : /** @type {import('@typescript-eslint/types').TSESTree.ObjectExpression} */node.parent.properties;
+  return sibling.some(child => {
+    const {
+      kind,
+      key: ky
+    } =
+    /**
+     * @type {import('@typescript-eslint/types').TSESTree.MethodDefinition|
+     *   import('@typescript-eslint/types').TSESTree.Property}
+     */
+    child;
+    const name = /** @type {import('@typescript-eslint/types').TSESTree.Identifier} */ky.name;
     return kind === oppositeKind && name === sourceName;
   });
 };
 
 /**
- * @param {import('comment-parser').Block} jsdoc
- * @param {ESTreeOrTypeScriptNode} node
+ * @param {import('./iterateJsdoc.js').JsdocBlockWithInline} jsdoc
+ * @param {import('eslint').Rule.Node|null} node
  * @param {import('eslint').Rule.RuleContext} context
- * @param {} schema
+ * @param {import('json-schema').JSONSchema4} schema
  * @returns {boolean}
  */
 const exemptSpeciaMethods = (jsdoc, node, context, schema) => {
+  /**
+   * @param {"checkGetters"|"checkSetters"|"checkConstructors"} prop
+   * @returns {boolean|"no-setter"|"no-getter"}
+   */
   const hasSchemaOption = prop => {
     var _context$options$2;
     const schemaProperties = schema[0].properties;
@@ -1163,7 +1264,7 @@ const exemptSpeciaMethods = (jsdoc, node, context, schema) => {
   };
   const checkGetters = hasSchemaOption('checkGetters');
   const checkSetters = hasSchemaOption('checkSetters');
-  return !hasSchemaOption('checkConstructors') && (isConstructor(node) || hasATag(jsdoc, ['class', 'constructor'])) || isGetter(node) && (!checkGetters || checkGetters === 'no-setter' && hasAccessorPair(node.parent)) || isSetter(node) && (!checkSetters || checkSetters === 'no-getter' && hasAccessorPair(node.parent));
+  return !hasSchemaOption('checkConstructors') && (isConstructor(node) || hasATag(jsdoc, ['class', 'constructor'])) || isGetter(node) && (!checkGetters || checkGetters === 'no-setter' && hasAccessorPair( /** @type {import('./iterateJsdoc.js').Node} */node.parent)) || isSetter(node) && (!checkSetters || checkSetters === 'no-getter' && hasAccessorPair( /** @type {import('./iterateJsdoc.js').Node} */node.parent));
 };
 
 /**
@@ -1171,17 +1272,16 @@ const exemptSpeciaMethods = (jsdoc, node, context, schema) => {
  * identifier or numeric literal) or single or double quoted, in either
  * the `@param` or in source, we need to strip the quotes to give a fair
  * comparison.
- *
  * @param {string} str
  * @returns {string}
  */
 const dropPathSegmentQuotes = str => {
-  return str.replace(/\.(['"])(.*)\1/gu, '.$2');
+  return str.replaceAll(/\.(['"])(.*)\1/gu, '.$2');
 };
 
 /**
  * @param {string} name
- * @returns {(otherPathName: string) => void}
+ * @returns {(otherPathName: string) => boolean}
  */
 const comparePaths = name => {
   return otherPathName => {
@@ -1190,17 +1290,20 @@ const comparePaths = name => {
 };
 
 /**
+ * @callback PathDoesNotBeginWith
  * @param {string} name
  * @param {string} otherPathName
  * @returns {boolean}
  */
+
+/** @type {PathDoesNotBeginWith} */
 const pathDoesNotBeginWith = (name, otherPathName) => {
   return !name.startsWith(otherPathName) && !dropPathSegmentQuotes(name).startsWith(dropPathSegmentQuotes(otherPathName));
 };
 
 /**
  * @param {string} regexString
- * @param {string} requiredFlags
+ * @param {string} [requiredFlags]
  * @returns {RegExp}
  */
 const getRegexFromString = (regexString, requiredFlags) => {
@@ -1222,7 +1325,6 @@ var _default = {
   dropPathSegmentQuotes,
   enforcedContexts,
   exemptSpeciaMethods,
-  filterTags,
   flattenRoots,
   getAllTags,
   getContextObject,