eslint-plugin-jsdoc 52.0.4 → 53.0.0

package/dist/jsdocUtils.js

@@ -0,0 +1,1123 @@
+import { __export } from "./_virtual/rolldown_runtime.js";
+import getDefaultTagStructureForMode_default from "./getDefaultTagStructureForMode.js";
+import { closureTags, jsdocTags, typeScriptTags } from "./tagNames.js";
+import WarnSettings_default from "./WarnSettings.js";
+import { hasReturnValue, hasValueOrExecutorHasNonEmptyResolveValue } from "./utils/hasReturnValue.js";
+import { tryParse } from "@es-joy/jsdoccomment";
+
+//#region src/jsdocUtils.js
+var jsdocUtils_exports = {};
+__export(jsdocUtils_exports, {
+	comparePaths: () => comparePaths,
+	dropPathSegmentQuotes: () => dropPathSegmentQuotes,
+	enforcedContexts: () => enforcedContexts,
+	exemptSpeciaMethods: () => exemptSpeciaMethods,
+	filterTags: () => filterTags,
+	flattenRoots: () => flattenRoots,
+	forEachPreferredTag: () => forEachPreferredTag,
+	getAllTags: () => getAllTags,
+	getContextObject: () => getContextObject,
+	getFunctionParameterNames: () => getFunctionParameterNames,
+	getIndent: () => getIndent,
+	getJsdocTagsDeep: () => getJsdocTagsDeep,
+	getPreferredTagName: () => getPreferredTagName,
+	getPreferredTagNameSimple: () => getPreferredTagNameSimple,
+	getRegexFromString: () => getRegexFromString,
+	getTagDescription: () => getTagDescription,
+	getTagStructureForMode: () => getTagStructureForMode,
+	getTags: () => getTags,
+	getTagsByType: () => getTagsByType,
+	hasATag: () => hasATag,
+	hasParams: () => hasParams,
+	hasReturnValue: () => hasReturnValue,
+	hasTag: () => hasTag,
+	hasThrowValue: () => hasThrowValue,
+	hasValueOrExecutorHasNonEmptyResolveValue: () => hasValueOrExecutorHasNonEmptyResolveValue,
+	hasYieldValue: () => hasYieldValue,
+	isConstructor: () => isConstructor,
+	isGetter: () => isGetter,
+	isNamepathDefiningTag: () => isNamepathDefiningTag,
+	isNamepathOrUrlReferencingTag: () => isNamepathOrUrlReferencingTag,
+	isNamepathReferencingTag: () => isNamepathReferencingTag,
+	isSetter: () => isSetter,
+	isValidTag: () => isValidTag,
+	mayBeUndefinedTypeTag: () => mayBeUndefinedTypeTag,
+	overrideTagStructure: () => overrideTagStructure,
+	parseClosureTemplateTag: () => parseClosureTemplateTag,
+	pathDoesNotBeginWith: () => pathDoesNotBeginWith,
+	setTagStructure: () => setTagStructure,
+	tagMightHaveEitherTypeOrNamePosition: () => tagMightHaveEitherTypeOrNamePosition,
+	tagMightHaveNamePosition: () => tagMightHaveNamePosition,
+	tagMightHaveNamepath: () => tagMightHaveNamepath,
+	tagMightHaveTypePosition: () => tagMightHaveTypePosition,
+	tagMissingRequiredTypeOrNamepath: () => tagMissingRequiredTypeOrNamepath,
+	tagMustHaveNamePosition: () => tagMustHaveNamePosition,
+	tagMustHaveTypePosition: () => tagMustHaveTypePosition
+});
+/**
+* @typedef {number} Integer
+*/
+/**
+* @typedef {import('./utils/hasReturnValue.js').ESTreeOrTypeScriptNode} ESTreeOrTypeScriptNode
+*/
+/**
+* @typedef {"jsdoc"|"typescript"|"closure"|"permissive"} ParserMode
+*/
+/**
+* @type {import('./getDefaultTagStructureForMode.js').TagStructure}
+*/
+let tagStructure;
+/**
+* @param {ParserMode} mode
+* @returns {void}
+*/
+const setTagStructure = (mode) => {
+	tagStructure = 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,
+*   hasRestElement: boolean,
+*   names: string[],
+*   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.
+* @callback FlattenRoots
+* @param {ParamInfo[]} params
+* @param {string} [root]
+* @returns {FlattendRootInfo}
+*/
+/** @type {FlattenRoots} */
+const flattenRoots = (params, root = "") => {
+	let hasRestElement = false;
+	let hasPropertyRest = false;
+	/**
+	* @type {boolean[]}
+	*/
+	const rests = [];
+	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])) nms = cur[1];
+				else {
+					if (cur[1].hasRestElement) hasRestElement = true;
+					if (cur[1].hasPropertyRest) hasPropertyRest = true;
+					nms = cur[1].names;
+				}
+				const flattened = flattenRoots(nms, root ? `${root}.${cur[0]}` : cur[0]);
+				if (flattened.hasRestElement) hasRestElement = true;
+				if (flattened.hasPropertyRest) hasPropertyRest = true;
+				const inner = [root ? `${root}.${cur[0]}` : cur[0], ...flattened.names].filter(Boolean);
+				rests.push(false, ...flattened.rests);
+				return acc.concat(inner);
+			}
+			if (typeof cur === "object") {
+				if ("isRestProperty" in cur && cur.isRestProperty) {
+					hasPropertyRest = true;
+					rests.push(true);
+				} else rests.push(false);
+				if ("restElement" in cur && cur.restElement) hasRestElement = true;
+				acc.push(root ? `${root}.${String(cur.name)}` : String(cur.name));
+			} else if (typeof cur !== "undefined") {
+				rests.push(false);
+				acc.push(root ? `${root}.${cur}` : cur);
+			}
+			return acc;
+		},
+		[]
+	);
+	return {
+		hasPropertyRest,
+		hasRestElement,
+		names,
+		rests
+	};
+};
+/**
+* @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 void 0;
+	if (propSignature.typeAnnotation && propSignature.typeAnnotation.typeAnnotation.type === "TSTypeLiteral") return [propSignature.key.name, propSignature.typeAnnotation.typeAnnotation.members.map((member) => {
+		return getPropertiesFromPropertySignature(member);
+	})];
+	return propSignature.key.name;
+};
+/**
+* @param {ESTreeOrTypeScriptNode|null} functionNode
+* @param {boolean} [checkDefaultObjects]
+* @throws {Error}
+* @returns {ParamNameInfo[]}
+*/
+const getFunctionParameterNames = (functionNode, checkDefaultObjects) => {
+	/**
+	* @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 {ParamNameInfo|[string, ParamNameInfo[]]}
+	*/
+	const getParamName = (param, isProperty) => {
+		const hasLeftTypeAnnotation = "left" in param && "typeAnnotation" in param.left;
+		if ("typeAnnotation" in param || hasLeftTypeAnnotation) {
+			const typeAnnotation = hasLeftTypeAnnotation ? param.left.typeAnnotation : param.typeAnnotation;
+			if (typeAnnotation?.typeAnnotation?.type === "TSTypeLiteral") {
+				const propertyNames = typeAnnotation.typeAnnotation.members.map((member) => {
+					return getPropertiesFromPropertySignature(member);
+				});
+				const flattened = {
+					...flattenRoots(propertyNames),
+					annotationParamName: "name" in param ? param.name : void 0
+				};
+				const hasLeftName = "left" in param && "name" in param.left;
+				if ("name" in param || hasLeftName) return [hasLeftName ? param.left.name : param.name, flattened];
+				return [void 0, flattened];
+			}
+		}
+		if ("name" in param) return param.name;
+		if ("left" in param && "name" in param.left) return param.left.name;
+		if (param.type === "ObjectPattern" || "left" in param && param.left.type === "ObjectPattern") {
+			const properties = param.properties || param.left?.properties;
+			const roots = properties.map((prop) => {
+				return getParamName(prop, true);
+			});
+			return [void 0, flattenRoots(roots)];
+		}
+		if (param.type === "Property") {
+			switch (param.value.type) {
+				case "ArrayPattern": return [param.key.name, param.value.elements.map((prop, idx) => {
+					return {
+						name: idx,
+						restElement: prop?.type === "RestElement"
+					};
+				})];
+				case "ObjectPattern": return [param.key.name, param.value.properties.map((prop) => {
+					return getParamName(prop, isProperty);
+				})];
+				case "AssignmentPattern": switch (param.value.left.type) {
+					case "ArrayPattern": return [param.key.name, param.value.left.elements.map((prop, idx) => {
+						return {
+							name: idx,
+							restElement: prop?.type === "RestElement"
+						};
+					})];
+					case "Identifier":
+						if (checkDefaultObjects && param.value.right.type === "ObjectExpression") return [param.key.name, param.value.right.properties.map((prop) => {
+							return getParamName(prop, isProperty);
+						})];
+						break;
+					case "ObjectPattern": return [param.key.name, param.value.left.properties.map((prop) => {
+						return getParamName(prop, isProperty);
+					})];
+				}
+			}
+			switch (param.key.type) {
+				case "Identifier": return param.key.name;
+				case "Literal":
+ /* c8 ignore next 2 -- `raw` may not be present in all parsers */
+				return param.key.raw || param.key.value;
+				default: return void 0;
+			}
+		}
+		if (param.type === "ArrayPattern" || param.left?.type === "ArrayPattern") {
+			const elements = param.elements || param.left?.elements;
+			const roots = elements.map((prop, idx) => {
+				return {
+					name: `"${idx}"`,
+					restElement: prop?.type === "RestElement"
+				};
+			});
+			return [void 0, flattenRoots(roots)];
+		}
+		if (["ExperimentalRestProperty", "RestElement"].includes(param.type)) return {
+			isRestProperty: isProperty,
+			name: param.argument.name ?? param?.argument?.elements?.map(({ name }) => {
+				return name;
+			}),
+			restElement: true
+		};
+		if (param.type === "TSParameterProperty") return getParamName(
+			/** @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?.params || []).map((param) => {
+		return getParamName(param);
+	});
+};
+/**
+* @param {ESTreeOrTypeScriptNode} functionNode
+* @returns {Integer}
+*/
+const hasParams = (functionNode) => {
+	return functionNode.params.length;
+};
+/**
+* Gets all names of the target type, including those that refer to a path, e.g.
+* `foo` or `foo.bar`.
+* @param {import('comment-parser').Block} jsdoc
+* @param {string} targetTagName
+* @returns {{
+*   idx: Integer,
+*   name: string,
+*   type: string
+* }[]}
+*/
+const getJsdocTagsDeep = (jsdoc, targetTagName) => {
+	const ret = [];
+	for (const [idx, { name, tag, type }] of jsdoc.tags.entries()) {
+		if (tag !== targetTagName) continue;
+		ret.push({
+			idx,
+			name,
+			type
+		});
+	}
+	return ret;
+};
+const modeWarnSettings = WarnSettings_default();
+/**
+* @param {ParserMode|undefined} mode
+* @param {Reporter} context
+* @returns {import('./tagNames.js').AliasedTags}
+*/
+const getTagNamesForMode = (mode, context) => {
+	switch (mode) {
+		case "closure":
+		case "permissive": return closureTags;
+		case "jsdoc": return jsdocTags;
+		case "typescript": return typeScriptTags;
+		default:
+			if (!modeWarnSettings.hasBeenWarned(context, "mode")) {
+				context.report({
+					loc: {
+						end: {
+							column: 1,
+							line: 1
+						},
+						start: {
+							column: 1,
+							line: 1
+						}
+					},
+					message: `Unrecognized value \`${mode}\` for \`settings.jsdoc.mode\`.`
+				});
+				modeWarnSettings.markSettingAsWarned(context, "mode");
+			}
+			return jsdocTags;
+	}
+};
+/**
+* @param {import('comment-parser').Spec} tg
+* @param {boolean} [returnArray]
+* @returns {string[]|string}
+*/
+const getTagDescription = (tg, returnArray) => {
+	/**
+	* @type {string[]}
+	*/
+	const descriptions = [];
+	tg.source.some(({ tokens: { description, end, lineEnd, name, postDelimiter, postTag, tag, type } }) => {
+		const desc = (tag && postTag || !tag && !name && !type && postDelimiter || "").slice(1) + (description || "") + (lineEnd || "");
+		if (end) {
+			if (desc) descriptions.push(desc);
+			return true;
+		}
+		descriptions.push(desc);
+		return false;
+	});
+	return returnArray ? descriptions : descriptions.join("\n");
+};
+/**
+* @typedef {{
+*   report: (descriptor: import('eslint').Rule.ReportDescriptor) => void
+* }} Reporter
+*/
+/**
+* @param {string} name
+* @param {ParserMode|undefined} mode
+* @param {TagNamePreference} tagPreference
+* @param {Reporter} context
+* @returns {string|false|{
+*   message: string;
+*   replacement?: string|undefined;
+* }}
+*/
+const getPreferredTagNameSimple = (name, mode, tagPreference = {}, context = { report() {} }) => {
+	const prefValues = Object.values(tagPreference);
+	if (prefValues.includes(name) || prefValues.some((prefVal) => {
+		return prefVal && typeof prefVal === "object" && prefVal.replacement === name;
+	})) return name;
+	const tagPreferenceFixed = Object.fromEntries(Object.entries(tagPreference).map(([key, value]) => {
+		return [key.replace(/^tag /v, ""), value];
+	}));
+	if (Object.hasOwn(tagPreferenceFixed, name)) return tagPreferenceFixed[name];
+	const tagNames = getTagNamesForMode(mode, context);
+	const preferredTagName = Object.entries(tagNames).find(([, aliases]) => {
+		return aliases.includes(name);
+	})?.[0];
+	if (preferredTagName) return preferredTagName;
+	return name;
+};
+/**
+* @param {import('eslint').Rule.RuleContext} context
+* @param {ParserMode|undefined} mode
+* @param {string} name
+* @param {string[]} definedTags
+* @returns {boolean}
+*/
+const isValidTag = (context, mode, name, definedTags) => {
+	const tagNames = getTagNamesForMode(mode, context);
+	const validTagNames = Object.keys(tagNames).concat(Object.values(tagNames).flat());
+	const additionalTags = definedTags;
+	const allTags = validTagNames.concat(additionalTags);
+	return allTags.includes(name);
+};
+/**
+* @param {import('./iterateJsdoc.js').JsdocBlockWithInline} jsdoc
+* @param {string} targetTagName
+* @returns {boolean}
+*/
+const hasTag = (jsdoc, targetTagName) => {
+	const targetTagLower = targetTagName.toLowerCase();
+	return jsdoc.tags.some((doc) => {
+		return doc.tag.toLowerCase() === targetTagLower;
+	});
+};
+/**
+* @param {import('./iterateJsdoc.js').JsdocBlockWithInline} jsdoc
+* @param {(tag: import('@es-joy/jsdoccomment').JsdocTagWithInline) => boolean} filter
+* @returns {import('@es-joy/jsdoccomment').JsdocTagWithInline[]}
+*/
+const filterTags = (jsdoc, filter) => {
+	return jsdoc.tags.filter((tag) => {
+		return filter(tag);
+	});
+};
+/**
+* @param {import('./iterateJsdoc.js').JsdocBlockWithInline} jsdoc
+* @param {string} tagName
+* @returns {import('comment-parser').Spec[]}
+*/
+const getTags = (jsdoc, tagName) => {
+	return filterTags(jsdoc, (item) => {
+		return item.tag === tagName;
+	});
+};
+/**
+* @param {import('./iterateJsdoc.js').JsdocBlockWithInline} jsdoc
+* @param {{
+*   tagName: string,
+*   context?: import('eslint').Rule.RuleContext,
+*   mode?: ParserMode,
+*   report?: import('./iterateJsdoc.js').Report
+*   tagNamePreference?: TagNamePreference
+*   skipReportingBlockedTag?: boolean,
+*   allowObjectReturn?: boolean,
+*   defaultMessage?: string,
+* }} cfg
+* @returns {string|undefined|false|{
+*   message: string;
+*   replacement?: string|undefined;
+* }|{
+*   blocked: true,
+*   tagName: string
+* }}
+*/
+const getPreferredTagName = (jsdoc, { allowObjectReturn = false, context, tagName, defaultMessage = `Unexpected tag \`@${tagName}\``, mode, report = () => {}, skipReportingBlockedTag = false, tagNamePreference }) => {
+	const ret = getPreferredTagNameSimple(tagName, mode, tagNamePreference, context);
+	const isObject = ret && typeof ret === "object";
+	if (hasTag(jsdoc, tagName) && (ret === false || isObject && !ret.replacement)) {
+		if (skipReportingBlockedTag) return {
+			blocked: true,
+			tagName
+		};
+		const message = isObject && ret.message || defaultMessage;
+		report(message, null, getTags(jsdoc, tagName)[0]);
+		return false;
+	}
+	return isObject && !allowObjectReturn ? ret.replacement : ret;
+};
+/**
+* @param {import('./iterateJsdoc.js').JsdocBlockWithInline} jsdoc
+* @param {string} tagName
+* @param {(
+*   matchingJsdocTag: import('@es-joy/jsdoccomment').JsdocTagWithInline,
+*   targetTagName: string
+* ) => void} arrayHandler
+* @param {object} cfg
+* @param {import('eslint').Rule.RuleContext} [cfg.context]
+* @param {ParserMode} [cfg.mode]
+* @param {import('./iterateJsdoc.js').Report} [cfg.report]
+* @param {TagNamePreference} [cfg.tagNamePreference]
+* @param {boolean} [cfg.skipReportingBlockedTag]
+* @returns {void}
+*/
+const forEachPreferredTag = (jsdoc, tagName, arrayHandler, { context, mode, report, skipReportingBlockedTag = false, tagNamePreference } = {}) => {
+	const targetTagName = getPreferredTagName(jsdoc, {
+		context,
+		mode,
+		report,
+		skipReportingBlockedTag,
+		tagName,
+		tagNamePreference
+	});
+	if (!targetTagName || skipReportingBlockedTag && targetTagName && typeof targetTagName === "object") return;
+	const matchingJsdocTags = jsdoc.tags.filter(({ tag }) => {
+		return tag === targetTagName;
+	});
+	for (const matchingJsdocTag of matchingJsdocTags) arrayHandler(matchingJsdocTag, targetTagName);
+};
+/**
+* Get all tags, inline tags and inline tags in tags
+* @param {import('./iterateJsdoc.js').JsdocBlockWithInline} jsdoc
+* @returns {(import('comment-parser').Spec|
+*   import('@es-joy/jsdoccomment').JsdocInlineTagNoType)[]}
+*/
+const getAllTags = (jsdoc) => {
+	return [
+		...jsdoc.tags,
+		...jsdoc.inlineTags.map((inlineTag) => {
+			let line = -1;
+			for (const { tokens: { description } } of jsdoc.source) {
+				line++;
+				if (description && description.includes(`{@${inlineTag.tag}`)) break;
+			}
+			inlineTag.line = line;
+			return inlineTag;
+		}),
+		...jsdoc.tags.flatMap((tag) => {
+			let tagBegins = -1;
+			for (const { tokens: { tag: tg } } of jsdoc.source) {
+				tagBegins++;
+				if (tg) break;
+			}
+			for (const inlineTag of tag.inlineTags) {
+				/** @type {import('./iterateJsdoc.js').Integer} */
+				let line = 0;
+				for (const { number, tokens: { description } } of tag.source) if (description && description.includes(`{@${inlineTag.tag}`)) {
+					line = number;
+					break;
+				}
+				inlineTag.line = tagBegins + line - 1;
+			}
+			return tag.inlineTags;
+		})
+	];
+};
+/**
+* @param {import('./iterateJsdoc.js').JsdocBlockWithInline} jsdoc
+* @param {string[]} targetTagNames
+* @returns {boolean}
+*/
+const hasATag = (jsdoc, targetTagNames) => {
+	return targetTagNames.some((targetTagName) => {
+		return hasTag(jsdoc, targetTagName);
+	});
+};
+/**
+* Checks if the JSDoc comment has an undefined type.
+* @param {import('comment-parser').Spec|null|undefined} tag
+*   the tag which should be checked.
+* @param {ParserMode} mode
+* @returns {boolean}
+*   true in case a defined type is undeclared; otherwise false.
+*/
+const mayBeUndefinedTypeTag = (tag, mode) => {
+	if (typeof tag === "undefined" || tag === null) return true;
+	const tagType = tag.type.trim();
+	if (tagType === "undefined" || tagType === "void" || tagType === "*" || tagType === "any") return true;
+	let parsedTypes;
+	try {
+		parsedTypes = tryParse(tagType, mode === "permissive" ? void 0 : [mode]);
+	} catch {}
+	if (parsedTypes && parsedTypes.type === "JsdocTypeUnion" && parsedTypes.elements.find((elem) => {
+		return elem.type === "JsdocTypeUndefined" || elem.type === "JsdocTypeName" && elem.value === "void";
+	})) return true;
+	return false;
+};
+/**
+* @param {import('./getDefaultTagStructureForMode.js').TagStructure} map
+* @param {string} tag
+* @returns {Map<string, string|string[]|boolean|undefined>}
+*/
+const ensureMap = (map, tag) => {
+	if (!map.has(tag)) map.set(tag, /* @__PURE__ */ new Map());
+	return map.get(tag);
+};
+/**
+* @param {import('./iterateJsdoc.js').StructuredTags} structuredTags
+* @param {import('./getDefaultTagStructureForMode.js').TagStructure} tagMap
+* @returns {void}
+*/
+const overrideTagStructure = (structuredTags, tagMap = tagStructure) => {
+	for (const [tag, { name, required = [], type }] of Object.entries(structuredTags)) {
+		const tagStruct = ensureMap(tagMap, tag);
+		tagStruct.set("namepathRole", name);
+		tagStruct.set("typeAllowed", type);
+		const requiredName = required.includes("name");
+		if (requiredName && name === false) throw new Error("Cannot add \"name\" to `require` with the tag's `name` set to `false`");
+		tagStruct.set("nameRequired", requiredName);
+		const requiredType = required.includes("type");
+		if (requiredType && type === false) throw new Error("Cannot add \"type\" to `require` with the tag's `type` set to `false`");
+		tagStruct.set("typeRequired", requiredType);
+		const typeOrNameRequired = required.includes("typeOrNameRequired");
+		if (typeOrNameRequired && name === false) throw new Error("Cannot add \"typeOrNameRequired\" to `require` with the tag's `name` set to `false`");
+		if (typeOrNameRequired && type === false) throw new Error("Cannot add \"typeOrNameRequired\" to `require` with the tag's `type` set to `false`");
+		tagStruct.set("typeOrNameRequired", typeOrNameRequired);
+	}
+};
+/**
+* @param {ParserMode} mode
+* @param {import('./iterateJsdoc.js').StructuredTags} structuredTags
+* @returns {import('./getDefaultTagStructureForMode.js').TagStructure}
+*/
+const getTagStructureForMode = (mode, structuredTags) => {
+	const tagStruct = getDefaultTagStructureForMode_default(mode);
+	try {
+		overrideTagStructure(structuredTags, tagStruct);
+	} catch {}
+	return tagStruct;
+};
+/**
+* @param {string} tag
+* @param {import('./getDefaultTagStructureForMode.js').TagStructure} tagMap
+* @returns {boolean}
+*/
+const isNamepathDefiningTag = (tag, tagMap = tagStructure) => {
+	const tagStruct = ensureMap(tagMap, tag);
+	return tagStruct.get("namepathRole") === "namepath-defining";
+};
+/**
+* @param {string} tag
+* @param {import('./getDefaultTagStructureForMode.js').TagStructure} tagMap
+* @returns {boolean}
+*/
+const isNamepathReferencingTag = (tag, tagMap = tagStructure) => {
+	const tagStruct = ensureMap(tagMap, tag);
+	return tagStruct.get("namepathRole") === "namepath-referencing";
+};
+/**
+* @param {string} tag
+* @param {import('./getDefaultTagStructureForMode.js').TagStructure} tagMap
+* @returns {boolean}
+*/
+const isNamepathOrUrlReferencingTag = (tag, tagMap = tagStructure) => {
+	const tagStruct = ensureMap(tagMap, tag);
+	return tagStruct.get("namepathRole") === "namepath-or-url-referencing";
+};
+/**
+* @param {string} tag
+* @param {import('./getDefaultTagStructureForMode.js').TagStructure} tagMap
+* @returns {boolean|undefined}
+*/
+const tagMustHaveTypePosition = (tag, tagMap = tagStructure) => {
+	const tagStruct = ensureMap(tagMap, tag);
+	return tagStruct.get("typeRequired");
+};
+/**
+* @param {string} tag
+* @param {import('./getDefaultTagStructureForMode.js').TagStructure} tagMap
+* @returns {boolean|string}
+*/
+const tagMightHaveTypePosition = (tag, tagMap = tagStructure) => {
+	if (tagMustHaveTypePosition(tag, tagMap)) return true;
+	const tagStruct = ensureMap(tagMap, tag);
+	const ret = tagStruct.get("typeAllowed");
+	return ret === void 0 ? true : ret;
+};
+const namepathTypes = new Set(["namepath-defining", "namepath-referencing"]);
+/**
+* @param {string} tag
+* @param {import('./getDefaultTagStructureForMode.js').TagStructure} tagMap
+* @returns {boolean}
+*/
+const tagMightHaveNamePosition = (tag, tagMap = tagStructure) => {
+	const tagStruct = ensureMap(tagMap, tag);
+	const ret = tagStruct.get("namepathRole");
+	return ret === void 0 ? true : Boolean(ret);
+};
+/**
+* @param {string} tag
+* @param {import('./getDefaultTagStructureForMode.js').TagStructure} tagMap
+* @returns {boolean}
+*/
+const tagMightHaveNamepath = (tag, tagMap = tagStructure) => {
+	const tagStruct = ensureMap(tagMap, tag);
+	const nampathRole = tagStruct.get("namepathRole");
+	return nampathRole !== false && namepathTypes.has(nampathRole);
+};
+/**
+* @param {string} tag
+* @param {import('./getDefaultTagStructureForMode.js').TagStructure} tagMap
+* @returns {boolean|undefined}
+*/
+const tagMustHaveNamePosition = (tag, tagMap = tagStructure) => {
+	const tagStruct = ensureMap(tagMap, tag);
+	return tagStruct.get("nameRequired");
+};
+/**
+* @param {string} tag
+* @param {import('./getDefaultTagStructureForMode.js').TagStructure} tagMap
+* @returns {boolean}
+*/
+const tagMightHaveEitherTypeOrNamePosition = (tag, tagMap) => {
+	return Boolean(tagMightHaveTypePosition(tag, tagMap)) || tagMightHaveNamepath(tag, tagMap);
+};
+/**
+* @param {string} tag
+* @param {import('./getDefaultTagStructureForMode.js').TagStructure} tagMap
+* @returns {boolean|undefined}
+*/
+const tagMustHaveEitherTypeOrNamePosition = (tag, tagMap) => {
+	const tagStruct = ensureMap(tagMap, tag);
+	return tagStruct.get("typeOrNameRequired");
+};
+/**
+* @param {import('comment-parser').Spec} tag
+* @param {import('./getDefaultTagStructureForMode.js').TagStructure} tagMap
+* @returns {boolean|undefined}
+*/
+const tagMissingRequiredTypeOrNamepath = (tag, tagMap = tagStructure) => {
+	const mustHaveTypePosition = tagMustHaveTypePosition(tag.tag, tagMap);
+	const mightHaveTypePosition = tagMightHaveTypePosition(tag.tag, tagMap);
+	const hasTypePosition = mightHaveTypePosition && Boolean(tag.type);
+	const hasNameOrNamepathPosition = (tagMustHaveNamePosition(tag.tag, tagMap) || tagMightHaveNamepath(tag.tag, tagMap)) && Boolean(tag.name);
+	const mustHaveEither = tagMustHaveEitherTypeOrNamePosition(tag.tag, tagMap);
+	const hasEither = tagMightHaveEitherTypeOrNamePosition(tag.tag, tagMap) && (hasTypePosition || hasNameOrNamepathPosition);
+	return mustHaveEither && !hasEither && !mustHaveTypePosition;
+};
+/**
+* @param {ESTreeOrTypeScriptNode|null|undefined} node
+* @param {boolean} [checkYieldReturnValue]
+* @returns {boolean}
+*/
+const hasNonFunctionYield = (node, checkYieldReturnValue) => {
+	if (!node) return false;
+	switch (node.type) {
+		case "ArrayExpression":
+		case "ArrayPattern": return node.elements.some((element) => {
+			return hasNonFunctionYield(element, checkYieldReturnValue);
+		});
+		case "AssignmentExpression":
+		case "BinaryExpression":
+		case "LogicalExpression": return hasNonFunctionYield(node.left, checkYieldReturnValue) || hasNonFunctionYield(node.right, checkYieldReturnValue);
+		case "AssignmentPattern": return hasNonFunctionYield(node.right, checkYieldReturnValue);
+		case "BlockStatement": return node.body.some((bodyNode) => {
+			return ![
+				"ArrowFunctionExpression",
+				"FunctionDeclaration",
+				"FunctionExpression"
+			].includes(bodyNode.type) && hasNonFunctionYield(bodyNode, checkYieldReturnValue);
+		});
+		case "CallExpression":
+		case "OptionalCallExpression": return node.arguments.some((element) => {
+			return hasNonFunctionYield(element, checkYieldReturnValue);
+		});
+		case "ChainExpression":
+		case "ExpressionStatement": return hasNonFunctionYield(node.expression, checkYieldReturnValue);
+		case "ClassProperty":
+		case "ObjectProperty":
+		case "Property":
+		case "PropertyDefinition": return node.computed && hasNonFunctionYield(node.key, checkYieldReturnValue) || hasNonFunctionYield(node.value, checkYieldReturnValue);
+		case "ConditionalExpression":
+		case "IfStatement": return hasNonFunctionYield(node.test, checkYieldReturnValue) || hasNonFunctionYield(node.consequent, checkYieldReturnValue) || hasNonFunctionYield(node.alternate, checkYieldReturnValue);
+		case "DoWhileStatement":
+		case "ForInStatement":
+		case "ForOfStatement":
+		case "ForStatement":
+		case "LabeledStatement":
+		case "WhileStatement":
+		case "WithStatement": return hasNonFunctionYield(node.body, checkYieldReturnValue);
+		case "Import":
+		case "ImportExpression": return hasNonFunctionYield(node.source, checkYieldReturnValue);
+		case "MemberExpression":
+		case "OptionalMemberExpression": return hasNonFunctionYield(node.object, checkYieldReturnValue) || hasNonFunctionYield(node.property, checkYieldReturnValue);
+		case "ObjectExpression":
+		case "ObjectPattern": return node.properties.some((property) => {
+			return hasNonFunctionYield(property, checkYieldReturnValue);
+		});
+		case "ObjectMethod":
+ /* c8 ignore next 6 -- In Babel? */
+		return node.computed && hasNonFunctionYield(node.key, checkYieldReturnValue) || node.arguments.some((nde) => {
+			return hasNonFunctionYield(nde, checkYieldReturnValue);
+		});
+		case "ReturnStatement":
+			if (node.argument === null) return false;
+			return hasNonFunctionYield(node.argument, checkYieldReturnValue);
+		case "SequenceExpression":
+		case "TemplateLiteral": return node.expressions.some((subExpression) => {
+			return hasNonFunctionYield(subExpression, checkYieldReturnValue);
+		});
+		case "SpreadElement":
+		case "UnaryExpression": return hasNonFunctionYield(node.argument, checkYieldReturnValue);
+		case "SwitchStatement": return node.cases.some((someCase) => {
+			return someCase.consequent.some((nde) => {
+				return hasNonFunctionYield(nde, checkYieldReturnValue);
+			});
+		});
+		case "TaggedTemplateExpression": return hasNonFunctionYield(node.quasi, checkYieldReturnValue);
+		case "TryStatement": return hasNonFunctionYield(node.block, checkYieldReturnValue) || hasNonFunctionYield(node.handler && node.handler.body, checkYieldReturnValue) || hasNonFunctionYield(node.finalizer, checkYieldReturnValue);
+		case "VariableDeclaration": return node.declarations.some((nde) => {
+			return hasNonFunctionYield(nde, checkYieldReturnValue);
+		});
+		case "VariableDeclarator": return hasNonFunctionYield(node.id, checkYieldReturnValue) || hasNonFunctionYield(node.init, checkYieldReturnValue);
+		case "YieldExpression":
+			if (checkYieldReturnValue) {
+				if (node.parent.type === "VariableDeclarator") return true;
+				return false;
+			}
+			if (node.argument === null) return false;
+			return true;
+		default: return false;
+	}
+};
+/**
+* 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(
+		/** @type {import('@typescript-eslint/types').TSESTree.FunctionDeclaration} */
+		node.body,
+		checkYieldReturnValue
+	));
+};
+/**
+* Checks if a node has a throws statement.
+* @param {ESTreeOrTypeScriptNode|null|undefined} node
+* @param {boolean} [innerFunction]
+* @returns {boolean}
+*/
+const hasThrowValue = (node, innerFunction) => {
+	if (!node) return false;
+	switch (node.type) {
+		case "ArrowFunctionExpression":
+		case "FunctionDeclaration":
+		case "FunctionExpression": return !innerFunction && !node.async && hasThrowValue(node.body, true);
+		case "BlockStatement": return node.body.some((bodyNode) => {
+			return bodyNode.type !== "FunctionDeclaration" && hasThrowValue(bodyNode);
+		});
+		case "DoWhileStatement":
+		case "ForInStatement":
+		case "ForOfStatement":
+		case "ForStatement":
+		case "LabeledStatement":
+		case "WhileStatement":
+		case "WithStatement": return hasThrowValue(node.body);
+		case "IfStatement": return hasThrowValue(node.consequent) || hasThrowValue(node.alternate);
+		case "SwitchStatement": return node.cases.some((someCase) => {
+			return someCase.consequent.some((nde) => {
+				return hasThrowValue(nde);
+			});
+		});
+		case "ThrowStatement": return true;
+		case "TryStatement": return hasThrowValue(node.handler && node.handler.body) || hasThrowValue(node.finalizer);
+		default: return false;
+	}
+};
+/**
+* @param {string} tag
+*/
+/**
+* Parses GCC Generic/Template types
+* @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[]}
+*/
+const parseClosureTemplateTag = (tag) => {
+	return tag.name.split(",").map((type) => {
+		return type.trim().replace(/^\[?(?<name>.*?)=.*$/v, "$<name>");
+	});
+};
+/**
+* @typedef {true|string[]} DefaultContexts
+*/
+/**
+* Checks user option for `contexts` array, defaulting to
+* contexts designated by the rule. Returns an array of
+* ESTree AST types, indicating allowable contexts.
+* @param {import('eslint').Rule.RuleContext} context
+* @param {DefaultContexts|undefined} defaultContexts
+* @param {{
+*   contexts?: import('./iterateJsdoc.js').Context[]
+* }} settings
+* @returns {(string|import('./iterateJsdoc.js').ContextObject)[]}
+*/
+const enforcedContexts = (context, defaultContexts, settings) => {
+	const contexts = context.options[0]?.contexts || settings.contexts || (defaultContexts === true ? [
+		"ArrowFunctionExpression",
+		"FunctionDeclaration",
+		"FunctionExpression",
+		"TSDeclareFunction"
+	] : defaultContexts);
+	return contexts;
+};
+/**
+* @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 = {
+				lastIndex: idx,
+				selector: prop.context
+			};
+			if (prop.comment) {
+				property = prop.context;
+				value = checkJsdoc.bind(
+					null,
+					{
+						...selInfo,
+						comment: prop.comment
+					},
+					/** @type {import('@es-joy/jsdoccomment').CommentHandler} */
+					handler.bind(null, prop.comment)
+				);
+			} else {
+				property = prop.context;
+				value = checkJsdoc.bind(null, selInfo, null);
+			}
+		} else {
+			const selInfo = {
+				lastIndex: idx,
+				selector: prop
+			};
+			property = prop;
+			value = checkJsdoc.bind(null, selInfo, null);
+		}
+		const old = properties[property];
+		properties[property] = old ? function(node) {
+			old(node);
+			value(node);
+		} : value;
+	}
+	return properties;
+};
+const tagsWithNamesAndDescriptions = new Set([
+	"arg",
+	"argument",
+	"param",
+	"prop",
+	"property",
+	"return",
+	"returns",
+	"template"
+]);
+/**
+* @typedef {{
+*   [key: string]: false|string|
+*     {message: string, replacement?: string}
+* }} TagNamePreference
+*/
+/**
+* @param {import('eslint').Rule.RuleContext} context
+* @param {ParserMode|undefined} mode
+* @param {import('comment-parser').Spec[]} tags
+* @returns {{
+*   tagsWithNames: import('comment-parser').Spec[],
+*   tagsWithoutNames: import('comment-parser').Spec[]
+* }}
+*/
+const getTagsByType = (context, mode, tags) => {
+	/**
+	* @type {import('comment-parser').Spec[]}
+	*/
+	const tagsWithoutNames = [];
+	const tagsWithNames = tags.filter((tag) => {
+		const { tag: tagName } = tag;
+		const tagWithName = tagsWithNamesAndDescriptions.has(tagName);
+		if (!tagWithName) tagsWithoutNames.push(tag);
+		return tagWithName;
+	});
+	return {
+		tagsWithNames,
+		tagsWithoutNames
+	};
+};
+/**
+* @param {import('eslint').SourceCode|{
+*   text: string
+* }} sourceCode
+* @returns {string}
+*/
+const getIndent = (sourceCode) => {
+	return (sourceCode.text.match(/^\n*([ \t]+)/v)?.[1] ?? "") + " ";
+};
+/**
+* @param {import('eslint').Rule.Node|null} node
+* @returns {boolean}
+*/
+const isConstructor = (node) => {
+	return node?.type === "MethodDefinition" && node.kind === "constructor" || (node?.parent)?.kind === "constructor";
+};
+/**
+* @param {import('eslint').Rule.Node|null} node
+* @returns {boolean}
+*/
+const isGetter = (node) => {
+	return node !== null && node.parent?.kind === "get";
+};
+/**
+* @param {import('eslint').Rule.Node|null} node
+* @returns {boolean}
+*/
+const isSetter = (node) => {
+	return node !== null && node.parent?.kind === "set";
+};
+/**
+* @param {import('eslint').Rule.Node} node
+* @returns {boolean}
+*/
+const hasAccessorPair = (node) => {
+	const { key, kind: sourceKind, type } = node;
+	const sourceName = key.name;
+	const oppositeKind = sourceKind === "get" ? "set" : "get";
+	const sibling = type === "MethodDefinition" ? node.parent.body : node.parent.properties;
+	return sibling.some((child) => {
+		const { key: ky, kind } = child;
+		const name = ky.name;
+		return kind === oppositeKind && name === sourceName;
+	});
+};
+/**
+* @param {import('./iterateJsdoc.js').JsdocBlockWithInline} jsdoc
+* @param {import('eslint').Rule.Node|null} node
+* @param {import('eslint').Rule.RuleContext} context
+* @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) => {
+		const schemaProperties = schema[0].properties;
+		return context.options[0]?.[prop] ?? (schemaProperties[prop] && schemaProperties[prop].default);
+	};
+	const checkGetters = hasSchemaOption("checkGetters");
+	const checkSetters = hasSchemaOption("checkSetters");
+	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
+	));
+};
+/**
+* Since path segments may be unquoted (if matching a reserved word,
+* 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.replaceAll(/\.(['"])(.*)\1/gv, ".$2");
+};
+/**
+* @param {string} name
+* @returns {(otherPathName: string) => boolean}
+*/
+const comparePaths = (name) => {
+	return (otherPathName) => {
+		return otherPathName === name || dropPathSegmentQuotes(otherPathName) === dropPathSegmentQuotes(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]
+* @returns {RegExp}
+*/
+const getRegexFromString = (regexString, requiredFlags) => {
+	const match = regexString.match(/^\/(.*)\/([gimyvus]*)$/sv);
+	let flags = "v";
+	let regex = regexString;
+	if (match) {
+		[, regex, flags] = match;
+		if (!flags) flags = "v";
+	}
+	const uniqueFlags = [...new Set(flags + (requiredFlags || ""))];
+	flags = uniqueFlags.join("");
+	return new RegExp(regex, flags);
+};
+
+//#endregion
+export { comparePaths, dropPathSegmentQuotes, enforcedContexts, exemptSpeciaMethods, filterTags, flattenRoots, forEachPreferredTag, getAllTags, getContextObject, getFunctionParameterNames, getIndent, getJsdocTagsDeep, getPreferredTagName, getPreferredTagNameSimple, getRegexFromString, getTagDescription, getTagStructureForMode, getTags, getTagsByType, hasATag, hasParams, hasTag, hasThrowValue, hasYieldValue, isConstructor, isValidTag, jsdocUtils_exports, mayBeUndefinedTypeTag, overrideTagStructure, parseClosureTemplateTag, pathDoesNotBeginWith, setTagStructure, tagMissingRequiredTypeOrNamepath };
+//# sourceMappingURL=jsdocUtils.js.map