eslint-plugin-jsdoc 63.3.2 → 64.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (270) hide show
  1. package/dist/index.d.ts +7 -4
  2. package/package.json +27 -52
  3. package/src/index.js +7 -8
  4. package/dist/WarnSettings.cjs +0 -38
  5. package/dist/WarnSettings.cjs.map +0 -1
  6. package/dist/alignTransform.cjs +0 -402
  7. package/dist/alignTransform.cjs.map +0 -1
  8. package/dist/buildForbidRuleDefinition.cjs +0 -101
  9. package/dist/buildForbidRuleDefinition.cjs.map +0 -1
  10. package/dist/buildRejectOrPreferRuleDefinition.cjs +0 -352
  11. package/dist/buildRejectOrPreferRuleDefinition.cjs.map +0 -1
  12. package/dist/cjs/WarnSettings.d.ts +0 -16
  13. package/dist/cjs/alignTransform.d.ts +0 -33
  14. package/dist/cjs/buildForbidRuleDefinition.d.ts +0 -14
  15. package/dist/cjs/buildRejectOrPreferRuleDefinition.d.ts +0 -8
  16. package/dist/cjs/defaultTagOrder.d.ts +0 -4
  17. package/dist/cjs/exportParser.d.ts +0 -40
  18. package/dist/cjs/getDefaultTagStructureForMode.d.ts +0 -10
  19. package/dist/cjs/getJsdocProcessorPlugin.d.cts +0 -5
  20. package/dist/cjs/getJsdocProcessorPlugin.d.ts +0 -66
  21. package/dist/cjs/index-cjs.d.ts +0 -23
  22. package/dist/cjs/index.cjs.d.cts +0 -2
  23. package/dist/cjs/iterateJsdoc.d.cts +0 -7
  24. package/dist/cjs/iterateJsdoc.d.ts +0 -495
  25. package/dist/cjs/jsdocUtils.d.ts +0 -500
  26. package/dist/cjs/rules/checkAccess.d.ts +0 -2
  27. package/dist/cjs/rules/checkAlignment.d.ts +0 -2
  28. package/dist/cjs/rules/checkExamples.d.ts +0 -3
  29. package/dist/cjs/rules/checkIndentation.d.ts +0 -2
  30. package/dist/cjs/rules/checkLineAlignment.d.ts +0 -9
  31. package/dist/cjs/rules/checkParamNames.d.ts +0 -2
  32. package/dist/cjs/rules/checkPropertyNames.d.ts +0 -2
  33. package/dist/cjs/rules/checkSyntax.d.ts +0 -2
  34. package/dist/cjs/rules/checkTagNames.d.ts +0 -2
  35. package/dist/cjs/rules/checkTemplateNames.d.ts +0 -2
  36. package/dist/cjs/rules/checkTypes.d.ts +0 -7
  37. package/dist/cjs/rules/checkValues.d.ts +0 -2
  38. package/dist/cjs/rules/convertToJsdocComments.d.ts +0 -266
  39. package/dist/cjs/rules/emptyTags.d.ts +0 -2
  40. package/dist/cjs/rules/escapeInlineTags.d.ts +0 -2
  41. package/dist/cjs/rules/implementsOnClasses.d.ts +0 -2
  42. package/dist/cjs/rules/importsAsDependencies.d.ts +0 -2
  43. package/dist/cjs/rules/informativeDocs.d.ts +0 -2
  44. package/dist/cjs/rules/linesBeforeBlock.d.ts +0 -2
  45. package/dist/cjs/rules/matchDescription.d.ts +0 -2
  46. package/dist/cjs/rules/matchName.d.ts +0 -2
  47. package/dist/cjs/rules/multilineBlocks.d.ts +0 -2
  48. package/dist/cjs/rules/noBadBlocks.d.ts +0 -2
  49. package/dist/cjs/rules/noBlankBlockDescriptions.d.ts +0 -2
  50. package/dist/cjs/rules/noBlankBlocks.d.ts +0 -2
  51. package/dist/cjs/rules/noDefaults.d.ts +0 -2
  52. package/dist/cjs/rules/noMissingSyntax.d.ts +0 -9
  53. package/dist/cjs/rules/noMultiAsterisks.d.ts +0 -2
  54. package/dist/cjs/rules/noRestrictedSyntax.d.ts +0 -2
  55. package/dist/cjs/rules/noTypes.d.ts +0 -2
  56. package/dist/cjs/rules/noUndefinedTypes.d.ts +0 -2
  57. package/dist/cjs/rules/normalizeSeeLinks.d.ts +0 -2
  58. package/dist/cjs/rules/preferImportTag.d.ts +0 -2
  59. package/dist/cjs/rules/requireAsteriskPrefix.d.ts +0 -2
  60. package/dist/cjs/rules/requireDescription.d.ts +0 -2
  61. package/dist/cjs/rules/requireDescriptionCompleteSentence.d.ts +0 -2
  62. package/dist/cjs/rules/requireExample.d.ts +0 -2
  63. package/dist/cjs/rules/requireFileOverview.d.ts +0 -2
  64. package/dist/cjs/rules/requireHyphenBeforeParamDescription.d.ts +0 -2
  65. package/dist/cjs/rules/requireJsdoc.d.ts +0 -24
  66. package/dist/cjs/rules/requireParam.d.ts +0 -3
  67. package/dist/cjs/rules/requireParamDescription.d.ts +0 -2
  68. package/dist/cjs/rules/requireParamName.d.ts +0 -2
  69. package/dist/cjs/rules/requireParamType.d.ts +0 -2
  70. package/dist/cjs/rules/requireProperty.d.ts +0 -2
  71. package/dist/cjs/rules/requirePropertyDescription.d.ts +0 -2
  72. package/dist/cjs/rules/requirePropertyName.d.ts +0 -2
  73. package/dist/cjs/rules/requirePropertyType.d.ts +0 -2
  74. package/dist/cjs/rules/requireRejects.d.ts +0 -2
  75. package/dist/cjs/rules/requireReturns.d.ts +0 -2
  76. package/dist/cjs/rules/requireReturnsCheck.d.ts +0 -2
  77. package/dist/cjs/rules/requireReturnsDescription.d.ts +0 -2
  78. package/dist/cjs/rules/requireReturnsType.d.ts +0 -2
  79. package/dist/cjs/rules/requireTags.d.ts +0 -2
  80. package/dist/cjs/rules/requireTemplate.d.ts +0 -2
  81. package/dist/cjs/rules/requireThrows.d.ts +0 -2
  82. package/dist/cjs/rules/requireYields.d.ts +0 -2
  83. package/dist/cjs/rules/requireYieldsCheck.d.ts +0 -2
  84. package/dist/cjs/rules/sortTags.d.ts +0 -2
  85. package/dist/cjs/rules/tagLines.d.ts +0 -2
  86. package/dist/cjs/rules/textEscaping.d.ts +0 -2
  87. package/dist/cjs/rules/tsMethodSignatureStyle.d.ts +0 -2
  88. package/dist/cjs/rules/tsNoEmptyObjectType.d.ts +0 -2
  89. package/dist/cjs/rules/tsNoUnnecessaryTemplateExpression.d.ts +0 -2
  90. package/dist/cjs/rules/tsPreferFunctionType.d.ts +0 -2
  91. package/dist/cjs/rules/typeFormatting.d.ts +0 -2
  92. package/dist/cjs/rules/validTypes.d.ts +0 -2
  93. package/dist/cjs/tagNames.d.ts +0 -15
  94. package/dist/cjs/utils/hasReturnValue.d.ts +0 -19
  95. package/dist/defaultTagOrder.cjs +0 -46
  96. package/dist/defaultTagOrder.cjs.map +0 -1
  97. package/dist/exportParser.cjs +0 -732
  98. package/dist/exportParser.cjs.map +0 -1
  99. package/dist/generateDocs.cjs +0 -342
  100. package/dist/generateDocs.cjs.map +0 -1
  101. package/dist/generateOptions.cjs +0 -62
  102. package/dist/generateOptions.cjs.map +0 -1
  103. package/dist/generateRule.cjs +0 -248
  104. package/dist/generateRule.cjs.map +0 -1
  105. package/dist/generateRuleTypes.cjs +0 -24
  106. package/dist/generateRuleTypes.cjs.map +0 -1
  107. package/dist/getDefaultTagStructureForMode.cjs +0 -289
  108. package/dist/getDefaultTagStructureForMode.cjs.map +0 -1
  109. package/dist/getJsdocProcessorPlugin.cjs +0 -587
  110. package/dist/getJsdocProcessorPlugin.cjs.map +0 -1
  111. package/dist/getJsdocProcessorPlugin.cts +0 -5
  112. package/dist/index-cjs.cjs +0 -598
  113. package/dist/index-cjs.cjs.map +0 -1
  114. package/dist/index-cjs.d.ts +0 -24
  115. package/dist/index-esm.cjs +0 -162
  116. package/dist/index-esm.cjs.map +0 -1
  117. package/dist/index-esm.d.ts +0 -72
  118. package/dist/index.cjs +0 -746
  119. package/dist/index.cjs.cts +0 -3
  120. package/dist/index.cjs.map +0 -1
  121. package/dist/iterateJsdoc.cjs +0 -2150
  122. package/dist/iterateJsdoc.cjs.map +0 -1
  123. package/dist/iterateJsdoc.cts +0 -7
  124. package/dist/jsdocUtils.cjs +0 -1786
  125. package/dist/jsdocUtils.cjs.map +0 -1
  126. package/dist/rules/checkAccess.cjs +0 -40
  127. package/dist/rules/checkAccess.cjs.map +0 -1
  128. package/dist/rules/checkAlignment.cjs +0 -78
  129. package/dist/rules/checkAlignment.cjs.map +0 -1
  130. package/dist/rules/checkExamples.cjs +0 -521
  131. package/dist/rules/checkExamples.cjs.map +0 -1
  132. package/dist/rules/checkIndentation.cjs +0 -170
  133. package/dist/rules/checkIndentation.cjs.map +0 -1
  134. package/dist/rules/checkLineAlignment.cjs +0 -398
  135. package/dist/rules/checkLineAlignment.cjs.map +0 -1
  136. package/dist/rules/checkParamNames.cjs +0 -407
  137. package/dist/rules/checkParamNames.cjs.map +0 -1
  138. package/dist/rules/checkPropertyNames.cjs +0 -135
  139. package/dist/rules/checkPropertyNames.cjs.map +0 -1
  140. package/dist/rules/checkSyntax.cjs +0 -38
  141. package/dist/rules/checkSyntax.cjs.map +0 -1
  142. package/dist/rules/checkTagNames.cjs +0 -312
  143. package/dist/rules/checkTagNames.cjs.map +0 -1
  144. package/dist/rules/checkTemplateNames.cjs +0 -192
  145. package/dist/rules/checkTemplateNames.cjs.map +0 -1
  146. package/dist/rules/checkTypes.cjs +0 -111
  147. package/dist/rules/checkTypes.cjs.map +0 -1
  148. package/dist/rules/checkValues.cjs +0 -166
  149. package/dist/rules/checkValues.cjs.map +0 -1
  150. package/dist/rules/convertToJsdocComments.cjs +0 -356
  151. package/dist/rules/convertToJsdocComments.cjs.map +0 -1
  152. package/dist/rules/emptyTags.cjs +0 -98
  153. package/dist/rules/emptyTags.cjs.map +0 -1
  154. package/dist/rules/escapeInlineTags.cjs +0 -234
  155. package/dist/rules/escapeInlineTags.cjs.map +0 -1
  156. package/dist/rules/implementsOnClasses.cjs +0 -74
  157. package/dist/rules/implementsOnClasses.cjs.map +0 -1
  158. package/dist/rules/importsAsDependencies.cjs +0 -104
  159. package/dist/rules/importsAsDependencies.cjs.map +0 -1
  160. package/dist/rules/informativeDocs.cjs +0 -187
  161. package/dist/rules/informativeDocs.cjs.map +0 -1
  162. package/dist/rules/linesBeforeBlock.cjs +0 -120
  163. package/dist/rules/linesBeforeBlock.cjs.map +0 -1
  164. package/dist/rules/matchDescription.cjs +0 -356
  165. package/dist/rules/matchDescription.cjs.map +0 -1
  166. package/dist/rules/matchName.cjs +0 -160
  167. package/dist/rules/matchName.cjs.map +0 -1
  168. package/dist/rules/multilineBlocks.cjs +0 -431
  169. package/dist/rules/multilineBlocks.cjs.map +0 -1
  170. package/dist/rules/noBadBlocks.cjs +0 -100
  171. package/dist/rules/noBadBlocks.cjs.map +0 -1
  172. package/dist/rules/noBlankBlockDescriptions.cjs +0 -63
  173. package/dist/rules/noBlankBlockDescriptions.cjs.map +0 -1
  174. package/dist/rules/noBlankBlocks.cjs +0 -54
  175. package/dist/rules/noBlankBlocks.cjs.map +0 -1
  176. package/dist/rules/noDefaults.cjs +0 -102
  177. package/dist/rules/noDefaults.cjs.map +0 -1
  178. package/dist/rules/noMissingSyntax.cjs +0 -196
  179. package/dist/rules/noMissingSyntax.cjs.map +0 -1
  180. package/dist/rules/noMultiAsterisks.cjs +0 -126
  181. package/dist/rules/noMultiAsterisks.cjs.map +0 -1
  182. package/dist/rules/noRestrictedSyntax.cjs +0 -68
  183. package/dist/rules/noRestrictedSyntax.cjs.map +0 -1
  184. package/dist/rules/noTypes.cjs +0 -101
  185. package/dist/rules/noTypes.cjs.map +0 -1
  186. package/dist/rules/noUndefinedTypes.cjs +0 -616
  187. package/dist/rules/noUndefinedTypes.cjs.map +0 -1
  188. package/dist/rules/normalizeSeeLinks.cjs +0 -271
  189. package/dist/rules/normalizeSeeLinks.cjs.map +0 -1
  190. package/dist/rules/preferImportTag.cjs +0 -362
  191. package/dist/rules/preferImportTag.cjs.map +0 -1
  192. package/dist/rules/requireAsteriskPrefix.cjs +0 -190
  193. package/dist/rules/requireAsteriskPrefix.cjs.map +0 -1
  194. package/dist/rules/requireDescription.cjs +0 -164
  195. package/dist/rules/requireDescription.cjs.map +0 -1
  196. package/dist/rules/requireDescriptionCompleteSentence.cjs +0 -321
  197. package/dist/rules/requireDescriptionCompleteSentence.cjs.map +0 -1
  198. package/dist/rules/requireExample.cjs +0 -136
  199. package/dist/rules/requireExample.cjs.map +0 -1
  200. package/dist/rules/requireFileOverview.cjs +0 -194
  201. package/dist/rules/requireFileOverview.cjs.map +0 -1
  202. package/dist/rules/requireHyphenBeforeParamDescription.cjs +0 -166
  203. package/dist/rules/requireHyphenBeforeParamDescription.cjs.map +0 -1
  204. package/dist/rules/requireJsdoc.cjs +0 -721
  205. package/dist/rules/requireJsdoc.cjs.map +0 -1
  206. package/dist/rules/requireParam.cjs +0 -772
  207. package/dist/rules/requireParam.cjs.map +0 -1
  208. package/dist/rules/requireParamDescription.cjs +0 -105
  209. package/dist/rules/requireParamDescription.cjs.map +0 -1
  210. package/dist/rules/requireParamName.cjs +0 -68
  211. package/dist/rules/requireParamName.cjs.map +0 -1
  212. package/dist/rules/requireParamType.cjs +0 -104
  213. package/dist/rules/requireParamType.cjs.map +0 -1
  214. package/dist/rules/requireProperty.cjs +0 -63
  215. package/dist/rules/requireProperty.cjs.map +0 -1
  216. package/dist/rules/requirePropertyDescription.cjs +0 -29
  217. package/dist/rules/requirePropertyDescription.cjs.map +0 -1
  218. package/dist/rules/requirePropertyName.cjs +0 -29
  219. package/dist/rules/requirePropertyName.cjs.map +0 -1
  220. package/dist/rules/requirePropertyType.cjs +0 -29
  221. package/dist/rules/requirePropertyType.cjs.map +0 -1
  222. package/dist/rules/requireRejects.cjs +0 -226
  223. package/dist/rules/requireRejects.cjs.map +0 -1
  224. package/dist/rules/requireReturns.cjs +0 -262
  225. package/dist/rules/requireReturns.cjs.map +0 -1
  226. package/dist/rules/requireReturnsCheck.cjs +0 -225
  227. package/dist/rules/requireReturnsCheck.cjs.map +0 -1
  228. package/dist/rules/requireReturnsDescription.cjs +0 -72
  229. package/dist/rules/requireReturnsDescription.cjs.map +0 -1
  230. package/dist/rules/requireReturnsType.cjs +0 -68
  231. package/dist/rules/requireReturnsType.cjs.map +0 -1
  232. package/dist/rules/requireTags.cjs +0 -74
  233. package/dist/rules/requireTags.cjs.map +0 -1
  234. package/dist/rules/requireTemplate.cjs +0 -220
  235. package/dist/rules/requireTemplate.cjs.map +0 -1
  236. package/dist/rules/requireThrows.cjs +0 -118
  237. package/dist/rules/requireThrows.cjs.map +0 -1
  238. package/dist/rules/requireYields.cjs +0 -224
  239. package/dist/rules/requireYields.cjs.map +0 -1
  240. package/dist/rules/requireYieldsCheck.cjs +0 -179
  241. package/dist/rules/requireYieldsCheck.cjs.map +0 -1
  242. package/dist/rules/sortTags.cjs +0 -656
  243. package/dist/rules/sortTags.cjs.map +0 -1
  244. package/dist/rules/tagLines.cjs +0 -374
  245. package/dist/rules/tagLines.cjs.map +0 -1
  246. package/dist/rules/textEscaping.cjs +0 -141
  247. package/dist/rules/textEscaping.cjs.map +0 -1
  248. package/dist/rules/tsMethodSignatureStyle.cjs +0 -240
  249. package/dist/rules/tsMethodSignatureStyle.cjs.map +0 -1
  250. package/dist/rules/tsNoEmptyObjectType.cjs +0 -62
  251. package/dist/rules/tsNoEmptyObjectType.cjs.map +0 -1
  252. package/dist/rules/tsNoUnnecessaryTemplateExpression.cjs +0 -104
  253. package/dist/rules/tsNoUnnecessaryTemplateExpression.cjs.map +0 -1
  254. package/dist/rules/tsPreferFunctionType.cjs +0 -110
  255. package/dist/rules/tsPreferFunctionType.cjs.map +0 -1
  256. package/dist/rules/typeFormatting.cjs +0 -607
  257. package/dist/rules/typeFormatting.cjs.map +0 -1
  258. package/dist/rules/validTypes.cjs +0 -324
  259. package/dist/rules/validTypes.cjs.map +0 -1
  260. package/dist/tagNames.cjs +0 -244
  261. package/dist/tagNames.cjs.map +0 -1
  262. package/dist/to-valid-identifier.cjs +0 -263
  263. package/dist/utils/hasReturnValue.cjs +0 -495
  264. package/dist/utils/hasReturnValue.cjs.map +0 -1
  265. package/rollup.config.js +0 -16
  266. package/src/getJsdocProcessorPlugin.cts +0 -5
  267. package/src/index-cjs.js +0 -758
  268. package/src/index-esm.js +0 -196
  269. package/src/index.cjs.cts +0 -3
  270. package/src/iterateJsdoc.cts +0 -7
