eslint-plugin-jsdoc 53.0.1 → 54.0.0

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