UNPKG

eslint-plugin-jsdoc

Version:

JSDoc linting rules for ESLint.

github.com/gajus/eslint-plugin-jsdoc

gajus/eslint-plugin-jsdoc

1 lines • 10.3 kB
1
{"version":3,"file":"checkTemplateNames.cjs","names":["iterateJsdoc","tryParseType","parseType","traverse","getTags","getJSDocComment","parseComment"],"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 tgName = /** @type {string} */ (utils.getPreferredTagName({\n tagName: 'template',\n }));\n if (!tgName) {\n return;\n }\n\n const templateTags = utils.getTags(tgName);\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 names = utils.parseClosureTemplateTag(tag);\n for (const nme of names) {\n if (!usedNames.has(nme)) {\n report(`@${tgName} ${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 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 // Template names may be used only within the heritage clause types of a\n // class/interface, e.g. `@template T` used in `@augments {Base<T>}`.\n for (const heritageTagName of [\n 'augments', 'extends', 'implements',\n ]) {\n for (const heritageTag of getTags(jsdoc, heritageTagName)) {\n checkForUsedTypes(heritageTag.type);\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":"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","ignoreList":[]}