@@ -1,616 +0,0 @@
1
- "use strict";
2
-
3
- Object.defineProperty(exports, "__esModule", {
4
- value: true
5
- });
6
- exports.default = void 0;
7
- var _iterateJsdoc = _interopRequireWildcard(require("../iterateJsdoc.cjs"));
8
- var _jsdocUtils = require("../jsdocUtils.cjs");
9
- var _jsdoccomment = require("@es-joy/jsdoccomment");
10
- var _parseImportsExports = require("parse-imports-exports");
11
- function _interopRequireWildcard(e, t) { if ("function" == typeof WeakMap) var r = new WeakMap(), n = new WeakMap(); return (_interopRequireWildcard = function (e, t) { if (!t && e && e.__esModule) return e; var o, i, f = { __proto__: null, default: e }; if (null === e || "object" != typeof e && "function" != typeof e) return f; if (o = t ? n : r) { if (o.has(e)) return o.get(e); o.set(e, f); } for (const t in e) "default" !== t && {}.hasOwnProperty.call(e, t) && ((i = (o = Object.defineProperty) && Object.getOwnPropertyDescriptor(e, t)) && (i.get || i.set) ? o(f, t, i) : f[t] = e[t]); return f; })(e, t); }
12
- const extraTypes = ['null', 'undefined', 'void', 'string', 'boolean', 'object', 'function', 'symbol', 'number', 'bigint', 'NaN', 'Infinity', 'any', '*', 'never', 'unknown', 'const', 'this', 'true', 'false', 'Array', 'Object', 'RegExp', 'Date', 'Function', 'Intl'];
13
- const globalTypes = ['globalThis', 'global', 'window', 'self'];
14
- const iterableIterator = ['Iterable', 'Iterator', 'IteratorObject'];
15
- const typescriptGlobals = [...iterableIterator,
16
- // https://www.typescriptlang.org/docs/handbook/utility-types.html
17
- 'Awaited', 'Partial', 'Required', 'Readonly', 'Record', 'Pick', 'Omit', 'Exclude', 'Extract', 'NonNullable', 'Parameters', 'ConstructorParameters', 'ReturnType', 'InstanceType', 'ThisParameterType', 'OmitThisParameter', 'ThisType', 'Uppercase', 'Lowercase', 'Capitalize', 'Uncapitalize'];
18
-
19
- /**
20
- * @param {string|false|undefined} [str]
21
- * @returns {undefined|string|false}
22
- */
23
- const stripPseudoTypes = str => {
24
- return str && str.replace(/(?:\.|<>|\.<>|\[\])$/v, '');
25
- };
26
- var _default = exports.default = (0, _iterateJsdoc.default)(({
27
- context,
28
- node,
29
- report,
30
- settings,
31
- sourceCode,
32
- state,
33
- utils
34
- }) => {
35
- /** @type {string[]} */
36
- const foundTypedefValues = [];
37
- const {
38
- scopeManager
39
- } = sourceCode;
40
-
41
- // When is this ever `null`?
42
- const globalScope = /** @type {import('eslint').Scope.Scope} */
43
- scopeManager.globalScope;
44
- const
45
- /**
46
- * @type {{
47
- * checkUsedTypedefs: boolean
48
- * definedTypes: string[],
49
- * disableReporting: boolean,
50
- * markVariablesAsUsed: boolean,
51
- * }}
52
- */
53
- {
54
- checkUsedTypedefs = false,
55
- definedTypes = [],
56
- disableReporting = false,
57
- markVariablesAsUsed = true
58
- } = context.options[0] || {};
59
-
60
- /** @type {(string|undefined)[]} */
61
- let definedPreferredTypes = [];
62
- const {
63
- mode,
64
- preferredTypes,
65
- structuredTags
66
- } = settings;
67
- if (Object.keys(preferredTypes).length) {
68
- definedPreferredTypes = /** @type {string[]} */Object.values(preferredTypes).map(preferredType => {
69
- if (typeof preferredType === 'string') {
70
- // May become an empty string but will be filtered out below
71
- return stripPseudoTypes(preferredType);
72
- }
73
- if (!preferredType) {
74
- return undefined;
75
- }
76
- if (typeof preferredType !== 'object') {
77
- utils.reportSettings('Invalid `settings.jsdoc.preferredTypes`. Values must be falsy, a string, or an object.');
78
- }
79
- return stripPseudoTypes(preferredType.replacement);
80
- }).filter(Boolean);
81
- }
82
- const allComments = sourceCode.getAllComments();
83
- const comments = (0, _jsdocUtils.getJSDocCommentBlocks)(sourceCode);
84
- const globals = allComments.filter(comment => {
85
- return /^\s*globals/v.test(comment.value);
86
- }).flatMap(commentNode => {
87
- return commentNode.value.replace(/^\s*globals/v, '').trim().split(/,\s*/v);
88
- }).concat(Object.keys(context.languageOptions.globals ?? []));
89
- const typedefs = (0, _jsdocUtils.getDocumentNamepathDefiningTags)(sourceCode);
90
- const typedefDeclarations = typedefs.map(tag => {
91
- return tag.name;
92
- });
93
- const importTags = settings.mode === 'typescript' ? (/** @type {string[]} */comments.flatMap(doc => {
94
- return doc.tags.filter(({
95
- tag
96
- }) => {
97
- return tag === 'import';
98
- });
99
- }).flatMap(tag => {
100
- const {
101
- description,
102
- name,
103
- type
104
- } = tag;
105
- const typePart = type ? `{${type}} ` : '';
106
- const imprt = 'import ' + (description ? `${typePart}${name} ${description}` : `${typePart}${name}`);
107
- const importsExports = (0, _parseImportsExports.parseImportsExports)(imprt.trim());
108
- const types = [];
109
- const namedImports = Object.values(importsExports.namedImports || {})[0]?.[0];
110
- if (namedImports) {
111
- if (namedImports.default) {
112
- types.push(namedImports.default);
113
- }
114
- if (namedImports.names) {
115
- types.push(...Object.keys(namedImports.names));
116
- }
117
- }
118
- const namespaceImports = Object.values(importsExports.namespaceImports || {})[0]?.[0];
119
- if (namespaceImports) {
120
- if (namespaceImports.namespace) {
121
- types.push(namespaceImports.namespace);
122
- }
123
- if (namespaceImports.default) {
124
- types.push(namespaceImports.default);
125
- }
126
- }
127
- return types;
128
- }).filter(Boolean)) : [];
129
- const ancestorNodes = [];
130
- let currentNode = node;
131
- // No need for Program node?
132
- while (currentNode?.parent) {
133
- ancestorNodes.push(currentNode);
134
- currentNode = currentNode.parent;
135
- }
136
-
137
- /**
138
- * @param {import('eslint').Rule.Node} ancestorNode
139
- * @returns {import('comment-parser').Spec[]}
140
- */
141
- const getTemplateTags = function (ancestorNode) {
142
- const commentNode = (0, _jsdoccomment.getJSDocComment)(sourceCode, ancestorNode, settings);
143
- if (!commentNode) {
144
- return [];
145
- }
146
- const jsdc = (0, _iterateJsdoc.parseComment)(commentNode, '');
147
- return jsdc.tags.filter(tag => {
148
- return tag.tag === 'template';
149
- });
150
- };
151
-
152
- // `currentScope` may be `null` or `Program`, so in such a case,
153
- // we look to present tags instead
154
- const templateTags = ancestorNodes.length ? ancestorNodes.flatMap(ancestorNode => {
155
- return getTemplateTags(ancestorNode);
156
- }) :
157
- // We err on the side of being too aggressive; checking only
158
- // present tags is not sufficient
159
- comments.flatMap(doc => {
160
- return doc.tags.filter(({
161
- tag
162
- }) => {
163
- return tag === 'template';
164
- });
165
- });
166
- const closureGenericTypes = templateTags.flatMap(tag => {
167
- return utils.parseClosureTemplateTag(tag);
168
- });
169
-
170
- // In modules, including Node, there is a global scope at top with the
171
- // Program scope inside
172
- const cjsOrESMScope = globalScope.childScopes[0]?.block?.type === 'Program';
173
-
174
- /**
175
- * @param {import("eslint").Scope.Scope | null} scope
176
- * @returns {Set<string>}
177
- */
178
- const getValidRuntimeIdentifiers = scope => {
179
- const result = new Set();
180
- let scp = scope;
181
-
182
- /**
183
- * @param {import("eslint").Scope.Scope | null} sc
184
- */
185
- const getChildScopes = sc => {
186
- if (sc) {
187
- // We must check child scopes because when multiple nodes find
188
- // the same comment block, only one node is reported by our code,
189
- // and it can be the children which are not reported.
190
- for (const childScope of sc.childScopes) {
191
- for (const {
192
- name
193
- } of childScope.variables) {
194
- result.add(name);
195
- }
196
- for (const grandChildScope of childScope.childScopes) {
197
- getChildScopes(grandChildScope);
198
- }
199
- }
200
- }
201
- };
202
- getChildScopes(scp);
203
- while (scp) {
204
- for (const {
205
- name
206
- } of scp.variables) {
207
- result.add(name);
208
- }
209
- scp = scp.upper;
210
- }
211
- return result;
212
- };
213
-
214
- /**
215
- * Recursively extracts types from a namespace declaration.
216
- * @param {string} prefix - The namespace prefix (e.g., "MyNamespace" or "Outer.Inner").
217
- * @param {import('@typescript-eslint/types').TSESTree.TSModuleDeclaration} moduleDeclaration - The module declaration node.
218
- * @returns {string[]} Array of fully qualified type names.
219
- */
220
- const getNamespaceTypes = (prefix, moduleDeclaration) => {
221
- /* c8 ignore next 3 -- Guard for ambient modules without body. */
222
- if (!moduleDeclaration.body || moduleDeclaration.body.type !== 'TSModuleBlock') {
223
- return [];
224
- }
225
- return moduleDeclaration.body.body.flatMap(item => {
226
- /** @type {import('@typescript-eslint/types').TSESTree.ProgramStatement | import('@typescript-eslint/types').TSESTree.NamedExportDeclarations | null} */
227
- let declaration = item;
228
- if (item.type === 'ExportNamedDeclaration' && item.declaration) {
229
- declaration = item.declaration;
230
- }
231
- if (declaration.type === 'TSTypeAliasDeclaration' || declaration.type === 'ClassDeclaration') {
232
- /* c8 ignore next 4 -- Guard for anonymous class declarations. */
233
- if (!declaration.id) {
234
- return [];
235
- }
236
- return [`${prefix}.${declaration.id.name}`];
237
- }
238
- if (declaration.type === 'TSInterfaceDeclaration') {
239
- return [`${prefix}.${declaration.id.name}`, ...declaration.body.body.map(prop => {
240
- // Only `TSPropertySignature` and `TSMethodSignature` have 'key'.
241
- if (prop.type !== 'TSPropertySignature' && prop.type !== 'TSMethodSignature') {
242
- return '';
243
- }
244
-
245
- // Key can be computed or a literal, only handle Identifier.
246
- if (prop.key.type !== 'Identifier') {
247
- return '';
248
- }
249
- const propName = prop.key.name;
250
- /* c8 ignore next -- `propName` is always truthy for Identifiers. */
251
- return propName ? `${prefix}.${declaration.id.name}.${propName}` : '';
252
- }).filter(Boolean)];
253
- }
254
-
255
- // Handle nested namespaces.
256
- if (declaration.type === 'TSModuleDeclaration') {
257
- /* c8 ignore next -- Nested string-literal modules aren't valid TS syntax. */
258
- const nestedName = declaration.id?.type === 'Identifier' ? declaration.id.name : '';
259
- /* c8 ignore next 3 -- Guard. */
260
- if (!nestedName) {
261
- return [];
262
- }
263
- return [`${prefix}.${nestedName}`, ...getNamespaceTypes(`${prefix}.${nestedName}`, declaration)];
264
- }
265
-
266
- // Fallback for unhandled declaration types (e.g., TSEnumDeclaration, FunctionDeclaration, etc.).
267
- return [];
268
- });
269
- };
270
-
271
- /**
272
- * We treat imports differently as we can't introspect their children.
273
- * @type {string[]}
274
- */
275
- const imports = [];
276
-
277
- /** @type {Set<string>} */
278
- const closedTypes = new Set();
279
- const tsModuleVariables = scopeManager.scopes.filter(({
280
- type
281
- }) => {
282
- // @ts-expect-error TS
283
- return type === 'tsModule';
284
- }).flatMap(({
285
- variables
286
- }) => {
287
- return variables.map(({
288
- name
289
- }) => {
290
- return name;
291
- });
292
- });
293
- const allDefinedTypes = new Set(globalScope.variables.map(({
294
- name
295
- }) => {
296
- return name;
297
- })
298
-
299
- // If the file is a module, concat the variables from the module scope.
300
- .concat(cjsOrESMScope ? globalScope.childScopes.flatMap(({
301
- variables
302
- }) => {
303
- return variables;
304
- }).flatMap(({
305
- identifiers,
306
- name
307
- }) => {
308
- const globalItem = /** @type {import('estree').Identifier & {parent: import('@typescript-eslint/types').TSESTree.Node}} */identifiers?.[0]?.parent;
309
- switch (globalItem?.type) {
310
- case 'ClassDeclaration':
311
- closedTypes.add(name);
312
- return [name, ...globalItem.body.body.map(item => {
313
- const property = /** @type {import('@typescript-eslint/types').TSESTree.Identifier} */(/** @type {import('@typescript-eslint/types').TSESTree.PropertyDefinition} */item?.key)?.name;
314
- /* c8 ignore next 3 -- Guard */
315
- if (!property) {
316
- return '';
317
- }
318
- return `${name}.${property}`;
319
- }).filter(Boolean)];
320
- case 'ImportDefaultSpecifier':
321
- case 'ImportNamespaceSpecifier':
322
- case 'ImportSpecifier':
323
- imports.push(name);
324
- break;
325
- case 'TSInterfaceDeclaration':
326
- return [name, ...globalItem.body.body.map(item => {
327
- const property = /** @type {import('@typescript-eslint/types').TSESTree.Identifier} */(/** @type {import('@typescript-eslint/types').TSESTree.TSPropertySignature} */item?.key)?.name;
328
- /* c8 ignore next 3 -- Guard */
329
- if (!property) {
330
- return '';
331
- }
332
- return `${name}.${property}`;
333
- }).filter(Boolean)];
334
- case 'TSModuleDeclaration':
335
- closedTypes.add(name);
336
- return [name, ...getNamespaceTypes(name, globalItem)];
337
- case 'VariableDeclarator':
338
- if (/** @type {import('@typescript-eslint/types').TSESTree.Identifier} */(/** @type {import('@typescript-eslint/types').TSESTree.CallExpression} */globalItem?.init?.callee)?.name === 'require') {
339
- imports.push(/** @type {import('@typescript-eslint/types').TSESTree.Identifier} */globalItem.id.name);
340
- break;
341
- }
342
-
343
- // Module scope names are also defined
344
- return [name];
345
- }
346
- return [name];
347
- /* c8 ignore next */
348
- }) : []).concat(extraTypes).concat(typedefDeclarations).concat(importTags).concat(definedTypes).concat(tsModuleVariables).concat(/** @type {string[]} */definedPreferredTypes).concat((() => {
349
- // Other methods are not in scope, but we need them, and we grab them here
350
- if (node?.type === 'MethodDefinition') {
351
- return /** @type {import('estree').ClassBody} */node.parent.body.flatMap(methodOrProp => {
352
- if (methodOrProp.type === 'MethodDefinition') {
353
- // eslint-disable-next-line unicorn/no-lonely-if -- Pattern
354
- if (methodOrProp.key.type === 'Identifier') {
355
- return [methodOrProp.key.name, `${ /** @type {import('estree').ClassDeclaration} */node.parent?.parent?.id?.name}.${methodOrProp.key.name}`];
356
- }
357
- }
358
- if (methodOrProp.type === 'PropertyDefinition') {
359
- // eslint-disable-next-line unicorn/no-lonely-if -- Pattern
360
- if (methodOrProp.key.type === 'Identifier') {
361
- return [methodOrProp.key.name, `${ /** @type {import('estree').ClassDeclaration} */node.parent?.parent?.id?.name}.${methodOrProp.key.name}`];
362
- }
363
- }
364
- /* c8 ignore next 2 -- Not yet built */
365
-
366
- return '';
367
- }).filter(Boolean);
368
- }
369
- return [];
370
- })()).concat((() => {
371
- // Detect static property assignments like `MyClass.Prop = ...`
372
- const programBody = /** @type {import('@typescript-eslint/types').TSESTree.Program} */sourceCode.ast.body;
373
- return programBody.flatMap(statement => {
374
- if (statement.type === 'ExpressionStatement' && statement.expression.type === 'AssignmentExpression' && statement.expression.left.type === 'MemberExpression' && statement.expression.left.object.type === 'Identifier' && statement.expression.left.property.type === 'Identifier' && closedTypes.has(statement.expression.left.object.name)) {
375
- return [`${statement.expression.left.object.name}.${statement.expression.left.property.name}`];
376
- }
377
- return [];
378
- });
379
- })()).concat(...getValidRuntimeIdentifiers(node && (sourceCode.getScope && /* c8 ignore next 3 */
380
- sourceCode.getScope(node) ||
381
- // @ts-expect-error ESLint 8
382
- context.getScope()))).concat(settings.mode === 'jsdoc' ? [] : [...(settings.mode === 'typescript' ? typescriptGlobals : []), ...closureGenericTypes]));
383
-
384
- /**
385
- * @typedef {{
386
- * parsedType: import('jsdoc-type-pratt-parser').RootResult;
387
- * tag: import('comment-parser').Spec|import('@es-joy/jsdoccomment').JsdocInlineTagNoType & {
388
- * line?: import('../iterateJsdoc.js').Integer
389
- * }
390
- * }} TypeAndTagInfo
391
- */
392
-
393
- /**
394
- * @param {string} propertyName
395
- * @returns {(tag: (import('@es-joy/jsdoccomment').JsdocInlineTagNoType & {
396
- * name?: string,
397
- * type?: string,
398
- * line?: import('../iterateJsdoc.js').Integer
399
- * })|import('comment-parser').Spec & {
400
- * namepathOrURL?: string
401
- * }
402
- * ) => undefined|TypeAndTagInfo}
403
- */
404
- const tagToParsedType = propertyName => {
405
- return tag => {
406
- try {
407
- const potentialType = tag[(/** @type {"type"|"name"|"namepathOrURL"} */propertyName)];
408
- return {
409
- parsedType: mode === 'permissive' ? (0, _jsdoccomment.tryParse)(/** @type {string} */potentialType) : (0, _jsdoccomment.parse)(/** @type {string} */potentialType, mode),
410
- tag
411
- };
412
- } catch {
413
- return undefined;
414
- }
415
- };
416
- };
417
- const typeTags = utils.filterTags(({
418
- tag
419
- }) => {
420
- return tag !== 'import' && utils.tagMightHaveTypePosition(tag) && (tag !== 'suppress' || settings.mode !== 'closure');
421
- }).map(tagToParsedType('type'));
422
- const namepathReferencingTags = utils.filterTags(({
423
- tag
424
- }) => {
425
- return utils.isNamepathReferencingTag(tag);
426
- }).map(tagToParsedType('name'));
427
- const namepathOrUrlReferencingTags = utils.filterAllTags(({
428
- tag
429
- }) => {
430
- return utils.isNamepathOrUrlReferencingTag(tag);
431
- }).map(tagToParsedType('namepathOrURL'));
432
- const definedNamesAndNamepaths = new Set(utils.filterTags(({
433
- tag
434
- }) => {
435
- return utils.isNameOrNamepathDefiningTag(tag);
436
- }).map(({
437
- name
438
- }) => {
439
- return name;
440
- }));
441
- const tagsWithTypes = /** @type {TypeAndTagInfo[]} */[...typeTags, ...namepathReferencingTags, ...namepathOrUrlReferencingTags
442
- // Remove types which failed to parse
443
- ].filter(Boolean);
444
- for (const {
445
- parsedType,
446
- tag
447
- } of tagsWithTypes) {
448
- // eslint-disable-next-line complexity -- Refactor
449
- (0, _jsdoccomment.traverse)(parsedType, (nde, parentNode) => {
450
- /**
451
- * @type {import('jsdoc-type-pratt-parser').NameResult & {
452
- * _parent?: import('jsdoc-type-pratt-parser').NonRootResult
453
- * }}
454
- */
455
- // eslint-disable-next-line canonical/id-match -- Avoid clashes
456
- nde._parent = parentNode;
457
- const {
458
- type,
459
- value
460
- } = /** @type {import('jsdoc-type-pratt-parser').NameResult} */nde;
461
- let val = value;
462
-
463
- /** @type {import('jsdoc-type-pratt-parser').NonRootResult|undefined} */
464
- let currNode = nde;
465
- do {
466
- currNode =
467
- /**
468
- * @type {import('jsdoc-type-pratt-parser').NameResult & {
469
- * _parent?: import('jsdoc-type-pratt-parser').NonRootResult
470
- * }}
471
- */
472
- currNode._parent;
473
- if (
474
- // Avoid appending for imports and globals since we don't want to
475
- // check their properties which may or may not exist
476
- !imports.includes(val) && !globals.includes(val) && !importTags.includes(val) && !extraTypes.includes(val) && !typedefDeclarations.includes(val) && !globalTypes.includes(val) && currNode && 'right' in currNode && currNode.right?.type === 'JsdocTypeProperty') {
477
- val = val + '.' + currNode.right.value;
478
- }
479
- } while (currNode?.type === 'JsdocTypeNamePath');
480
- if (type === 'JsdocTypeName') {
481
- const structuredTypes = structuredTags[tag.tag]?.type;
482
- const rootNamespace = val.split('.')[0];
483
- const isNamespaceValid = (definedTypes.includes(rootNamespace) || allDefinedTypes.has(rootNamespace)) && !closedTypes.has(rootNamespace);
484
- if (!allDefinedTypes.has(val) && !definedNamesAndNamepaths.has(val) && (!Array.isArray(structuredTypes) || !structuredTypes.includes(val)) && !isNamespaceValid) {
485
- const parent =
486
- /**
487
- * @type {import('jsdoc-type-pratt-parser').RootResult & {
488
- * _parent?: import('jsdoc-type-pratt-parser').NonRootResult
489
- * }}
490
- */
491
- nde._parent;
492
- if (parent?.type === 'JsdocTypeTypeParameter') {
493
- return;
494
- }
495
- if (parent?.type === 'JsdocTypeFunction' && /** @type {import('jsdoc-type-pratt-parser').FunctionResult} */
496
- parent?.typeParameters?.some(typeParam => {
497
- return value === typeParam.name.value;
498
- })) {
499
- return;
500
- }
501
- if (parent?.type === 'JsdocTypeInfer' && value === parent.element.value) {
502
- allDefinedTypes.add(value);
503
- return;
504
- }
505
- if (!disableReporting) {
506
- report(`The type '${val}' is undefined.`, null, tag);
507
- }
508
- } else if (markVariablesAsUsed && !extraTypes.includes(val)) {
509
- if (sourceCode.markVariableAsUsed) {
510
- sourceCode.markVariableAsUsed(val);
511
- /* c8 ignore next 4 */
512
- } else {
513
- // @ts-expect-error ESLint 8
514
- context.markVariableAsUsed(val);
515
- }
516
- }
517
- if (checkUsedTypedefs && typedefDeclarations.includes(val)) {
518
- foundTypedefValues.push(val);
519
- }
520
- }
521
- });
522
- }
523
- state.foundTypedefValues = foundTypedefValues;
524
- }, {
525
- // We use this method rather than checking at end of handler above because
526
- // in that case, it is invoked too many times and would thus report errors
527
- // too many times.
528
- exit({
529
- context,
530
- state,
531
- utils
532
- }) {
533
- const {
534
- checkUsedTypedefs = false
535
- } = context.options[0] || {};
536
- if (!checkUsedTypedefs) {
537
- return;
538
- }
539
- const allComments = context.sourceCode.getAllComments();
540
- const comments = allComments.filter(comment => {
541
- return /^\*(?!\*)/v.test(comment.value);
542
- }).map(commentNode => {
543
- return {
544
- doc: (0, _iterateJsdoc.parseComment)(commentNode, ''),
545
- loc: commentNode.loc
546
- };
547
- });
548
- const typedefs = comments.flatMap(({
549
- doc,
550
- loc
551
- }) => {
552
- const tags = doc.tags.filter(({
553
- tag
554
- }) => {
555
- return utils.isNameOrNamepathDefiningTag(tag);
556
- });
557
- if (!tags.length) {
558
- return [];
559
- }
560
- return {
561
- loc,
562
- tags
563
- };
564
- });
565
- for (const typedef of typedefs) {
566
- if (!state.foundTypedefValues.includes(typedef.tags[0].name)) {
567
- context.report({
568
- loc: (/** @type {import('@eslint/core').SourceLocation} */typedef.loc),
569
- message: 'This typedef was not used within the file'
570
- });
571
- }
572
- }
573
- },
574
- iterateAllJsdocs: true,
575
- meta: {
576
- docs: {
577
- description: 'Besides some expected built-in types, prohibits any types not specified as globals or within `@typedef`.',
578
- url: 'https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/no-undefined-types.md#repos-sticky-header'
579
- },
580
- schema: [{
581
- additionalProperties: false,
582
- properties: {
583
- checkUsedTypedefs: {
584
- description: 'Whether to check typedefs for use within the file',
585
- type: 'boolean'
586
- },
587
- definedTypes: {
588
- description: `This array can be populated to indicate other types which
589
- are automatically considered as defined (in addition to globals, etc.).
590
- Defaults to an empty array.`,
591
- items: {
592
- type: 'string'
593
- },
594
- type: 'array'
595
- },
596
- disableReporting: {
597
- description: `Whether to disable reporting of errors. Defaults to
598
- \`false\`. This may be set to \`true\` in order to take advantage of only
599
- marking defined variables as used or checking used typedefs.`,
600
- type: 'boolean'
601
- },
602
- markVariablesAsUsed: {
603
- description: `Whether to mark variables as used for the purposes
604
- of the \`no-unused-vars\` rule when they are not found to be undefined.
605
- Defaults to \`true\`. May be set to \`false\` to enforce a practice of not
606
- importing types unless used in code.`,
607
- type: 'boolean'
608
- }
609
- },
610
- type: 'object'
611
- }],
612
- type: 'suggestion'
613
- }
614
- });
615
- module.exports = exports.default;
616
- //# sourceMappingURL=noUndefinedTypes.cjs.map