eslint-plugin-jsdoc 52.0.3 → 52.0.4

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 (357) hide show
  1. package/dist/WarnSettings.cjs +35 -18
  2. package/dist/WarnSettings.cjs.map +1 -1
  3. package/dist/alignTransform.cjs +305 -224
  4. package/dist/alignTransform.cjs.map +1 -1
  5. package/dist/defaultTagOrder.cjs +43 -132
  6. package/dist/defaultTagOrder.cjs.map +1 -1
  7. package/dist/exportParser.cjs +696 -478
  8. package/dist/exportParser.cjs.map +1 -1
  9. package/dist/generateRule.cjs +242 -0
  10. package/dist/generateRule.cjs.map +1 -0
  11. package/dist/getDefaultTagStructureForMode.cjs +288 -184
  12. package/dist/getDefaultTagStructureForMode.cjs.map +1 -1
  13. package/dist/getJsdocProcessorPlugin.cjs +550 -364
  14. package/dist/getJsdocProcessorPlugin.cjs.map +1 -1
  15. package/dist/getJsdocProcessorPlugin.d.ts +65 -68
  16. package/dist/getJsdocProcessorPlugin.d.ts.map +1 -1
  17. package/dist/index.cjs +383 -398
  18. package/dist/index.cjs.map +1 -1
  19. package/dist/index.d.ts +6 -11
  20. package/dist/index.d.ts.map +1 -1
  21. package/dist/iterateJsdoc.cjs +1988 -1528
  22. package/dist/iterateJsdoc.cjs.map +1 -1
  23. package/dist/iterateJsdoc.d.ts +349 -358
  24. package/dist/iterateJsdoc.d.ts.map +1 -1
  25. package/dist/jsdocUtils.cjs +1376 -1009
  26. package/dist/jsdocUtils.cjs.map +1 -1
  27. package/dist/rules/checkAccess.cjs +36 -29
  28. package/dist/rules/checkAccess.cjs.map +1 -1
  29. package/dist/rules/checkAlignment.cjs +54 -41
  30. package/dist/rules/checkAlignment.cjs.map +1 -1
  31. package/dist/rules/checkExamples.cjs +484 -327
  32. package/dist/rules/checkExamples.cjs.map +1 -1
  33. package/dist/rules/checkIndentation.cjs +65 -50
  34. package/dist/rules/checkIndentation.cjs.map +1 -1
  35. package/dist/rules/checkLineAlignment.cjs +311 -220
  36. package/dist/rules/checkLineAlignment.cjs.map +1 -1
  37. package/dist/rules/checkParamNames.cjs +335 -227
  38. package/dist/rules/checkParamNames.cjs.map +1 -1
  39. package/dist/rules/checkPropertyNames.cjs +106 -78
  40. package/dist/rules/checkPropertyNames.cjs.map +1 -1
  41. package/dist/rules/checkSyntax.cjs +34 -21
  42. package/dist/rules/checkSyntax.cjs.map +1 -1
  43. package/dist/rules/checkTagNames.cjs +210 -188
  44. package/dist/rules/checkTagNames.cjs.map +1 -1
  45. package/dist/rules/checkTemplateNames.cjs +178 -121
  46. package/dist/rules/checkTemplateNames.cjs.map +1 -1
  47. package/dist/rules/checkTypes.cjs +385 -291
  48. package/dist/rules/checkTypes.cjs.map +1 -1
  49. package/dist/rules/checkValues.cjs +146 -100
  50. package/dist/rules/checkValues.cjs.map +1 -1
  51. package/dist/rules/convertToJsdocComments.cjs +306 -228
  52. package/dist/rules/convertToJsdocComments.cjs.map +1 -1
  53. package/dist/rules/emptyTags.cjs +72 -62
  54. package/dist/rules/emptyTags.cjs.map +1 -1
  55. package/dist/rules/implementsOnClasses.cjs +56 -36
  56. package/dist/rules/implementsOnClasses.cjs.map +1 -1
  57. package/dist/rules/importsAsDependencies.cjs +99 -62
  58. package/dist/rules/importsAsDependencies.cjs.map +1 -1
  59. package/dist/rules/informativeDocs.cjs +142 -105
  60. package/dist/rules/informativeDocs.cjs.map +1 -1
  61. package/dist/rules/linesBeforeBlock.cjs +105 -70
  62. package/dist/rules/linesBeforeBlock.cjs.map +1 -1
  63. package/dist/rules/matchDescription.cjs +222 -160
  64. package/dist/rules/matchDescription.cjs.map +1 -1
  65. package/dist/rules/matchName.cjs +128 -73
  66. package/dist/rules/matchName.cjs.map +1 -1
  67. package/dist/rules/multilineBlocks.cjs +352 -235
  68. package/dist/rules/multilineBlocks.cjs.map +1 -1
  69. package/dist/rules/noBadBlocks.cjs +86 -63
  70. package/dist/rules/noBadBlocks.cjs.map +1 -1
  71. package/dist/rules/noBlankBlockDescriptions.cjs +57 -35
  72. package/dist/rules/noBlankBlockDescriptions.cjs.map +1 -1
  73. package/dist/rules/noBlankBlocks.cjs +48 -26
  74. package/dist/rules/noBlankBlocks.cjs.map +1 -1
  75. package/dist/rules/noDefaults.cjs +79 -52
  76. package/dist/rules/noDefaults.cjs.map +1 -1
  77. package/dist/rules/noMissingSyntax.cjs +165 -115
  78. package/dist/rules/noMissingSyntax.cjs.map +1 -1
  79. package/dist/rules/noMultiAsterisks.cjs +89 -48
  80. package/dist/rules/noMultiAsterisks.cjs.map +1 -1
  81. package/dist/rules/noRestrictedSyntax.cjs +79 -45
  82. package/dist/rules/noRestrictedSyntax.cjs.map +1 -1
  83. package/dist/rules/noTypes.cjs +80 -59
  84. package/dist/rules/noTypes.cjs.map +1 -1
  85. package/dist/rules/noUndefinedTypes.cjs +388 -297
  86. package/dist/rules/noUndefinedTypes.cjs.map +1 -1
  87. package/dist/rules/requireAsteriskPrefix.cjs +159 -108
  88. package/dist/rules/requireAsteriskPrefix.cjs.map +1 -1
  89. package/dist/rules/requireDescription.cjs +129 -89
  90. package/dist/rules/requireDescription.cjs.map +1 -1
  91. package/dist/rules/requireDescriptionCompleteSentence.cjs +262 -201
  92. package/dist/rules/requireDescriptionCompleteSentence.cjs.map +1 -1
  93. package/dist/rules/requireExample.cjs +104 -73
  94. package/dist/rules/requireExample.cjs.map +1 -1
  95. package/dist/rules/requireFileOverview.cjs +129 -75
  96. package/dist/rules/requireFileOverview.cjs.map +1 -1
  97. package/dist/rules/requireHyphenBeforeParamDescription.cjs +133 -85
  98. package/dist/rules/requireHyphenBeforeParamDescription.cjs.map +1 -1
  99. package/dist/rules/requireJsdoc.cjs +557 -384
  100. package/dist/rules/requireJsdoc.cjs.map +1 -1
  101. package/dist/rules/requireParam.cjs +526 -336
  102. package/dist/rules/requireParam.cjs.map +1 -1
  103. package/dist/rules/requireParamDescription.cjs +80 -55
  104. package/dist/rules/requireParamDescription.cjs.map +1 -1
  105. package/dist/rules/requireParamName.cjs +50 -32
  106. package/dist/rules/requireParamName.cjs.map +1 -1
  107. package/dist/rules/requireParamType.cjs +80 -55
  108. package/dist/rules/requireParamType.cjs.map +1 -1
  109. package/dist/rules/requireProperty.cjs +42 -31
  110. package/dist/rules/requireProperty.cjs.map +1 -1
  111. package/dist/rules/requirePropertyDescription.cjs +25 -17
  112. package/dist/rules/requirePropertyDescription.cjs.map +1 -1
  113. package/dist/rules/requirePropertyName.cjs +25 -17
  114. package/dist/rules/requirePropertyName.cjs.map +1 -1
  115. package/dist/rules/requirePropertyType.cjs +25 -17
  116. package/dist/rules/requirePropertyType.cjs.map +1 -1
  117. package/dist/rules/requireReturns.cjs +203 -125
  118. package/dist/rules/requireReturns.cjs.map +1 -1
  119. package/dist/rules/requireReturnsCheck.cjs +103 -60
  120. package/dist/rules/requireReturnsCheck.cjs.map +1 -1
  121. package/dist/rules/requireReturnsDescription.cjs +54 -39
  122. package/dist/rules/requireReturnsDescription.cjs.map +1 -1
  123. package/dist/rules/requireReturnsType.cjs +50 -32
  124. package/dist/rules/requireReturnsType.cjs.map +1 -1
  125. package/dist/rules/requireTemplate.cjs +178 -119
  126. package/dist/rules/requireTemplate.cjs.map +1 -1
  127. package/dist/rules/requireThrows.cjs +95 -61
  128. package/dist/rules/requireThrows.cjs.map +1 -1
  129. package/dist/rules/requireYields.cjs +166 -106
  130. package/dist/rules/requireYields.cjs.map +1 -1
  131. package/dist/rules/requireYieldsCheck.cjs +152 -96
  132. package/dist/rules/requireYieldsCheck.cjs.map +1 -1
  133. package/dist/rules/sortTags.cjs +444 -258
  134. package/dist/rules/sortTags.cjs.map +1 -1
  135. package/dist/rules/tagLines.cjs +266 -179
  136. package/dist/rules/tagLines.cjs.map +1 -1
  137. package/dist/rules/textEscaping.cjs +127 -92
  138. package/dist/rules/textEscaping.cjs.map +1 -1
  139. package/dist/rules/validTypes.cjs +265 -252
  140. package/dist/rules/validTypes.cjs.map +1 -1
  141. package/dist/tagNames.cjs +170 -134
  142. package/dist/tagNames.cjs.map +1 -1
  143. package/dist/utils/hasReturnValue.cjs +474 -246
  144. package/dist/utils/hasReturnValue.cjs.map +1 -1
  145. package/package.json +24 -40
  146. package/src/WarnSettings.js +34 -0
  147. package/src/alignTransform.js +358 -0
  148. package/src/defaultTagOrder.js +169 -0
  149. package/src/exportParser.js +978 -0
  150. package/src/getDefaultTagStructureForMode.js +969 -0
  151. package/src/getJsdocProcessorPlugin.js +672 -0
  152. package/src/index.js +530 -0
  153. package/src/iterateJsdoc.js +2518 -0
  154. package/src/jsdocUtils.js +1896 -0
  155. package/src/rules/checkAccess.js +45 -0
  156. package/src/rules/checkAlignment.js +63 -0
  157. package/src/rules/checkExamples.js +589 -0
  158. package/src/rules/checkIndentation.js +75 -0
  159. package/src/rules/checkLineAlignment.js +372 -0
  160. package/src/rules/checkParamNames.js +474 -0
  161. package/src/rules/checkPropertyNames.js +152 -0
  162. package/src/rules/checkSyntax.js +30 -0
  163. package/src/rules/checkTagNames.js +314 -0
  164. package/src/rules/checkTemplateNames.js +204 -0
  165. package/src/rules/checkTypes.js +535 -0
  166. package/src/rules/checkValues.js +248 -0
  167. package/src/rules/convertToJsdocComments.js +398 -0
  168. package/src/rules/emptyTags.js +98 -0
  169. package/src/rules/implementsOnClasses.js +64 -0
  170. package/src/rules/importsAsDependencies.js +133 -0
  171. package/src/rules/informativeDocs.js +189 -0
  172. package/src/rules/linesBeforeBlock.js +134 -0
  173. package/src/rules/matchDescription.js +286 -0
  174. package/src/rules/matchName.js +151 -0
  175. package/src/rules/multilineBlocks.js +493 -0
  176. package/src/rules/noBadBlocks.js +119 -0
  177. package/src/rules/noBlankBlockDescriptions.js +69 -0
  178. package/src/rules/noBlankBlocks.js +53 -0
  179. package/src/rules/noDefaults.js +85 -0
  180. package/src/rules/noMissingSyntax.js +195 -0
  181. package/src/rules/noMultiAsterisks.js +134 -0
  182. package/src/rules/noRestrictedSyntax.js +91 -0
  183. package/src/rules/noTypes.js +93 -0
  184. package/src/rules/noUndefinedTypes.js +543 -0
  185. package/src/rules/requireAsteriskPrefix.js +190 -0
  186. package/src/rules/requireDescription.js +161 -0
  187. package/src/rules/requireDescriptionCompleteSentence.js +335 -0
  188. package/src/rules/requireExample.js +118 -0
  189. package/src/rules/requireFileOverview.js +154 -0
  190. package/src/rules/requireHyphenBeforeParamDescription.js +176 -0
  191. package/src/rules/requireJsdoc.js +743 -0
  192. package/src/rules/requireParam.js +602 -0
  193. package/src/rules/requireParamDescription.js +89 -0
  194. package/src/rules/requireParamName.js +55 -0
  195. package/src/rules/requireParamType.js +89 -0
  196. package/src/rules/requireProperty.js +48 -0
  197. package/src/rules/requirePropertyDescription.js +25 -0
  198. package/src/rules/requirePropertyName.js +25 -0
  199. package/src/rules/requirePropertyType.js +25 -0
  200. package/src/rules/requireReturns.js +238 -0
  201. package/src/rules/requireReturnsCheck.js +145 -0
  202. package/src/rules/requireReturnsDescription.js +59 -0
  203. package/src/rules/requireReturnsType.js +51 -0
  204. package/src/rules/requireTemplate.js +201 -0
  205. package/src/rules/requireThrows.js +111 -0
  206. package/src/rules/requireYields.js +216 -0
  207. package/src/rules/requireYieldsCheck.js +208 -0
  208. package/src/rules/sortTags.js +558 -0
  209. package/src/rules/tagLines.js +359 -0
  210. package/src/rules/textEscaping.js +154 -0
  211. package/src/rules/validTypes.js +401 -0
  212. package/src/tagNames.js +238 -0
  213. package/src/utils/hasReturnValue.js +572 -0
  214. package/dist/WarnSettings.js +0 -20
  215. package/dist/WarnSettings.js.map +0 -1
  216. package/dist/_virtual/rolldown_runtime.cjs +0 -32
  217. package/dist/_virtual/rolldown_runtime.js +0 -11
  218. package/dist/alignTransform.js +0 -241
  219. package/dist/alignTransform.js.map +0 -1
  220. package/dist/defaultTagOrder.js +0 -134
  221. package/dist/defaultTagOrder.js.map +0 -1
  222. package/dist/exportParser.js +0 -518
  223. package/dist/exportParser.js.map +0 -1
  224. package/dist/getDefaultTagStructureForMode.js +0 -188
  225. package/dist/getDefaultTagStructureForMode.js.map +0 -1
  226. package/dist/getJsdocProcessorPlugin.d.cts +0 -70
  227. package/dist/getJsdocProcessorPlugin.d.cts.map +0 -1
  228. package/dist/getJsdocProcessorPlugin.js +0 -383
  229. package/dist/getJsdocProcessorPlugin.js.map +0 -1
  230. package/dist/index.d.cts +0 -22
  231. package/dist/index.d.cts.map +0 -1
  232. package/dist/index.js +0 -425
  233. package/dist/index.js.map +0 -1
  234. package/dist/iterateJsdoc.d.cts +0 -471
  235. package/dist/iterateJsdoc.d.cts.map +0 -1
  236. package/dist/iterateJsdoc.js +0 -1617
  237. package/dist/iterateJsdoc.js.map +0 -1
  238. package/dist/jsdocUtils.js +0 -1123
  239. package/dist/jsdocUtils.js.map +0 -1
  240. package/dist/rules/checkAccess.js +0 -33
  241. package/dist/rules/checkAccess.js.map +0 -1
  242. package/dist/rules/checkAlignment.js +0 -47
  243. package/dist/rules/checkAlignment.js.map +0 -1
  244. package/dist/rules/checkExamples.js +0 -348
  245. package/dist/rules/checkExamples.js.map +0 -1
  246. package/dist/rules/checkIndentation.js +0 -59
  247. package/dist/rules/checkIndentation.js.map +0 -1
  248. package/dist/rules/checkLineAlignment.js +0 -229
  249. package/dist/rules/checkLineAlignment.js.map +0 -1
  250. package/dist/rules/checkParamNames.js +0 -237
  251. package/dist/rules/checkParamNames.js.map +0 -1
  252. package/dist/rules/checkPropertyNames.js +0 -88
  253. package/dist/rules/checkPropertyNames.js.map +0 -1
  254. package/dist/rules/checkSyntax.js +0 -25
  255. package/dist/rules/checkSyntax.js.map +0 -1
  256. package/dist/rules/checkTagNames.js +0 -191
  257. package/dist/rules/checkTagNames.js.map +0 -1
  258. package/dist/rules/checkTemplateNames.js +0 -124
  259. package/dist/rules/checkTemplateNames.js.map +0 -1
  260. package/dist/rules/checkTypes.js +0 -299
  261. package/dist/rules/checkTypes.js.map +0 -1
  262. package/dist/rules/checkValues.js +0 -103
  263. package/dist/rules/checkValues.js.map +0 -1
  264. package/dist/rules/convertToJsdocComments.js +0 -231
  265. package/dist/rules/convertToJsdocComments.js.map +0 -1
  266. package/dist/rules/emptyTags.js +0 -67
  267. package/dist/rules/emptyTags.js.map +0 -1
  268. package/dist/rules/implementsOnClasses.js +0 -40
  269. package/dist/rules/implementsOnClasses.js.map +0 -1
  270. package/dist/rules/importsAsDependencies.js +0 -68
  271. package/dist/rules/importsAsDependencies.js.map +0 -1
  272. package/dist/rules/informativeDocs.js +0 -110
  273. package/dist/rules/informativeDocs.js.map +0 -1
  274. package/dist/rules/linesBeforeBlock.js +0 -75
  275. package/dist/rules/linesBeforeBlock.js.map +0 -1
  276. package/dist/rules/matchDescription.js +0 -167
  277. package/dist/rules/matchDescription.js.map +0 -1
  278. package/dist/rules/matchName.js +0 -77
  279. package/dist/rules/matchName.js.map +0 -1
  280. package/dist/rules/multilineBlocks.js +0 -245
  281. package/dist/rules/multilineBlocks.js.map +0 -1
  282. package/dist/rules/noBadBlocks.js +0 -68
  283. package/dist/rules/noBadBlocks.js.map +0 -1
  284. package/dist/rules/noBlankBlockDescriptions.js +0 -41
  285. package/dist/rules/noBlankBlockDescriptions.js.map +0 -1
  286. package/dist/rules/noBlankBlocks.js +0 -30
  287. package/dist/rules/noBlankBlocks.js.map +0 -1
  288. package/dist/rules/noDefaults.js +0 -56
  289. package/dist/rules/noDefaults.js.map +0 -1
  290. package/dist/rules/noMissingSyntax.js +0 -126
  291. package/dist/rules/noMissingSyntax.js.map +0 -1
  292. package/dist/rules/noMultiAsterisks.js +0 -58
  293. package/dist/rules/noMultiAsterisks.js.map +0 -1
  294. package/dist/rules/noRestrictedSyntax.js +0 -49
  295. package/dist/rules/noRestrictedSyntax.js.map +0 -1
  296. package/dist/rules/noTypes.js +0 -65
  297. package/dist/rules/noTypes.js.map +0 -1
  298. package/dist/rules/noUndefinedTypes.js +0 -303
  299. package/dist/rules/noUndefinedTypes.js.map +0 -1
  300. package/dist/rules/requireAsteriskPrefix.js +0 -112
  301. package/dist/rules/requireAsteriskPrefix.js.map +0 -1
  302. package/dist/rules/requireDescription.js +0 -95
  303. package/dist/rules/requireDescription.js.map +0 -1
  304. package/dist/rules/requireDescriptionCompleteSentence.js +0 -220
  305. package/dist/rules/requireDescriptionCompleteSentence.js.map +0 -1
  306. package/dist/rules/requireExample.js +0 -77
  307. package/dist/rules/requireExample.js.map +0 -1
  308. package/dist/rules/requireFileOverview.js +0 -81
  309. package/dist/rules/requireFileOverview.js.map +0 -1
  310. package/dist/rules/requireHyphenBeforeParamDescription.js +0 -89
  311. package/dist/rules/requireHyphenBeforeParamDescription.js.map +0 -1
  312. package/dist/rules/requireJsdoc.js +0 -404
  313. package/dist/rules/requireJsdoc.js.map +0 -1
  314. package/dist/rules/requireParam.js +0 -344
  315. package/dist/rules/requireParam.js.map +0 -1
  316. package/dist/rules/requireParamDescription.js +0 -59
  317. package/dist/rules/requireParamDescription.js.map +0 -1
  318. package/dist/rules/requireParamName.js +0 -36
  319. package/dist/rules/requireParamName.js.map +0 -1
  320. package/dist/rules/requireParamType.js +0 -59
  321. package/dist/rules/requireParamType.js.map +0 -1
  322. package/dist/rules/requireProperty.js +0 -35
  323. package/dist/rules/requireProperty.js.map +0 -1
  324. package/dist/rules/requirePropertyDescription.js +0 -21
  325. package/dist/rules/requirePropertyDescription.js.map +0 -1
  326. package/dist/rules/requirePropertyName.js +0 -21
  327. package/dist/rules/requirePropertyName.js.map +0 -1
  328. package/dist/rules/requirePropertyType.js +0 -21
  329. package/dist/rules/requirePropertyType.js.map +0 -1
  330. package/dist/rules/requireReturns.js +0 -131
  331. package/dist/rules/requireReturns.js.map +0 -1
  332. package/dist/rules/requireReturnsCheck.js +0 -66
  333. package/dist/rules/requireReturnsCheck.js.map +0 -1
  334. package/dist/rules/requireReturnsDescription.js +0 -43
  335. package/dist/rules/requireReturnsDescription.js.map +0 -1
  336. package/dist/rules/requireReturnsType.js +0 -36
  337. package/dist/rules/requireReturnsType.js.map +0 -1
  338. package/dist/rules/requireTemplate.js +0 -122
  339. package/dist/rules/requireTemplate.js.map +0 -1
  340. package/dist/rules/requireThrows.js +0 -67
  341. package/dist/rules/requireThrows.js.map +0 -1
  342. package/dist/rules/requireYields.js +0 -115
  343. package/dist/rules/requireYields.js.map +0 -1
  344. package/dist/rules/requireYieldsCheck.js +0 -105
  345. package/dist/rules/requireYieldsCheck.js.map +0 -1
  346. package/dist/rules/sortTags.js +0 -262
  347. package/dist/rules/sortTags.js.map +0 -1
  348. package/dist/rules/tagLines.js +0 -183
  349. package/dist/rules/tagLines.js.map +0 -1
  350. package/dist/rules/textEscaping.js +0 -102
  351. package/dist/rules/textEscaping.js.map +0 -1
  352. package/dist/rules/validTypes.js +0 -259
  353. package/dist/rules/validTypes.js.map +0 -1
  354. package/dist/tagNames.js +0 -144
  355. package/dist/tagNames.js.map +0 -1
  356. package/dist/utils/hasReturnValue.js +0 -265
  357. package/dist/utils/hasReturnValue.js.map +0 -1
