eslint-plugin-jsdoc 52.0.1 → 52.0.3

package/dist/iterateJsdoc.js

@@ -0,0 +1,1617 @@
+import { hasValueOrExecutorHasNonEmptyResolveValue } from "./utils/hasReturnValue.js";
+import { comparePaths, dropPathSegmentQuotes, enforcedContexts, exemptSpeciaMethods, filterTags, flattenRoots, forEachPreferredTag, getAllTags, getContextObject, getFunctionParameterNames, getJsdocTagsDeep, getPreferredTagName, getPreferredTagNameSimple, getRegexFromString, getTagDescription, getTagStructureForMode, getTags, getTagsByType, hasATag, hasParams, hasTag, hasThrowValue, hasYieldValue, isConstructor, isValidTag, jsdocUtils_exports, mayBeUndefinedTypeTag, overrideTagStructure, parseClosureTemplateTag, pathDoesNotBeginWith, setTagStructure, tagMissingRequiredTypeOrNamepath } from "./jsdocUtils.js";
+import { commentHandler, getJSDocComment, parseComment, parseComment as parseComment$1 } from "@es-joy/jsdoccomment";
+import { stringify as stringify$1, util } from "comment-parser";
+import esquery from "esquery";
+
+//#region src/iterateJsdoc.js
+/**
+* @typedef {number} Integer
+*/
+/**
+* @typedef {import('@es-joy/jsdoccomment').JsdocBlockWithInline} JsdocBlockWithInline
+*/
+/**
+* @typedef {{
+*   disallowName?: string,
+*   allowName?: string,
+*   context?: string,
+*   comment?: string,
+*   tags?: string[],
+*   replacement?: string,
+*   minimum?: Integer,
+*   message?: string,
+*   forceRequireReturn?: boolean
+* }} ContextObject
+*/
+/**
+* @typedef {string|ContextObject} Context
+*/
+/**
+* @callback CheckJsdoc
+* @param {{
+*   lastIndex?: Integer,
+*   isFunctionContext?: boolean,
+*   selector?: string,
+*   comment?: string
+* }} info
+* @param {null|((jsdoc: import('@es-joy/jsdoccomment').JsdocBlockWithInline) => boolean|undefined)} handler
+* @param {import('eslint').Rule.Node} node
+* @returns {void}
+*/
+/**
+* @callback ForEachPreferredTag
+* @param {string} tagName
+* @param {(
+*   matchingJsdocTag: import('@es-joy/jsdoccomment').JsdocTagWithInline,
+*   targetTagName: string
+* ) => void} arrayHandler
+* @param {boolean} [skipReportingBlockedTag]
+* @returns {void}
+*/
+/**
+* @callback ReportSettings
+* @param {string} message
+* @returns {void}
+*/
+/**
+* @callback ParseClosureTemplateTag
+* @param {import('comment-parser').Spec} tag
+* @returns {string[]}
+*/
+/**
+* @callback GetPreferredTagNameObject
+* @param {{
+*   tagName: string
+* }} cfg
+* @returns {string|false|{
+*   message: string;
+*   replacement?: string|undefined
+* }|{
+*   blocked: true,
+*   tagName: string
+* }}
+*/
+/**
+* @typedef {{
+*   forEachPreferredTag: ForEachPreferredTag,
+*   reportSettings: ReportSettings,
+*   parseClosureTemplateTag: ParseClosureTemplateTag,
+*   getPreferredTagNameObject: GetPreferredTagNameObject,
+*   pathDoesNotBeginWith: import('./jsdocUtils.js').PathDoesNotBeginWith
+* }} BasicUtils
+*/
+/**
+* @callback IsIteratingFunction
+* @returns {boolean}
+*/
+/**
+* @callback IsVirtualFunction
+* @returns {boolean}
+*/
+/**
+* @callback Stringify
+* @param {import('comment-parser').Block} tagBlock
+* @param {boolean} [specRewire]
+* @returns {string}
+*/
+/**
+* @callback ReportJSDoc
+* @param {string} msg
+* @param {null|import('comment-parser').Spec|{line: Integer, column?: Integer}} [tag]
+* @param {(() => void)|null} [handler]
+* @param {boolean} [specRewire]
+* @param {undefined|{
+*   [key: string]: string
+* }} [data]
+*/
+/**
+* @callback GetRegexFromString
+* @param {string} str
+* @param {string} [requiredFlags]
+* @returns {RegExp}
+*/
+/**
+* @callback GetTagDescription
+* @param {import('comment-parser').Spec} tg
+* @param {boolean} [returnArray]
+* @returns {string[]|string}
+*/
+/**
+* @callback SetTagDescription
+* @param {import('comment-parser').Spec} tg
+* @param {RegExp} matcher
+* @param {(description: string) => string} setter
+* @returns {Integer}
+*/
+/**
+* @callback GetDescription
+* @returns {{
+*   description: string,
+*   descriptions: string[],
+*   lastDescriptionLine: Integer
+* }}
+*/
+/**
+* @callback SetBlockDescription
+* @param {(
+*   info: {
+*     delimiter: string,
+*     postDelimiter: string,
+*     start: string
+*   },
+*   seedTokens: (
+*     tokens?: Partial<import('comment-parser').Tokens>
+*   ) => import('comment-parser').Tokens,
+*   descLines: string[]
+* ) => import('comment-parser').Line[]} setter
+* @returns {void}
+*/
+/**
+* @callback SetDescriptionLines
+* @param {RegExp} matcher
+* @param {(description: string) => string} setter
+* @returns {Integer}
+*/
+/**
+* @callback ChangeTag
+* @param {import('comment-parser').Spec} tag
+* @param {...Partial<import('comment-parser').Tokens>} tokens
+* @returns {void}
+*/
+/**
+* @callback SetTag
+* @param {import('comment-parser').Spec & {
+*   line: Integer
+* }} tag
+* @param {Partial<import('comment-parser').Tokens>} [tokens]
+* @returns {void}
+*/
+/**
+* @callback RemoveTag
+* @param {Integer} tagIndex
+* @param {{
+*   removeEmptyBlock?: boolean,
+*   tagSourceOffset?: Integer
+* }} [cfg]
+* @returns {void}
+*/
+/**
+* @callback AddTag
+* @param {string} targetTagName
+* @param {Integer} [number]
+* @param {import('comment-parser').Tokens|{}} [tokens]
+* @returns {void}
+*/
+/**
+* @callback GetFirstLine
+* @returns {Integer|undefined}
+*/
+/**
+* @typedef {(
+*   tokens?: Partial<import('comment-parser').Tokens> | undefined
+* ) => import('comment-parser').Tokens} SeedTokens
+*/
+/**
+* Sets tokens to empty string.
+* @callback EmptyTokens
+* @param {import('comment-parser').Tokens} tokens
+* @returns {void}
+*/
+/**
+* @callback AddLine
+* @param {Integer} sourceIndex
+* @param {Partial<import('comment-parser').Tokens>} tokens
+* @returns {void}
+*/
+/**
+* @callback AddLines
+* @param {Integer} tagIndex
+* @param {Integer} tagSourceOffset
+* @param {Integer} numLines
+* @returns {void}
+*/
+/**
+* @callback MakeMultiline
+* @returns {void}
+*/
+/**
+* @callback GetFunctionParameterNames
+* @param {boolean} [useDefaultObjectProperties]
+* @returns {import('./jsdocUtils.js').ParamNameInfo[]}
+*/
+/**
+* @callback HasParams
+* @returns {Integer}
+*/
+/**
+* @callback IsGenerator
+* @returns {boolean}
+*/
+/**
+* @callback IsConstructor
+* @returns {boolean}
+*/
+/**
+* @callback GetJsdocTagsDeep
+* @param {string} tagName
+* @returns {false|{
+*   idx: Integer,
+*   name: string,
+*   type: string
+* }[]}
+*/
+/**
+* @callback GetPreferredTagName
+* @param {{
+*   tagName: string,
+*   skipReportingBlockedTag?: boolean,
+*   allowObjectReturn?: boolean,
+*   defaultMessage?: string
+* }} cfg
+* @returns {string|undefined|false|{
+*   message: string;
+*   replacement?: string|undefined;
+* }|{
+*   blocked: true,
+*   tagName: string
+* }}
+*/
+/**
+* @callback IsValidTag
+* @param {string} name
+* @param {string[]} definedTags
+* @returns {boolean}
+*/
+/**
+* @callback HasATag
+* @param {string[]} names
+* @returns {boolean}
+*/
+/**
+* @callback HasTag
+* @param {string} name
+* @returns {boolean}
+*/
+/**
+* @callback ComparePaths
+* @param {string} name
+* @returns {(otherPathName: string) => boolean}
+*/
+/**
+* @callback DropPathSegmentQuotes
+* @param {string} name
+* @returns {string}
+*/
+/**
+* @callback AvoidDocs
+* @returns {boolean}
+*/
+/**
+* @callback TagMightHaveNamePositionTypePosition
+* @param {string} tagName
+* @param {import('./getDefaultTagStructureForMode.js').
+*   TagStructure[]} [otherModeMaps]
+* @returns {boolean|{otherMode: true}}
+*/
+/**
+* @callback TagMustHave
+* @param {string} tagName
+* @param {import('./getDefaultTagStructureForMode.js').
+*   TagStructure[]} otherModeMaps
+* @returns {boolean|{
+*   otherMode: false
+* }}
+*/
+/**
+* @callback TagMissingRequiredTypeOrNamepath
+* @param {import('comment-parser').Spec} tag
+* @param {import('./getDefaultTagStructureForMode.js').
+*   TagStructure[]} otherModeMaps
+* @returns {boolean|{
+*   otherMode: false
+* }}
+*/
+/**
+* @callback IsNamepathX
+* @param {string} tagName
+* @returns {boolean}
+*/
+/**
+* @callback GetTagStructureForMode
+* @param {import('./jsdocUtils.js').ParserMode} mde
+* @returns {import('./getDefaultTagStructureForMode.js').TagStructure}
+*/
+/**
+* @callback MayBeUndefinedTypeTag
+* @param {import('comment-parser').Spec} tag
+* @returns {boolean}
+*/
+/**
+* @callback HasValueOrExecutorHasNonEmptyResolveValue
+* @param {boolean} anyPromiseAsReturn
+* @param {boolean} [allBranches]
+* @returns {boolean}
+*/
+/**
+* @callback HasYieldValue
+* @returns {boolean}
+*/
+/**
+* @callback HasYieldReturnValue
+* @returns {boolean}
+*/
+/**
+* @callback HasThrowValue
+* @returns {boolean}
+*/
+/**
+* @callback IsAsync
+* @returns {boolean|undefined}
+*/
+/**
+* @callback GetTags
+* @param {string} tagName
+* @returns {import('comment-parser').Spec[]}
+*/
+/**
+* @callback GetPresentTags
+* @param {string[]} tagList
+* @returns {import('@es-joy/jsdoccomment').JsdocTagWithInline[]}
+*/
+/**
+* @callback FilterTags
+* @param {(tag: import('@es-joy/jsdoccomment').JsdocTagWithInline) => boolean} filter
+* @returns {import('@es-joy/jsdoccomment').JsdocTagWithInline[]}
+*/
+/**
+* @callback FilterAllTags
+* @param {(tag: (import('comment-parser').Spec|
+*   import('@es-joy/jsdoccomment').JsdocInlineTagNoType)) => boolean} filter
+* @returns {(import('comment-parser').Spec|
+*   import('@es-joy/jsdoccomment').JsdocInlineTagNoType)[]}
+*/
+/**
+* @callback GetTagsByType
+* @param {import('comment-parser').Spec[]} tags
+* @returns {{
+*   tagsWithNames: import('comment-parser').Spec[],
+*   tagsWithoutNames: import('comment-parser').Spec[]
+* }}
+*/
+/**
+* @callback HasOptionTag
+* @param {string} tagName
+* @returns {boolean}
+*/
+/**
+* @callback GetClassNode
+* @returns {Node|null}
+*/
+/**
+* @callback GetClassJsdoc
+* @returns {null|JsdocBlockWithInline}
+*/
+/**
+* @callback ClassHasTag
+* @param {string} tagName
+* @returns {boolean}
+*/
+/**
+* @callback FindContext
+* @param {Context[]} contexts
+* @param {string|undefined} comment
+* @returns {{
+*   foundContext: Context|undefined,
+*   contextStr: string
+* }}
+*/
+/**
+* @typedef {BasicUtils & {
+*   isIteratingFunction: IsIteratingFunction,
+*   isVirtualFunction: IsVirtualFunction,
+*   stringify: Stringify,
+*   reportJSDoc: ReportJSDoc,
+*   getRegexFromString: GetRegexFromString,
+*   getTagDescription: GetTagDescription,
+*   setTagDescription: SetTagDescription,
+*   getDescription: GetDescription,
+*   setBlockDescription: SetBlockDescription,
+*   setDescriptionLines: SetDescriptionLines,
+*   changeTag: ChangeTag,
+*   setTag: SetTag,
+*   removeTag: RemoveTag,
+*   addTag: AddTag,
+*   getFirstLine: GetFirstLine,
+*   seedTokens: SeedTokens,
+*   emptyTokens: EmptyTokens,
+*   addLine: AddLine,
+*   addLines: AddLines,
+*   makeMultiline: MakeMultiline,
+*   flattenRoots: import('./jsdocUtils.js').FlattenRoots,
+*   getFunctionParameterNames: GetFunctionParameterNames,
+*   hasParams: HasParams,
+*   isGenerator: IsGenerator,
+*   isConstructor: IsConstructor,
+*   getJsdocTagsDeep: GetJsdocTagsDeep,
+*   getPreferredTagName: GetPreferredTagName,
+*   isValidTag: IsValidTag,
+*   hasATag: HasATag,
+*   hasTag: HasTag,
+*   comparePaths: ComparePaths,
+*   dropPathSegmentQuotes: DropPathSegmentQuotes,
+*   avoidDocs: AvoidDocs,
+*   tagMightHaveNamePosition: TagMightHaveNamePositionTypePosition,
+*   tagMightHaveTypePosition: TagMightHaveNamePositionTypePosition,
+*   tagMustHaveNamePosition: TagMustHave,
+*   tagMustHaveTypePosition: TagMustHave,
+*   tagMissingRequiredTypeOrNamepath: TagMissingRequiredTypeOrNamepath,
+*   isNamepathDefiningTag: IsNamepathX,
+*   isNamepathReferencingTag: IsNamepathX,
+*   isNamepathOrUrlReferencingTag: IsNamepathX,
+*   tagMightHaveNamepath: IsNamepathX,
+*   getTagStructureForMode: GetTagStructureForMode,
+*   mayBeUndefinedTypeTag: MayBeUndefinedTypeTag,
+*   hasValueOrExecutorHasNonEmptyResolveValue: HasValueOrExecutorHasNonEmptyResolveValue,
+*   hasYieldValue: HasYieldValue,
+*   hasYieldReturnValue: HasYieldReturnValue,
+*   hasThrowValue: HasThrowValue,
+*   isAsync: IsAsync,
+*   getTags: GetTags,
+*   getPresentTags: GetPresentTags,
+*   filterTags: FilterTags,
+*   filterAllTags: FilterAllTags,
+*   getTagsByType: GetTagsByType,
+*   hasOptionTag: HasOptionTag,
+*   getClassNode: GetClassNode,
+*   getClassJsdoc: GetClassJsdoc,
+*   classHasTag: ClassHasTag,
+*   findContext: FindContext
+* }} Utils
+*/
+const { rewireSpecs, seedTokens } = util;
+/**
+* Should use ESLint rule's typing.
+* @typedef {import('eslint').Rule.RuleMetaData} EslintRuleMeta
+*/
+/**
+* A plain object for tracking state as needed by rules across iterations.
+* @typedef {{
+*   globalTags: {},
+*   hasDuplicates: {
+*     [key: string]: boolean
+*   },
+*   selectorMap: {
+*     [selector: string]: {
+*       [comment: string]: Integer
+*     }
+*   },
+*   hasTag: {
+*     [key: string]: boolean
+*   },
+*   hasNonComment: number,
+*   hasNonCommentBeforeTag: {
+*     [key: string]: boolean|number
+*   }
+* }} StateObject
+*/
+/**
+* The Node AST as supplied by the parser.
+* @typedef {import('eslint').Rule.Node} Node
+*/
+const globalState = /* @__PURE__ */ new Map();
+/**
+* @param {import('eslint').Rule.RuleContext} context
+* @param {{
+*   tagNamePreference?: import('./jsdocUtils.js').TagNamePreference,
+*   mode?: import('./jsdocUtils.js').ParserMode
+* }} cfg
+* @returns {BasicUtils}
+*/
+const getBasicUtils = (context, { mode, tagNamePreference }) => {
+	/** @type {BasicUtils} */
+	const utils = {};
+	/** @type {ReportSettings} */
+	utils.reportSettings = (message) => {
+		context.report({
+			loc: {
+				end: {
+					column: 1,
+					line: 1
+				},
+				start: {
+					column: 1,
+					line: 1
+				}
+			},
+			message
+		});
+	};
+	/** @type {ParseClosureTemplateTag} */
+	utils.parseClosureTemplateTag = (tag) => {
+		return parseClosureTemplateTag(tag);
+	};
+	utils.pathDoesNotBeginWith = pathDoesNotBeginWith;
+	/** @type {GetPreferredTagNameObject} */
+	utils.getPreferredTagNameObject = ({ tagName }) => {
+		const ret = getPreferredTagNameSimple(tagName, mode, tagNamePreference, context);
+		const isObject = ret && typeof ret === "object";
+		if (ret === false || isObject && !ret.replacement) return {
+			blocked: true,
+			tagName
+		};
+		return ret;
+	};
+	return utils;
+};
+/**
+* @callback Report
+* @param {string} message
+* @param {import('eslint').Rule.ReportFixer|null} [fix]
+* @param {null|
+*   {line?: Integer, column?: Integer}|
+*   import('comment-parser').Spec & {line?: Integer}
+* } [jsdocLoc]
+* @param {undefined|{
+*   [key: string]: string
+* }} [data]
+* @returns {void}
+*/
+/**
+* @param {Node|null} node
+* @param {JsdocBlockWithInline} jsdoc
+* @param {import('eslint').AST.Token} jsdocNode
+* @param {Settings} settings
+* @param {Report} report
+* @param {import('eslint').Rule.RuleContext} context
+* @param {import('eslint').SourceCode} sc
+* @param {boolean|undefined} iteratingAll
+* @param {RuleConfig} ruleConfig
+* @param {string} indent
+* @returns {Utils}
+*/
+const getUtils = (node, jsdoc, jsdocNode, settings, report, context, sc, iteratingAll, ruleConfig, indent) => {
+	const ancestors = node ? sc.getAncestors ? sc.getAncestors(node) : context.getAncestors() : [];
+	/* c8 ignore next -- Fallback to deprecated method */
+	const { sourceCode = context.getSourceCode() } = context;
+	const utils = getBasicUtils(context, settings);
+	const { augmentsExtendsReplacesDocs, ignoreReplacesDocs, implementsReplacesDocs, maxLines, minLines, mode, overrideReplacesDocs, tagNamePreference } = settings;
+	/** @type {IsIteratingFunction} */
+	utils.isIteratingFunction = () => {
+		return !iteratingAll || [
+			"ArrowFunctionExpression",
+			"FunctionDeclaration",
+			"FunctionExpression",
+			"MethodDefinition"
+		].includes(String(node && node.type));
+	};
+	/** @type {IsVirtualFunction} */
+	utils.isVirtualFunction = () => {
+		return Boolean(iteratingAll) && utils.hasATag([
+			"callback",
+			"function",
+			"func",
+			"method"
+		]);
+	};
+	/** @type {Stringify} */
+	utils.stringify = (tagBlock, specRewire) => {
+		let block;
+		if (specRewire) block = rewireSpecs(tagBlock);
+		return stringify$1(specRewire ? block : tagBlock);
+	};
+	/** @type {ReportJSDoc} */
+	utils.reportJSDoc = (msg, tag, handler, specRewire, data) => {
+		report(msg, handler ? (fixer) => {
+			handler();
+			const replacement = utils.stringify(jsdoc, specRewire);
+			if (!replacement) {
+				const text = sourceCode.getText();
+				const lastLineBreakPos = text.slice(0, jsdocNode.range[0]).search(/\n[ \t]*$/v);
+				if (lastLineBreakPos > -1) return fixer.removeRange([lastLineBreakPos, jsdocNode.range[1]]);
+				return fixer.removeRange(/\s/v.test(text.charAt(jsdocNode.range[1])) ? [jsdocNode.range[0], jsdocNode.range[1] + 1] : jsdocNode.range);
+			}
+			return fixer.replaceText(jsdocNode, replacement);
+		} : null, tag, data);
+	};
+	/** @type {GetRegexFromString} */
+	utils.getRegexFromString = (str, requiredFlags) => {
+		return getRegexFromString(str, requiredFlags);
+	};
+	/** @type {GetTagDescription} */
+	utils.getTagDescription = (tg, returnArray) => {
+		return getTagDescription(tg, returnArray);
+	};
+	/** @type {SetTagDescription} */
+	utils.setTagDescription = (tg, matcher, setter) => {
+		let finalIdx = 0;
+		tg.source.some(({ tokens: { description } }, idx) => {
+			if (description && matcher.test(description)) {
+				tg.source[idx].tokens.description = setter(description);
+				finalIdx = idx;
+				return true;
+			}
+			return false;
+		});
+		return finalIdx;
+	};
+	/** @type {GetDescription} */
+	utils.getDescription = () => {
+		/** @type {string[]} */
+		const descriptions = [];
+		let lastDescriptionLine = 0;
+		let tagsBegun = false;
+		jsdoc.source.some(({ tokens: { description, end, tag } }, idx) => {
+			if (tag) tagsBegun = true;
+			if (idx && (tag || end)) {
+				lastDescriptionLine = idx - 1;
+				if (!tagsBegun && description) descriptions.push(description);
+				return true;
+			}
+			if (!tagsBegun && (idx || description)) descriptions.push(description || (descriptions.length ? "" : "\n"));
+			return false;
+		});
+		return {
+			description: descriptions.join("\n"),
+			descriptions,
+			lastDescriptionLine
+		};
+	};
+	/** @type {SetBlockDescription} */
+	utils.setBlockDescription = (setter) => {
+		/** @type {string[]} */
+		const descLines = [];
+		/**
+		* @type {undefined|Integer}
+		*/
+		let startIdx;
+		/**
+		* @type {undefined|Integer}
+		*/
+		let endIdx;
+		/**
+		* @type {undefined|{
+		*   delimiter: string,
+		*   postDelimiter: string,
+		*   start: string
+		* }}
+		*/
+		let info;
+		jsdoc.source.some(({ tokens: { delimiter, description, end, postDelimiter, start, tag } }, idx) => {
+			if (delimiter === "/**") return false;
+			if (startIdx === void 0) {
+				startIdx = idx;
+				info = {
+					delimiter,
+					postDelimiter,
+					start
+				};
+			}
+			if (tag || end) {
+				endIdx = idx;
+				return true;
+			}
+			descLines.push(description);
+			return false;
+		});
+		/* c8 ignore else -- Won't be called if missing */
+		if (descLines.length) jsdoc.source.splice(
+			startIdx,
+			/** @type {Integer} */
+			endIdx - startIdx,
+			...setter(info, seedTokens, descLines)
+		);
+	};
+	/** @type {SetDescriptionLines} */
+	utils.setDescriptionLines = (matcher, setter) => {
+		let finalIdx = 0;
+		jsdoc.source.some(({ tokens: { description, end, tag } }, idx) => {
+			/* c8 ignore next 3 -- Already checked */
+			if (idx && (tag || end)) return true;
+			if (description && matcher.test(description)) {
+				jsdoc.source[idx].tokens.description = setter(description);
+				finalIdx = idx;
+				return true;
+			}
+			return false;
+		});
+		return finalIdx;
+	};
+	/** @type {ChangeTag} */
+	utils.changeTag = (tag, ...tokens) => {
+		for (const [idx, src] of tag.source.entries()) src.tokens = {
+			...src.tokens,
+			...tokens[idx]
+		};
+	};
+	/** @type {SetTag} */
+	utils.setTag = (tag, tokens) => {
+		tag.source = [{
+			number: tag.line,
+			source: "",
+			tokens: seedTokens({
+				delimiter: "*",
+				postDelimiter: " ",
+				start: indent + " ",
+				tag: "@" + tag.tag,
+				...tokens
+			})
+		}];
+	};
+	/** @type {RemoveTag} */
+	utils.removeTag = (tagIndex, { removeEmptyBlock = false, tagSourceOffset = 0 } = {}) => {
+		const { source: tagSource } = jsdoc.tags[tagIndex];
+		/** @type {Integer|undefined} */
+		let lastIndex;
+		const firstNumber = jsdoc.source[0].number;
+		tagSource.some(({ number }, tagIdx) => {
+			const sourceIndex = jsdoc.source.findIndex(({ number: srcNumber }) => {
+				return number === srcNumber;
+			});
+			// c8 ignore else
+			if (sourceIndex > -1) {
+				let spliceCount = 1;
+				tagSource.slice(tagIdx + 1).some(({ tokens: { end: ending, tag } }) => {
+					if (!tag && !ending) {
+						spliceCount++;
+						return false;
+					}
+					return true;
+				});
+				const spliceIdx = sourceIndex + tagSourceOffset;
+				const { delimiter, end } = jsdoc.source[spliceIdx].tokens;
+				if (spliceIdx === 0 && jsdoc.tags.length >= 2 || !removeEmptyBlock && (end || delimiter === "/**")) {
+					const { tokens } = jsdoc.source[spliceIdx];
+					for (const item of [
+						"postDelimiter",
+						"tag",
+						"postTag",
+						"type",
+						"postType",
+						"name",
+						"postName",
+						"description"
+					]) tokens[item] = "";
+				} else {
+					jsdoc.source.splice(spliceIdx, spliceCount - tagSourceOffset + (spliceIdx ? 0 : jsdoc.source.length));
+					tagSource.splice(tagIdx + tagSourceOffset, spliceCount - tagSourceOffset + (spliceIdx ? 0 : jsdoc.source.length));
+				}
+				lastIndex = sourceIndex;
+				return true;
+			}
+			/* c8 ignore next 2 */
+			return false;
+		});
+		for (const [idx, src] of jsdoc.source.slice(lastIndex).entries()) src.number = firstNumber + lastIndex + idx;
+	};
+	/** @type {AddTag} */
+	utils.addTag = (targetTagName, number = (jsdoc.tags[jsdoc.tags.length - 1]?.source[0]?.number ?? jsdoc.source.findIndex(({ tokens: { tag } }) => {
+		return tag;
+	}) - 1) + 1, tokens = {}) => {
+		jsdoc.source.splice(number, 0, {
+			number,
+			source: "",
+			tokens: seedTokens({
+				delimiter: "*",
+				postDelimiter: " ",
+				start: indent + " ",
+				tag: `@${targetTagName}`,
+				...tokens
+			})
+		});
+		for (const src of jsdoc.source.slice(number + 1)) src.number++;
+	};
+	/** @type {GetFirstLine} */
+	utils.getFirstLine = () => {
+		let firstLine;
+		for (const { number, tokens: { tag } } of jsdoc.source) if (tag) {
+			firstLine = number;
+			break;
+		}
+		return firstLine;
+	};
+	/** @type {SeedTokens} */
+	utils.seedTokens = seedTokens;
+	/** @type {EmptyTokens} */
+	utils.emptyTokens = (tokens) => {
+		for (const prop of [
+			"start",
+			"postDelimiter",
+			"tag",
+			"type",
+			"postType",
+			"postTag",
+			"name",
+			"postName",
+			"description",
+			"end",
+			"lineEnd"
+		]) tokens[prop] = "";
+	};
+	/** @type {AddLine} */
+	utils.addLine = (sourceIndex, tokens) => {
+		const number = (jsdoc.source[sourceIndex - 1]?.number || 0) + 1;
+		jsdoc.source.splice(sourceIndex, 0, {
+			number,
+			source: "",
+			tokens: seedTokens(tokens)
+		});
+		for (const src of jsdoc.source.slice(number + 1)) src.number++;
+	};
+	/** @type {AddLines} */
+	utils.addLines = (tagIndex, tagSourceOffset, numLines) => {
+		const { source: tagSource } = jsdoc.tags[tagIndex];
+		/** @type {Integer|undefined} */
+		let lastIndex;
+		const firstNumber = jsdoc.source[0].number;
+		tagSource.some(({ number }) => {
+			const makeLine = () => {
+				return {
+					number,
+					source: "",
+					tokens: seedTokens({
+						delimiter: "*",
+						start: indent + " "
+					})
+				};
+			};
+			const makeLines = () => {
+				return Array.from({ length: numLines }, makeLine);
+			};
+			const sourceIndex = jsdoc.source.findIndex(({ number: srcNumber, tokens: { end } }) => {
+				return number === srcNumber && !end;
+			});
+			// c8 ignore else
+			if (sourceIndex > -1) {
+				const lines = makeLines();
+				jsdoc.source.splice(sourceIndex + tagSourceOffset, 0, ...lines);
+				lastIndex = sourceIndex;
+				return true;
+			}
+			/* c8 ignore next 2 */
+			return false;
+		});
+		for (const [idx, src] of jsdoc.source.slice(lastIndex).entries()) src.number = firstNumber + lastIndex + idx;
+	};
+	/** @type {MakeMultiline} */
+	utils.makeMultiline = () => {
+		const { source: [{ tokens }] } = jsdoc;
+		const { description, lineEnd, name, postDelimiter, tag, type } = tokens;
+		let { tokens: { postName, postTag, postType } } = jsdoc.source[0];
+		if (!description) {
+			if (postName) postName = "";
+			else if (postType) postType = "";
+			else if (postTag) postTag = "";
+		}
+		utils.emptyTokens(tokens);
+		utils.addLine(1, {
+			delimiter: "*",
+			description: description.trimEnd(),
+			name,
+			postDelimiter,
+			postName,
+			postTag,
+			postType,
+			start: indent + " ",
+			tag,
+			type
+		});
+		utils.addLine(2, {
+			end: "*/",
+			lineEnd,
+			start: indent + " "
+		});
+	};
+	/**
+	* @type {import('./jsdocUtils.js').FlattenRoots}
+	*/
+	utils.flattenRoots = flattenRoots;
+	/** @type {GetFunctionParameterNames} */
+	utils.getFunctionParameterNames = (useDefaultObjectProperties) => {
+		return getFunctionParameterNames(node, useDefaultObjectProperties);
+	};
+	/** @type {HasParams} */
+	utils.hasParams = () => {
+		return hasParams(node);
+	};
+	/** @type {IsGenerator} */
+	utils.isGenerator = () => {
+		return node !== null && Boolean(
+			/**
+			* @type {import('estree').FunctionDeclaration|
+			*   import('estree').FunctionExpression}
+			*/
+			node.generator || node.type === "MethodDefinition" && node.value.generator || ["ExportDefaultDeclaration", "ExportNamedDeclaration"].includes(node.type) && node.declaration?.generator
+		);
+	};
+	/** @type {IsConstructor} */
+	utils.isConstructor = () => {
+		return isConstructor(node);
+	};
+	/** @type {GetJsdocTagsDeep} */
+	utils.getJsdocTagsDeep = (tagName) => {
+		const name = utils.getPreferredTagName({ tagName });
+		if (!name) return false;
+		return getJsdocTagsDeep(jsdoc, name);
+	};
+	/** @type {GetPreferredTagName} */
+	utils.getPreferredTagName = (args) => {
+		return getPreferredTagName(jsdoc, {
+			...args,
+			context,
+			mode,
+			report,
+			tagNamePreference
+		});
+	};
+	/** @type {IsValidTag} */
+	utils.isValidTag = (name, definedTags) => {
+		return isValidTag(context, mode, name, definedTags);
+	};
+	/** @type {HasATag} */
+	utils.hasATag = (names) => {
+		return hasATag(jsdoc, names);
+	};
+	/** @type {HasTag} */
+	utils.hasTag = (name) => {
+		return hasTag(jsdoc, name);
+	};
+	/** @type {ComparePaths} */
+	utils.comparePaths = (name) => {
+		return comparePaths(name);
+	};
+	/** @type {DropPathSegmentQuotes} */
+	utils.dropPathSegmentQuotes = (name) => {
+		return dropPathSegmentQuotes(name);
+	};
+	/** @type {AvoidDocs} */
+	utils.avoidDocs = () => {
+		if (ignoreReplacesDocs !== false && (utils.hasTag("ignore") || utils.classHasTag("ignore")) || overrideReplacesDocs !== false && (utils.hasTag("override") || utils.classHasTag("override")) || implementsReplacesDocs !== false && (utils.hasTag("implements") || utils.classHasTag("implements")) || augmentsExtendsReplacesDocs && (utils.hasATag(["augments", "extends"]) || utils.classHasTag("augments") || utils.classHasTag("extends"))) return true;
+		if (exemptSpeciaMethods(jsdoc, node, context, ruleConfig.meta.schema)) return true;
+		const exemptedBy = context.options[0]?.exemptedBy ?? ["inheritDoc", ...mode === "closure" ? [] : ["inheritdoc"]];
+		if (exemptedBy.length && utils.getPresentTags(exemptedBy).length) return true;
+		return false;
+	};
+	for (const method of ["tagMightHaveNamePosition", "tagMightHaveTypePosition"])
+ /** @type {TagMightHaveNamePositionTypePosition} */
+	utils[method] = (tagName, otherModeMaps) => {
+		const result = jsdocUtils_exports[method](tagName);
+		if (result) return true;
+		if (!otherModeMaps) return false;
+		const otherResult = otherModeMaps.some((otherModeMap) => {
+			return jsdocUtils_exports[method](tagName, otherModeMap);
+		});
+		return otherResult ? { otherMode: true } : false;
+	};
+	/** @type {TagMissingRequiredTypeOrNamepath} */
+	utils.tagMissingRequiredTypeOrNamepath = (tagName, otherModeMaps) => {
+		const result = tagMissingRequiredTypeOrNamepath(tagName);
+		if (!result) return false;
+		const otherResult = otherModeMaps.every((otherModeMap) => {
+			return tagMissingRequiredTypeOrNamepath(tagName, otherModeMap);
+		});
+		return otherResult ? true : { otherMode: false };
+	};
+	for (const method of ["tagMustHaveNamePosition", "tagMustHaveTypePosition"])
+ /** @type {TagMustHave} */
+	utils[method] = (tagName, otherModeMaps) => {
+		const result = jsdocUtils_exports[method](tagName);
+		if (!result) return false;
+		const otherResult = otherModeMaps.every((otherModeMap) => {
+			return jsdocUtils_exports[method](tagName, otherModeMap);
+		});
+		return otherResult ? true : { otherMode: false };
+	};
+	for (const method of [
+		"isNamepathDefiningTag",
+		"isNamepathReferencingTag",
+		"isNamepathOrUrlReferencingTag",
+		"tagMightHaveNamepath"
+	])
+ /** @type {IsNamepathX} */
+	utils[method] = (tagName) => {
+		return jsdocUtils_exports[method](tagName);
+	};
+	/** @type {GetTagStructureForMode} */
+	utils.getTagStructureForMode = (mde) => {
+		return getTagStructureForMode(mde, settings.structuredTags);
+	};
+	/** @type {MayBeUndefinedTypeTag} */
+	utils.mayBeUndefinedTypeTag = (tag) => {
+		return mayBeUndefinedTypeTag(tag, settings.mode);
+	};
+	/** @type {HasValueOrExecutorHasNonEmptyResolveValue} */
+	utils.hasValueOrExecutorHasNonEmptyResolveValue = (anyPromiseAsReturn, allBranches) => {
+		return hasValueOrExecutorHasNonEmptyResolveValue(node, anyPromiseAsReturn, allBranches);
+	};
+	/** @type {HasYieldValue} */
+	utils.hasYieldValue = () => {
+		if (["ExportDefaultDeclaration", "ExportNamedDeclaration"].includes(
+			/** @type {Node} */
+			node.type
+		)) return hasYieldValue(
+			/** @type {import('estree').ExportNamedDeclaration|import('estree').ExportDefaultDeclaration} */
+			node.declaration
+		);
+		return hasYieldValue(node);
+	};
+	/** @type {HasYieldReturnValue} */
+	utils.hasYieldReturnValue = () => {
+		return hasYieldValue(node, true);
+	};
+	/** @type {HasThrowValue} */
+	utils.hasThrowValue = () => {
+		return hasThrowValue(node);
+	};
+	/** @type {IsAsync} */
+	utils.isAsync = () => {
+		return Boolean(node && "async" in node && node.async);
+	};
+	/** @type {GetTags} */
+	utils.getTags = (tagName) => {
+		return getTags(jsdoc, tagName);
+	};
+	/** @type {GetPresentTags} */
+	utils.getPresentTags = (tagList) => {
+		return filterTags(jsdoc, (tag) => {
+			return tagList.includes(tag.tag);
+		});
+	};
+	/** @type {FilterTags} */
+	utils.filterTags = (filter) => {
+		return filterTags(jsdoc, (tag) => {
+			return filter(tag);
+		});
+	};
+	/** @type {FilterAllTags} */
+	utils.filterAllTags = (filter) => {
+		const tags = getAllTags(jsdoc);
+		return tags.filter((tag) => {
+			return filter(tag);
+		});
+	};
+	/** @type {GetTagsByType} */
+	utils.getTagsByType = (tags) => {
+		return getTagsByType(context, mode, tags);
+	};
+	/** @type {HasOptionTag} */
+	utils.hasOptionTag = (tagName) => {
+		const { tags } = context.options[0] ?? {};
+		return Boolean(tags && tags.includes(tagName));
+	};
+	/** @type {GetClassNode} */
+	utils.getClassNode = () => {
+		return [...ancestors, node].reverse().find((parent) => {
+			return parent && ["ClassDeclaration", "ClassExpression"].includes(parent.type);
+		}) ?? null;
+	};
+	/** @type {GetClassJsdoc} */
+	utils.getClassJsdoc = () => {
+		const classNode = utils.getClassNode();
+		if (!classNode) return null;
+		const classJsdocNode = getJSDocComment(sourceCode, classNode, {
+			maxLines,
+			minLines
+		});
+		if (classJsdocNode) return parseComment$1(classJsdocNode, "");
+		return null;
+	};
+	/** @type {ClassHasTag} */
+	utils.classHasTag = (tagName) => {
+		const classJsdoc = utils.getClassJsdoc();
+		return classJsdoc !== null && hasTag(classJsdoc, tagName);
+	};
+	/** @type {ForEachPreferredTag} */
+	utils.forEachPreferredTag = (tagName, arrayHandler, skipReportingBlockedTag) => {
+		return forEachPreferredTag(jsdoc, tagName, arrayHandler, {
+			context,
+			mode,
+			report,
+			skipReportingBlockedTag,
+			tagNamePreference
+		});
+	};
+	/** @type {FindContext} */
+	utils.findContext = (contexts, comment) => {
+		const foundContext = contexts.find((cntxt) => {
+			return typeof cntxt === "string" ? esquery.matches(node, esquery.parse(cntxt), void 0, { visitorKeys: sourceCode.visitorKeys }) : (!cntxt.context || cntxt.context === "any" || esquery.matches(node, esquery.parse(cntxt.context), void 0, { visitorKeys: sourceCode.visitorKeys })) && comment === cntxt.comment;
+		});
+		const contextStr = typeof foundContext === "object" ? foundContext.context ?? "any" : String(foundContext);
+		return {
+			contextStr,
+			foundContext
+		};
+	};
+	return utils;
+};
+/**
+* @typedef {{
+*   [key: string]: false|string|{
+*     message: string,
+*     replacement?: false|string
+*     skipRootChecking?: boolean
+*   }
+* }} PreferredTypes
+*/
+/**
+* @typedef {{
+*   [key: string]: {
+*     name?: "text"|"namepath-defining"|"namepath-referencing"|false,
+*     type?: boolean|string[],
+*     required?: ("name"|"type"|"typeOrNameRequired")[]
+*   }
+* }} StructuredTags
+*/
+/**
+* Settings from ESLint types.
+* @typedef {{
+*   maxLines: Integer,
+*   minLines: Integer,
+*   tagNamePreference: import('./jsdocUtils.js').TagNamePreference,
+*   mode: import('./jsdocUtils.js').ParserMode,
+*   preferredTypes: PreferredTypes,
+*   structuredTags: StructuredTags,
+*   [name: string]: any,
+*   contexts?: Context[]
+* }} Settings
+*/
+/**
+* @typedef {{
+*   settings?: {
+*     jsdoc?: {
+*       ignorePrivate: boolean,
+*       ignoreInternal: boolean,
+*       maxLines: Integer,
+*       minLines: Integer,
+*       tagNamePreference: import('./jsdocUtils.js').TagNamePreference,
+*       preferredTypes: PreferredTypes,
+*       structuredTags: StructuredTags,
+*       overrideReplacesDocs: boolean,
+*       ignoreReplacesDocs: boolean,
+*       implementsReplacesDocs: boolean,
+*       augmentsExtendsReplacesDocs: boolean,
+*       exemptDestructuredRootsFromChecks: boolean,
+*       mode: import('./jsdocUtils.js').ParserMode,
+*       contexts: Context[],
+*     }
+*   }
+* }} JSDocSettings
+*/
+/**
+* @param {import('eslint').Rule.RuleContext & JSDocSettings} context
+* @returns {Settings|false}
+*/
+const getSettings = (context) => {
+	const settings = {
+		ignorePrivate: Boolean(context.settings.jsdoc?.ignorePrivate),
+		ignoreInternal: Boolean(context.settings.jsdoc?.ignoreInternal),
+		maxLines: Number(context.settings.jsdoc?.maxLines ?? 1),
+		minLines: Number(context.settings.jsdoc?.minLines ?? 0),
+		tagNamePreference: context.settings.jsdoc?.tagNamePreference ?? {},
+		preferredTypes: context.settings.jsdoc?.preferredTypes ?? {},
+		structuredTags: context.settings.jsdoc?.structuredTags ?? {},
+		overrideReplacesDocs: context.settings.jsdoc?.overrideReplacesDocs,
+		ignoreReplacesDocs: context.settings.jsdoc?.ignoreReplacesDocs,
+		implementsReplacesDocs: context.settings.jsdoc?.implementsReplacesDocs,
+		augmentsExtendsReplacesDocs: context.settings.jsdoc?.augmentsExtendsReplacesDocs,
+		exemptDestructuredRootsFromChecks: context.settings.jsdoc?.exemptDestructuredRootsFromChecks,
+		mode: context.settings.jsdoc?.mode ?? "typescript",
+		contexts: context.settings.jsdoc?.contexts
+	};
+	setTagStructure(settings.mode);
+	try {
+		overrideTagStructure(settings.structuredTags);
+	} catch (error) {
+		context.report({
+			loc: {
+				end: {
+					column: 1,
+					line: 1
+				},
+				start: {
+					column: 1,
+					line: 1
+				}
+			},
+			message: error.message
+		});
+		return false;
+	}
+	return settings;
+};
+/**
+* Create the report function
+* @callback MakeReport
+* @param {import('eslint').Rule.RuleContext} context
+* @param {import('estree').Node} commentNode
+* @returns {Report}
+*/
+/** @type {MakeReport} */
+const makeReport = (context, commentNode) => {
+	/** @type {Report} */
+	const report = (message, fix = null, jsdocLoc = null, data = void 0) => {
+		let loc;
+		if (jsdocLoc) {
+			if (!("line" in jsdocLoc)) jsdocLoc.line = jsdocLoc.source[0].number;
+			const lineNumber = commentNode.loc.start.line + jsdocLoc.line;
+			loc = {
+				end: {
+					column: 0,
+					line: lineNumber
+				},
+				start: {
+					column: 0,
+					line: lineNumber
+				}
+			};
+			if ("column" in jsdocLoc && typeof jsdocLoc.column === "number") {
+				const colNumber = commentNode.loc.start.column + jsdocLoc.column;
+				loc.end.column = colNumber;
+				loc.start.column = colNumber;
+			}
+		}
+		context.report({
+			data,
+			fix,
+			loc,
+			message,
+			node: commentNode
+		});
+	};
+	return report;
+};
+/**
+* @typedef {(
+*   arg: {
+*     context: import('eslint').Rule.RuleContext,
+*     sourceCode: import('eslint').SourceCode,
+*     indent?: string,
+*     info?: {
+*       comment?: string|undefined,
+*       lastIndex?: Integer|undefined
+*     },
+*     state?: StateObject,
+*     globalState?: Map<string, Map<string, string>>,
+*     jsdoc?: JsdocBlockWithInline,
+*     jsdocNode?: import('eslint').Rule.Node & {
+*       range: [number, number]
+*     },
+*     node?: Node,
+*     allComments?: import('estree').Node[]
+*     report?: Report,
+*     makeReport?: MakeReport,
+*     settings: Settings,
+*     utils: BasicUtils,
+*   }
+* ) => any } JsdocVisitorBasic
+*/
+/**
+* @typedef {(
+*   arg: {
+*     context: import('eslint').Rule.RuleContext,
+*     sourceCode: import('eslint').SourceCode,
+*     indent: string,
+*     info: {
+*       comment?: string|undefined,
+*       lastIndex?: Integer|undefined
+*     },
+*     state: StateObject,
+*     globalState: Map<string, Map<string, string>>,
+*     jsdoc: JsdocBlockWithInline,
+*     jsdocNode: import('eslint').Rule.Node & {
+*       range: [number, number]
+*     },
+*     node: Node|null,
+*     allComments?: import('estree').Node[]
+*     report: Report,
+*     makeReport?: MakeReport,
+*     settings: Settings,
+*     utils: Utils,
+*   }
+* ) => any } JsdocVisitor
+*/
+/**
+* @param {{
+*   comment?: string,
+*   lastIndex?: Integer,
+*   selector?: string,
+*   isFunctionContext?: boolean,
+* }} info
+* @param {string} indent
+* @param {JsdocBlockWithInline} jsdoc
+* @param {RuleConfig} ruleConfig
+* @param {import('eslint').Rule.RuleContext} context
+* @param {import('@es-joy/jsdoccomment').Token} jsdocNode
+* @param {Node|null} node
+* @param {Settings} settings
+* @param {import('eslint').SourceCode} sourceCode
+* @param {JsdocVisitor} iterator
+* @param {StateObject} state
+* @param {boolean} [iteratingAll]
+* @returns {void}
+*/
+const iterate = (info, indent, jsdoc, ruleConfig, context, jsdocNode, node, settings, sourceCode, iterator, state, iteratingAll) => {
+	const jsdocNde = jsdocNode;
+	const report = makeReport(context, jsdocNde);
+	const utils = getUtils(node, jsdoc, jsdocNode, settings, report, context, sourceCode, iteratingAll, ruleConfig, indent);
+	if (!ruleConfig.checkInternal && settings.ignoreInternal && utils.hasTag("internal")) return;
+	if (!ruleConfig.checkPrivate && settings.ignorePrivate && (utils.hasTag("private") || filterTags(jsdoc, ({ tag }) => {
+		return tag === "access";
+	}).some(({ description }) => {
+		return description === "private";
+	}))) return;
+	iterator({
+		context,
+		globalState,
+		indent,
+		info,
+		jsdoc,
+		jsdocNode: jsdocNde,
+		node,
+		report,
+		settings,
+		sourceCode,
+		state,
+		utils
+	});
+};
+/**
+* @param {string[]} lines
+* @param {import('estree').Comment} jsdocNode
+* @returns {[indent: string, jsdoc: JsdocBlockWithInline]}
+*/
+const getIndentAndJSDoc = function(lines, jsdocNode) {
+	const sourceLine = lines[jsdocNode.loc.start.line - 1];
+	let indentChar = sourceLine.charAt(0);
+	if (indentChar !== " " && indentChar !== "	") indentChar = " ";
+	const indnt = indentChar.repeat(
+		/** @type {import('estree').SourceLocation} */
+		jsdocNode.loc.start.column
+	);
+	const jsdc = parseComment$1(jsdocNode, "");
+	return [indnt, jsdc];
+};
+/**
+*
+* @typedef {{node: Node & {
+*   range: [number, number]
+* }, state: StateObject}} NonCommentArgs
+*/
+/**
+* @typedef {object} RuleConfig
+* @property {EslintRuleMeta} meta ESLint rule meta
+* @property {import('./jsdocUtils.js').DefaultContexts} [contextDefaults] Any default contexts
+* @property {true} [contextSelected] Whether to force a `contexts` check
+* @property {true} [iterateAllJsdocs] Whether to iterate all JSDoc blocks by default
+*   regardless of context
+* @property {true} [checkPrivate] Whether to check `@private` blocks (normally exempted)
+* @property {true} [checkInternal] Whether to check `@internal` blocks (normally exempted)
+* @property {true} [checkFile] Whether to iterates over all JSDoc blocks regardless of attachment
+* @property {true} [nonGlobalSettings] Whether to avoid relying on settings for global contexts
+* @property {true} [noTracking] Whether to disable the tracking of visited comment nodes (as
+*   non-tracked may conduct further actions)
+* @property {true} [matchContext] Whether the rule expects contexts to be based on a match option
+* @property {(args: {
+*   context: import('eslint').Rule.RuleContext,
+*   state: StateObject,
+*   settings: Settings,
+*   utils: BasicUtils
+* }) => void} [exit] Handler to be executed upon exiting iteration of program AST
+* @property {(nca: NonCommentArgs) => void} [nonComment] Handler to be executed if rule wishes
+*   to be supplied nodes without comments
+*/
+/**
+* Create an eslint rule that iterates over all JSDocs, regardless of whether
+* they are attached to a function-like node.
+* @param {JsdocVisitor} iterator
+* @param {RuleConfig} ruleConfig The rule's configuration
+* @param {ContextObject[]|null} [contexts] The `contexts` containing relevant `comment` info.
+* @param {boolean} [additiveCommentContexts] If true, will have a separate
+*   iteration for each matching comment context. Otherwise, will iterate
+*   once if there is a single matching comment context.
+* @returns {import('eslint').Rule.RuleModule}
+*/
+const iterateAllJsdocs = (iterator, ruleConfig, contexts, additiveCommentContexts) => {
+	const trackedJsdocs = /* @__PURE__ */ new Set();
+	/** @type {import('@es-joy/jsdoccomment').CommentHandler} */
+	let handler;
+	/** @type {Settings|false} */
+	let settings;
+	/**
+	* @param {import('eslint').Rule.RuleContext} context
+	* @param {Node|null} node
+	* @param {import('estree').Comment[]} jsdocNodes
+	* @param {StateObject} state
+	* @param {boolean} [lastCall]
+	* @returns {void}
+	*/
+	const callIterator = (context, node, jsdocNodes, state, lastCall) => {
+		/* c8 ignore next -- Fallback to deprecated method */
+		const { sourceCode = context.getSourceCode() } = context;
+		const { lines } = sourceCode;
+		const utils = getBasicUtils(context, settings);
+		for (const jsdocNode of jsdocNodes) {
+			const jsdocNde = jsdocNode;
+			if (!/^\/\*\*\s/v.test(sourceCode.getText(jsdocNde))) continue;
+			const [indent, jsdoc] = getIndentAndJSDoc(lines, jsdocNode);
+			if (additiveCommentContexts) {
+				for (const [idx, { comment }] of contexts.entries()) {
+					if (comment && handler(comment, jsdoc) === false) continue;
+					iterate({
+						comment,
+						lastIndex: idx,
+						selector: node?.type
+					}, indent, jsdoc, ruleConfig, context, jsdocNode, node, settings, sourceCode, iterator, state, true);
+				}
+				continue;
+			}
+			let lastComment;
+			let lastIndex;
+			if (contexts && contexts.every(({ comment }, idx) => {
+				lastComment = comment;
+				lastIndex = idx;
+				return comment && handler(comment, jsdoc) === false;
+			})) continue;
+			iterate(lastComment ? {
+				comment: lastComment,
+				lastIndex,
+				selector: node?.type
+			} : {
+				lastIndex,
+				selector: node?.type
+			}, indent, jsdoc, ruleConfig, context, jsdocNode, node, settings, sourceCode, iterator, state, true);
+		}
+		const settngs = settings;
+		if (lastCall && ruleConfig.exit) ruleConfig.exit({
+			context,
+			settings: settngs,
+			state,
+			utils
+		});
+	};
+	return {
+		create(context) {
+			/* c8 ignore next -- Fallback to deprecated method */
+			const { sourceCode = context.getSourceCode() } = context;
+			settings = getSettings(context);
+			if (!settings) return {};
+			if (contexts) handler = commentHandler(settings);
+			const state = {};
+			return {
+				"*:not(Program)"(node) {
+					const commentNode = getJSDocComment(sourceCode, node, settings);
+					if (!ruleConfig.noTracking && trackedJsdocs.has(commentNode)) return;
+					if (!commentNode) {
+						if (ruleConfig.nonComment) {
+							const ste = state;
+							ruleConfig.nonComment({
+								node,
+								state: ste
+							});
+						}
+						return;
+					}
+					trackedJsdocs.add(commentNode);
+					callIterator(context, node, [commentNode], state);
+				},
+				"Program:exit"() {
+					const allComments = sourceCode.getAllComments();
+					const untrackedJSdoc = allComments.filter((node) => {
+						return !trackedJsdocs.has(node);
+					});
+					callIterator(context, null, untrackedJSdoc, state, true);
+				}
+			};
+		},
+		meta: ruleConfig.meta
+	};
+};
+/**
+* Create an eslint rule that iterates over all JSDocs, regardless of whether
+* they are attached to a function-like node.
+* @param {JsdocVisitorBasic} iterator
+* @param {RuleConfig} ruleConfig
+* @returns {import('eslint').Rule.RuleModule}
+*/
+const checkFile = (iterator, ruleConfig) => {
+	return {
+		create(context) {
+			/* c8 ignore next -- Fallback to deprecated method */
+			const { sourceCode = context.getSourceCode() } = context;
+			const settings = getSettings(context);
+			if (!settings) return {};
+			return { "Program:exit"() {
+				const allComms = sourceCode.getAllComments();
+				const utils = getBasicUtils(context, settings);
+				iterator({
+					allComments: allComms,
+					context,
+					makeReport,
+					settings,
+					sourceCode,
+					utils
+				});
+			} };
+		},
+		meta: ruleConfig.meta
+	};
+};
+/**
+* @param {JsdocVisitor} iterator
+* @param {RuleConfig} ruleConfig
+* @returns {import('eslint').Rule.RuleModule}
+*/
+function iterateJsdoc(iterator, ruleConfig) {
+	const metaType = ruleConfig?.meta?.type;
+	if (!metaType || ![
+		"layout",
+		"problem",
+		"suggestion"
+	].includes(metaType)) throw new TypeError("Rule must include `meta.type` option (with value \"problem\", \"suggestion\", or \"layout\")");
+	if (typeof iterator !== "function") throw new TypeError("The iterator argument must be a function.");
+	if (ruleConfig.checkFile) return checkFile(iterator, ruleConfig);
+	if (ruleConfig.iterateAllJsdocs) return iterateAllJsdocs(iterator, ruleConfig);
+	/** @type {import('eslint').Rule.RuleModule} */
+	return {
+		create(context) {
+			const settings = getSettings(context);
+			if (!settings) return {};
+			/**
+			* @type {Context[]|undefined}
+			*/
+			let contexts;
+			if (ruleConfig.contextDefaults || ruleConfig.contextSelected || ruleConfig.matchContext) {
+				contexts = ruleConfig.matchContext && context.options[0]?.match ? context.options[0].match : enforcedContexts(context, ruleConfig.contextDefaults, ruleConfig.nonGlobalSettings ? {} : settings);
+				if (contexts) contexts = contexts.map((obj) => {
+					if (typeof obj === "object" && !obj.context) return {
+						...obj,
+						context: "any"
+					};
+					return obj;
+				});
+				const hasPlainAny = contexts?.includes("any");
+				const hasObjectAny = !hasPlainAny && contexts?.find((ctxt) => {
+					if (typeof ctxt === "string") return false;
+					return ctxt?.context === "any";
+				});
+				if (hasPlainAny || hasObjectAny) return iterateAllJsdocs(iterator, ruleConfig, hasObjectAny ? contexts : null, ruleConfig.matchContext).create(context);
+			}
+			/* c8 ignore next -- Fallback to deprecated method */
+			const { sourceCode = context.getSourceCode() } = context;
+			const { lines } = sourceCode;
+			/** @type {Partial<StateObject>} */
+			const state = {};
+			/** @type {CheckJsdoc} */
+			const checkJsdoc = (info, handler, node) => {
+				const jsdocNode = getJSDocComment(sourceCode, node, settings);
+				if (!jsdocNode) return;
+				const [indent, jsdoc] = getIndentAndJSDoc(lines, jsdocNode);
+				if (handler && handler(jsdoc) === false) return;
+				iterate(info, indent, jsdoc, ruleConfig, context, jsdocNode, node, settings, sourceCode, iterator, state);
+			};
+			/** @type {import('eslint').Rule.RuleListener} */
+			let contextObject = {};
+			if (contexts && (ruleConfig.contextDefaults || ruleConfig.contextSelected || ruleConfig.matchContext)) contextObject = getContextObject(contexts, checkJsdoc, commentHandler(settings));
+			else for (const prop of [
+				"ArrowFunctionExpression",
+				"FunctionDeclaration",
+				"FunctionExpression",
+				"TSDeclareFunction"
+			]) contextObject[prop] = checkJsdoc.bind(null, { selector: prop }, null);
+			if (typeof ruleConfig.exit === "function") contextObject["Program:exit"] = () => {
+				const ste = state;
+				/** @type {Required<RuleConfig>} */ ruleConfig.exit({
+					context,
+					settings,
+					state: ste
+				});
+			};
+			return contextObject;
+		},
+		meta: ruleConfig.meta
+	};
+}
+
+//#endregion
+export { iterateJsdoc as default, getSettings, parseComment };
+//# sourceMappingURL=iterateJsdoc.js.map