eslint-plugin-jsdoc 52.0.4 → 53.0.0

package/dist/rules/checkTemplateNames.js

@@ -0,0 +1,124 @@
+import { getTags } from "../jsdocUtils.js";
+import iterateJsdoc, { parseComment } from "../iterateJsdoc.js";
+import { getJSDocComment, parse, traverse, tryParse } from "@es-joy/jsdoccomment";
+
+//#region src/rules/checkTemplateNames.js
+var checkTemplateNames_default = iterateJsdoc(({ jsdoc, node, report, settings, sourceCode, utils }) => {
+	const { mode } = settings;
+	const templateTags = utils.getTags("template");
+	const usedNames = /* @__PURE__ */ new Set();
+	/**
+	* @param {string} potentialType
+	*/
+	const checkForUsedTypes = (potentialType) => {
+		let parsedType;
+		try {
+			parsedType = mode === "permissive" ? tryParse(potentialType) : parse(potentialType, mode);
+		} catch {
+			return;
+		}
+		traverse(parsedType, (nde) => {
+			const { type, value } = nde;
+			if (type === "JsdocTypeName") usedNames.add(value);
+		});
+	};
+	const checkParamsAndReturnsTags = (jsdc = jsdoc) => {
+		const paramName = utils.getPreferredTagName({ tagName: "param" });
+		const paramTags = getTags(jsdc, paramName);
+		for (const paramTag of paramTags) checkForUsedTypes(paramTag.type);
+		const returnsName = utils.getPreferredTagName({ tagName: "returns" });
+		const returnsTags = getTags(jsdc, returnsName);
+		for (const returnsTag of returnsTags) checkForUsedTypes(returnsTag.type);
+	};
+	const checkTemplateTags = () => {
+		for (const tag of templateTags) {
+			const { name } = tag;
+			const names = name.split(/,\s*/v);
+			for (const nme of names) if (!usedNames.has(nme)) report(`@template ${nme} not in use`, null, tag);
+		}
+	};
+	/**
+	* @param {import('@typescript-eslint/types').TSESTree.FunctionDeclaration|
+	*   import('@typescript-eslint/types').TSESTree.ClassDeclaration|
+	*   import('@typescript-eslint/types').TSESTree.TSInterfaceDeclaration|
+	*   import('@typescript-eslint/types').TSESTree.TSTypeAliasDeclaration} aliasDeclaration
+	* @param {boolean} [checkParamsAndReturns]
+	*/
+	const checkParameters = (aliasDeclaration, checkParamsAndReturns) => {
+		/* c8 ignore next -- Guard */
+		const { params } = aliasDeclaration.typeParameters ?? { params: [] };
+		for (const { name: { name } } of params) usedNames.add(name);
+		if (checkParamsAndReturns) checkParamsAndReturnsTags();
+		else if (aliasDeclaration.type === "ClassDeclaration")
+ /* c8 ignore next -- TS */
+		for (const nde of aliasDeclaration?.body?.body ?? []) {
+			const commentNode = getJSDocComment(sourceCode, nde, settings);
+			if (!commentNode) continue;
+			const innerJsdoc = parseComment(commentNode, "");
+			checkParamsAndReturnsTags(innerJsdoc);
+			const typeName = utils.getPreferredTagName({ tagName: "type" });
+			const typeTags = getTags(innerJsdoc, typeName);
+			for (const typeTag of typeTags) checkForUsedTypes(typeTag.type);
+		}
+		checkTemplateTags();
+	};
+	const handleTypeAliases = () => {
+		const nde = node;
+		if (!nde) return;
+		switch (nde.type) {
+			case "ClassDeclaration":
+			case "TSInterfaceDeclaration":
+			case "TSTypeAliasDeclaration":
+				checkParameters(nde);
+				break;
+			case "ExportDefaultDeclaration":
+			case "ExportNamedDeclaration":
+				switch (nde.declaration?.type) {
+					case "ClassDeclaration":
+					case "TSInterfaceDeclaration":
+					case "TSTypeAliasDeclaration":
+						checkParameters(nde.declaration);
+						break;
+					case "FunctionDeclaration":
+						checkParameters(nde.declaration, true);
+						break;
+				}
+				break;
+			case "FunctionDeclaration":
+				checkParameters(nde, true);
+				break;
+		}
+	};
+	const callbackTags = utils.getTags("callback");
+	const functionTags = utils.getTags("function");
+	if (callbackTags.length || functionTags.length) {
+		checkParamsAndReturnsTags();
+		checkTemplateTags();
+		return;
+	}
+	const typedefTags = utils.getTags("typedef");
+	if (!typedefTags.length || typedefTags.length >= 2) {
+		handleTypeAliases();
+		return;
+	}
+	const potentialTypedefType = typedefTags[0].type;
+	checkForUsedTypes(potentialTypedefType);
+	const propertyName = utils.getPreferredTagName({ tagName: "property" });
+	const propertyTags = utils.getTags(propertyName);
+	for (const propertyTag of propertyTags) checkForUsedTypes(propertyTag.type);
+	checkTemplateTags();
+}, {
+	iterateAllJsdocs: true,
+	meta: {
+		docs: {
+			description: "Checks that any `@template` names are actually used in the connected `@typedef` or type alias.",
+			url: "https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/check-template-names.md#repos-sticky-header"
+		},
+		schema: [],
+		type: "suggestion"
+	}
+});
+
+//#endregion
+export { checkTemplateNames_default as default };
+//# sourceMappingURL=checkTemplateNames.js.map