@@ -1,1626 +1,2086 @@
1
- Object.defineProperty(exports, '__esModule', { value: true });
2
- const require_rolldown_runtime = require('./_virtual/rolldown_runtime.cjs');
3
- const require_hasReturnValue = require('./utils/hasReturnValue.cjs');
4
- const require_jsdocUtils = require('./jsdocUtils.cjs');
5
- const __es_joy_jsdoccomment = require_rolldown_runtime.__toESM(require("@es-joy/jsdoccomment"));
6
- const comment_parser = require_rolldown_runtime.__toESM(require("comment-parser"));
7
- const esquery = require_rolldown_runtime.__toESM(require("esquery"));
1
+ "use strict";
2
+
3
+ Object.defineProperty(exports, "__esModule", {
4
+ value: true
5
+ });
6
+ exports.default = iterateJsdoc;
7
+ exports.getSettings = void 0;
8
+ Object.defineProperty(exports, "parseComment", {
9
+ enumerable: true,
10
+ get: function () {
11
+ return _jsdoccomment.parseComment;
12
+ }
13
+ });
14
+ var jsdocUtils = _interopRequireWildcard(require("./jsdocUtils.cjs"));
15
+ var _jsdoccomment = require("@es-joy/jsdoccomment");
16
+ var _commentParser = require("comment-parser");
17
+ var _esquery = _interopRequireDefault(require("esquery"));
18
+ function _interopRequireDefault(e) { return e && e.__esModule ? e : { default: e }; }
19
+ 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); }
20
+ /**
21
+ * @typedef {number} Integer
22
+ */
8
23
 