package/dist/rules/checkTemplateNames.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"checkTemplateNames.js","names":["tryParseType","parseType"],"sources":["../../src/rules/checkTemplateNames.js"],"sourcesContent":["import iterateJsdoc, {\n  parseComment,\n} from '../iterateJsdoc.js';\nimport {\n  getTags,\n} from '../jsdocUtils.js';\nimport {\n  getJSDocComment,\n  parse as parseType,\n  traverse,\n  tryParse as tryParseType,\n} from '@es-joy/jsdoccomment';\n\nexport default iterateJsdoc(({\n  jsdoc,\n  node,\n  report,\n  settings,\n  sourceCode,\n  utils,\n}) => {\n  const {\n    mode,\n  } = settings;\n\n  const templateTags = utils.getTags('template');\n\n  const usedNames = new Set();\n  /**\n   * @param {string} potentialType\n   */\n  const checkForUsedTypes = (potentialType) => {\n    let parsedType;\n    try {\n      parsedType = mode === 'permissive' ?\n        tryParseType(/** @type {string} */ (potentialType)) :\n        parseType(/** @type {string} */ (potentialType), mode);\n    } catch {\n      return;\n    }\n\n    traverse(parsedType, (nde) => {\n      const {\n        type,\n        value,\n      } = /** @type {import('jsdoc-type-pratt-parser').NameResult} */ (nde);\n      if (type === 'JsdocTypeName') {\n        usedNames.add(value);\n      }\n    });\n  };\n\n  const checkParamsAndReturnsTags = (jsdc = jsdoc) => {\n    const paramName = /** @type {string} */ (utils.getPreferredTagName({\n      tagName: 'param',\n    }));\n    const paramTags = getTags(jsdc, paramName);\n    for (const paramTag of paramTags) {\n      checkForUsedTypes(paramTag.type);\n    }\n\n    const returnsName = /** @type {string} */ (utils.getPreferredTagName({\n      tagName: 'returns',\n    }));\n    const returnsTags = getTags(jsdc, returnsName);\n    for (const returnsTag of returnsTags) {\n      checkForUsedTypes(returnsTag.type);\n    }\n  };\n\n  const checkTemplateTags = () => {\n    for (const tag of templateTags) {\n      const {\n        name,\n      } = tag;\n      const names = name.split(/,\\s*/v);\n      for (const nme of names) {\n        if (!usedNames.has(nme)) {\n          report(`@template ${nme} not in use`, null, tag);\n        }\n      }\n    }\n  };\n\n  /**\n   * @param {import('@typescript-eslint/types').TSESTree.FunctionDeclaration|\n   *   import('@typescript-eslint/types').TSESTree.ClassDeclaration|\n   *   import('@typescript-eslint/types').TSESTree.TSInterfaceDeclaration|\n   *   import('@typescript-eslint/types').TSESTree.TSTypeAliasDeclaration} aliasDeclaration\n   * @param {boolean} [checkParamsAndReturns]\n   */\n  const checkParameters = (aliasDeclaration, checkParamsAndReturns) => {\n    /* c8 ignore next -- Guard */\n    const {\n      params,\n    } = aliasDeclaration.typeParameters ?? {\n      params: [],\n    };\n    for (const {\n      name: {\n        name,\n      },\n    } of params) {\n      usedNames.add(name);\n    }\n\n    if (checkParamsAndReturns) {\n      checkParamsAndReturnsTags();\n    } else if (aliasDeclaration.type === 'ClassDeclaration') {\n      /* c8 ignore next -- TS */\n      for (const nde of aliasDeclaration?.body?.body ?? []) {\n        // @ts-expect-error Should be ok\n        const commentNode = getJSDocComment(sourceCode, nde, settings);\n        if (!commentNode) {\n          continue;\n        }\n\n        const innerJsdoc = parseComment(commentNode, '');\n        checkParamsAndReturnsTags(innerJsdoc);\n\n        const typeName = /** @type {string} */ (utils.getPreferredTagName({\n          tagName: 'type',\n        }));\n        const typeTags = getTags(innerJsdoc, typeName);\n        for (const typeTag of typeTags) {\n          checkForUsedTypes(typeTag.type);\n        }\n      }\n    }\n\n    checkTemplateTags();\n  };\n\n  const handleTypeAliases = () => {\n    const nde = /** @type {import('@typescript-eslint/types').TSESTree.Node} */ (\n      node\n    );\n    if (!nde) {\n      return;\n    }\n\n    switch (nde.type) {\n      case 'ClassDeclaration':\n      case 'TSInterfaceDeclaration':\n      case 'TSTypeAliasDeclaration':\n        checkParameters(nde);\n        break;\n      case 'ExportDefaultDeclaration':\n      case 'ExportNamedDeclaration':\n        switch (nde.declaration?.type) {\n          case 'ClassDeclaration':\n          case 'TSInterfaceDeclaration':\n          case 'TSTypeAliasDeclaration':\n            checkParameters(nde.declaration);\n            break;\n          case 'FunctionDeclaration':\n            checkParameters(nde.declaration, true);\n            break;\n        }\n\n        break;\n      case 'FunctionDeclaration':\n        checkParameters(nde, true);\n        break;\n    }\n  };\n\n  const callbackTags = utils.getTags('callback');\n  const functionTags = utils.getTags('function');\n  if (callbackTags.length || functionTags.length) {\n    checkParamsAndReturnsTags();\n    checkTemplateTags();\n    return;\n  }\n\n  const typedefTags = utils.getTags('typedef');\n  if (!typedefTags.length || typedefTags.length >= 2) {\n    handleTypeAliases();\n    return;\n  }\n\n  const potentialTypedefType = typedefTags[0].type;\n  checkForUsedTypes(potentialTypedefType);\n\n  const propertyName = /** @type {string} */ (utils.getPreferredTagName({\n    tagName: 'property',\n  }));\n  const propertyTags = utils.getTags(propertyName);\n  for (const propertyTag of propertyTags) {\n    checkForUsedTypes(propertyTag.type);\n  }\n\n  checkTemplateTags();\n}, {\n  iterateAllJsdocs: true,\n  meta: {\n    docs: {\n      description: 'Checks that any `@template` names are actually used in the connected `@typedef` or type alias.',\n      url: 'https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/check-template-names.md#repos-sticky-header',\n    },\n    schema: [],\n    type: 'suggestion',\n  },\n});\n"],"mappings":";;;;;AAaA,iCAAe,aAAa,CAAC,EAC3B,OACA,MACA,QACA,UACA,YACA,OACD,KAAK;CACJ,MAAM,EACJ,MACD,GAAG;CAEJ,MAAM,eAAe,MAAM,QAAQ,WAAW;CAE9C,MAAM,4BAAY,IAAI;;;;CAItB,MAAM,oBAAoB,CAAC,kBAAkB;EAC3C,IAAI;AACJ,MAAI;GACF,aAAa,SAAS,eACpBA,SAAoC,cAAe,GACnDC,MAAiC,eAAgB,KAAK;EACzD,QAAO;AACN;EACD;EAED,SAAS,YAAY,CAAC,QAAQ;GAC5B,MAAM,EACJ,MACA,OACD,GAAgE;AACjE,OAAI,SAAS,iBACX,UAAU,IAAI,MAAM;EAEvB,EAAC;CACH;CAED,MAAM,4BAA4B,CAAC,OAAO,UAAU;EAClD,MAAM,YAAmC,MAAM,oBAAoB,EACjE,SAAS,QACV,EAAC;EACF,MAAM,YAAY,QAAQ,MAAM,UAAU;AAC1C,OAAK,MAAM,YAAY,WACrB,kBAAkB,SAAS,KAAK;EAGlC,MAAM,cAAqC,MAAM,oBAAoB,EACnE,SAAS,UACV,EAAC;EACF,MAAM,cAAc,QAAQ,MAAM,YAAY;AAC9C,OAAK,MAAM,cAAc,aACvB,kBAAkB,WAAW,KAAK;CAErC;CAED,MAAM,oBAAoB,MAAM;AAC9B,OAAK,MAAM,OAAO,cAAc;GAC9B,MAAM,EACJ,MACD,GAAG;GACJ,MAAM,QAAQ,KAAK,MAAM,QAAQ;AACjC,QAAK,MAAM,OAAO,MAChB,KAAI,CAAC,UAAU,IAAI,IAAI,EACrB,OAAO,CAAC,UAAU,EAAE,IAAI,WAAW,CAAC,EAAE,MAAM,IAAI;EAGrD;CACF;;;;;;;;CASD,MAAM,kBAAkB,CAAC,kBAAkB,0BAA0B;;EAEnE,MAAM,EACJ,QACD,GAAG,iBAAiB,kBAAkB,EACrC,QAAQ,CAAE,EACX;AACD,OAAK,MAAM,EACT,MAAM,EACJ,MACD,EACF,IAAI,QACH,UAAU,IAAI,KAAK;AAGrB,MAAI,uBACF,2BAA2B;WAClB,iBAAiB,SAAS;;AAEnC,OAAK,MAAM,OAAO,kBAAkB,MAAM,QAAQ,CAAE,GAAE;GAEpD,MAAM,cAAc,gBAAgB,YAAY,KAAK,SAAS;AAC9D,OAAI,CAAC,YACH;GAGF,MAAM,aAAa,aAAa,aAAa,GAAG;GAChD,0BAA0B,WAAW;GAErC,MAAM,WAAkC,MAAM,oBAAoB,EAChE,SAAS,OACV,EAAC;GACF,MAAM,WAAW,QAAQ,YAAY,SAAS;AAC9C,QAAK,MAAM,WAAW,UACpB,kBAAkB,QAAQ,KAAK;EAElC;EAGH,mBAAmB;CACpB;CAED,MAAM,oBAAoB,MAAM;EAC9B,MAAM,MACJ;AAEF,MAAI,CAAC,IACH;AAGF,UAAQ,IAAI,MAAZ;GACE,KAAK;GACL,KAAK;GACL,KAAK;IACH,gBAAgB,IAAI;AACpB;GACF,KAAK;GACL,KAAK;AACH,YAAQ,IAAI,aAAa,MAAzB;KACE,KAAK;KACL,KAAK;KACL,KAAK;MACH,gBAAgB,IAAI,YAAY;AAChC;KACF,KAAK;MACH,gBAAgB,IAAI,aAAa,KAAK;AACtC;IACH;AAED;GACF,KAAK;IACH,gBAAgB,KAAK,KAAK;AAC1B;EACH;CACF;CAED,MAAM,eAAe,MAAM,QAAQ,WAAW;CAC9C,MAAM,eAAe,MAAM,QAAQ,WAAW;AAC9C,KAAI,aAAa,UAAU,aAAa,QAAQ;EAC9C,2BAA2B;EAC3B,mBAAmB;AACnB;CACD;CAED,MAAM,cAAc,MAAM,QAAQ,UAAU;AAC5C,KAAI,CAAC,YAAY,UAAU,YAAY,UAAU,GAAG;EAClD,mBAAmB;AACnB;CACD;CAED,MAAM,uBAAuB,YAAY,GAAG;CAC5C,kBAAkB,qBAAqB;CAEvC,MAAM,eAAsC,MAAM,oBAAoB,EACpE,SAAS,WACV,EAAC;CACF,MAAM,eAAe,MAAM,QAAQ,aAAa;AAChD,MAAK,MAAM,eAAe,cACxB,kBAAkB,YAAY,KAAK;CAGrC,mBAAmB;AACpB,GAAE;CACD,kBAAkB;CAClB,MAAM;EACJ,MAAM;GACJ,aAAa;GACb,KAAK;EACN;EACD,QAAQ,CAAE;EACV,MAAM;CACP;AACF,EAAC"}