9
- //#region src/iterateJsdoc.js
10
- /**
11
- * @typedef {number} Integer
12
- */
13
- /**
14
- * @typedef {import('@es-joy/jsdoccomment').JsdocBlockWithInline} JsdocBlockWithInline
15
- */
16
24
  /**
17
- * @typedef {{
18
- * disallowName?: string,
19
- * allowName?: string,
20
- * context?: string,
21
- * comment?: string,
22
- * tags?: string[],
23
- * replacement?: string,
24
- * minimum?: Integer,
25
- * message?: string,
26
- * forceRequireReturn?: boolean
27
- * }} ContextObject
28
- */
25
+ * @typedef {import('@es-joy/jsdoccomment').JsdocBlockWithInline} JsdocBlockWithInline
26
+ */
27
+
29
28
  /**
30
- * @typedef {string|ContextObject} Context
31
- */
29
+ * @typedef {{
30
+ * disallowName?: string,
31
+ * allowName?: string,
32
+ * context?: string,
33
+ * comment?: string,
34
+ * tags?: string[],
35
+ * replacement?: string,
36
+ * minimum?: Integer,
37
+ * message?: string,
38
+ * forceRequireReturn?: boolean
39
+ * }} ContextObject
40
+ */
41
+ /**
42
+ * @typedef {string|ContextObject} Context
43
+ */
44
+
32
45
  /**
33
- * @callback CheckJsdoc
34
- * @param {{
35
- * lastIndex?: Integer,
36
- * isFunctionContext?: boolean,
37
- * selector?: string,
38
- * comment?: string
39
- * }} info
40
- * @param {null|((jsdoc: import('@es-joy/jsdoccomment').JsdocBlockWithInline) => boolean|undefined)} handler
41
- * @param {import('eslint').Rule.Node} node
42
- * @returns {void}
43
- */
46
+ * @callback CheckJsdoc
47
+ * @param {{
48
+ * lastIndex?: Integer,
49
+ * isFunctionContext?: boolean,
50
+ * selector?: string,
51
+ * comment?: string
52
+ * }} info
53
+ * @param {null|((jsdoc: import('@es-joy/jsdoccomment').JsdocBlockWithInline) => boolean|undefined)} handler
54
+ * @param {import('eslint').Rule.Node} node
55
+ * @returns {void}
56
+ */
57
+
44
58
  /**
45
- * @callback ForEachPreferredTag
46
- * @param {string} tagName
47
- * @param {(
48
- * matchingJsdocTag: import('@es-joy/jsdoccomment').JsdocTagWithInline,
49
- * targetTagName: string
50
- * ) => void} arrayHandler
51
- * @param {boolean} [skipReportingBlockedTag]
52
- * @returns {void}
53
- */
59
+ * @callback ForEachPreferredTag
60
+ * @param {string} tagName
61
+ * @param {(
62
+ * matchingJsdocTag: import('@es-joy/jsdoccomment').JsdocTagWithInline,
63
+ * targetTagName: string
64
+ * ) => void} arrayHandler
65
+ * @param {boolean} [skipReportingBlockedTag]
66
+ * @returns {void}
67
+ */
68
+
54
69
  /**
55
- * @callback ReportSettings
56
- * @param {string} message
57
- * @returns {void}
58
- */
70
+ * @callback ReportSettings
71
+ * @param {string} message
72
+ * @returns {void}
73
+ */
74
+
59
75
  /**
60
- * @callback ParseClosureTemplateTag
61
- * @param {import('comment-parser').Spec} tag
62
- * @returns {string[]}
63
- */
76
+ * @callback ParseClosureTemplateTag
77
+ * @param {import('comment-parser').Spec} tag
78
+ * @returns {string[]}
79
+ */
80
+
64
81
  /**
65
- * @callback GetPreferredTagNameObject
66
- * @param {{
67
- * tagName: string
68
- * }} cfg
69
- * @returns {string|false|{
70
- * message: string;
71
- * replacement?: string|undefined
72
- * }|{
73
- * blocked: true,
74
- * tagName: string
75
- * }}
76
- */
82
+ * @callback GetPreferredTagNameObject
83
+ * @param {{
84
+ * tagName: string
85
+ * }} cfg
86
+ * @returns {string|false|{
87
+ * message: string;
88
+ * replacement?: string|undefined
89
+ * }|{
90
+ * blocked: true,
91
+ * tagName: string
92
+ * }}
93
+ */
94
+
77
95
  /**
78
- * @typedef {{
79
- * forEachPreferredTag: ForEachPreferredTag,
80
- * reportSettings: ReportSettings,
81
- * parseClosureTemplateTag: ParseClosureTemplateTag,
82
- * getPreferredTagNameObject: GetPreferredTagNameObject,
83
- * pathDoesNotBeginWith: import('./jsdocUtils.js').PathDoesNotBeginWith
84
- * }} BasicUtils
85
- */
96
+ * @typedef {{
97
+ * forEachPreferredTag: ForEachPreferredTag,
98
+ * reportSettings: ReportSettings,
99
+ * parseClosureTemplateTag: ParseClosureTemplateTag,
100
+ * getPreferredTagNameObject: GetPreferredTagNameObject,
101
+ * pathDoesNotBeginWith: import('./jsdocUtils.js').PathDoesNotBeginWith
102
+ * }} BasicUtils
103
+ */
104
+
86
105
  /**
87
- * @callback IsIteratingFunction
88
- * @returns {boolean}
89
- */
106
+ * @callback IsIteratingFunction
107
+ * @returns {boolean}
108
+ */
109
+
90
110
  /**
91
- * @callback IsVirtualFunction
92
- * @returns {boolean}
93
- */
111
+ * @callback IsVirtualFunction
112
+ * @returns {boolean}
113
+ */
114
+
94
115
  /**
95
- * @callback Stringify
96
- * @param {import('comment-parser').Block} tagBlock
97
- * @param {boolean} [specRewire]
98
- * @returns {string}
99
- */
116
+ * @callback Stringify
117
+ * @param {import('comment-parser').Block} tagBlock
118
+ * @param {boolean} [specRewire]
119
+ * @returns {string}
120
+ */
121
+
100
122
  /**
101
- * @callback ReportJSDoc
102
- * @param {string} msg
103
- * @param {null|import('comment-parser').Spec|{line: Integer, column?: Integer}} [tag]
104
- * @param {(() => void)|null} [handler]
105
- * @param {boolean} [specRewire]
106
- * @param {undefined|{
107
- * [key: string]: string
108
- * }} [data]
109
- */
123
+ * @callback ReportJSDoc
124
+ * @param {string} msg
125
+ * @param {null|import('comment-parser').Spec|{line: Integer, column?: Integer}} [tag]
126
+ * @param {(() => void)|null} [handler]
127
+ * @param {boolean} [specRewire]
128
+ * @param {undefined|{
129
+ * [key: string]: string
130
+ * }} [data]
131
+ */
132
+
110
133
  /**
111
- * @callback GetRegexFromString
112
- * @param {string} str
113
- * @param {string} [requiredFlags]
114
- * @returns {RegExp}
115
- */
134
+ * @callback GetRegexFromString
135
+ * @param {string} str
136
+ * @param {string} [requiredFlags]
137
+ * @returns {RegExp}
138
+ */
139
+
116
140
  /**
117
- * @callback GetTagDescription
118
- * @param {import('comment-parser').Spec} tg
119
- * @param {boolean} [returnArray]
120
- * @returns {string[]|string}
121
- */
141
+ * @callback GetTagDescription
142
+ * @param {import('comment-parser').Spec} tg
143
+ * @param {boolean} [returnArray]
144
+ * @returns {string[]|string}
145
+ */
146
+
122
147
  /**
123
- * @callback SetTagDescription
124
- * @param {import('comment-parser').Spec} tg
125
- * @param {RegExp} matcher
126
- * @param {(description: string) => string} setter
127
- * @returns {Integer}
128
- */
148
+ * @callback SetTagDescription
149
+ * @param {import('comment-parser').Spec} tg
150
+ * @param {RegExp} matcher
151
+ * @param {(description: string) => string} setter
152
+ * @returns {Integer}
153
+ */
154
+
129
155
  /**
130
- * @callback GetDescription
131
- * @returns {{
132
- * description: string,
133
- * descriptions: string[],
134
- * lastDescriptionLine: Integer
135
- * }}
136
- */
156
+ * @callback GetDescription
157
+ * @returns {{
158
+ * description: string,
159
+ * descriptions: string[],
160
+ * lastDescriptionLine: Integer
161
+ * }}
162
+ */
163
+
137
164
  /**
138
- * @callback SetBlockDescription
139
- * @param {(
140
- * info: {
141
- * delimiter: string,
142
- * postDelimiter: string,
143
- * start: string
144
- * },
145
- * seedTokens: (
146
- * tokens?: Partial<import('comment-parser').Tokens>
147
- * ) => import('comment-parser').Tokens,
148
- * descLines: string[]
149
- * ) => import('comment-parser').Line[]} setter
150
- * @returns {void}
151
- */
165
+ * @callback SetBlockDescription
166
+ * @param {(
167
+ * info: {
168
+ * delimiter: string,
169
+ * postDelimiter: string,
170
+ * start: string
171
+ * },
172
+ * seedTokens: (
173
+ * tokens?: Partial<import('comment-parser').Tokens>
174
+ * ) => import('comment-parser').Tokens,
175
+ * descLines: string[]
176
+ * ) => import('comment-parser').Line[]} setter
177
+ * @returns {void}
178
+ */
179
+
152
180
  /**
153
- * @callback SetDescriptionLines
154
- * @param {RegExp} matcher
155
- * @param {(description: string) => string} setter
156
- * @returns {Integer}
157
- */
181
+ * @callback SetDescriptionLines
182
+ * @param {RegExp} matcher
183
+ * @param {(description: string) => string} setter
184
+ * @returns {Integer}
185
+ */
186
+
158
187
  /**
159
- * @callback ChangeTag
160
- * @param {import('comment-parser').Spec} tag
161
- * @param {...Partial<import('comment-parser').Tokens>} tokens
162
- * @returns {void}
163
- */
188
+ * @callback ChangeTag
189
+ * @param {import('comment-parser').Spec} tag
190
+ * @param {...Partial<import('comment-parser').Tokens>} tokens
191
+ * @returns {void}
192
+ */
193
+
164
194
  /**
165
- * @callback SetTag
166
- * @param {import('comment-parser').Spec & {
167
- * line: Integer
168
- * }} tag
169
- * @param {Partial<import('comment-parser').Tokens>} [tokens]
170
- * @returns {void}
171
- */
195
+ * @callback SetTag
196
+ * @param {import('comment-parser').Spec & {
197
+ * line: Integer
198
+ * }} tag
199
+ * @param {Partial<import('comment-parser').Tokens>} [tokens]
200
+ * @returns {void}
201
+ */
202
+
172
203
  /**
173
- * @callback RemoveTag
174
- * @param {Integer} tagIndex
175
- * @param {{
176
- * removeEmptyBlock?: boolean,
177
- * tagSourceOffset?: Integer
178
- * }} [cfg]
179
- * @returns {void}
180
- */
204
+ * @callback RemoveTag
205
+ * @param {Integer} tagIndex
206
+ * @param {{
207
+ * removeEmptyBlock?: boolean,
208
+ * tagSourceOffset?: Integer
209
+ * }} [cfg]
210
+ * @returns {void}
211
+ */
212
+
181
213
  /**
182
- * @callback AddTag
183
- * @param {string} targetTagName
184
- * @param {Integer} [number]
185
- * @param {import('comment-parser').Tokens|{}} [tokens]
186
- * @returns {void}
187
- */
214
+ * @callback AddTag
215
+ * @param {string} targetTagName
216
+ * @param {Integer} [number]
217
+ * @param {import('comment-parser').Tokens|{}} [tokens]
218
+ * @returns {void}
219
+ */
220
+
188
221
  /**
189
- * @callback GetFirstLine
190
- * @returns {Integer|undefined}
191
- */
222
+ * @callback GetFirstLine
223
+ * @returns {Integer|undefined}
224
+ */
225
+
192
226
  /**
193
- * @typedef {(
194
- * tokens?: Partial<import('comment-parser').Tokens> | undefined
195
- * ) => import('comment-parser').Tokens} SeedTokens
196
- */
227
+ * @typedef {(
228
+ * tokens?: Partial<import('comment-parser').Tokens> | undefined
229
+ * ) => import('comment-parser').Tokens} SeedTokens
230
+ */
231
+
197
232
  /**
198
- * Sets tokens to empty string.
199
- * @callback EmptyTokens
200
- * @param {import('comment-parser').Tokens} tokens
201
- * @returns {void}
202
- */
233
+ * Sets tokens to empty string.
234
+ * @callback EmptyTokens
235
+ * @param {import('comment-parser').Tokens} tokens
236
+ * @returns {void}
237
+ */
238
+
203
239
  /**
204
- * @callback AddLine
205
- * @param {Integer} sourceIndex
206
- * @param {Partial<import('comment-parser').Tokens>} tokens
207
- * @returns {void}
208
- */
240
+ * @callback AddLine
241
+ * @param {Integer} sourceIndex
242
+ * @param {Partial<import('comment-parser').Tokens>} tokens
243
+ * @returns {void}
244
+ */
245
+
209
246
  /**
210
- * @callback AddLines
211
- * @param {Integer} tagIndex
212
- * @param {Integer} tagSourceOffset
213
- * @param {Integer} numLines
214
- * @returns {void}
215
- */
247
+ * @callback AddLines
248
+ * @param {Integer} tagIndex
249
+ * @param {Integer} tagSourceOffset
250
+ * @param {Integer} numLines
251
+ * @returns {void}
252
+ */
253
+
216
254
  /**
217
- * @callback MakeMultiline
218
- * @returns {void}
219
- */
255
+ * @callback MakeMultiline
256
+ * @returns {void}
257
+ */
258
+
220
259
  /**
221
- * @callback GetFunctionParameterNames
222
- * @param {boolean} [useDefaultObjectProperties]
223
- * @returns {import('./jsdocUtils.js').ParamNameInfo[]}
224
- */
260
+ * @callback GetFunctionParameterNames
261
+ * @param {boolean} [useDefaultObjectProperties]
262
+ * @returns {import('./jsdocUtils.js').ParamNameInfo[]}
263
+ */
264
+
225
265
  /**
226
- * @callback HasParams
227
- * @returns {Integer}
228
- */
266
+ * @callback HasParams
267
+ * @returns {Integer}
268
+ */
269
+
229
270
  /**
230
- * @callback IsGenerator
231
- * @returns {boolean}
232
- */
271
+ * @callback IsGenerator
272
+ * @returns {boolean}
273
+ */
274
+
233
275
  /**
234
- * @callback IsConstructor
235
- * @returns {boolean}
236
- */
276
+ * @callback IsConstructor
277
+ * @returns {boolean}
278
+ */
279
+
237
280
  /**
238
- * @callback GetJsdocTagsDeep
239
- * @param {string} tagName
240
- * @returns {false|{
241
- * idx: Integer,
242
- * name: string,
243
- * type: string
244
- * }[]}
245
- */
281
+ * @callback GetJsdocTagsDeep
282
+ * @param {string} tagName
283
+ * @returns {false|{
284
+ * idx: Integer,
285
+ * name: string,
286
+ * type: string
287
+ * }[]}
288
+ */
289
+
246
290
  /**
247
- * @callback GetPreferredTagName
248
- * @param {{
249
- * tagName: string,
250
- * skipReportingBlockedTag?: boolean,
251
- * allowObjectReturn?: boolean,
252
- * defaultMessage?: string
253
- * }} cfg
254
- * @returns {string|undefined|false|{
255
- * message: string;
256
- * replacement?: string|undefined;
257
- * }|{
258
- * blocked: true,
259
- * tagName: string
260
- * }}
261
- */
291
+ * @callback GetPreferredTagName
292
+ * @param {{
293
+ * tagName: string,
294
+ * skipReportingBlockedTag?: boolean,
295
+ * allowObjectReturn?: boolean,
296
+ * defaultMessage?: string
297
+ * }} cfg
298
+ * @returns {string|undefined|false|{
299
+ * message: string;
300
+ * replacement?: string|undefined;
301
+ * }|{
302
+ * blocked: true,
303
+ * tagName: string
304
+ * }}
305
+ */
306
+
262
307
  /**
263
- * @callback IsValidTag
264
- * @param {string} name
265
- * @param {string[]} definedTags
266
- * @returns {boolean}
267
- */
308
+ * @callback IsValidTag
309
+ * @param {string} name
310
+ * @param {string[]} definedTags
311
+ * @returns {boolean}
312
+ */
313
+
268
314
  /**
269
- * @callback HasATag
270
- * @param {string[]} names
271
- * @returns {boolean}
272
- */
315
+ * @callback HasATag
316
+ * @param {string[]} names
317
+ * @returns {boolean}
318
+ */
319
+
273
320
  /**
274
- * @callback HasTag
275
- * @param {string} name
276
- * @returns {boolean}
277
- */
321
+ * @callback HasTag
322
+ * @param {string} name
323
+ * @returns {boolean}
324
+ */
325
+
278
326
  /**
279
- * @callback ComparePaths
280
- * @param {string} name
281
- * @returns {(otherPathName: string) => boolean}
282
- */
327
+ * @callback ComparePaths
328
+ * @param {string} name
329
+ * @returns {(otherPathName: string) => boolean}
330
+ */
331
+
283
332
  /**
284
- * @callback DropPathSegmentQuotes
285
- * @param {string} name
286
- * @returns {string}
287
- */
333
+ * @callback DropPathSegmentQuotes
334
+ * @param {string} name
335
+ * @returns {string}
336
+ */
337
+
288
338
  /**
289
- * @callback AvoidDocs
290
- * @returns {boolean}
291
- */
339
+ * @callback AvoidDocs
340
+ * @returns {boolean}
341
+ */
342
+
292
343
  /**
293
- * @callback TagMightHaveNamePositionTypePosition
294
- * @param {string} tagName
295
- * @param {import('./getDefaultTagStructureForMode.js').
296
- * TagStructure[]} [otherModeMaps]
297
- * @returns {boolean|{otherMode: true}}
298
- */
344
+ * @callback TagMightHaveNamePositionTypePosition
345
+ * @param {string} tagName
346
+ * @param {import('./getDefaultTagStructureForMode.js').
347
+ * TagStructure[]} [otherModeMaps]
348
+ * @returns {boolean|{otherMode: true}}
349
+ */
350
+
299
351
  /**
300
- * @callback TagMustHave
301
- * @param {string} tagName
302
- * @param {import('./getDefaultTagStructureForMode.js').
303
- * TagStructure[]} otherModeMaps
304
- * @returns {boolean|{
305
- * otherMode: false
306
- * }}
307
- */
352
+ * @callback TagMustHave
353
+ * @param {string} tagName
354
+ * @param {import('./getDefaultTagStructureForMode.js').
355
+ * TagStructure[]} otherModeMaps
356
+ * @returns {boolean|{
357
+ * otherMode: false
358
+ * }}
359
+ */
360
+
308
361
  /**
309
- * @callback TagMissingRequiredTypeOrNamepath
310
- * @param {import('comment-parser').Spec} tag
311
- * @param {import('./getDefaultTagStructureForMode.js').
312
- * TagStructure[]} otherModeMaps
313
- * @returns {boolean|{
314
- * otherMode: false
315
- * }}
316
- */
362
+ * @callback TagMissingRequiredTypeOrNamepath
363
+ * @param {import('comment-parser').Spec} tag
364
+ * @param {import('./getDefaultTagStructureForMode.js').
365
+ * TagStructure[]} otherModeMaps
366
+ * @returns {boolean|{
367
+ * otherMode: false
368
+ * }}
369
+ */
370
+
317
371
  /**
318
- * @callback IsNamepathX
319
- * @param {string} tagName
320
- * @returns {boolean}
321
- */
372
+ * @callback IsNamepathX
373
+ * @param {string} tagName
374
+ * @returns {boolean}
375
+ */
376
+
322
377
  /**
323
- * @callback GetTagStructureForMode
324
- * @param {import('./jsdocUtils.js').ParserMode} mde
325
- * @returns {import('./getDefaultTagStructureForMode.js').TagStructure}
326
- */
378
+ * @callback GetTagStructureForMode
379
+ * @param {import('./jsdocUtils.js').ParserMode} mde
380
+ * @returns {import('./getDefaultTagStructureForMode.js').TagStructure}
381
+ */
382
+
327
383
  /**
328
- * @callback MayBeUndefinedTypeTag
329
- * @param {import('comment-parser').Spec} tag
330
- * @returns {boolean}
331
- */
384
+ * @callback MayBeUndefinedTypeTag
385
+ * @param {import('comment-parser').Spec} tag
386
+ * @returns {boolean}
387
+ */
388
+
332
389
  /**
333
- * @callback HasValueOrExecutorHasNonEmptyResolveValue
334
- * @param {boolean} anyPromiseAsReturn
335
- * @param {boolean} [allBranches]
336
- * @returns {boolean}
337
- */
390
+ * @callback HasValueOrExecutorHasNonEmptyResolveValue
391
+ * @param {boolean} anyPromiseAsReturn
392
+ * @param {boolean} [allBranches]
393
+ * @returns {boolean}
394
+ */
395
+
338
396
  /**
339
- * @callback HasYieldValue
340
- * @returns {boolean}
341
- */
397
+ * @callback HasYieldValue
398
+ * @returns {boolean}
399
+ */
400
+
342
401
  /**
343
- * @callback HasYieldReturnValue
344
- * @returns {boolean}
345
- */
402
+ * @callback HasYieldReturnValue
403
+ * @returns {boolean}
404
+ */
405
+
346
406
  /**
347
- * @callback HasThrowValue
348
- * @returns {boolean}
349
- */
407
+ * @callback HasThrowValue
408
+ * @returns {boolean}
409
+ */
410
+
350
411
  /**
351
- * @callback IsAsync
352
- * @returns {boolean|undefined}
353
- */
412
+ * @callback IsAsync
413
+ * @returns {boolean|undefined}
414
+ */
415
+
354
416
  /**
355
- * @callback GetTags
356
- * @param {string} tagName
357
- * @returns {import('comment-parser').Spec[]}
358
- */
417
+ * @callback GetTags
418
+ * @param {string} tagName
419
+ * @returns {import('comment-parser').Spec[]}
420
+ */
421
+
359
422
  /**
360
- * @callback GetPresentTags
361
- * @param {string[]} tagList
362
- * @returns {import('@es-joy/jsdoccomment').JsdocTagWithInline[]}
363
- */
423
+ * @callback GetPresentTags
424
+ * @param {string[]} tagList
425
+ * @returns {import('@es-joy/jsdoccomment').JsdocTagWithInline[]}
426
+ */
427
+
364
428
  /**
365
- * @callback FilterTags
366
- * @param {(tag: import('@es-joy/jsdoccomment').JsdocTagWithInline) => boolean} filter
367
- * @returns {import('@es-joy/jsdoccomment').JsdocTagWithInline[]}
368
- */
429
+ * @callback FilterTags
430
+ * @param {(tag: import('@es-joy/jsdoccomment').JsdocTagWithInline) => boolean} filter
431
+ * @returns {import('@es-joy/jsdoccomment').JsdocTagWithInline[]}
432
+ */
433
+
369
434
  /**
370
- * @callback FilterAllTags
371
- * @param {(tag: (import('comment-parser').Spec|
372
- * import('@es-joy/jsdoccomment').JsdocInlineTagNoType)) => boolean} filter
373
- * @returns {(import('comment-parser').Spec|
374
- * import('@es-joy/jsdoccomment').JsdocInlineTagNoType)[]}
375
- */
435
+ * @callback FilterAllTags
436
+ * @param {(tag: (import('comment-parser').Spec|
437
+ * import('@es-joy/jsdoccomment').JsdocInlineTagNoType)) => boolean} filter
438
+ * @returns {(import('comment-parser').Spec|
439
+ * import('@es-joy/jsdoccomment').JsdocInlineTagNoType)[]}
440
+ */
441
+
376
442
  /**
377
- * @callback GetTagsByType
378
- * @param {import('comment-parser').Spec[]} tags
379
- * @returns {{
380
- * tagsWithNames: import('comment-parser').Spec[],
381
- * tagsWithoutNames: import('comment-parser').Spec[]
382
- * }}
383
- */
443
+ * @callback GetTagsByType
444
+ * @param {import('comment-parser').Spec[]} tags
445
+ * @returns {{
446
+ * tagsWithNames: import('comment-parser').Spec[],
447
+ * tagsWithoutNames: import('comment-parser').Spec[]
448
+ * }}
449
+ */
450
+
384
451
  /**
385
- * @callback HasOptionTag
386
- * @param {string} tagName
387
- * @returns {boolean}
388
- */
452
+ * @callback HasOptionTag
453
+ * @param {string} tagName
454
+ * @returns {boolean}
455
+ */
456
+
389
457
  /**
390
- * @callback GetClassNode
391
- * @returns {Node|null}
392
- */
458
+ * @callback GetClassNode
459
+ * @returns {Node|null}
460
+ */
461
+
393
462
  /**
394
- * @callback GetClassJsdoc
395
- * @returns {null|JsdocBlockWithInline}
396
- */
463
+ * @callback GetClassJsdoc
464
+ * @returns {null|JsdocBlockWithInline}
465
+ */
466
+
397
467
  /**
398
- * @callback ClassHasTag
399
- * @param {string} tagName
400
- * @returns {boolean}
401
- */
468
+ * @callback ClassHasTag
469
+ * @param {string} tagName
470
+ * @returns {boolean}
471
+ */
472
+
402
473
  /**
403
- * @callback FindContext
404
- * @param {Context[]} contexts
405
- * @param {string|undefined} comment
406
- * @returns {{
407
- * foundContext: Context|undefined,
408
- * contextStr: string
409
- * }}
410
- */
474
+ * @callback FindContext
475
+ * @param {Context[]} contexts
476
+ * @param {string|undefined} comment
477
+ * @returns {{
478
+ * foundContext: Context|undefined,
479
+ * contextStr: string
480
+ * }}
481
+ */
482
+
411
483
  /**
412
- * @typedef {BasicUtils & {
413
- * isIteratingFunction: IsIteratingFunction,
414
- * isVirtualFunction: IsVirtualFunction,
415
- * stringify: Stringify,
416
- * reportJSDoc: ReportJSDoc,
417
- * getRegexFromString: GetRegexFromString,
418
- * getTagDescription: GetTagDescription,
419
- * setTagDescription: SetTagDescription,
420
- * getDescription: GetDescription,
421
- * setBlockDescription: SetBlockDescription,
422
- * setDescriptionLines: SetDescriptionLines,
423
- * changeTag: ChangeTag,
424
- * setTag: SetTag,
425
- * removeTag: RemoveTag,
426
- * addTag: AddTag,
427
- * getFirstLine: GetFirstLine,
428
- * seedTokens: SeedTokens,
429
- * emptyTokens: EmptyTokens,
430
- * addLine: AddLine,
431
- * addLines: AddLines,
432
- * makeMultiline: MakeMultiline,
433
- * flattenRoots: import('./jsdocUtils.js').FlattenRoots,
434
- * getFunctionParameterNames: GetFunctionParameterNames,
435
- * hasParams: HasParams,
436
- * isGenerator: IsGenerator,
437
- * isConstructor: IsConstructor,
438
- * getJsdocTagsDeep: GetJsdocTagsDeep,
439
- * getPreferredTagName: GetPreferredTagName,
440
- * isValidTag: IsValidTag,
441
- * hasATag: HasATag,
442
- * hasTag: HasTag,
443
- * comparePaths: ComparePaths,
444
- * dropPathSegmentQuotes: DropPathSegmentQuotes,
445
- * avoidDocs: AvoidDocs,
446
- * tagMightHaveNamePosition: TagMightHaveNamePositionTypePosition,
447
- * tagMightHaveTypePosition: TagMightHaveNamePositionTypePosition,
448
- * tagMustHaveNamePosition: TagMustHave,
449
- * tagMustHaveTypePosition: TagMustHave,
450
- * tagMissingRequiredTypeOrNamepath: TagMissingRequiredTypeOrNamepath,
451
- * isNamepathDefiningTag: IsNamepathX,
452
- * isNamepathReferencingTag: IsNamepathX,
453
- * isNamepathOrUrlReferencingTag: IsNamepathX,
454
- * tagMightHaveNamepath: IsNamepathX,
455
- * getTagStructureForMode: GetTagStructureForMode,
456
- * mayBeUndefinedTypeTag: MayBeUndefinedTypeTag,
457
- * hasValueOrExecutorHasNonEmptyResolveValue: HasValueOrExecutorHasNonEmptyResolveValue,
458
- * hasYieldValue: HasYieldValue,
459
- * hasYieldReturnValue: HasYieldReturnValue,
460
- * hasThrowValue: HasThrowValue,
461
- * isAsync: IsAsync,
462
- * getTags: GetTags,
463
- * getPresentTags: GetPresentTags,
464
- * filterTags: FilterTags,
465
- * filterAllTags: FilterAllTags,
466
- * getTagsByType: GetTagsByType,
467
- * hasOptionTag: HasOptionTag,
468
- * getClassNode: GetClassNode,
469
- * getClassJsdoc: GetClassJsdoc,
470
- * classHasTag: ClassHasTag,
471
- * findContext: FindContext
472
- * }} Utils
473
- */
474
- const { rewireSpecs, seedTokens } = comment_parser.util;
484
+ * @typedef {BasicUtils & {
485
+ * isIteratingFunction: IsIteratingFunction,
486
+ * isVirtualFunction: IsVirtualFunction,
487
+ * stringify: Stringify,
488
+ * reportJSDoc: ReportJSDoc,
489
+ * getRegexFromString: GetRegexFromString,
490
+ * getTagDescription: GetTagDescription,
491
+ * setTagDescription: SetTagDescription,
492
+ * getDescription: GetDescription,
493
+ * setBlockDescription: SetBlockDescription,
494
+ * setDescriptionLines: SetDescriptionLines,
495
+ * changeTag: ChangeTag,
496
+ * setTag: SetTag,
497
+ * removeTag: RemoveTag,
498
+ * addTag: AddTag,
499
+ * getFirstLine: GetFirstLine,
500
+ * seedTokens: SeedTokens,
501
+ * emptyTokens: EmptyTokens,
502
+ * addLine: AddLine,
503
+ * addLines: AddLines,
504
+ * makeMultiline: MakeMultiline,
505
+ * flattenRoots: import('./jsdocUtils.js').FlattenRoots,
506
+ * getFunctionParameterNames: GetFunctionParameterNames,
507
+ * hasParams: HasParams,
508
+ * isGenerator: IsGenerator,
509
+ * isConstructor: IsConstructor,
510
+ * getJsdocTagsDeep: GetJsdocTagsDeep,
511
+ * getPreferredTagName: GetPreferredTagName,
512
+ * isValidTag: IsValidTag,
513
+ * hasATag: HasATag,
514
+ * hasTag: HasTag,
515
+ * comparePaths: ComparePaths,
516
+ * dropPathSegmentQuotes: DropPathSegmentQuotes,
517
+ * avoidDocs: AvoidDocs,
518
+ * tagMightHaveNamePosition: TagMightHaveNamePositionTypePosition,
519
+ * tagMightHaveTypePosition: TagMightHaveNamePositionTypePosition,
520
+ * tagMustHaveNamePosition: TagMustHave,
521
+ * tagMustHaveTypePosition: TagMustHave,
522
+ * tagMissingRequiredTypeOrNamepath: TagMissingRequiredTypeOrNamepath,
523
+ * isNamepathDefiningTag: IsNamepathX,
524
+ * isNamepathReferencingTag: IsNamepathX,
525
+ * isNamepathOrUrlReferencingTag: IsNamepathX,
526
+ * tagMightHaveNamepath: IsNamepathX,
527
+ * getTagStructureForMode: GetTagStructureForMode,
528
+ * mayBeUndefinedTypeTag: MayBeUndefinedTypeTag,
529
+ * hasValueOrExecutorHasNonEmptyResolveValue: HasValueOrExecutorHasNonEmptyResolveValue,
530
+ * hasYieldValue: HasYieldValue,
531
+ * hasYieldReturnValue: HasYieldReturnValue,
532
+ * hasThrowValue: HasThrowValue,
533
+ * isAsync: IsAsync,
534
+ * getTags: GetTags,
535
+ * getPresentTags: GetPresentTags,
536
+ * filterTags: FilterTags,
537
+ * filterAllTags: FilterAllTags,
538
+ * getTagsByType: GetTagsByType,
539
+ * hasOptionTag: HasOptionTag,
540
+ * getClassNode: GetClassNode,
541
+ * getClassJsdoc: GetClassJsdoc,
542
+ * classHasTag: ClassHasTag,
543
+ * findContext: FindContext
544
+ * }} Utils
545
+ */
546
+
547
+ const {
548
+ rewireSpecs,
549
+ seedTokens
550
+ } = _commentParser.util;
551
+
552
+ // todo: Change these `any` types once importing types properly.
553
+
475
554
  /**
476
- * Should use ESLint rule's typing.
477
- * @typedef {import('eslint').Rule.RuleMetaData} EslintRuleMeta
478
- */
555
+ * Should use ESLint rule's typing.
556
+ * @typedef {import('eslint').Rule.RuleMetaData} EslintRuleMeta
557
+ */
558
+
479
559
  /**
480
- * A plain object for tracking state as needed by rules across iterations.
481
- * @typedef {{
482
- * globalTags: {},
483
- * hasDuplicates: {
484
- * [key: string]: boolean
485
- * },
486
- * selectorMap: {
487
- * [selector: string]: {
488
- * [comment: string]: Integer
489
- * }
490
- * },
491
- * hasTag: {
492
- * [key: string]: boolean
493
- * },
494
- * hasNonComment: number,
495
- * hasNonCommentBeforeTag: {
496
- * [key: string]: boolean|number
497
- * }
498
- * }} StateObject
499
- */
560
+ * A plain object for tracking state as needed by rules across iterations.
561
+ * @typedef {{
562
+ * globalTags: {},
563
+ * hasDuplicates: {
564
+ * [key: string]: boolean
565
+ * },
566
+ * selectorMap: {
567
+ * [selector: string]: {
568
+ * [comment: string]: Integer
569
+ * }
570
+ * },
571
+ * hasTag: {
572
+ * [key: string]: boolean
573
+ * },
574
+ * hasNonComment: number,
575
+ * hasNonCommentBeforeTag: {
576
+ * [key: string]: boolean|number
577
+ * }
578
+ * }} StateObject
579
+ */
580
+
500
581
  /**
501
- * The Node AST as supplied by the parser.
502
- * @typedef {import('eslint').Rule.Node} Node
503
- */
504
- const globalState = /* @__PURE__ */ new Map();
505
- /**
506
- * @param {import('eslint').Rule.RuleContext} context
507
- * @param {{
508
- * tagNamePreference?: import('./jsdocUtils.js').TagNamePreference,
509
- * mode?: import('./jsdocUtils.js').ParserMode
510
- * }} cfg
511
- * @returns {BasicUtils}
582
+ * The Node AST as supplied by the parser.
583
+ * @typedef {import('eslint').Rule.Node} Node
584
+ */
585
+
586
+ /*
587
+ const {
588
+ align as commentAlign,
589
+ flow: commentFlow,
590
+ indent: commentIndent,
591
+ } = transforms;
512
592
  */
513
- const getBasicUtils = (context, { mode, tagNamePreference }) => {
514
- /** @type {BasicUtils} */
515
- const utils = {};
516
- /** @type {ReportSettings} */
517
- utils.reportSettings = (message) => {
518
- context.report({
519
- loc: {
520
- end: {
521
- column: 1,
522
- line: 1
523
- },
524
- start: {
525
- column: 1,
526
- line: 1
527
- }
528
- },
529
- message
530
- });
531
- };
532
- /** @type {ParseClosureTemplateTag} */
533
- utils.parseClosureTemplateTag = (tag) => {
534
- return require_jsdocUtils.parseClosureTemplateTag(tag);
535
- };
536
- utils.pathDoesNotBeginWith = require_jsdocUtils.pathDoesNotBeginWith;
537
- /** @type {GetPreferredTagNameObject} */
538
- utils.getPreferredTagNameObject = ({ tagName }) => {
539
- const ret = require_jsdocUtils.getPreferredTagNameSimple(tagName, mode, tagNamePreference, context);
540
- const isObject = ret && typeof ret === "object";
541
- if (ret === false || isObject && !ret.replacement) return {
542
- blocked: true,
543
- tagName
544
- };
545
- return ret;
546
- };
547
- return utils;
593
+
594
+ const globalState = new Map();
595
+ /**
596
+ * @param {import('eslint').Rule.RuleContext} context
597
+ * @param {{
598
+ * tagNamePreference?: import('./jsdocUtils.js').TagNamePreference,
599
+ * mode?: import('./jsdocUtils.js').ParserMode
600
+ * }} cfg
601
+ * @returns {BasicUtils}
602
+ */
603
+ const getBasicUtils = (context, {
604
+ mode,
605
+ tagNamePreference
606
+ }) => {
607
+ /** @type {BasicUtils} */
608
+ const utils = {};
609
+
610
+ /** @type {ReportSettings} */
611
+ utils.reportSettings = message => {
612
+ context.report({
613
+ loc: {
614
+ end: {
615
+ column: 1,
616
+ line: 1
617
+ },
618
+ start: {
619
+ column: 1,
620
+ line: 1
621
+ }
622
+ },
623
+ message
624
+ });
625
+ };
626
+
627
+ /** @type {ParseClosureTemplateTag} */
628
+ utils.parseClosureTemplateTag = tag => {
629
+ return jsdocUtils.parseClosureTemplateTag(tag);
630
+ };
631
+ utils.pathDoesNotBeginWith = jsdocUtils.pathDoesNotBeginWith;
632
+
633
+ /** @type {GetPreferredTagNameObject} */
634
+ utils.getPreferredTagNameObject = ({
635
+ tagName
636
+ }) => {
637
+ const ret = jsdocUtils.getPreferredTagNameSimple(tagName, /** @type {import('./jsdocUtils.js').ParserMode} */mode, tagNamePreference, context);
638
+ const isObject = ret && typeof ret === 'object';
639
+ if (ret === false || isObject && !ret.replacement) {
640
+ return {
641
+ blocked: true,
642
+ tagName
643
+ };
644
+ }
645
+ return ret;
646
+ };
647
+ return utils;
548
648
  };
649
+
549
650
  /**
550
- * @callback Report
551
- * @param {string} message
552
- * @param {import('eslint').Rule.ReportFixer|null} [fix]
553
- * @param {null|
554
- * {line?: Integer, column?: Integer}|
555
- * import('comment-parser').Spec & {line?: Integer}
556
- * } [jsdocLoc]
557
- * @param {undefined|{
558
- * [key: string]: string
559
- * }} [data]
560
- * @returns {void}
561
- */
651
+ * @callback Report
652
+ * @param {string} message
653
+ * @param {import('eslint').Rule.ReportFixer|null} [fix]
654
+ * @param {null|
655
+ * {line?: Integer, column?: Integer}|
656
+ * import('comment-parser').Spec & {line?: Integer}
657
+ * } [jsdocLoc]
658
+ * @param {undefined|{
659
+ * [key: string]: string
660
+ * }} [data]
661
+ * @returns {void}
662
+ */
663
+
562
664
  /**
563
- * @param {Node|null} node
564
- * @param {JsdocBlockWithInline} jsdoc
565
- * @param {import('eslint').AST.Token} jsdocNode
566
- * @param {Settings} settings
567
- * @param {Report} report
568
- * @param {import('eslint').Rule.RuleContext} context
569
- * @param {import('eslint').SourceCode} sc
570
- * @param {boolean|undefined} iteratingAll
571
- * @param {RuleConfig} ruleConfig
572
- * @param {string} indent
573
- * @returns {Utils}
574
- */
665
+ * @param {Node|null} node
666
+ * @param {JsdocBlockWithInline} jsdoc
667
+ * @param {import('eslint').AST.Token} jsdocNode
668
+ * @param {Settings} settings
669
+ * @param {Report} report
670
+ * @param {import('eslint').Rule.RuleContext} context
671
+ * @param {import('eslint').SourceCode} sc
672
+ * @param {boolean|undefined} iteratingAll
673
+ * @param {RuleConfig} ruleConfig
674
+ * @param {string} indent
675
+ * @returns {Utils}
676
+ */
575
677
  const getUtils = (node, jsdoc, jsdocNode, settings, report, context, sc, iteratingAll, ruleConfig, indent) => {
576
- const ancestors = node ? sc.getAncestors ? sc.getAncestors(node) : context.getAncestors() : [];
577
- /* c8 ignore next -- Fallback to deprecated method */
578
- const { sourceCode = context.getSourceCode() } = context;
579
- const utils = getBasicUtils(context, settings);
580
- const { augmentsExtendsReplacesDocs, ignoreReplacesDocs, implementsReplacesDocs, maxLines, minLines, mode, overrideReplacesDocs, tagNamePreference } = settings;
581
- /** @type {IsIteratingFunction} */
582
- utils.isIteratingFunction = () => {
583
- return !iteratingAll || [
584
- "ArrowFunctionExpression",
585
- "FunctionDeclaration",
586
- "FunctionExpression",
587
- "MethodDefinition"
588
- ].includes(String(node && node.type));
589
- };
590
- /** @type {IsVirtualFunction} */
591
- utils.isVirtualFunction = () => {
592
- return Boolean(iteratingAll) && utils.hasATag([
593
- "callback",
594
- "function",
595
- "func",
596
- "method"
597
- ]);
598
- };
599
- /** @type {Stringify} */
600
- utils.stringify = (tagBlock, specRewire) => {
601
- let block;
602
- if (specRewire) block = rewireSpecs(tagBlock);
603
- return (0, comment_parser.stringify)(specRewire ? block : tagBlock);
604
- };
605
- /** @type {ReportJSDoc} */
606
- utils.reportJSDoc = (msg, tag, handler, specRewire, data) => {
607
- report(msg, handler ? (fixer) => {
608
- handler();
609
- const replacement = utils.stringify(jsdoc, specRewire);
610
- if (!replacement) {
611
- const text = sourceCode.getText();
612
- const lastLineBreakPos = text.slice(0, jsdocNode.range[0]).search(/\n[ \t]*$/v);
613
- if (lastLineBreakPos > -1) return fixer.removeRange([lastLineBreakPos, jsdocNode.range[1]]);
614
- return fixer.removeRange(/\s/v.test(text.charAt(jsdocNode.range[1])) ? [jsdocNode.range[0], jsdocNode.range[1] + 1] : jsdocNode.range);
615
- }
616
- return fixer.replaceText(jsdocNode, replacement);
617
- } : null, tag, data);
618
- };
619
- /** @type {GetRegexFromString} */
620
- utils.getRegexFromString = (str, requiredFlags) => {
621
- return require_jsdocUtils.getRegexFromString(str, requiredFlags);
622
- };
623
- /** @type {GetTagDescription} */
624
- utils.getTagDescription = (tg, returnArray) => {
625
- return require_jsdocUtils.getTagDescription(tg, returnArray);
626
- };
627
- /** @type {SetTagDescription} */
628
- utils.setTagDescription = (tg, matcher, setter) => {
629
- let finalIdx = 0;
630
- tg.source.some(({ tokens: { description } }, idx) => {
631
- if (description && matcher.test(description)) {
632
- tg.source[idx].tokens.description = setter(description);
633
- finalIdx = idx;
634
- return true;
635
- }
636
- return false;
637
- });
638
- return finalIdx;
639
- };
640
- /** @type {GetDescription} */
641
- utils.getDescription = () => {
642
- /** @type {string[]} */
643
- const descriptions = [];
644
- let lastDescriptionLine = 0;
645
- let tagsBegun = false;
646
- jsdoc.source.some(({ tokens: { description, end, tag } }, idx) => {
647
- if (tag) tagsBegun = true;
648
- if (idx && (tag || end)) {
649
- lastDescriptionLine = idx - 1;
650
- if (!tagsBegun && description) descriptions.push(description);
651
- return true;
652
- }
653
- if (!tagsBegun && (idx || description)) descriptions.push(description || (descriptions.length ? "" : "\n"));
654
- return false;
655
- });
656
- return {
657
- description: descriptions.join("\n"),
658
- descriptions,
659
- lastDescriptionLine
660
- };
661
- };
662
- /** @type {SetBlockDescription} */
663
- utils.setBlockDescription = (setter) => {
664
- /** @type {string[]} */
665
- const descLines = [];
666
- /**
667
- * @type {undefined|Integer}
668
- */
669
- let startIdx;
670
- /**
671
- * @type {undefined|Integer}
672
- */
673
- let endIdx;
674
- /**
675
- * @type {undefined|{
676
- * delimiter: string,
677
- * postDelimiter: string,
678
- * start: string
679
- * }}
680
- */
681
- let info;
682
- jsdoc.source.some(({ tokens: { delimiter, description, end, postDelimiter, start, tag } }, idx) => {
683
- if (delimiter === "/**") return false;
684
- if (startIdx === void 0) {
685
- startIdx = idx;
686
- info = {
687
- delimiter,
688
- postDelimiter,
689
- start
690
- };
691
- }
692
- if (tag || end) {
693
- endIdx = idx;
694
- return true;
695
- }
696
- descLines.push(description);
697
- return false;
698
- });
699
- /* c8 ignore else -- Won't be called if missing */
700
- if (descLines.length) jsdoc.source.splice(
701
- startIdx,
702
- /** @type {Integer} */
703
- endIdx - startIdx,
704
- ...setter(info, seedTokens, descLines)
705
- );
706
- };
707
- /** @type {SetDescriptionLines} */
708
- utils.setDescriptionLines = (matcher, setter) => {
709
- let finalIdx = 0;
710
- jsdoc.source.some(({ tokens: { description, end, tag } }, idx) => {
711
- /* c8 ignore next 3 -- Already checked */
712
- if (idx && (tag || end)) return true;
713
- if (description && matcher.test(description)) {
714
- jsdoc.source[idx].tokens.description = setter(description);
715
- finalIdx = idx;
716
- return true;
717
- }
718
- return false;
719
- });
720
- return finalIdx;
721
- };
722
- /** @type {ChangeTag} */
723
- utils.changeTag = (tag, ...tokens) => {
724
- for (const [idx, src] of tag.source.entries()) src.tokens = {
725
- ...src.tokens,
726
- ...tokens[idx]
727
- };
728
- };
729
- /** @type {SetTag} */
730
- utils.setTag = (tag, tokens) => {
731
- tag.source = [{
732
- number: tag.line,
733
- source: "",
734
- tokens: seedTokens({
735
- delimiter: "*",
736
- postDelimiter: " ",
737
- start: indent + " ",
738
- tag: "@" + tag.tag,
739
- ...tokens
740
- })
741
- }];
742
- };
743
- /** @type {RemoveTag} */
744
- utils.removeTag = (tagIndex, { removeEmptyBlock = false, tagSourceOffset = 0 } = {}) => {
745
- const { source: tagSource } = jsdoc.tags[tagIndex];
746
- /** @type {Integer|undefined} */
747
- let lastIndex;
748
- const firstNumber = jsdoc.source[0].number;
749
- tagSource.some(({ number }, tagIdx) => {
750
- const sourceIndex = jsdoc.source.findIndex(({ number: srcNumber }) => {
751
- return number === srcNumber;
752
- });
753
- // c8 ignore else
754
- if (sourceIndex > -1) {
755
- let spliceCount = 1;
756
- tagSource.slice(tagIdx + 1).some(({ tokens: { end: ending, tag } }) => {
757
- if (!tag && !ending) {
758
- spliceCount++;
759
- return false;
760
- }
761
- return true;
762
- });
763
- const spliceIdx = sourceIndex + tagSourceOffset;
764
- const { delimiter, end } = jsdoc.source[spliceIdx].tokens;
765
- if (spliceIdx === 0 && jsdoc.tags.length >= 2 || !removeEmptyBlock && (end || delimiter === "/**")) {
766
- const { tokens } = jsdoc.source[spliceIdx];
767
- for (const item of [
768
- "postDelimiter",
769
- "tag",
770
- "postTag",
771
- "type",
772
- "postType",
773
- "name",
774
- "postName",
775
- "description"
776
- ]) tokens[item] = "";
777
- } else {
778
- jsdoc.source.splice(spliceIdx, spliceCount - tagSourceOffset + (spliceIdx ? 0 : jsdoc.source.length));
779
- tagSource.splice(tagIdx + tagSourceOffset, spliceCount - tagSourceOffset + (spliceIdx ? 0 : jsdoc.source.length));
780
- }
781
- lastIndex = sourceIndex;
782
- return true;
783
- }
784
- /* c8 ignore next 2 */
785
- return false;
786
- });
787
- for (const [idx, src] of jsdoc.source.slice(lastIndex).entries()) src.number = firstNumber + lastIndex + idx;
788
- };
789
- /** @type {AddTag} */
790
- utils.addTag = (targetTagName, number = (jsdoc.tags[jsdoc.tags.length - 1]?.source[0]?.number ?? jsdoc.source.findIndex(({ tokens: { tag } }) => {
791
- return tag;
792
- }) - 1) + 1, tokens = {}) => {
793
- jsdoc.source.splice(number, 0, {
794
- number,
795
- source: "",
796
- tokens: seedTokens({
797
- delimiter: "*",
798
- postDelimiter: " ",
799
- start: indent + " ",
800
- tag: `@${targetTagName}`,
801
- ...tokens
802
- })
803
- });
804
- for (const src of jsdoc.source.slice(number + 1)) src.number++;
805
- };
806
- /** @type {GetFirstLine} */
807
- utils.getFirstLine = () => {
808
- let firstLine;
809
- for (const { number, tokens: { tag } } of jsdoc.source) if (tag) {
810
- firstLine = number;
811
- break;
812
- }
813
- return firstLine;
814
- };
815
- /** @type {SeedTokens} */
816
- utils.seedTokens = seedTokens;
817
- /** @type {EmptyTokens} */
818
- utils.emptyTokens = (tokens) => {
819
- for (const prop of [
820
- "start",
821
- "postDelimiter",
822
- "tag",
823
- "type",
824
- "postType",
825
- "postTag",
826
- "name",
827
- "postName",
828
- "description",
829
- "end",
830
- "lineEnd"
831
- ]) tokens[prop] = "";
832
- };
833
- /** @type {AddLine} */
834
- utils.addLine = (sourceIndex, tokens) => {
835
- const number = (jsdoc.source[sourceIndex - 1]?.number || 0) + 1;
836
- jsdoc.source.splice(sourceIndex, 0, {
837
- number,
838
- source: "",
839
- tokens: seedTokens(tokens)
840
- });
841
- for (const src of jsdoc.source.slice(number + 1)) src.number++;
842
- };
843
- /** @type {AddLines} */
844
- utils.addLines = (tagIndex, tagSourceOffset, numLines) => {
845
- const { source: tagSource } = jsdoc.tags[tagIndex];
846
- /** @type {Integer|undefined} */
847
- let lastIndex;
848
- const firstNumber = jsdoc.source[0].number;
849
- tagSource.some(({ number }) => {
850
- const makeLine = () => {
851
- return {
852
- number,
853
- source: "",
854
- tokens: seedTokens({
855
- delimiter: "*",
856
- start: indent + " "
857
- })
858
- };
859
- };
860
- const makeLines = () => {
861
- return Array.from({ length: numLines }, makeLine);
862
- };
863
- const sourceIndex = jsdoc.source.findIndex(({ number: srcNumber, tokens: { end } }) => {
864
- return number === srcNumber && !end;
865
- });
866
- // c8 ignore else
867
- if (sourceIndex > -1) {
868
- const lines = makeLines();
869
- jsdoc.source.splice(sourceIndex + tagSourceOffset, 0, ...lines);
870
- lastIndex = sourceIndex;
871
- return true;
872
- }
873
- /* c8 ignore next 2 */
874
- return false;
875
- });
876
- for (const [idx, src] of jsdoc.source.slice(lastIndex).entries()) src.number = firstNumber + lastIndex + idx;
877
- };
878
- /** @type {MakeMultiline} */
879
- utils.makeMultiline = () => {
880
- const { source: [{ tokens }] } = jsdoc;
881
- const { description, lineEnd, name, postDelimiter, tag, type } = tokens;
882
- let { tokens: { postName, postTag, postType } } = jsdoc.source[0];
883
- if (!description) {
884
- if (postName) postName = "";
885
- else if (postType) postType = "";
886
- else if (postTag) postTag = "";
887
- }
888
- utils.emptyTokens(tokens);
889
- utils.addLine(1, {
890
- delimiter: "*",
891
- description: description.trimEnd(),
892
- name,
893
- postDelimiter,
894
- postName,
895
- postTag,
896
- postType,
897
- start: indent + " ",
898
- tag,
899
- type
900
- });
901
- utils.addLine(2, {
902
- end: "*/",
903
- lineEnd,
904
- start: indent + " "
905
- });
906
- };
907
- /**
908
- * @type {import('./jsdocUtils.js').FlattenRoots}
909
- */
910
- utils.flattenRoots = require_jsdocUtils.flattenRoots;
911
- /** @type {GetFunctionParameterNames} */
912
- utils.getFunctionParameterNames = (useDefaultObjectProperties) => {
913
- return require_jsdocUtils.getFunctionParameterNames(node, useDefaultObjectProperties);
914
- };
915
- /** @type {HasParams} */
916
- utils.hasParams = () => {
917
- return require_jsdocUtils.hasParams(node);
918
- };
919
- /** @type {IsGenerator} */
920
- utils.isGenerator = () => {
921
- return node !== null && Boolean(
922
- /**
923
- * @type {import('estree').FunctionDeclaration|
924
- * import('estree').FunctionExpression}
925
- */
926
- node.generator || node.type === "MethodDefinition" && node.value.generator || ["ExportDefaultDeclaration", "ExportNamedDeclaration"].includes(node.type) && node.declaration?.generator
927
- );
928
- };
929
- /** @type {IsConstructor} */
930
- utils.isConstructor = () => {
931
- return require_jsdocUtils.isConstructor(node);
932
- };
933
- /** @type {GetJsdocTagsDeep} */
934
- utils.getJsdocTagsDeep = (tagName) => {
935
- const name = utils.getPreferredTagName({ tagName });
936
- if (!name) return false;
937
- return require_jsdocUtils.getJsdocTagsDeep(jsdoc, name);
938
- };
939
- /** @type {GetPreferredTagName} */
940
- utils.getPreferredTagName = (args) => {
941
- return require_jsdocUtils.getPreferredTagName(jsdoc, {
942
- ...args,
943
- context,
944
- mode,
945
- report,
946
- tagNamePreference
947
- });
948
- };
949
- /** @type {IsValidTag} */
950
- utils.isValidTag = (name, definedTags) => {
951
- return require_jsdocUtils.isValidTag(context, mode, name, definedTags);
952
- };
953
- /** @type {HasATag} */
954
- utils.hasATag = (names) => {
955
- return require_jsdocUtils.hasATag(jsdoc, names);
956
- };
957
- /** @type {HasTag} */
958
- utils.hasTag = (name) => {
959
- return require_jsdocUtils.hasTag(jsdoc, name);
960
- };
961
- /** @type {ComparePaths} */
962
- utils.comparePaths = (name) => {
963
- return require_jsdocUtils.comparePaths(name);
964
- };
965
- /** @type {DropPathSegmentQuotes} */
966
- utils.dropPathSegmentQuotes = (name) => {
967
- return require_jsdocUtils.dropPathSegmentQuotes(name);
968
- };
969
- /** @type {AvoidDocs} */
970
- utils.avoidDocs = () => {
971
- if (ignoreReplacesDocs !== false && (utils.hasTag("ignore") || utils.classHasTag("ignore")) || overrideReplacesDocs !== false && (utils.hasTag("override") || utils.classHasTag("override")) || implementsReplacesDocs !== false && (utils.hasTag("implements") || utils.classHasTag("implements")) || augmentsExtendsReplacesDocs && (utils.hasATag(["augments", "extends"]) || utils.classHasTag("augments") || utils.classHasTag("extends"))) return true;
972
- if (require_jsdocUtils.exemptSpeciaMethods(jsdoc, node, context, ruleConfig.meta.schema)) return true;
973
- const exemptedBy = context.options[0]?.exemptedBy ?? ["inheritDoc", ...mode === "closure" ? [] : ["inheritdoc"]];
974
- if (exemptedBy.length && utils.getPresentTags(exemptedBy).length) return true;
975
- return false;
976
- };
977
- for (const method of ["tagMightHaveNamePosition", "tagMightHaveTypePosition"])
978
- /** @type {TagMightHaveNamePositionTypePosition} */
979
- utils[method] = (tagName, otherModeMaps) => {
980
- const result = require_jsdocUtils.jsdocUtils_exports[method](tagName);
981
- if (result) return true;
982
- if (!otherModeMaps) return false;
983
- const otherResult = otherModeMaps.some((otherModeMap) => {
984
- return require_jsdocUtils.jsdocUtils_exports[method](tagName, otherModeMap);
985
- });
986
- return otherResult ? { otherMode: true } : false;
987
- };
988
- /** @type {TagMissingRequiredTypeOrNamepath} */
989
- utils.tagMissingRequiredTypeOrNamepath = (tagName, otherModeMaps) => {
990
- const result = require_jsdocUtils.tagMissingRequiredTypeOrNamepath(tagName);
991
- if (!result) return false;
992
- const otherResult = otherModeMaps.every((otherModeMap) => {
993
- return require_jsdocUtils.tagMissingRequiredTypeOrNamepath(tagName, otherModeMap);
994
- });
995
- return otherResult ? true : { otherMode: false };
996
- };
997
- for (const method of ["tagMustHaveNamePosition", "tagMustHaveTypePosition"])
998
- /** @type {TagMustHave} */
999
- utils[method] = (tagName, otherModeMaps) => {
1000
- const result = require_jsdocUtils.jsdocUtils_exports[method](tagName);
1001
- if (!result) return false;
1002
- const otherResult = otherModeMaps.every((otherModeMap) => {
1003
- return require_jsdocUtils.jsdocUtils_exports[method](tagName, otherModeMap);
1004
- });
1005
- return otherResult ? true : { otherMode: false };
1006
- };
1007
- for (const method of [
1008
- "isNamepathDefiningTag",
1009
- "isNamepathReferencingTag",
1010
- "isNamepathOrUrlReferencingTag",
1011
- "tagMightHaveNamepath"
1012
- ])
1013
- /** @type {IsNamepathX} */
1014
- utils[method] = (tagName) => {
1015
- return require_jsdocUtils.jsdocUtils_exports[method](tagName);
1016
- };
1017
- /** @type {GetTagStructureForMode} */
1018
- utils.getTagStructureForMode = (mde) => {
1019
- return require_jsdocUtils.getTagStructureForMode(mde, settings.structuredTags);
1020
- };
1021
- /** @type {MayBeUndefinedTypeTag} */
1022
- utils.mayBeUndefinedTypeTag = (tag) => {
1023
- return require_jsdocUtils.mayBeUndefinedTypeTag(tag, settings.mode);
1024
- };
1025
- /** @type {HasValueOrExecutorHasNonEmptyResolveValue} */
1026
- utils.hasValueOrExecutorHasNonEmptyResolveValue = (anyPromiseAsReturn, allBranches) => {
1027
- return require_hasReturnValue.hasValueOrExecutorHasNonEmptyResolveValue(node, anyPromiseAsReturn, allBranches);
1028
- };
1029
- /** @type {HasYieldValue} */
1030
- utils.hasYieldValue = () => {
1031
- if (["ExportDefaultDeclaration", "ExportNamedDeclaration"].includes(
1032
- /** @type {Node} */
1033
- node.type
1034
- )) return require_jsdocUtils.hasYieldValue(
1035
- /** @type {import('estree').ExportNamedDeclaration|import('estree').ExportDefaultDeclaration} */
1036
- node.declaration
1037
- );
1038
- return require_jsdocUtils.hasYieldValue(node);
1039
- };
1040
- /** @type {HasYieldReturnValue} */
1041
- utils.hasYieldReturnValue = () => {
1042
- return require_jsdocUtils.hasYieldValue(node, true);
1043
- };
1044
- /** @type {HasThrowValue} */
1045
- utils.hasThrowValue = () => {
1046
- return require_jsdocUtils.hasThrowValue(node);
1047
- };
1048
- /** @type {IsAsync} */
1049
- utils.isAsync = () => {
1050
- return Boolean(node && "async" in node && node.async);
1051
- };
1052
- /** @type {GetTags} */
1053
- utils.getTags = (tagName) => {
1054
- return require_jsdocUtils.getTags(jsdoc, tagName);
1055
- };
1056
- /** @type {GetPresentTags} */
1057
- utils.getPresentTags = (tagList) => {
1058
- return require_jsdocUtils.filterTags(jsdoc, (tag) => {
1059
- return tagList.includes(tag.tag);
1060
- });
1061
- };
1062
- /** @type {FilterTags} */
1063
- utils.filterTags = (filter) => {
1064
- return require_jsdocUtils.filterTags(jsdoc, (tag) => {
1065
- return filter(tag);
1066
- });
1067
- };
1068
- /** @type {FilterAllTags} */
1069
- utils.filterAllTags = (filter) => {
1070
- const tags = require_jsdocUtils.getAllTags(jsdoc);
1071
- return tags.filter((tag) => {
1072
- return filter(tag);
1073
- });
1074
- };
1075
- /** @type {GetTagsByType} */
1076
- utils.getTagsByType = (tags) => {
1077
- return require_jsdocUtils.getTagsByType(context, mode, tags);
1078
- };
1079
- /** @type {HasOptionTag} */
1080
- utils.hasOptionTag = (tagName) => {
1081
- const { tags } = context.options[0] ?? {};
1082
- return Boolean(tags && tags.includes(tagName));
1083
- };
1084
- /** @type {GetClassNode} */
1085
- utils.getClassNode = () => {
1086
- return [...ancestors, node].reverse().find((parent) => {
1087
- return parent && ["ClassDeclaration", "ClassExpression"].includes(parent.type);
1088
- }) ?? null;
1089
- };
1090
- /** @type {GetClassJsdoc} */
1091
- utils.getClassJsdoc = () => {
1092
- const classNode = utils.getClassNode();
1093
- if (!classNode) return null;
1094
- const classJsdocNode = (0, __es_joy_jsdoccomment.getJSDocComment)(sourceCode, classNode, {
1095
- maxLines,
1096
- minLines
1097
- });
1098
- if (classJsdocNode) return (0, __es_joy_jsdoccomment.parseComment)(classJsdocNode, "");
1099
- return null;
1100
- };
1101
- /** @type {ClassHasTag} */
1102
- utils.classHasTag = (tagName) => {
1103
- const classJsdoc = utils.getClassJsdoc();
1104
- return classJsdoc !== null && require_jsdocUtils.hasTag(classJsdoc, tagName);
1105
- };
1106
- /** @type {ForEachPreferredTag} */
1107
- utils.forEachPreferredTag = (tagName, arrayHandler, skipReportingBlockedTag) => {
1108
- return require_jsdocUtils.forEachPreferredTag(jsdoc, tagName, arrayHandler, {
1109
- context,
1110
- mode,
1111
- report,
1112
- skipReportingBlockedTag,
1113
- tagNamePreference
1114
- });
1115
- };
1116
- /** @type {FindContext} */
1117
- utils.findContext = (contexts, comment) => {
1118
- const foundContext = contexts.find((cntxt) => {
1119
- return typeof cntxt === "string" ? esquery.default.matches(node, esquery.default.parse(cntxt), void 0, { visitorKeys: sourceCode.visitorKeys }) : (!cntxt.context || cntxt.context === "any" || esquery.default.matches(node, esquery.default.parse(cntxt.context), void 0, { visitorKeys: sourceCode.visitorKeys })) && comment === cntxt.comment;
1120
- });
1121
- const contextStr = typeof foundContext === "object" ? foundContext.context ?? "any" : String(foundContext);
1122
- return {
1123
- contextStr,
1124
- foundContext
1125
- };
1126
- };
1127
- return utils;
678
+ const ancestors = /** @type {import('eslint').Rule.Node[]} */node ? sc.getAncestors ? sc.getAncestors(node)
679
+ /* c8 ignore next 4 */ : context.getAncestors() : [];
680
+
681
+ /* c8 ignore next -- Fallback to deprecated method */
682
+ const {
683
+ sourceCode = context.getSourceCode()
684
+ } = context;
685
+ const utils = /** @type {Utils} */getBasicUtils(context, settings);
686
+ const {
687
+ augmentsExtendsReplacesDocs,
688
+ ignoreReplacesDocs,
689
+ implementsReplacesDocs,
690
+ maxLines,
691
+ minLines,
692
+ mode,
693
+ overrideReplacesDocs,
694
+ tagNamePreference
695
+ } = settings;
696
+
697
+ /** @type {IsIteratingFunction} */
698
+ utils.isIteratingFunction = () => {
699
+ return !iteratingAll || ['ArrowFunctionExpression', 'FunctionDeclaration', 'FunctionExpression', 'MethodDefinition'].includes(String(node && node.type));
700
+ };
701
+
702
+ /** @type {IsVirtualFunction} */
703
+ utils.isVirtualFunction = () => {
704
+ return Boolean(iteratingAll) && utils.hasATag(['callback', 'function', 'func', 'method']);
705
+ };
706
+
707
+ /** @type {Stringify} */
708
+ utils.stringify = (tagBlock, specRewire) => {
709
+ let block;
710
+ if (specRewire) {
711
+ block = rewireSpecs(tagBlock);
712
+ }
713
+ return (0, _commentParser.stringify)(/** @type {import('comment-parser').Block} */
714
+ specRewire ? block : tagBlock);
715
+ };
716
+
717
+ /** @type {ReportJSDoc} */
718
+ utils.reportJSDoc = (msg, tag, handler, specRewire, data) => {
719
+ report(msg, handler ? /** @type {import('eslint').Rule.ReportFixer} */fixer => {
720
+ handler();
721
+ const replacement = utils.stringify(jsdoc, specRewire);
722
+ if (!replacement) {
723
+ const text = sourceCode.getText();
724
+ const lastLineBreakPos = text.slice(0, jsdocNode.range[0]).search(/\n[ \t]*$/v);
725
+ if (lastLineBreakPos > -1) {
726
+ return fixer.removeRange([lastLineBreakPos, jsdocNode.range[1]]);
727
+ }
728
+ return fixer.removeRange(/\s/v.test(text.charAt(jsdocNode.range[1])) ? [jsdocNode.range[0], jsdocNode.range[1] + 1] : jsdocNode.range);
729
+ }
730
+ return fixer.replaceText(jsdocNode, replacement);
731
+ } : null, tag, data);
732
+ };
733
+
734
+ /** @type {GetRegexFromString} */
735
+ utils.getRegexFromString = (str, requiredFlags) => {
736
+ return jsdocUtils.getRegexFromString(str, requiredFlags);
737
+ };
738
+
739
+ /** @type {GetTagDescription} */
740
+ utils.getTagDescription = (tg, returnArray) => {
741
+ return jsdocUtils.getTagDescription(tg, returnArray);
742
+ };
743
+
744
+ /** @type {SetTagDescription} */
745
+ utils.setTagDescription = (tg, matcher, setter) => {
746
+ let finalIdx = 0;
747
+ tg.source.some(({
748
+ tokens: {
749
+ description
750
+ }
751
+ }, idx) => {
752
+ if (description && matcher.test(description)) {
753
+ tg.source[idx].tokens.description = setter(description);
754
+ finalIdx = idx;
755
+ return true;
756
+ }
757
+ return false;
758
+ });
759
+ return finalIdx;
760
+ };
761
+
762
+ /** @type {GetDescription} */
763
+ utils.getDescription = () => {
764
+ /** @type {string[]} */
765
+ const descriptions = [];
766
+ let lastDescriptionLine = 0;
767
+ let tagsBegun = false;
768
+ jsdoc.source.some(({
769
+ tokens: {
770
+ description,
771
+ end,
772
+ tag
773
+ }
774
+ }, idx) => {
775
+ if (tag) {
776
+ tagsBegun = true;
777
+ }
778
+ if (idx && (tag || end)) {
779
+ lastDescriptionLine = idx - 1;
780
+ if (!tagsBegun && description) {
781
+ descriptions.push(description);
782
+ }
783
+ return true;
784
+ }
785
+ if (!tagsBegun && (idx || description)) {
786
+ descriptions.push(description || (descriptions.length ? '' : '\n'));
787
+ }
788
+ return false;
789
+ });
790
+ return {
791
+ description: descriptions.join('\n'),
792
+ descriptions,
793
+ lastDescriptionLine
794
+ };
795
+ };
796
+
797
+ /** @type {SetBlockDescription} */
798
+ utils.setBlockDescription = setter => {
799
+ /** @type {string[]} */
800
+ const descLines = [];
801
+ /**
802
+ * @type {undefined|Integer}
803
+ */
804
+ let startIdx;
805
+ /**
806
+ * @type {undefined|Integer}
807
+ */
808
+ let endIdx;
809
+
810
+ /**
811
+ * @type {undefined|{
812
+ * delimiter: string,
813
+ * postDelimiter: string,
814
+ * start: string
815
+ * }}
816
+ */
817
+ let info;
818
+ jsdoc.source.some(({
819
+ tokens: {
820
+ delimiter,
821
+ description,
822
+ end,
823
+ postDelimiter,
824
+ start,
825
+ tag
826
+ }
827
+ }, idx) => {
828
+ if (delimiter === '/**') {
829
+ return false;
830
+ }
831
+ if (startIdx === undefined) {
832
+ startIdx = idx;
833
+ info = {
834
+ delimiter,
835
+ postDelimiter,
836
+ start
837
+ };
838
+ }
839
+ if (tag || end) {
840
+ endIdx = idx;
841
+ return true;
842
+ }
843
+ descLines.push(description);
844
+ return false;
845
+ });
846
+
847
+ /* c8 ignore else -- Won't be called if missing */
848
+ if (descLines.length) {
849
+ jsdoc.source.splice(/** @type {Integer} */startIdx, /** @type {Integer} */endIdx - (/** @type {Integer} */startIdx), ...setter(
850
+ /**
851
+ * @type {{
852
+ * delimiter: string,
853
+ * postDelimiter: string,
854
+ * start: string
855
+ * }}
856
+ */
857
+ info, seedTokens, descLines));
858
+ }
859
+ };
860
+
861
+ /** @type {SetDescriptionLines} */
862
+ utils.setDescriptionLines = (matcher, setter) => {
863
+ let finalIdx = 0;
864
+ jsdoc.source.some(({
865
+ tokens: {
866
+ description,
867
+ end,
868
+ tag
869
+ }
870
+ }, idx) => {
871
+ /* c8 ignore next 3 -- Already checked */
872
+ if (idx && (tag || end)) {
873
+ return true;
874
+ }
875
+ if (description && matcher.test(description)) {
876
+ jsdoc.source[idx].tokens.description = setter(description);
877
+ finalIdx = idx;
878
+ return true;
879
+ }
880
+ return false;
881
+ });
882
+ return finalIdx;
883
+ };
884
+
885
+ /** @type {ChangeTag} */
886
+ utils.changeTag = (tag, ...tokens) => {
887
+ for (const [idx, src] of tag.source.entries()) {
888
+ src.tokens = {
889
+ ...src.tokens,
890
+ ...tokens[idx]
891
+ };
892
+ }
893
+ };
894
+
895
+ /** @type {SetTag} */
896
+ utils.setTag = (tag, tokens) => {
897
+ tag.source = [{
898
+ number: tag.line,
899
+ // Or tag.source[0].number?
900
+ source: '',
901
+ tokens: seedTokens({
902
+ delimiter: '*',
903
+ postDelimiter: ' ',
904
+ start: indent + ' ',
905
+ tag: '@' + tag.tag,
906
+ ...tokens
907
+ })
908
+ }];
909
+ };
910
+
911
+ /** @type {RemoveTag} */
912
+ utils.removeTag = (tagIndex, {
913
+ removeEmptyBlock = false,
914
+ tagSourceOffset = 0
915
+ } = {}) => {
916
+ const {
917
+ source: tagSource
918
+ } = jsdoc.tags[tagIndex];
919
+ /** @type {Integer|undefined} */
920
+ let lastIndex;
921
+ const firstNumber = jsdoc.source[0].number;
922
+ tagSource.some(({
923
+ number
924
+ }, tagIdx) => {
925
+ const sourceIndex = jsdoc.source.findIndex(({
926
+ number: srcNumber
927
+ }) => {
928
+ return number === srcNumber;
929
+ });
930
+ // c8 ignore else
931
+ if (sourceIndex > -1) {
932
+ let spliceCount = 1;
933
+ tagSource.slice(tagIdx + 1).some(({
934
+ tokens: {
935
+ end: ending,
936
+ tag
937
+ }
938
+ }) => {
939
+ if (!tag && !ending) {
940
+ spliceCount++;
941
+ return false;
942
+ }
943
+ return true;
944
+ });
945
+ const spliceIdx = sourceIndex + tagSourceOffset;
946
+ const {
947
+ delimiter,
948
+ end
949
+ } = jsdoc.source[spliceIdx].tokens;
950
+ if (spliceIdx === 0 && jsdoc.tags.length >= 2 || !removeEmptyBlock && (end || delimiter === '/**')) {
951
+ const {
952
+ tokens
953
+ } = jsdoc.source[spliceIdx];
954
+ for (const item of ['postDelimiter', 'tag', 'postTag', 'type', 'postType', 'name', 'postName', 'description']) {
955
+ tokens[(
956
+ /**
957
+ * @type {"postDelimiter"|"tag"|"type"|"postType"|
958
+ * "postTag"|"name"|"postName"|"description"}
959
+ */
960
+ item)] = '';
961
+ }
962
+ } else {
963
+ jsdoc.source.splice(spliceIdx, spliceCount - tagSourceOffset + (spliceIdx ? 0 : jsdoc.source.length));
964
+ tagSource.splice(tagIdx + tagSourceOffset, spliceCount - tagSourceOffset + (spliceIdx ? 0 : jsdoc.source.length));
965
+ }
966
+ lastIndex = sourceIndex;
967
+ return true;
968
+ }
969
+ /* c8 ignore next 2 */
970
+ // eslint-disable-next-line @stylistic/padding-line-between-statements -- c8
971
+ return false;
972
+ });
973
+ for (const [idx, src] of jsdoc.source.slice(lastIndex).entries()) {
974
+ src.number = firstNumber + (/** @type {Integer} */lastIndex) + idx;
975
+ }
976
+
977
+ // Todo: Once rewiring of tags may be fixed in comment-parser to reflect
978
+ // missing tags, this step should be added here (so that, e.g.,
979
+ // if accessing `jsdoc.tags`, such as to add a new tag, the
980
+ // correct information will be available)
981
+ };
982
+
983
+ /** @type {AddTag} */
984
+ utils.addTag = (targetTagName, number = (jsdoc.tags[jsdoc.tags.length - 1]?.source[0]?.number ?? jsdoc.source.findIndex(({
985
+ tokens: {
986
+ tag
987
+ }
988
+ }) => {
989
+ return tag;
990
+ }) - 1) + 1, tokens = {}) => {
991
+ jsdoc.source.splice(number, 0, {
992
+ number,
993
+ source: '',
994
+ tokens: seedTokens({
995
+ delimiter: '*',
996
+ postDelimiter: ' ',
997
+ start: indent + ' ',
998
+ tag: `@${targetTagName}`,
999
+ ...tokens
1000
+ })
1001
+ });
1002
+ for (const src of jsdoc.source.slice(number + 1)) {
1003
+ src.number++;
1004
+ }
1005
+ };
1006
+
1007
+ /** @type {GetFirstLine} */
1008
+ utils.getFirstLine = () => {
1009
+ let firstLine;
1010
+ for (const {
1011
+ number,
1012
+ tokens: {
1013
+ tag
1014
+ }
1015
+ } of jsdoc.source) {
1016
+ if (tag) {
1017
+ firstLine = number;
1018
+ break;
1019
+ }
1020
+ }
1021
+ return firstLine;
1022
+ };
1023
+
1024
+ /** @type {SeedTokens} */
1025
+ utils.seedTokens = seedTokens;
1026
+
1027
+ /** @type {EmptyTokens} */
1028
+ utils.emptyTokens = tokens => {
1029
+ for (const prop of ['start', 'postDelimiter', 'tag', 'type', 'postType', 'postTag', 'name', 'postName', 'description', 'end', 'lineEnd']) {
1030
+ tokens[(
1031
+ /**
1032
+ * @type {"start"|"postDelimiter"|"tag"|"type"|"postType"|
1033
+ * "postTag"|"name"|"postName"|"description"|"end"|"lineEnd"}
1034
+ */
1035
+ prop)] = '';
1036
+ }
1037
+ };
1038
+
1039
+ /** @type {AddLine} */
1040
+ utils.addLine = (sourceIndex, tokens) => {
1041
+ const number = (jsdoc.source[sourceIndex - 1]?.number || 0) + 1;
1042
+ jsdoc.source.splice(sourceIndex, 0, {
1043
+ number,
1044
+ source: '',
1045
+ tokens: seedTokens(tokens)
1046
+ });
1047
+ for (const src of jsdoc.source.slice(number + 1)) {
1048
+ src.number++;
1049
+ }
1050
+ // If necessary, we can rewire the tags (misnamed method)
1051
+ // rewireSource(jsdoc);
1052
+ };
1053
+
1054
+ /** @type {AddLines} */
1055
+ utils.addLines = (tagIndex, tagSourceOffset, numLines) => {
1056
+ const {
1057
+ source: tagSource
1058
+ } = jsdoc.tags[tagIndex];
1059
+ /** @type {Integer|undefined} */
1060
+ let lastIndex;
1061
+ const firstNumber = jsdoc.source[0].number;
1062
+ tagSource.some(({
1063
+ number
1064
+ }) => {
1065
+ const makeLine = () => {
1066
+ return {
1067
+ number,
1068
+ source: '',
1069
+ tokens: seedTokens({
1070
+ delimiter: '*',
1071
+ start: indent + ' '
1072
+ })
1073
+ };
1074
+ };
1075
+ const makeLines = () => {
1076
+ return Array.from({
1077
+ length: numLines
1078
+ }, makeLine);
1079
+ };
1080
+ const sourceIndex = jsdoc.source.findIndex(({
1081
+ number: srcNumber,
1082
+ tokens: {
1083
+ end
1084
+ }
1085
+ }) => {
1086
+ return number === srcNumber && !end;
1087
+ });
1088
+ // c8 ignore else
1089
+ if (sourceIndex > -1) {
1090
+ const lines = makeLines();
1091
+ jsdoc.source.splice(sourceIndex + tagSourceOffset, 0, ...lines);
1092
+
1093
+ // tagSource.splice(tagIdx + 1, 0, ...makeLines());
1094
+ lastIndex = sourceIndex;
1095
+ return true;
1096
+ }
1097
+ /* c8 ignore next 2 */
1098
+ // eslint-disable-next-line @stylistic/padding-line-between-statements -- c8
1099
+ return false;
1100
+ });
1101
+ for (const [idx, src] of jsdoc.source.slice(lastIndex).entries()) {
1102
+ src.number = firstNumber + (/** @type {Integer} */lastIndex) + idx;
1103
+ }
1104
+ };
1105
+
1106
+ /** @type {MakeMultiline} */
1107
+ utils.makeMultiline = () => {
1108
+ const {
1109
+ source: [{
1110
+ tokens
1111
+ }]
1112
+ } = jsdoc;
1113
+ const {
1114
+ description,
1115
+ lineEnd,
1116
+ name,
1117
+ postDelimiter,
1118
+ tag,
1119
+ type
1120
+ } = tokens;
1121
+ let {
1122
+ tokens: {
1123
+ postName,
1124
+ postTag,
1125
+ postType
1126
+ }
1127
+ } = jsdoc.source[0];
1128
+
1129
+ // Strip trailing leftovers from single line ending
1130
+ if (!description) {
1131
+ if (postName) {
1132
+ postName = '';
1133
+ } else if (postType) {
1134
+ postType = '';
1135
+ } else /* c8 ignore else -- `comment-parser` prevents empty blocks currently per https://github.com/syavorsky/comment-parser/issues/128 */if (postTag) {
1136
+ postTag = '';
1137
+ }
1138
+ }
1139
+ utils.emptyTokens(tokens);
1140
+ utils.addLine(1, {
1141
+ delimiter: '*',
1142
+ // If a description were present, it may have whitespace attached
1143
+ // due to being at the end of the single line
1144
+ description: description.trimEnd(),
1145
+ name,
1146
+ postDelimiter,
1147
+ postName,
1148
+ postTag,
1149
+ postType,
1150
+ start: indent + ' ',
1151
+ tag,
1152
+ type
1153
+ });
1154
+ utils.addLine(2, {
1155
+ end: '*/',
1156
+ lineEnd,
1157
+ start: indent + ' '
1158
+ });
1159
+ };
1160
+
1161
+ /**
1162
+ * @type {import('./jsdocUtils.js').FlattenRoots}
1163
+ */
1164
+ utils.flattenRoots = jsdocUtils.flattenRoots;
1165
+
1166
+ /** @type {GetFunctionParameterNames} */
1167
+ utils.getFunctionParameterNames = useDefaultObjectProperties => {
1168
+ return jsdocUtils.getFunctionParameterNames(node, useDefaultObjectProperties);
1169
+ };
1170
+
1171
+ /** @type {HasParams} */
1172
+ utils.hasParams = () => {
1173
+ return jsdocUtils.hasParams(/** @type {Node} */node);
1174
+ };
1175
+
1176
+ /** @type {IsGenerator} */
1177
+ utils.isGenerator = () => {
1178
+ return node !== null && Boolean(
1179
+ /**
1180
+ * @type {import('estree').FunctionDeclaration|
1181
+ * import('estree').FunctionExpression}
1182
+ */
1183
+ node.generator || node.type === 'MethodDefinition' && node.value.generator || ['ExportDefaultDeclaration', 'ExportNamedDeclaration'].includes(node.type) && /** @type {import('estree').FunctionDeclaration} */
1184
+ (
1185
+ /**
1186
+ * @type {import('estree').ExportNamedDeclaration|
1187
+ * import('estree').ExportDefaultDeclaration}
1188
+ */
1189
+ node.declaration)?.generator);
1190
+ };
1191
+
1192
+ /** @type {IsConstructor} */
1193
+ utils.isConstructor = () => {
1194
+ return jsdocUtils.isConstructor(/** @type {Node} */node);
1195
+ };
1196
+
1197
+ /** @type {GetJsdocTagsDeep} */
1198
+ utils.getJsdocTagsDeep = tagName => {
1199
+ const name = /** @type {string|false} */utils.getPreferredTagName({
1200
+ tagName
1201
+ });
1202
+ if (!name) {
1203
+ return false;
1204
+ }
1205
+ return jsdocUtils.getJsdocTagsDeep(jsdoc, name);
1206
+ };
1207
+
1208
+ /** @type {GetPreferredTagName} */
1209
+ utils.getPreferredTagName = args => {
1210
+ return jsdocUtils.getPreferredTagName(jsdoc, {
1211
+ ...args,
1212
+ context,
1213
+ mode,
1214
+ report,
1215
+ tagNamePreference
1216
+ });
1217
+ };
1218
+
1219
+ /** @type {IsValidTag} */
1220
+ utils.isValidTag = (name, definedTags) => {
1221
+ return jsdocUtils.isValidTag(context, mode, name, definedTags);
1222
+ };
1223
+
1224
+ /** @type {HasATag} */
1225
+ utils.hasATag = names => {
1226
+ return jsdocUtils.hasATag(jsdoc, names);
1227
+ };
1228
+
1229
+ /** @type {HasTag} */
1230
+ utils.hasTag = name => {
1231
+ return jsdocUtils.hasTag(jsdoc, name);
1232
+ };
1233
+
1234
+ /** @type {ComparePaths} */
1235
+ utils.comparePaths = name => {
1236
+ return jsdocUtils.comparePaths(name);
1237
+ };
1238
+
1239
+ /** @type {DropPathSegmentQuotes} */
1240
+ utils.dropPathSegmentQuotes = name => {
1241
+ return jsdocUtils.dropPathSegmentQuotes(name);
1242
+ };
1243
+
1244
+ /** @type {AvoidDocs} */
1245
+ utils.avoidDocs = () => {
1246
+ if (ignoreReplacesDocs !== false && (utils.hasTag('ignore') || utils.classHasTag('ignore')) || overrideReplacesDocs !== false && (utils.hasTag('override') || utils.classHasTag('override')) || implementsReplacesDocs !== false && (utils.hasTag('implements') || utils.classHasTag('implements')) || augmentsExtendsReplacesDocs && (utils.hasATag(['augments', 'extends']) || utils.classHasTag('augments') || utils.classHasTag('extends'))) {
1247
+ return true;
1248
+ }
1249
+ if (jsdocUtils.exemptSpeciaMethods(jsdoc, node, context, /** @type {import('json-schema').JSONSchema4|import('json-schema').JSONSchema4[]} */
1250
+ ruleConfig.meta.schema)) {
1251
+ return true;
1252
+ }
1253
+ const exemptedBy = context.options[0]?.exemptedBy ?? ['inheritDoc', ...(mode === 'closure' ? [] : ['inheritdoc'])];
1254
+ if (exemptedBy.length && utils.getPresentTags(exemptedBy).length) {
1255
+ return true;
1256
+ }
1257
+ return false;
1258
+ };
1259
+ for (const method of ['tagMightHaveNamePosition', 'tagMightHaveTypePosition']) {
1260
+ /** @type {TagMightHaveNamePositionTypePosition} */
1261
+ utils[(/** @type {"tagMightHaveNamePosition"|"tagMightHaveTypePosition"} */
1262
+ method)] = (tagName, otherModeMaps) => {
1263
+ const result = jsdocUtils[(/** @type {"tagMightHaveNamePosition"|"tagMightHaveTypePosition"} */
1264
+ method)](tagName);
1265
+ if (result) {
1266
+ return true;
1267
+ }
1268
+ if (!otherModeMaps) {
1269
+ return false;
1270
+ }
1271
+ const otherResult = otherModeMaps.some(otherModeMap => {
1272
+ return jsdocUtils[(/** @type {"tagMightHaveNamePosition"|"tagMightHaveTypePosition"} */
1273
+ method)](tagName, otherModeMap);
1274
+ });
1275
+ return otherResult ? {
1276
+ otherMode: true
1277
+ } : false;
1278
+ };
1279
+ }
1280
+
1281
+ /** @type {TagMissingRequiredTypeOrNamepath} */
1282
+ utils.tagMissingRequiredTypeOrNamepath = (tagName, otherModeMaps) => {
1283
+ const result = jsdocUtils.tagMissingRequiredTypeOrNamepath(tagName);
1284
+ if (!result) {
1285
+ return false;
1286
+ }
1287
+ const otherResult = otherModeMaps.every(otherModeMap => {
1288
+ return jsdocUtils.tagMissingRequiredTypeOrNamepath(tagName, otherModeMap);
1289
+ });
1290
+ return otherResult ? true : {
1291
+ otherMode: false
1292
+ };
1293
+ };
1294
+ for (const method of ['tagMustHaveNamePosition', 'tagMustHaveTypePosition']) {
1295
+ /** @type {TagMustHave} */
1296
+ utils[(/** @type {"tagMustHaveNamePosition"|"tagMustHaveTypePosition"} */
1297
+ method)] = (tagName, otherModeMaps) => {
1298
+ const result = jsdocUtils[(/** @type {"tagMustHaveNamePosition"|"tagMustHaveTypePosition"} */
1299
+ method)](tagName);
1300
+ if (!result) {
1301
+ return false;
1302
+ }
1303
+
1304
+ // if (!otherModeMaps) { return true; }
1305
+
1306
+ const otherResult = otherModeMaps.every(otherModeMap => {
1307
+ return jsdocUtils[(/** @type {"tagMustHaveNamePosition"|"tagMustHaveTypePosition"} */
1308
+ method)](tagName, otherModeMap);
1309
+ });
1310
+ return otherResult ? true : {
1311
+ otherMode: false
1312
+ };
1313
+ };
1314
+ }
1315
+ for (const method of ['isNamepathDefiningTag', 'isNamepathReferencingTag', 'isNamepathOrUrlReferencingTag', 'tagMightHaveNamepath']) {
1316
+ /** @type {IsNamepathX} */
1317
+ utils[(/** @type {"isNamepathDefiningTag"|"isNamepathReferencingTag"|"isNamepathOrUrlReferencingTag"|"tagMightHaveNamepath"} */
1318
+ method)] = tagName => {
1319
+ return jsdocUtils[(/** @type {"isNamepathDefiningTag"|"isNamepathReferencingTag"|"isNamepathOrUrlReferencingTag"|"tagMightHaveNamepath"} */
1320
+ method)](tagName);
1321
+ };
1322
+ }
1323
+
1324
+ /** @type {GetTagStructureForMode} */
1325
+ utils.getTagStructureForMode = mde => {
1326
+ return jsdocUtils.getTagStructureForMode(mde, settings.structuredTags);
1327
+ };
1328
+
1329
+ /** @type {MayBeUndefinedTypeTag} */
1330
+ utils.mayBeUndefinedTypeTag = tag => {
1331
+ return jsdocUtils.mayBeUndefinedTypeTag(tag, settings.mode);
1332
+ };
1333
+
1334
+ /** @type {HasValueOrExecutorHasNonEmptyResolveValue} */
1335
+ utils.hasValueOrExecutorHasNonEmptyResolveValue = (anyPromiseAsReturn, allBranches) => {
1336
+ return jsdocUtils.hasValueOrExecutorHasNonEmptyResolveValue(/** @type {Node} */node, anyPromiseAsReturn, allBranches);
1337
+ };
1338
+
1339
+ /** @type {HasYieldValue} */
1340
+ utils.hasYieldValue = () => {
1341
+ if (['ExportDefaultDeclaration', 'ExportNamedDeclaration'].includes(/** @type {Node} */node.type)) {
1342
+ return jsdocUtils.hasYieldValue(/** @type {import('estree').Declaration|import('estree').Expression} */
1343
+ /** @type {import('estree').ExportNamedDeclaration|import('estree').ExportDefaultDeclaration} */
1344
+ node.declaration);
1345
+ }
1346
+ return jsdocUtils.hasYieldValue(/** @type {Node} */node);
1347
+ };
1348
+
1349
+ /** @type {HasYieldReturnValue} */
1350
+ utils.hasYieldReturnValue = () => {
1351
+ return jsdocUtils.hasYieldValue(/** @type {Node} */node, true);
1352
+ };
1353
+
1354
+ /** @type {HasThrowValue} */
1355
+ utils.hasThrowValue = () => {
1356
+ return jsdocUtils.hasThrowValue(node);
1357
+ };
1358
+
1359
+ /** @type {IsAsync} */
1360
+ utils.isAsync = () => {
1361
+ return Boolean(node && 'async' in node && node.async);
1362
+ };
1363
+
1364
+ /** @type {GetTags} */
1365
+ utils.getTags = tagName => {
1366
+ return jsdocUtils.getTags(jsdoc, tagName);
1367
+ };
1368
+
1369
+ /** @type {GetPresentTags} */
1370
+ utils.getPresentTags = tagList => {
1371
+ return jsdocUtils.filterTags(jsdoc, tag => {
1372
+ return tagList.includes(tag.tag);
1373
+ });
1374
+ };
1375
+
1376
+ /** @type {FilterTags} */
1377
+ utils.filterTags = filter => {
1378
+ return jsdocUtils.filterTags(jsdoc, tag => {
1379
+ return filter(tag);
1380
+ });
1381
+ };
1382
+
1383
+ /** @type {FilterAllTags} */
1384
+ utils.filterAllTags = filter => {
1385
+ const tags = jsdocUtils.getAllTags(jsdoc);
1386
+ return tags.filter(tag => {
1387
+ return filter(tag);
1388
+ });
1389
+ };
1390
+
1391
+ /** @type {GetTagsByType} */
1392
+ utils.getTagsByType = tags => {
1393
+ return jsdocUtils.getTagsByType(context, mode, tags);
1394
+ };
1395
+
1396
+ /** @type {HasOptionTag} */
1397
+ utils.hasOptionTag = tagName => {
1398
+ const {
1399
+ tags
1400
+ } = context.options[0] ?? {};
1401
+ return Boolean(tags && tags.includes(tagName));
1402
+ };
1403
+
1404
+ /** @type {GetClassNode} */
1405
+ utils.getClassNode = () => {
1406
+ return [...ancestors, node].reverse().find(parent => {
1407
+ return parent && ['ClassDeclaration', 'ClassExpression'].includes(parent.type);
1408
+ }) ?? null;
1409
+ };
1410
+
1411
+ /** @type {GetClassJsdoc} */
1412
+ utils.getClassJsdoc = () => {
1413
+ const classNode = utils.getClassNode();
1414
+ if (!classNode) {
1415
+ return null;
1416
+ }
1417
+ const classJsdocNode = (0, _jsdoccomment.getJSDocComment)(sourceCode, classNode, {
1418
+ maxLines,
1419
+ minLines
1420
+ });
1421
+ if (classJsdocNode) {
1422
+ return (0, _jsdoccomment.parseComment)(classJsdocNode, '');
1423
+ }
1424
+ return null;
1425
+ };
1426
+
1427
+ /** @type {ClassHasTag} */
1428
+ utils.classHasTag = tagName => {
1429
+ const classJsdoc = utils.getClassJsdoc();
1430
+ return classJsdoc !== null && jsdocUtils.hasTag(classJsdoc, tagName);
1431
+ };
1432
+
1433
+ /** @type {ForEachPreferredTag} */
1434
+ utils.forEachPreferredTag = (tagName, arrayHandler, skipReportingBlockedTag) => {
1435
+ return jsdocUtils.forEachPreferredTag(jsdoc, tagName, arrayHandler, {
1436
+ context,
1437
+ mode,
1438
+ report,
1439
+ skipReportingBlockedTag,
1440
+ tagNamePreference
1441
+ });
1442
+ };
1443
+
1444
+ /** @type {FindContext} */
1445
+ utils.findContext = (contexts, comment) => {
1446
+ const foundContext = contexts.find(cntxt => {
1447
+ return typeof cntxt === 'string' ? _esquery.default.matches(/** @type {Node} */node, _esquery.default.parse(cntxt), undefined, {
1448
+ visitorKeys: sourceCode.visitorKeys
1449
+ }) : (!cntxt.context || cntxt.context === 'any' || _esquery.default.matches(/** @type {Node} */node, _esquery.default.parse(cntxt.context), undefined, {
1450
+ visitorKeys: sourceCode.visitorKeys
1451
+ })) && comment === cntxt.comment;
1452
+ });
1453
+ const contextStr = typeof foundContext === 'object' ? foundContext.context ?? 'any' : String(foundContext);
1454
+ return {
1455
+ contextStr,
1456
+ foundContext
1457
+ };
1458
+ };
1459
+ return utils;
1128
1460
  };
1461
+
1129
1462
  /**
1130
- * @typedef {{
1131
- * [key: string]: false|string|{
1132
- * message: string,
1133
- * replacement?: false|string
1134
- * skipRootChecking?: boolean
1135
- * }
1136
- * }} PreferredTypes
1137
- */
1138
- /**
1139
- * @typedef {{
1140
- * [key: string]: {
1141
- * name?: "text"|"namepath-defining"|"namepath-referencing"|false,
1142
- * type?: boolean|string[],
1143
- * required?: ("name"|"type"|"typeOrNameRequired")[]
1144
- * }
1145
- * }} StructuredTags
1146
- */
1147
- /**
1148
- * Settings from ESLint types.
1149
- * @typedef {{
1150
- * maxLines: Integer,
1151
- * minLines: Integer,
1152
- * tagNamePreference: import('./jsdocUtils.js').TagNamePreference,
1153
- * mode: import('./jsdocUtils.js').ParserMode,
1154
- * preferredTypes: PreferredTypes,
1155
- * structuredTags: StructuredTags,
1156
- * [name: string]: any,
1157
- * contexts?: Context[]
1158
- * }} Settings
1159
- */
1463
+ * @typedef {{
1464
+ * [key: string]: false|string|{
1465
+ * message: string,
1466
+ * replacement?: false|string
1467
+ * skipRootChecking?: boolean
1468
+ * }
1469
+ * }} PreferredTypes
1470
+ */
1471
+ /**
1472
+ * @typedef {{
1473
+ * [key: string]: {
1474
+ * name?: "text"|"namepath-defining"|"namepath-referencing"|false,
1475
+ * type?: boolean|string[],
1476
+ * required?: ("name"|"type"|"typeOrNameRequired")[]
1477
+ * }
1478
+ * }} StructuredTags
1479
+ */
1480
+ /**
1481
+ * Settings from ESLint types.
1482
+ * @typedef {{
1483
+ * maxLines: Integer,
1484
+ * minLines: Integer,
1485
+ * tagNamePreference: import('./jsdocUtils.js').TagNamePreference,
1486
+ * mode: import('./jsdocUtils.js').ParserMode,
1487
+ * preferredTypes: PreferredTypes,
1488
+ * structuredTags: StructuredTags,
1489
+ * [name: string]: any,
1490
+ * contexts?: Context[]
1491
+ * }} Settings
1492
+ */
1493
+
1160
1494
  /**
1161
- * @typedef {{
1162
- * settings?: {
1163
- * jsdoc?: {
1164
- * ignorePrivate: boolean,
1165
- * ignoreInternal: boolean,
1166
- * maxLines: Integer,
1167
- * minLines: Integer,
1168
- * tagNamePreference: import('./jsdocUtils.js').TagNamePreference,
1169
- * preferredTypes: PreferredTypes,
1170
- * structuredTags: StructuredTags,
1171
- * overrideReplacesDocs: boolean,
1172
- * ignoreReplacesDocs: boolean,
1173
- * implementsReplacesDocs: boolean,
1174
- * augmentsExtendsReplacesDocs: boolean,
1175
- * exemptDestructuredRootsFromChecks: boolean,
1176
- * mode: import('./jsdocUtils.js').ParserMode,
1177
- * contexts: Context[],
1178
- * }
1179
- * }
1180
- * }} JSDocSettings
1181
- */
1495
+ * @typedef {{
1496
+ * settings?: {
1497
+ * jsdoc?: {
1498
+ * ignorePrivate: boolean,
1499
+ * ignoreInternal: boolean,
1500
+ * maxLines: Integer,
1501
+ * minLines: Integer,
1502
+ * tagNamePreference: import('./jsdocUtils.js').TagNamePreference,
1503
+ * preferredTypes: PreferredTypes,
1504
+ * structuredTags: StructuredTags,
1505
+ * overrideReplacesDocs: boolean,
1506
+ * ignoreReplacesDocs: boolean,
1507
+ * implementsReplacesDocs: boolean,
1508
+ * augmentsExtendsReplacesDocs: boolean,
1509
+ * exemptDestructuredRootsFromChecks: boolean,
1510
+ * mode: import('./jsdocUtils.js').ParserMode,
1511
+ * contexts: Context[],
1512
+ * }
1513
+ * }
1514
+ * }} JSDocSettings
1515
+ */
1516
+
1182
1517
  /**
1183
- * @param {import('eslint').Rule.RuleContext & JSDocSettings} context
1184
- * @returns {Settings|false}
1185
- */
1186
- const getSettings = (context) => {
1187
- const settings = {
1188
- ignorePrivate: Boolean(context.settings.jsdoc?.ignorePrivate),
1189
- ignoreInternal: Boolean(context.settings.jsdoc?.ignoreInternal),
1190
- maxLines: Number(context.settings.jsdoc?.maxLines ?? 1),
1191
- minLines: Number(context.settings.jsdoc?.minLines ?? 0),
1192
- tagNamePreference: context.settings.jsdoc?.tagNamePreference ?? {},
1193
- preferredTypes: context.settings.jsdoc?.preferredTypes ?? {},
1194
- structuredTags: context.settings.jsdoc?.structuredTags ?? {},
1195
- overrideReplacesDocs: context.settings.jsdoc?.overrideReplacesDocs,
1196
- ignoreReplacesDocs: context.settings.jsdoc?.ignoreReplacesDocs,
1197
- implementsReplacesDocs: context.settings.jsdoc?.implementsReplacesDocs,
1198
- augmentsExtendsReplacesDocs: context.settings.jsdoc?.augmentsExtendsReplacesDocs,
1199
- exemptDestructuredRootsFromChecks: context.settings.jsdoc?.exemptDestructuredRootsFromChecks,
1200
- mode: context.settings.jsdoc?.mode ?? "typescript",
1201
- contexts: context.settings.jsdoc?.contexts
1202
- };
1203
- require_jsdocUtils.setTagStructure(settings.mode);
1204
- try {
1205
- require_jsdocUtils.overrideTagStructure(settings.structuredTags);
1206
- } catch (error) {
1207
- context.report({
1208
- loc: {
1209
- end: {
1210
- column: 1,
1211
- line: 1
1212
- },
1213
- start: {
1214
- column: 1,
1215
- line: 1
1216
- }
1217
- },
1218
- message: error.message
1219
- });
1220
- return false;
1221
- }
1222
- return settings;
1518
+ * @param {import('eslint').Rule.RuleContext & JSDocSettings} context
1519
+ * @returns {Settings|false}
1520
+ */
1521
+ const getSettings = context => {
1522
+ /* eslint-disable perfectionist/sort-objects */
1523
+ const settings = {
1524
+ // All rules
1525
+ ignorePrivate: Boolean(context.settings.jsdoc?.ignorePrivate),
1526
+ ignoreInternal: Boolean(context.settings.jsdoc?.ignoreInternal),
1527
+ maxLines: Number(context.settings.jsdoc?.maxLines ?? 1),
1528
+ minLines: Number(context.settings.jsdoc?.minLines ?? 0),
1529
+ // `check-tag-names` and many returns/param rules
1530
+ tagNamePreference: context.settings.jsdoc?.tagNamePreference ?? {},
1531
+ // `check-types` and `no-undefined-types`
1532
+ preferredTypes: context.settings.jsdoc?.preferredTypes ?? {},
1533
+ // `check-types`, `no-undefined-types`, `valid-types`
1534
+ structuredTags: context.settings.jsdoc?.structuredTags ?? {},
1535
+ // `require-param`, `require-description`, `require-example`,
1536
+ // `require-returns`, `require-throw`, `require-yields`
1537
+ overrideReplacesDocs: context.settings.jsdoc?.overrideReplacesDocs,
1538
+ ignoreReplacesDocs: context.settings.jsdoc?.ignoreReplacesDocs,
1539
+ implementsReplacesDocs: context.settings.jsdoc?.implementsReplacesDocs,
1540
+ augmentsExtendsReplacesDocs: context.settings.jsdoc?.augmentsExtendsReplacesDocs,
1541
+ // `require-param-type`, `require-param-description`
1542
+ exemptDestructuredRootsFromChecks: context.settings.jsdoc?.exemptDestructuredRootsFromChecks,
1543
+ // Many rules, e.g., `check-tag-names`
1544
+ mode: context.settings.jsdoc?.mode ?? 'typescript',
1545
+ // Many rules
1546
+ contexts: context.settings.jsdoc?.contexts
1547
+ };
1548
+ /* eslint-enable perfectionist/sort-objects */
1549
+
1550
+ jsdocUtils.setTagStructure(settings.mode);
1551
+ try {
1552
+ jsdocUtils.overrideTagStructure(settings.structuredTags);
1553
+ } catch (error) {
1554
+ context.report({
1555
+ loc: {
1556
+ end: {
1557
+ column: 1,
1558
+ line: 1
1559
+ },
1560
+ start: {
1561
+ column: 1,
1562
+ line: 1
1563
+ }
1564
+ },
1565
+ message: /** @type {Error} */error.message
1566
+ });
1567
+ return false;
1568
+ }
1569
+ return settings;
1223
1570
  };
1571
+
1224
1572
  /**
1225
- * Create the report function
1226
- * @callback MakeReport
1227
- * @param {import('eslint').Rule.RuleContext} context
1228
- * @param {import('estree').Node} commentNode
1229
- * @returns {Report}
1230
- */
1573
+ * Create the report function
1574
+ * @callback MakeReport
1575
+ * @param {import('eslint').Rule.RuleContext} context
1576
+ * @param {import('estree').Node} commentNode
1577
+ * @returns {Report}
1578
+ */
1579
+
1231
1580
  /** @type {MakeReport} */
1581
+ exports.getSettings = getSettings;
1232
1582
  const makeReport = (context, commentNode) => {
1233
- /** @type {Report} */
1234
- const report = (message, fix = null, jsdocLoc = null, data = void 0) => {
1235
- let loc;
1236
- if (jsdocLoc) {
1237
- if (!("line" in jsdocLoc)) jsdocLoc.line = jsdocLoc.source[0].number;
1238
- const lineNumber = commentNode.loc.start.line + jsdocLoc.line;
1239
- loc = {
1240
- end: {
1241
- column: 0,
1242
- line: lineNumber
1243
- },
1244
- start: {
1245
- column: 0,
1246
- line: lineNumber
1247
- }
1248
- };
1249
- if ("column" in jsdocLoc && typeof jsdocLoc.column === "number") {
1250
- const colNumber = commentNode.loc.start.column + jsdocLoc.column;
1251
- loc.end.column = colNumber;
1252
- loc.start.column = colNumber;
1253
- }
1254
- }
1255
- context.report({
1256
- data,
1257
- fix,
1258
- loc,
1259
- message,
1260
- node: commentNode
1261
- });
1262
- };
1263
- return report;
1583
+ /** @type {Report} */
1584
+ const report = (message, fix = null, jsdocLoc = null, data = undefined) => {
1585
+ let loc;
1586
+ if (jsdocLoc) {
1587
+ if (!('line' in jsdocLoc)) {
1588
+ jsdocLoc.line = /** @type {import('comment-parser').Spec & {line?: Integer}} */jsdocLoc.source[0].number;
1589
+ }
1590
+ const lineNumber = /** @type {import('eslint').AST.SourceLocation} */commentNode.loc.start.line + (/** @type {Integer} */jsdocLoc.line);
1591
+ loc = {
1592
+ end: {
1593
+ column: 0,
1594
+ line: lineNumber
1595
+ },
1596
+ start: {
1597
+ column: 0,
1598
+ line: lineNumber
1599
+ }
1600
+ };
1601
+ if ('column' in jsdocLoc && typeof jsdocLoc.column === 'number') {
1602
+ const colNumber = /** @type {import('eslint').AST.SourceLocation} */commentNode.loc.start.column + jsdocLoc.column;
1603
+ loc.end.column = colNumber;
1604
+ loc.start.column = colNumber;
1605
+ }
1606
+ }
1607
+ context.report({
1608
+ data,
1609
+ fix,
1610
+ loc,
1611
+ message,
1612
+ node: commentNode
1613
+ });
1614
+ };
1615
+ return report;
1264
1616
  };
1617
+
1265
1618
  /**
1266
- * @typedef {(
1267
- * arg: {
1268
- * context: import('eslint').Rule.RuleContext,
1269
- * sourceCode: import('eslint').SourceCode,
1270
- * indent?: string,
1271
- * info?: {
1272
- * comment?: string|undefined,
1273
- * lastIndex?: Integer|undefined
1274
- * },
1275
- * state?: StateObject,
1276
- * globalState?: Map<string, Map<string, string>>,
1277
- * jsdoc?: JsdocBlockWithInline,
1278
- * jsdocNode?: import('eslint').Rule.Node & {
1279
- * range: [number, number]
1280
- * },
1281
- * node?: Node,
1282
- * allComments?: import('estree').Node[]
1283
- * report?: Report,
1284
- * makeReport?: MakeReport,
1285
- * settings: Settings,
1286
- * utils: BasicUtils,
1287
- * }
1288
- * ) => any } JsdocVisitorBasic
1289
- */
1290
- /**
1291
- * @typedef {(
1292
- * arg: {
1293
- * context: import('eslint').Rule.RuleContext,
1294
- * sourceCode: import('eslint').SourceCode,
1295
- * indent: string,
1296
- * info: {
1297
- * comment?: string|undefined,
1298
- * lastIndex?: Integer|undefined
1299
- * },
1300
- * state: StateObject,
1301
- * globalState: Map<string, Map<string, string>>,
1302
- * jsdoc: JsdocBlockWithInline,
1303
- * jsdocNode: import('eslint').Rule.Node & {
1304
- * range: [number, number]
1305
- * },
1306
- * node: Node|null,
1307
- * allComments?: import('estree').Node[]
1308
- * report: Report,
1309
- * makeReport?: MakeReport,
1310
- * settings: Settings,
1311
- * utils: Utils,
1312
- * }
1313
- * ) => any } JsdocVisitor
1314
- */
1619
+ * @typedef {(
1620
+ * arg: {
1621
+ * context: import('eslint').Rule.RuleContext,
1622
+ * sourceCode: import('eslint').SourceCode,
1623
+ * indent?: string,
1624
+ * info?: {
1625
+ * comment?: string|undefined,
1626
+ * lastIndex?: Integer|undefined
1627
+ * },
1628
+ * state?: StateObject,
1629
+ * globalState?: Map<string, Map<string, string>>,
1630
+ * jsdoc?: JsdocBlockWithInline,
1631
+ * jsdocNode?: import('eslint').Rule.Node & {
1632
+ * range: [number, number]
1633
+ * },
1634
+ * node?: Node,
1635
+ * allComments?: import('estree').Node[]
1636
+ * report?: Report,
1637
+ * makeReport?: MakeReport,
1638
+ * settings: Settings,
1639
+ * utils: BasicUtils,
1640
+ * }
1641
+ * ) => any } JsdocVisitorBasic
1642
+ */
1643
+ /**
1644
+ * @typedef {(
1645
+ * arg: {
1646
+ * context: import('eslint').Rule.RuleContext,
1647
+ * sourceCode: import('eslint').SourceCode,
1648
+ * indent: string,
1649
+ * info: {
1650
+ * comment?: string|undefined,
1651
+ * lastIndex?: Integer|undefined
1652
+ * },
1653
+ * state: StateObject,
1654
+ * globalState: Map<string, Map<string, string>>,
1655
+ * jsdoc: JsdocBlockWithInline,
1656
+ * jsdocNode: import('eslint').Rule.Node & {
1657
+ * range: [number, number]
1658
+ * },
1659
+ * node: Node|null,
1660
+ * allComments?: import('estree').Node[]
1661
+ * report: Report,
1662
+ * makeReport?: MakeReport,
1663
+ * settings: Settings,
1664
+ * utils: Utils,
1665
+ * }
1666
+ * ) => any } JsdocVisitor
1667
+ */
1668
+
1315
1669
  /**
1316
- * @param {{
1317
- * comment?: string,
1318
- * lastIndex?: Integer,
1319
- * selector?: string,
1320
- * isFunctionContext?: boolean,
1321
- * }} info
1322
- * @param {string} indent
1323
- * @param {JsdocBlockWithInline} jsdoc
1324
- * @param {RuleConfig} ruleConfig
1325
- * @param {import('eslint').Rule.RuleContext} context
1326
- * @param {import('@es-joy/jsdoccomment').Token} jsdocNode
1327
- * @param {Node|null} node
1328
- * @param {Settings} settings
1329
- * @param {import('eslint').SourceCode} sourceCode
1330
- * @param {JsdocVisitor} iterator
1331
- * @param {StateObject} state
1332
- * @param {boolean} [iteratingAll]
1333
- * @returns {void}
1334
- */
1670
+ * @param {{
1671
+ * comment?: string,
1672
+ * lastIndex?: Integer,
1673
+ * selector?: string,
1674
+ * isFunctionContext?: boolean,
1675
+ * }} info
1676
+ * @param {string} indent
1677
+ * @param {JsdocBlockWithInline} jsdoc
1678
+ * @param {RuleConfig} ruleConfig
1679
+ * @param {import('eslint').Rule.RuleContext} context
1680
+ * @param {import('@es-joy/jsdoccomment').Token} jsdocNode
1681
+ * @param {Node|null} node
1682
+ * @param {Settings} settings
1683
+ * @param {import('eslint').SourceCode} sourceCode
1684
+ * @param {JsdocVisitor} iterator
1685
+ * @param {StateObject} state
1686
+ * @param {boolean} [iteratingAll]
1687
+ * @returns {void}
1688
+ */
1335
1689
  const iterate = (info, indent, jsdoc, ruleConfig, context, jsdocNode, node, settings, sourceCode, iterator, state, iteratingAll) => {
1336
- const jsdocNde = jsdocNode;
1337
- const report = makeReport(context, jsdocNde);
1338
- const utils = getUtils(node, jsdoc, jsdocNode, settings, report, context, sourceCode, iteratingAll, ruleConfig, indent);
1339
- if (!ruleConfig.checkInternal && settings.ignoreInternal && utils.hasTag("internal")) return;
1340
- if (!ruleConfig.checkPrivate && settings.ignorePrivate && (utils.hasTag("private") || require_jsdocUtils.filterTags(jsdoc, ({ tag }) => {
1341
- return tag === "access";
1342
- }).some(({ description }) => {
1343
- return description === "private";
1344
- }))) return;
1345
- iterator({
1346
- context,
1347
- globalState,
1348
- indent,
1349
- info,
1350
- jsdoc,
1351
- jsdocNode: jsdocNde,
1352
- node,
1353
- report,
1354
- settings,
1355
- sourceCode,
1356
- state,
1357
- utils
1358
- });
1690
+ const jsdocNde = /** @type {unknown} */jsdocNode;
1691
+ const report = makeReport(context, /** @type {import('estree').Node} */
1692
+ jsdocNde);
1693
+ const utils = getUtils(node, jsdoc, /** @type {import('eslint').AST.Token} */
1694
+ jsdocNode, settings, report, context, sourceCode, iteratingAll, ruleConfig, indent);
1695
+ if (!ruleConfig.checkInternal && settings.ignoreInternal && utils.hasTag('internal')) {
1696
+ return;
1697
+ }
1698
+ if (!ruleConfig.checkPrivate && settings.ignorePrivate && (utils.hasTag('private') || jsdocUtils.filterTags(jsdoc, ({
1699
+ tag
1700
+ }) => {
1701
+ return tag === 'access';
1702
+ }).some(({
1703
+ description
1704
+ }) => {
1705
+ return description === 'private';
1706
+ }))) {
1707
+ return;
1708
+ }
1709
+ iterator({
1710
+ context,
1711
+ globalState,
1712
+ indent,
1713
+ info,
1714
+ jsdoc,
1715
+ jsdocNode: (
1716
+ /**
1717
+ * @type {import('eslint').Rule.Node & {
1718
+ * range: [number, number];}}
1719
+ */
1720
+ jsdocNde),
1721
+ node,
1722
+ report,
1723
+ settings,
1724
+ sourceCode,
1725
+ state,
1726
+ utils
1727
+ });
1359
1728
  };
1729
+
1360
1730
  /**
1361
- * @param {string[]} lines
1362
- * @param {import('estree').Comment} jsdocNode
1363
- * @returns {[indent: string, jsdoc: JsdocBlockWithInline]}
1364
- */
1365
- const getIndentAndJSDoc = function(lines, jsdocNode) {
1366
- const sourceLine = lines[jsdocNode.loc.start.line - 1];
1367
- let indentChar = sourceLine.charAt(0);
1368
- if (indentChar !== " " && indentChar !== " ") indentChar = " ";
1369
- const indnt = indentChar.repeat(
1370
- /** @type {import('estree').SourceLocation} */
1371
- jsdocNode.loc.start.column
1372
- );
1373
- const jsdc = (0, __es_joy_jsdoccomment.parseComment)(jsdocNode, "");
1374
- return [indnt, jsdc];
1731
+ * @param {string[]} lines
1732
+ * @param {import('estree').Comment} jsdocNode
1733
+ * @returns {[indent: string, jsdoc: JsdocBlockWithInline]}
1734
+ */
1735
+ const getIndentAndJSDoc = function (lines, jsdocNode) {
1736
+ const sourceLine = lines[/** @type {import('estree').SourceLocation} */
1737
+ jsdocNode.loc.start.line - 1];
1738
+ let indentChar = sourceLine.charAt(0);
1739
+ if (indentChar !== ' ' && indentChar !== '\t') {
1740
+ indentChar = ' ';
1741
+ }
1742
+ const indnt = indentChar.repeat(/** @type {import('estree').SourceLocation} */
1743
+ jsdocNode.loc.start.column);
1744
+ const jsdc = (0, _jsdoccomment.parseComment)(jsdocNode, '');
1745
+ return [indnt, jsdc];
1375
1746
  };
1747
+
1376
1748
  /**
1377
- *
1378
- * @typedef {{node: Node & {
1379
- * range: [number, number]
1380
- * }, state: StateObject}} NonCommentArgs
1381
- */
1749
+ *
1750
+ * @typedef {{node: Node & {
1751
+ * range: [number, number]
1752
+ * }, state: StateObject}} NonCommentArgs
1753
+ */
1754
+
1382
1755
  /**
1383
- * @typedef {object} RuleConfig
1384
- * @property {EslintRuleMeta} meta ESLint rule meta
1385
- * @property {import('./jsdocUtils.js').DefaultContexts} [contextDefaults] Any default contexts
1386
- * @property {true} [contextSelected] Whether to force a `contexts` check
1387
- * @property {true} [iterateAllJsdocs] Whether to iterate all JSDoc blocks by default
1388
- * regardless of context
1389
- * @property {true} [checkPrivate] Whether to check `@private` blocks (normally exempted)
1390
- * @property {true} [checkInternal] Whether to check `@internal` blocks (normally exempted)
1391
- * @property {true} [checkFile] Whether to iterates over all JSDoc blocks regardless of attachment
1392
- * @property {true} [nonGlobalSettings] Whether to avoid relying on settings for global contexts
1393
- * @property {true} [noTracking] Whether to disable the tracking of visited comment nodes (as
1394
- * non-tracked may conduct further actions)
1395
- * @property {true} [matchContext] Whether the rule expects contexts to be based on a match option
1396
- * @property {(args: {
1397
- * context: import('eslint').Rule.RuleContext,
1398
- * state: StateObject,
1399
- * settings: Settings,
1400
- * utils: BasicUtils
1401
- * }) => void} [exit] Handler to be executed upon exiting iteration of program AST
1402
- * @property {(nca: NonCommentArgs) => void} [nonComment] Handler to be executed if rule wishes
1403
- * to be supplied nodes without comments
1404
- */
1756
+ * @typedef {object} RuleConfig
1757
+ * @property {EslintRuleMeta} meta ESLint rule meta
1758
+ * @property {import('./jsdocUtils.js').DefaultContexts} [contextDefaults] Any default contexts
1759
+ * @property {true} [contextSelected] Whether to force a `contexts` check
1760
+ * @property {true} [iterateAllJsdocs] Whether to iterate all JSDoc blocks by default
1761
+ * regardless of context
1762
+ * @property {true} [checkPrivate] Whether to check `@private` blocks (normally exempted)
1763
+ * @property {true} [checkInternal] Whether to check `@internal` blocks (normally exempted)
1764
+ * @property {true} [checkFile] Whether to iterates over all JSDoc blocks regardless of attachment
1765
+ * @property {true} [nonGlobalSettings] Whether to avoid relying on settings for global contexts
1766
+ * @property {true} [noTracking] Whether to disable the tracking of visited comment nodes (as
1767
+ * non-tracked may conduct further actions)
1768
+ * @property {true} [matchContext] Whether the rule expects contexts to be based on a match option
1769
+ * @property {(args: {
1770
+ * context: import('eslint').Rule.RuleContext,
1771
+ * state: StateObject,
1772
+ * settings: Settings,
1773
+ * utils: BasicUtils
1774
+ * }) => void} [exit] Handler to be executed upon exiting iteration of program AST
1775
+ * @property {(nca: NonCommentArgs) => void} [nonComment] Handler to be executed if rule wishes
1776
+ * to be supplied nodes without comments
1777
+ */
1778
+
1405
1779
  /**
1406
- * Create an eslint rule that iterates over all JSDocs, regardless of whether
1407
- * they are attached to a function-like node.
1408
- * @param {JsdocVisitor} iterator
1409
- * @param {RuleConfig} ruleConfig The rule's configuration
1410
- * @param {ContextObject[]|null} [contexts] The `contexts` containing relevant `comment` info.
1411
- * @param {boolean} [additiveCommentContexts] If true, will have a separate
1412
- * iteration for each matching comment context. Otherwise, will iterate
1413
- * once if there is a single matching comment context.
1414
- * @returns {import('eslint').Rule.RuleModule}
1415
- */
1780
+ * Create an eslint rule that iterates over all JSDocs, regardless of whether
1781
+ * they are attached to a function-like node.
1782
+ * @param {JsdocVisitor} iterator
1783
+ * @param {RuleConfig} ruleConfig The rule's configuration
1784
+ * @param {ContextObject[]|null} [contexts] The `contexts` containing relevant `comment` info.
1785
+ * @param {boolean} [additiveCommentContexts] If true, will have a separate
1786
+ * iteration for each matching comment context. Otherwise, will iterate
1787
+ * once if there is a single matching comment context.
1788
+ * @returns {import('eslint').Rule.RuleModule}
1789
+ */
1416
1790
  const iterateAllJsdocs = (iterator, ruleConfig, contexts, additiveCommentContexts) => {
1417
- const trackedJsdocs = /* @__PURE__ */ new Set();
1418
- /** @type {import('@es-joy/jsdoccomment').CommentHandler} */
1419
- let handler;
1420
- /** @type {Settings|false} */
1421
- let settings;
1422
- /**
1423
- * @param {import('eslint').Rule.RuleContext} context
1424
- * @param {Node|null} node
1425
- * @param {import('estree').Comment[]} jsdocNodes
1426
- * @param {StateObject} state
1427
- * @param {boolean} [lastCall]
1428
- * @returns {void}
1429
- */
1430
- const callIterator = (context, node, jsdocNodes, state, lastCall) => {
1431
- /* c8 ignore next -- Fallback to deprecated method */
1432
- const { sourceCode = context.getSourceCode() } = context;
1433
- const { lines } = sourceCode;
1434
- const utils = getBasicUtils(context, settings);
1435
- for (const jsdocNode of jsdocNodes) {
1436
- const jsdocNde = jsdocNode;
1437
- if (!/^\/\*\*\s/v.test(sourceCode.getText(jsdocNde))) continue;
1438
- const [indent, jsdoc] = getIndentAndJSDoc(lines, jsdocNode);
1439
- if (additiveCommentContexts) {
1440
- for (const [idx, { comment }] of contexts.entries()) {
1441
- if (comment && handler(comment, jsdoc) === false) continue;
1442
- iterate({
1443
- comment,
1444
- lastIndex: idx,
1445
- selector: node?.type
1446
- }, indent, jsdoc, ruleConfig, context, jsdocNode, node, settings, sourceCode, iterator, state, true);
1447
- }
1448
- continue;
1449
- }
1450
- let lastComment;
1451
- let lastIndex;
1452
- if (contexts && contexts.every(({ comment }, idx) => {
1453
- lastComment = comment;
1454
- lastIndex = idx;
1455
- return comment && handler(comment, jsdoc) === false;
1456
- })) continue;
1457
- iterate(lastComment ? {
1458
- comment: lastComment,
1459
- lastIndex,
1460
- selector: node?.type
1461
- } : {
1462
- lastIndex,
1463
- selector: node?.type
1464
- }, indent, jsdoc, ruleConfig, context, jsdocNode, node, settings, sourceCode, iterator, state, true);
1465
- }
1466
- const settngs = settings;
1467
- if (lastCall && ruleConfig.exit) ruleConfig.exit({
1468
- context,
1469
- settings: settngs,
1470
- state,
1471
- utils
1472
- });
1473
- };
1474
- return {
1475
- create(context) {
1476
- /* c8 ignore next -- Fallback to deprecated method */
1477
- const { sourceCode = context.getSourceCode() } = context;
1478
- settings = getSettings(context);
1479
- if (!settings) return {};
1480
- if (contexts) handler = (0, __es_joy_jsdoccomment.commentHandler)(settings);
1481
- const state = {};
1482
- return {
1483
- "*:not(Program)"(node) {
1484
- const commentNode = (0, __es_joy_jsdoccomment.getJSDocComment)(sourceCode, node, settings);
1485
- if (!ruleConfig.noTracking && trackedJsdocs.has(commentNode)) return;
1486
- if (!commentNode) {
1487
- if (ruleConfig.nonComment) {
1488
- const ste = state;
1489
- ruleConfig.nonComment({
1490
- node,
1491
- state: ste
1492
- });
1493
- }
1494
- return;
1495
- }
1496
- trackedJsdocs.add(commentNode);
1497
- callIterator(context, node, [commentNode], state);
1498
- },
1499
- "Program:exit"() {
1500
- const allComments = sourceCode.getAllComments();
1501
- const untrackedJSdoc = allComments.filter((node) => {
1502
- return !trackedJsdocs.has(node);
1503
- });
1504
- callIterator(context, null, untrackedJSdoc, state, true);
1505
- }
1506
- };
1507
- },
1508
- meta: ruleConfig.meta
1509
- };
1791
+ const trackedJsdocs = new Set();
1792
+
1793
+ /** @type {import('@es-joy/jsdoccomment').CommentHandler} */
1794
+ let handler;
1795
+
1796
+ /** @type {Settings|false} */
1797
+ let settings;
1798
+
1799
+ /**
1800
+ * @param {import('eslint').Rule.RuleContext} context
1801
+ * @param {Node|null} node
1802
+ * @param {import('estree').Comment[]} jsdocNodes
1803
+ * @param {StateObject} state
1804
+ * @param {boolean} [lastCall]
1805
+ * @returns {void}
1806
+ */
1807
+ const callIterator = (context, node, jsdocNodes, state, lastCall) => {
1808
+ /* c8 ignore next -- Fallback to deprecated method */
1809
+ const {
1810
+ sourceCode = context.getSourceCode()
1811
+ } = context;
1812
+ const {
1813
+ lines
1814
+ } = sourceCode;
1815
+ const utils = getBasicUtils(context, /** @type {Settings} */settings);
1816
+ for (const jsdocNode of jsdocNodes) {
1817
+ const jsdocNde = /** @type {unknown} */jsdocNode;
1818
+ if (!/^\/\*\*\s/v.test(sourceCode.getText(/** @type {import('estree').Node} */
1819
+ jsdocNde))) {
1820
+ continue;
1821
+ }
1822
+ const [indent, jsdoc] = getIndentAndJSDoc(lines, jsdocNode);
1823
+ if (additiveCommentContexts) {
1824
+ for (const [idx, {
1825
+ comment
1826
+ }] of /** @type {ContextObject[]} */contexts.entries()) {
1827
+ if (comment && handler(comment, jsdoc) === false) {
1828
+ continue;
1829
+ }
1830
+ iterate({
1831
+ comment,
1832
+ lastIndex: idx,
1833
+ selector: node?.type
1834
+ }, indent, jsdoc, ruleConfig, context, jsdocNode, /** @type {Node} */
1835
+ node, /** @type {Settings} */
1836
+ settings, sourceCode, iterator, state, true);
1837
+ }
1838
+ continue;
1839
+ }
1840
+ let lastComment;
1841
+ let lastIndex;
1842
+ // eslint-disable-next-line no-loop-func
1843
+ if (contexts && contexts.every(({
1844
+ comment
1845
+ }, idx) => {
1846
+ lastComment = comment;
1847
+ lastIndex = idx;
1848
+ return comment && handler(comment, jsdoc) === false;
1849
+ })) {
1850
+ continue;
1851
+ }
1852
+ iterate(lastComment ? {
1853
+ comment: lastComment,
1854
+ lastIndex,
1855
+ selector: node?.type
1856
+ } : {
1857
+ lastIndex,
1858
+ selector: node?.type
1859
+ }, indent, jsdoc, ruleConfig, context, jsdocNode, node, /** @type {Settings} */
1860
+ settings, sourceCode, iterator, state, true);
1861
+ }
1862
+ const settngs = /** @type {Settings} */settings;
1863
+ if (lastCall && ruleConfig.exit) {
1864
+ ruleConfig.exit({
1865
+ context,
1866
+ settings: settngs,
1867
+ state,
1868
+ utils
1869
+ });
1870
+ }
1871
+ };
1872
+ return {
1873
+ create(context) {
1874
+ /* c8 ignore next -- Fallback to deprecated method */
1875
+ const {
1876
+ sourceCode = context.getSourceCode()
1877
+ } = context;
1878
+ settings = getSettings(context);
1879
+ if (!settings) {
1880
+ return {};
1881
+ }
1882
+ if (contexts) {
1883
+ handler = (0, _jsdoccomment.commentHandler)(settings);
1884
+ }
1885
+ const state = {};
1886
+ return {
1887
+ /**
1888
+ * @param {import('eslint').Rule.Node & {
1889
+ * range: [Integer, Integer];
1890
+ * }} node
1891
+ * @returns {void}
1892
+ */
1893
+ '*:not(Program)'(node) {
1894
+ const commentNode = (0, _jsdoccomment.getJSDocComment)(sourceCode, node, /** @type {Settings} */settings);
1895
+ if (!ruleConfig.noTracking && trackedJsdocs.has(commentNode)) {
1896
+ return;
1897
+ }
1898
+ if (!commentNode) {
1899
+ if (ruleConfig.nonComment) {
1900
+ const ste = /** @type {StateObject} */state;
1901
+ ruleConfig.nonComment({
1902
+ node,
1903
+ state: ste
1904
+ });
1905
+ }
1906
+ return;
1907
+ }
1908
+ trackedJsdocs.add(commentNode);
1909
+ callIterator(context, node, [(/** @type {import('estree').Comment} */
1910
+ commentNode)], /** @type {StateObject} */state);
1911
+ },
1912
+ 'Program:exit'() {
1913
+ const allComments = sourceCode.getAllComments();
1914
+ const untrackedJSdoc = allComments.filter(node => {
1915
+ return !trackedJsdocs.has(node);
1916
+ });
1917
+ callIterator(context, null, untrackedJSdoc, /** @type {StateObject} */
1918
+ state, true);
1919
+ }
1920
+ };
1921
+ },
1922
+ meta: ruleConfig.meta
1923
+ };
1510
1924
  };
1925
+
1511
1926
  /**
1512
- * Create an eslint rule that iterates over all JSDocs, regardless of whether
1513
- * they are attached to a function-like node.
1514
- * @param {JsdocVisitorBasic} iterator
1515
- * @param {RuleConfig} ruleConfig
1516
- * @returns {import('eslint').Rule.RuleModule}
1517
- */
1927
+ * Create an eslint rule that iterates over all JSDocs, regardless of whether
1928
+ * they are attached to a function-like node.
1929
+ * @param {JsdocVisitorBasic} iterator
1930
+ * @param {RuleConfig} ruleConfig
1931
+ * @returns {import('eslint').Rule.RuleModule}
1932
+ */
1518
1933
  const checkFile = (iterator, ruleConfig) => {
1519
- return {
1520
- create(context) {
1521
- /* c8 ignore next -- Fallback to deprecated method */
1522
- const { sourceCode = context.getSourceCode() } = context;
1523
- const settings = getSettings(context);
1524
- if (!settings) return {};
1525
- return { "Program:exit"() {
1526
- const allComms = sourceCode.getAllComments();
1527
- const utils = getBasicUtils(context, settings);
1528
- iterator({
1529
- allComments: allComms,
1530
- context,
1531
- makeReport,
1532
- settings,
1533
- sourceCode,
1534
- utils
1535
- });
1536
- } };
1537
- },
1538
- meta: ruleConfig.meta
1539
- };
1934
+ return {
1935
+ create(context) {
1936
+ /* c8 ignore next -- Fallback to deprecated method */
1937
+ const {
1938
+ sourceCode = context.getSourceCode()
1939
+ } = context;
1940
+ const settings = getSettings(context);
1941
+ if (!settings) {
1942
+ return {};
1943
+ }
1944
+ return {
1945
+ 'Program:exit'() {
1946
+ const allComms = /** @type {unknown} */sourceCode.getAllComments();
1947
+ const utils = getBasicUtils(context, settings);
1948
+ iterator({
1949
+ allComments: (/** @type {import('estree').Node[]} */allComms),
1950
+ context,
1951
+ makeReport,
1952
+ settings,
1953
+ sourceCode,
1954
+ utils
1955
+ });
1956
+ }
1957
+ };
1958
+ },
1959
+ meta: ruleConfig.meta
1960
+ };
1540
1961
  };
1541
1962
  /**
1542
- * @param {JsdocVisitor} iterator
1543
- * @param {RuleConfig} ruleConfig
1544
- * @returns {import('eslint').Rule.RuleModule}
1545
- */
1963
+ * @param {JsdocVisitor} iterator
1964
+ * @param {RuleConfig} ruleConfig
1965
+ * @returns {import('eslint').Rule.RuleModule}
1966
+ */
1546
1967
  function iterateJsdoc(iterator, ruleConfig) {
1547
- const metaType = ruleConfig?.meta?.type;
1548
- if (!metaType || ![
1549
- "layout",
1550
- "problem",
1551
- "suggestion"
1552
- ].includes(metaType)) throw new TypeError("Rule must include `meta.type` option (with value \"problem\", \"suggestion\", or \"layout\")");
1553
- if (typeof iterator !== "function") throw new TypeError("The iterator argument must be a function.");
1554
- if (ruleConfig.checkFile) return checkFile(iterator, ruleConfig);
1555
- if (ruleConfig.iterateAllJsdocs) return iterateAllJsdocs(iterator, ruleConfig);
1556
- /** @type {import('eslint').Rule.RuleModule} */
1557
- return {
1558
- create(context) {
1559
- const settings = getSettings(context);
1560
- if (!settings) return {};
1561
- /**
1562
- * @type {Context[]|undefined}
1563
- */
1564
- let contexts;
1565
- if (ruleConfig.contextDefaults || ruleConfig.contextSelected || ruleConfig.matchContext) {
1566
- contexts = ruleConfig.matchContext && context.options[0]?.match ? context.options[0].match : require_jsdocUtils.enforcedContexts(context, ruleConfig.contextDefaults, ruleConfig.nonGlobalSettings ? {} : settings);
1567
- if (contexts) contexts = contexts.map((obj) => {
1568
- if (typeof obj === "object" && !obj.context) return {
1569
- ...obj,
1570
- context: "any"
1571
- };
1572
- return obj;
1573
- });
1574
- const hasPlainAny = contexts?.includes("any");
1575
- const hasObjectAny = !hasPlainAny && contexts?.find((ctxt) => {
1576
- if (typeof ctxt === "string") return false;
1577
- return ctxt?.context === "any";
1578
- });
1579
- if (hasPlainAny || hasObjectAny) return iterateAllJsdocs(iterator, ruleConfig, hasObjectAny ? contexts : null, ruleConfig.matchContext).create(context);
1580
- }
1581
- /* c8 ignore next -- Fallback to deprecated method */
1582
- const { sourceCode = context.getSourceCode() } = context;
1583
- const { lines } = sourceCode;
1584
- /** @type {Partial<StateObject>} */
1585
- const state = {};
1586
- /** @type {CheckJsdoc} */
1587
- const checkJsdoc = (info, handler, node) => {
1588
- const jsdocNode = (0, __es_joy_jsdoccomment.getJSDocComment)(sourceCode, node, settings);
1589
- if (!jsdocNode) return;
1590
- const [indent, jsdoc] = getIndentAndJSDoc(lines, jsdocNode);
1591
- if (handler && handler(jsdoc) === false) return;
1592
- iterate(info, indent, jsdoc, ruleConfig, context, jsdocNode, node, settings, sourceCode, iterator, state);
1593
- };
1594
- /** @type {import('eslint').Rule.RuleListener} */
1595
- let contextObject = {};
1596
- if (contexts && (ruleConfig.contextDefaults || ruleConfig.contextSelected || ruleConfig.matchContext)) contextObject = require_jsdocUtils.getContextObject(contexts, checkJsdoc, (0, __es_joy_jsdoccomment.commentHandler)(settings));
1597
- else for (const prop of [
1598
- "ArrowFunctionExpression",
1599
- "FunctionDeclaration",
1600
- "FunctionExpression",
1601
- "TSDeclareFunction"
1602
- ]) contextObject[prop] = checkJsdoc.bind(null, { selector: prop }, null);
1603
- if (typeof ruleConfig.exit === "function") contextObject["Program:exit"] = () => {
1604
- const ste = state;
1605
- /** @type {Required<RuleConfig>} */ ruleConfig.exit({
1606
- context,
1607
- settings,
1608
- state: ste
1609
- });
1610
- };
1611
- return contextObject;
1612
- },
1613
- meta: ruleConfig.meta
1614
- };
1615
- }
1616
-
1617
- //#endregion
1618
- exports.default = iterateJsdoc;
1619
- exports.getSettings = getSettings;
1620
- Object.defineProperty(exports, 'parseComment', {
1621
- enumerable: true,
1622
- get: function () {
1623
- return __es_joy_jsdoccomment.parseComment;
1968
+ const metaType = ruleConfig?.meta?.type;
1969
+ if (!metaType || !['layout', 'problem', 'suggestion'].includes(metaType)) {
1970
+ throw new TypeError('Rule must include `meta.type` option (with value "problem", "suggestion", or "layout")');
1624
1971
  }
1625
- });
1972
+ if (typeof iterator !== 'function') {
1973
+ throw new TypeError('The iterator argument must be a function.');
1974
+ }
1975
+ if (ruleConfig.checkFile) {
1976
+ return checkFile(/** @type {JsdocVisitorBasic} */iterator, ruleConfig);
1977
+ }
1978
+ if (ruleConfig.iterateAllJsdocs) {
1979
+ return iterateAllJsdocs(iterator, ruleConfig);
1980
+ }
1981
+
1982
+ /** @type {import('eslint').Rule.RuleModule} */
1983
+ return {
1984
+ /**
1985
+ * The entrypoint for the JSDoc rule.
1986
+ * @param {import('eslint').Rule.RuleContext} context
1987
+ * a reference to the context which hold all important information
1988
+ * like settings and the sourcecode to check.
1989
+ * @returns {import('eslint').Rule.RuleListener}
1990
+ * a listener with parser callback function.
1991
+ */
1992
+ create(context) {
1993
+ const settings = getSettings(context);
1994
+ if (!settings) {
1995
+ return {};
1996
+ }
1997
+
1998
+ /**
1999
+ * @type {Context[]|undefined}
2000
+ */
2001
+ let contexts;
2002
+ if (ruleConfig.contextDefaults || ruleConfig.contextSelected || ruleConfig.matchContext) {
2003
+ contexts = ruleConfig.matchContext && context.options[0]?.match ? context.options[0].match : jsdocUtils.enforcedContexts(context, ruleConfig.contextDefaults, ruleConfig.nonGlobalSettings ? {} : settings);
2004
+ if (contexts) {
2005
+ contexts = contexts.map(obj => {
2006
+ if (typeof obj === 'object' && !obj.context) {
2007
+ return {
2008
+ ...obj,
2009
+ context: 'any'
2010
+ };
2011
+ }
2012
+ return obj;
2013
+ });
2014
+ }
2015
+ const hasPlainAny = contexts?.includes('any');
2016
+ const hasObjectAny = !hasPlainAny && contexts?.find(ctxt => {
2017
+ if (typeof ctxt === 'string') {
2018
+ return false;
2019
+ }
2020
+ return ctxt?.context === 'any';
2021
+ });
2022
+ if (hasPlainAny || hasObjectAny) {
2023
+ return iterateAllJsdocs(iterator, ruleConfig, hasObjectAny ? (/** @type {ContextObject[]} */contexts) : null, ruleConfig.matchContext).create(context);
2024
+ }
2025
+ }
2026
+
2027
+ /* c8 ignore next -- Fallback to deprecated method */
2028
+ const {
2029
+ sourceCode = context.getSourceCode()
2030
+ } = context;
2031
+ const {
2032
+ lines
2033
+ } = sourceCode;
2034
+
2035
+ /** @type {Partial<StateObject>} */
2036
+ const state = {};
2037
+
2038
+ /** @type {CheckJsdoc} */
2039
+ const checkJsdoc = (info, handler, node) => {
2040
+ const jsdocNode = (0, _jsdoccomment.getJSDocComment)(sourceCode, node, settings);
2041
+ if (!jsdocNode) {
2042
+ return;
2043
+ }
2044
+ const [indent, jsdoc] = getIndentAndJSDoc(lines, /** @type {import('estree').Comment} */
2045
+ jsdocNode);
2046
+ if (
2047
+ // Note, `handler` should already be bound in its first argument
2048
+ // with these only to be called after the value of
2049
+ // `comment`
2050
+ handler && handler(jsdoc) === false) {
2051
+ return;
2052
+ }
2053
+ iterate(info, indent, jsdoc, ruleConfig, context, jsdocNode, node, settings, sourceCode, iterator, /** @type {StateObject} */
2054
+ state);
2055
+ };
2056
+
2057
+ /** @type {import('eslint').Rule.RuleListener} */
2058
+ let contextObject = {};
2059
+ if (contexts && (ruleConfig.contextDefaults || ruleConfig.contextSelected || ruleConfig.matchContext)) {
2060
+ contextObject = jsdocUtils.getContextObject(contexts, checkJsdoc, (0, _jsdoccomment.commentHandler)(settings));
2061
+ } else {
2062
+ for (const prop of ['ArrowFunctionExpression', 'FunctionDeclaration', 'FunctionExpression', 'TSDeclareFunction']) {
2063
+ contextObject[prop] = checkJsdoc.bind(null, {
2064
+ selector: prop
2065
+ }, null);
2066
+ }
2067
+ }
2068
+ if (typeof ruleConfig.exit === 'function') {
2069
+ contextObject['Program:exit'] = () => {
2070
+ const ste = /** @type {StateObject} */state;
2071
+
2072
+ // @ts-expect-error `utils` not needed at this point
2073
+ /** @type {Required<RuleConfig>} */
2074
+ ruleConfig.exit({
2075
+ context,
2076
+ settings,
2077
+ state: ste
2078
+ });
2079
+ };
2080
+ }
2081
+ return contextObject;
2082
+ },
2083
+ meta: ruleConfig.meta
2084
+ };
2085
+ }
1626
2086
  //# sourceMappingURL=iterateJsdoc.cjs.map