eslint-plugin-jsdoc 53.0.1 → 54.1.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 +2007 -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 +391 -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 +559 -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 +41 -57
  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 +2542 -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 +545 -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 +744 -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,2105 @@
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 5 */ :
681
+ // @ts-expect-error ESLint 8
682
+ context.getAncestors() : [];
683
+
684
+ /* c8 ignore next -- Fallback to deprecated method */
685
+ const {
686
+ sourceCode = context.getSourceCode()
687
+ } = context;
688
+ const utils = /** @type {Utils} */getBasicUtils(context, settings);
689
+ const {
690
+ augmentsExtendsReplacesDocs,
691
+ ignoreReplacesDocs,
692
+ implementsReplacesDocs,
693
+ maxLines,
694
+ minLines,
695
+ mode,
696
+ overrideReplacesDocs,
697
+ tagNamePreference
698
+ } = settings;
699
+ const functionTypes = ['ArrowFunctionExpression', 'FunctionDeclaration', 'FunctionExpression', 'MethodDefinition'];
700
+
701
+ /** @type {IsIteratingFunction} */
702
+ utils.isIteratingFunction = () => {
703
+ return !iteratingAll || functionTypes.includes(String(node?.type));
704
+ };
705
+
706
+ /** @type {IsIteratingFunction} */
707
+ utils.isIteratingFunctionOrVariable = () => {
708
+ if (utils.isIteratingFunction()) {
709
+ return true;
710
+ }
711
+
712
+ /** @type {import('estree').VariableDeclarator[]} */
713
+ const declarations = node?.type === 'VariableDeclaration' ? node.declarations : node?.type === 'ExportNamedDeclaration' && node.declaration?.type === 'VariableDeclaration' ? node.declaration.declarations : [];
714
+ return declarations.some(({
715
+ init
716
+ }) => {
717
+ return functionTypes.includes(String(init?.type));
718
+ });
719
+ };
720
+
721
+ /** @type {IsVirtualFunction} */
722
+ utils.isVirtualFunction = () => {
723
+ return Boolean(iteratingAll) && utils.hasATag(['callback', 'function', 'func', 'method']);
724
+ };
725
+
726
+ /** @type {Stringify} */
727
+ utils.stringify = (tagBlock, specRewire) => {
728
+ let block;
729
+ if (specRewire) {
730
+ block = rewireSpecs(tagBlock);
731
+ }
732
+ return (0, _commentParser.stringify)(/** @type {import('comment-parser').Block} */
733
+ specRewire ? block : tagBlock);
734
+ };
735
+
736
+ /** @type {ReportJSDoc} */
737
+ utils.reportJSDoc = (msg, tag, handler, specRewire, data) => {
738
+ report(msg, handler ? /** @type {import('eslint').Rule.ReportFixer} */fixer => {
739
+ handler();
740
+ const replacement = utils.stringify(jsdoc, specRewire);
741
+ if (!replacement) {
742
+ const text = sourceCode.getText();
743
+ const lastLineBreakPos = text.slice(0, jsdocNode.range[0]).search(/\n[ \t]*$/v);
744
+ if (lastLineBreakPos > -1) {
745
+ return fixer.removeRange([lastLineBreakPos, jsdocNode.range[1]]);
746
+ }
747
+ return fixer.removeRange(/\s/v.test(text.charAt(jsdocNode.range[1])) ? [jsdocNode.range[0], jsdocNode.range[1] + 1] : jsdocNode.range);
748
+ }
749
+ return fixer.replaceText(jsdocNode, replacement);
750
+ } : null, tag, data);
751
+ };
752
+
753
+ /** @type {GetRegexFromString} */
754
+ utils.getRegexFromString = (str, requiredFlags) => {
755
+ return jsdocUtils.getRegexFromString(str, requiredFlags);
756
+ };
757
+
758
+ /** @type {GetTagDescription} */
759
+ utils.getTagDescription = (tg, returnArray) => {
760
+ return jsdocUtils.getTagDescription(tg, returnArray);
761
+ };
762
+
763
+ /** @type {SetTagDescription} */
764
+ utils.setTagDescription = (tg, matcher, setter) => {
765
+ let finalIdx = 0;
766
+ tg.source.some(({
767
+ tokens: {
768
+ description
769
+ }
770
+ }, idx) => {
771
+ if (description && matcher.test(description)) {
772
+ tg.source[idx].tokens.description = setter(description);
773
+ finalIdx = idx;
774
+ return true;
775
+ }
776
+ return false;
777
+ });
778
+ return finalIdx;
779
+ };
780
+
781
+ /** @type {GetDescription} */
782
+ utils.getDescription = () => {
783
+ /** @type {string[]} */
784
+ const descriptions = [];
785
+ let lastDescriptionLine = 0;
786
+ let tagsBegun = false;
787
+ jsdoc.source.some(({
788
+ tokens: {
789
+ description,
790
+ end,
791
+ tag
792
+ }
793
+ }, idx) => {
794
+ if (tag) {
795
+ tagsBegun = true;
796
+ }
797
+ if (idx && (tag || end)) {
798
+ lastDescriptionLine = idx - 1;
799
+ if (!tagsBegun && description) {
800
+ descriptions.push(description);
801
+ }
802
+ return true;
803
+ }
804
+ if (!tagsBegun && (idx || description)) {
805
+ descriptions.push(description || (descriptions.length ? '' : '\n'));
806
+ }
807
+ return false;
808
+ });
809
+ return {
810
+ description: descriptions.join('\n'),
811
+ descriptions,
812
+ lastDescriptionLine
813
+ };
814
+ };
815
+
816
+ /** @type {SetBlockDescription} */
817
+ utils.setBlockDescription = setter => {
818
+ /** @type {string[]} */
819
+ const descLines = [];
820
+ /**
821
+ * @type {undefined|Integer}
822
+ */
823
+ let startIdx;
824
+ /**
825
+ * @type {undefined|Integer}
826
+ */
827
+ let endIdx;
828
+
829
+ /**
830
+ * @type {undefined|{
831
+ * delimiter: string,
832
+ * postDelimiter: string,
833
+ * start: string
834
+ * }}
835
+ */
836
+ let info;
837
+ jsdoc.source.some(({
838
+ tokens: {
839
+ delimiter,
840
+ description,
841
+ end,
842
+ postDelimiter,
843
+ start,
844
+ tag
845
+ }
846
+ }, idx) => {
847
+ if (delimiter === '/**') {
848
+ return false;
849
+ }
850
+ if (startIdx === undefined) {
851
+ startIdx = idx;
852
+ info = {
853
+ delimiter,
854
+ postDelimiter,
855
+ start
856
+ };
857
+ }
858
+ if (tag || end) {
859
+ endIdx = idx;
860
+ return true;
861
+ }
862
+ descLines.push(description);
863
+ return false;
864
+ });
865
+
866
+ /* c8 ignore else -- Won't be called if missing */
867
+ if (descLines.length) {
868
+ jsdoc.source.splice(/** @type {Integer} */startIdx, /** @type {Integer} */endIdx - (/** @type {Integer} */startIdx), ...setter(
869
+ /**
870
+ * @type {{
871
+ * delimiter: string,
872
+ * postDelimiter: string,
873
+ * start: string
874
+ * }}
875
+ */
876
+ info, seedTokens, descLines));
877
+ }
878
+ };
879
+
880
+ /** @type {SetDescriptionLines} */
881
+ utils.setDescriptionLines = (matcher, setter) => {
882
+ let finalIdx = 0;
883
+ jsdoc.source.some(({
884
+ tokens: {
885
+ description,
886
+ end,
887
+ tag
888
+ }
889
+ }, idx) => {
890
+ /* c8 ignore next 3 -- Already checked */
891
+ if (idx && (tag || end)) {
892
+ return true;
893
+ }
894
+ if (description && matcher.test(description)) {
895
+ jsdoc.source[idx].tokens.description = setter(description);
896
+ finalIdx = idx;
897
+ return true;
898
+ }
899
+ return false;
900
+ });
901
+ return finalIdx;
902
+ };
903
+
904
+ /** @type {ChangeTag} */
905
+ utils.changeTag = (tag, ...tokens) => {
906
+ for (const [idx, src] of tag.source.entries()) {
907
+ src.tokens = {
908
+ ...src.tokens,
909
+ ...tokens[idx]
910
+ };
911
+ }
912
+ };
913
+
914
+ /** @type {SetTag} */
915
+ utils.setTag = (tag, tokens) => {
916
+ tag.source = [{
917
+ number: tag.line,
918
+ // Or tag.source[0].number?
919
+ source: '',
920
+ tokens: seedTokens({
921
+ delimiter: '*',
922
+ postDelimiter: ' ',
923
+ start: indent + ' ',
924
+ tag: '@' + tag.tag,
925
+ ...tokens
926
+ })
927
+ }];
928
+ };
929
+
930
+ /** @type {RemoveTag} */
931
+ utils.removeTag = (tagIndex, {
932
+ removeEmptyBlock = false,
933
+ tagSourceOffset = 0
934
+ } = {}) => {
935
+ const {
936
+ source: tagSource
937
+ } = jsdoc.tags[tagIndex];
938
+ /** @type {Integer|undefined} */
939
+ let lastIndex;
940
+ const firstNumber = jsdoc.source[0].number;
941
+ tagSource.some(({
942
+ number
943
+ }, tagIdx) => {
944
+ const sourceIndex = jsdoc.source.findIndex(({
945
+ number: srcNumber
946
+ }) => {
947
+ return number === srcNumber;
948
+ });
949
+ // c8 ignore else
950
+ if (sourceIndex > -1) {
951
+ let spliceCount = 1;
952
+ tagSource.slice(tagIdx + 1).some(({
953
+ tokens: {
954
+ end: ending,
955
+ tag
956
+ }
957
+ }) => {
958
+ if (!tag && !ending) {
959
+ spliceCount++;
960
+ return false;
961
+ }
962
+ return true;
963
+ });
964
+ const spliceIdx = sourceIndex + tagSourceOffset;
965
+ const {
966
+ delimiter,
967
+ end
968
+ } = jsdoc.source[spliceIdx].tokens;
969
+ if (spliceIdx === 0 && jsdoc.tags.length >= 2 || !removeEmptyBlock && (end || delimiter === '/**')) {
970
+ const {
971
+ tokens
972
+ } = jsdoc.source[spliceIdx];
973
+ for (const item of ['postDelimiter', 'tag', 'postTag', 'type', 'postType', 'name', 'postName', 'description']) {
974
+ tokens[(
975
+ /**
976
+ * @type {"postDelimiter"|"tag"|"type"|"postType"|
977
+ * "postTag"|"name"|"postName"|"description"}
978
+ */
979
+ item)] = '';
980
+ }
981
+ } else {
982
+ jsdoc.source.splice(spliceIdx, spliceCount - tagSourceOffset + (spliceIdx ? 0 : jsdoc.source.length));
983
+ tagSource.splice(tagIdx + tagSourceOffset, spliceCount - tagSourceOffset + (spliceIdx ? 0 : jsdoc.source.length));
984
+ }
985
+ lastIndex = sourceIndex;
986
+ return true;
987
+ }
988
+ /* c8 ignore next 2 */
989
+ // eslint-disable-next-line @stylistic/padding-line-between-statements -- c8
990
+ return false;
991
+ });
992
+ for (const [idx, src] of jsdoc.source.slice(lastIndex).entries()) {
993
+ src.number = firstNumber + (/** @type {Integer} */lastIndex) + idx;
994
+ }
995
+
996
+ // Todo: Once rewiring of tags may be fixed in comment-parser to reflect
997
+ // missing tags, this step should be added here (so that, e.g.,
998
+ // if accessing `jsdoc.tags`, such as to add a new tag, the
999
+ // correct information will be available)
1000
+ };
1001
+
1002
+ /** @type {AddTag} */
1003
+ utils.addTag = (targetTagName, number = (jsdoc.tags[jsdoc.tags.length - 1]?.source[0]?.number ?? jsdoc.source.findIndex(({
1004
+ tokens: {
1005
+ tag
1006
+ }
1007
+ }) => {
1008
+ return tag;
1009
+ }) - 1) + 1, tokens = {}) => {
1010
+ jsdoc.source.splice(number, 0, {
1011
+ number,
1012
+ source: '',
1013
+ tokens: seedTokens({
1014
+ delimiter: '*',
1015
+ postDelimiter: ' ',
1016
+ start: indent + ' ',
1017
+ tag: `@${targetTagName}`,
1018
+ ...tokens
1019
+ })
1020
+ });
1021
+ for (const src of jsdoc.source.slice(number + 1)) {
1022
+ src.number++;
1023
+ }
1024
+ };
1025
+
1026
+ /** @type {GetFirstLine} */
1027
+ utils.getFirstLine = () => {
1028
+ let firstLine;
1029
+ for (const {
1030
+ number,
1031
+ tokens: {
1032
+ tag
1033
+ }
1034
+ } of jsdoc.source) {
1035
+ if (tag) {
1036
+ firstLine = number;
1037
+ break;
1038
+ }
1039
+ }
1040
+ return firstLine;
1041
+ };
1042
+
1043
+ /** @type {SeedTokens} */
1044
+ utils.seedTokens = seedTokens;
1045
+
1046
+ /** @type {EmptyTokens} */
1047
+ utils.emptyTokens = tokens => {
1048
+ for (const prop of ['start', 'postDelimiter', 'tag', 'type', 'postType', 'postTag', 'name', 'postName', 'description', 'end', 'lineEnd']) {
1049
+ tokens[(
1050
+ /**
1051
+ * @type {"start"|"postDelimiter"|"tag"|"type"|"postType"|
1052
+ * "postTag"|"name"|"postName"|"description"|"end"|"lineEnd"}
1053
+ */
1054
+ prop)] = '';
1055
+ }
1056
+ };
1057
+
1058
+ /** @type {AddLine} */
1059
+ utils.addLine = (sourceIndex, tokens) => {
1060
+ const number = (jsdoc.source[sourceIndex - 1]?.number || 0) + 1;
1061
+ jsdoc.source.splice(sourceIndex, 0, {
1062
+ number,
1063
+ source: '',
1064
+ tokens: seedTokens(tokens)
1065
+ });
1066
+ for (const src of jsdoc.source.slice(number + 1)) {
1067
+ src.number++;
1068
+ }
1069
+ // If necessary, we can rewire the tags (misnamed method)
1070
+ // rewireSource(jsdoc);
1071
+ };
1072
+
1073
+ /** @type {AddLines} */
1074
+ utils.addLines = (tagIndex, tagSourceOffset, numLines) => {
1075
+ const {
1076
+ source: tagSource
1077
+ } = jsdoc.tags[tagIndex];
1078
+ /** @type {Integer|undefined} */
1079
+ let lastIndex;
1080
+ const firstNumber = jsdoc.source[0].number;
1081
+ tagSource.some(({
1082
+ number
1083
+ }) => {
1084
+ const makeLine = () => {
1085
+ return {
1086
+ number,
1087
+ source: '',
1088
+ tokens: seedTokens({
1089
+ delimiter: '*',
1090
+ start: indent + ' '
1091
+ })
1092
+ };
1093
+ };
1094
+ const makeLines = () => {
1095
+ return Array.from({
1096
+ length: numLines
1097
+ }, makeLine);
1098
+ };
1099
+ const sourceIndex = jsdoc.source.findIndex(({
1100
+ number: srcNumber,
1101
+ tokens: {
1102
+ end
1103
+ }
1104
+ }) => {
1105
+ return number === srcNumber && !end;
1106
+ });
1107
+ // c8 ignore else
1108
+ if (sourceIndex > -1) {
1109
+ const lines = makeLines();
1110
+ jsdoc.source.splice(sourceIndex + tagSourceOffset, 0, ...lines);
1111
+
1112
+ // tagSource.splice(tagIdx + 1, 0, ...makeLines());
1113
+ lastIndex = sourceIndex;
1114
+ return true;
1115
+ }
1116
+ /* c8 ignore next 2 */
1117
+ // eslint-disable-next-line @stylistic/padding-line-between-statements -- c8
1118
+ return false;
1119
+ });
1120
+ for (const [idx, src] of jsdoc.source.slice(lastIndex).entries()) {
1121
+ src.number = firstNumber + (/** @type {Integer} */lastIndex) + idx;
1122
+ }
1123
+ };
1124
+
1125
+ /** @type {MakeMultiline} */
1126
+ utils.makeMultiline = () => {
1127
+ const {
1128
+ source: [{
1129
+ tokens
1130
+ }]
1131
+ } = jsdoc;
1132
+ const {
1133
+ description,
1134
+ lineEnd,
1135
+ name,
1136
+ postDelimiter,
1137
+ tag,
1138
+ type
1139
+ } = tokens;
1140
+ let {
1141
+ tokens: {
1142
+ postName,
1143
+ postTag,
1144
+ postType
1145
+ }
1146
+ } = jsdoc.source[0];
1147
+
1148
+ // Strip trailing leftovers from single line ending
1149
+ if (!description) {
1150
+ if (postName) {
1151
+ postName = '';
1152
+ } else if (postType) {
1153
+ postType = '';
1154
+ } else /* c8 ignore else -- `comment-parser` prevents empty blocks currently per https://github.com/syavorsky/comment-parser/issues/128 */if (postTag) {
1155
+ postTag = '';
1156
+ }
1157
+ }
1158
+ utils.emptyTokens(tokens);
1159
+ utils.addLine(1, {
1160
+ delimiter: '*',
1161
+ // If a description were present, it may have whitespace attached
1162
+ // due to being at the end of the single line
1163
+ description: description.trimEnd(),
1164
+ name,
1165
+ postDelimiter,
1166
+ postName,
1167
+ postTag,
1168
+ postType,
1169
+ start: indent + ' ',
1170
+ tag,
1171
+ type
1172
+ });
1173
+ utils.addLine(2, {
1174
+ end: '*/',
1175
+ lineEnd,
1176
+ start: indent + ' '
1177
+ });
1178
+ };
1179
+
1180
+ /**
1181
+ * @type {import('./jsdocUtils.js').FlattenRoots}
1182
+ */
1183
+ utils.flattenRoots = jsdocUtils.flattenRoots;
1184
+
1185
+ /** @type {GetFunctionParameterNames} */
1186
+ utils.getFunctionParameterNames = useDefaultObjectProperties => {
1187
+ return jsdocUtils.getFunctionParameterNames(node, useDefaultObjectProperties);
1188
+ };
1189
+
1190
+ /** @type {HasParams} */
1191
+ utils.hasParams = () => {
1192
+ return jsdocUtils.hasParams(/** @type {Node} */node);
1193
+ };
1194
+
1195
+ /** @type {IsGenerator} */
1196
+ utils.isGenerator = () => {
1197
+ return node !== null && Boolean(
1198
+ /**
1199
+ * @type {import('estree').FunctionDeclaration|
1200
+ * import('estree').FunctionExpression}
1201
+ */
1202
+ node.generator || node.type === 'MethodDefinition' && node.value.generator || ['ExportDefaultDeclaration', 'ExportNamedDeclaration'].includes(node.type) && /** @type {import('estree').FunctionDeclaration} */
1203
+ (
1204
+ /**
1205
+ * @type {import('estree').ExportNamedDeclaration|
1206
+ * import('estree').ExportDefaultDeclaration}
1207
+ */
1208
+ node.declaration)?.generator);
1209
+ };
1210
+
1211
+ /** @type {IsConstructor} */
1212
+ utils.isConstructor = () => {
1213
+ return jsdocUtils.isConstructor(/** @type {Node} */node);
1214
+ };
1215
+
1216
+ /** @type {GetJsdocTagsDeep} */
1217
+ utils.getJsdocTagsDeep = tagName => {
1218
+ const name = /** @type {string|false} */utils.getPreferredTagName({
1219
+ tagName
1220
+ });
1221
+ if (!name) {
1222
+ return false;
1223
+ }
1224
+ return jsdocUtils.getJsdocTagsDeep(jsdoc, name);
1225
+ };
1226
+
1227
+ /** @type {GetPreferredTagName} */
1228
+ utils.getPreferredTagName = args => {
1229
+ return jsdocUtils.getPreferredTagName(jsdoc, {
1230
+ ...args,
1231
+ context,
1232
+ mode,
1233
+ report,
1234
+ tagNamePreference
1235
+ });
1236
+ };
1237
+
1238
+ /** @type {IsValidTag} */
1239
+ utils.isValidTag = (name, definedTags) => {
1240
+ return jsdocUtils.isValidTag(context, mode, name, definedTags);
1241
+ };
1242
+
1243
+ /** @type {HasATag} */
1244
+ utils.hasATag = names => {
1245
+ return jsdocUtils.hasATag(jsdoc, names);
1246
+ };
1247
+
1248
+ /** @type {HasTag} */
1249
+ utils.hasTag = name => {
1250
+ return jsdocUtils.hasTag(jsdoc, name);
1251
+ };
1252
+
1253
+ /** @type {ComparePaths} */
1254
+ utils.comparePaths = name => {
1255
+ return jsdocUtils.comparePaths(name);
1256
+ };
1257
+
1258
+ /** @type {DropPathSegmentQuotes} */
1259
+ utils.dropPathSegmentQuotes = name => {
1260
+ return jsdocUtils.dropPathSegmentQuotes(name);
1261
+ };
1262
+
1263
+ /** @type {AvoidDocs} */
1264
+ utils.avoidDocs = () => {
1265
+ 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'))) {
1266
+ return true;
1267
+ }
1268
+ if (jsdocUtils.exemptSpeciaMethods(jsdoc, node, context, /** @type {import('json-schema').JSONSchema4|import('json-schema').JSONSchema4[]} */
1269
+ ruleConfig.meta.schema)) {
1270
+ return true;
1271
+ }
1272
+ const exemptedBy = context.options[0]?.exemptedBy ?? ['inheritDoc', ...(mode === 'closure' ? [] : ['inheritdoc'])];
1273
+ if (exemptedBy.length && utils.getPresentTags(exemptedBy).length) {
1274
+ return true;
1275
+ }
1276
+ return false;
1277
+ };
1278
+ for (const method of ['tagMightHaveNamePosition', 'tagMightHaveTypePosition']) {
1279
+ /** @type {TagMightHaveNamePositionTypePosition} */
1280
+ utils[(/** @type {"tagMightHaveNamePosition"|"tagMightHaveTypePosition"} */
1281
+ method)] = (tagName, otherModeMaps) => {
1282
+ const result = jsdocUtils[(/** @type {"tagMightHaveNamePosition"|"tagMightHaveTypePosition"} */
1283
+ method)](tagName);
1284
+ if (result) {
1285
+ return true;
1286
+ }
1287
+ if (!otherModeMaps) {
1288
+ return false;
1289
+ }
1290
+ const otherResult = otherModeMaps.some(otherModeMap => {
1291
+ return jsdocUtils[(/** @type {"tagMightHaveNamePosition"|"tagMightHaveTypePosition"} */
1292
+ method)](tagName, otherModeMap);
1293
+ });
1294
+ return otherResult ? {
1295
+ otherMode: true
1296
+ } : false;
1297
+ };
1298
+ }
1299
+
1300
+ /** @type {TagMissingRequiredTypeOrNamepath} */
1301
+ utils.tagMissingRequiredTypeOrNamepath = (tagName, otherModeMaps) => {
1302
+ const result = jsdocUtils.tagMissingRequiredTypeOrNamepath(tagName);
1303
+ if (!result) {
1304
+ return false;
1305
+ }
1306
+ const otherResult = otherModeMaps.every(otherModeMap => {
1307
+ return jsdocUtils.tagMissingRequiredTypeOrNamepath(tagName, otherModeMap);
1308
+ });
1309
+ return otherResult ? true : {
1310
+ otherMode: false
1311
+ };
1312
+ };
1313
+ for (const method of ['tagMustHaveNamePosition', 'tagMustHaveTypePosition']) {
1314
+ /** @type {TagMustHave} */
1315
+ utils[(/** @type {"tagMustHaveNamePosition"|"tagMustHaveTypePosition"} */
1316
+ method)] = (tagName, otherModeMaps) => {
1317
+ const result = jsdocUtils[(/** @type {"tagMustHaveNamePosition"|"tagMustHaveTypePosition"} */
1318
+ method)](tagName);
1319
+ if (!result) {
1320
+ return false;
1321
+ }
1322
+
1323
+ // if (!otherModeMaps) { return true; }
1324
+
1325
+ const otherResult = otherModeMaps.every(otherModeMap => {
1326
+ return jsdocUtils[(/** @type {"tagMustHaveNamePosition"|"tagMustHaveTypePosition"} */
1327
+ method)](tagName, otherModeMap);
1328
+ });
1329
+ return otherResult ? true : {
1330
+ otherMode: false
1331
+ };
1332
+ };
1333
+ }
1334
+ for (const method of ['isNamepathDefiningTag', 'isNamepathReferencingTag', 'isNamepathOrUrlReferencingTag', 'tagMightHaveNamepath']) {
1335
+ /** @type {IsNamepathX} */
1336
+ utils[(/** @type {"isNamepathDefiningTag"|"isNamepathReferencingTag"|"isNamepathOrUrlReferencingTag"|"tagMightHaveNamepath"} */
1337
+ method)] = tagName => {
1338
+ return jsdocUtils[(/** @type {"isNamepathDefiningTag"|"isNamepathReferencingTag"|"isNamepathOrUrlReferencingTag"|"tagMightHaveNamepath"} */
1339
+ method)](tagName);
1340
+ };
1341
+ }
1342
+
1343
+ /** @type {GetTagStructureForMode} */
1344
+ utils.getTagStructureForMode = mde => {
1345
+ return jsdocUtils.getTagStructureForMode(mde, settings.structuredTags);
1346
+ };
1347
+
1348
+ /** @type {MayBeUndefinedTypeTag} */
1349
+ utils.mayBeUndefinedTypeTag = tag => {
1350
+ return jsdocUtils.mayBeUndefinedTypeTag(tag, settings.mode);
1351
+ };
1352
+
1353
+ /** @type {HasValueOrExecutorHasNonEmptyResolveValue} */
1354
+ utils.hasValueOrExecutorHasNonEmptyResolveValue = (anyPromiseAsReturn, allBranches) => {
1355
+ return jsdocUtils.hasValueOrExecutorHasNonEmptyResolveValue(/** @type {Node} */node, anyPromiseAsReturn, allBranches);
1356
+ };
1357
+
1358
+ /** @type {HasYieldValue} */
1359
+ utils.hasYieldValue = () => {
1360
+ if (['ExportDefaultDeclaration', 'ExportNamedDeclaration'].includes(/** @type {Node} */node.type)) {
1361
+ return jsdocUtils.hasYieldValue(/** @type {import('estree').Declaration|import('estree').Expression} */
1362
+ /** @type {import('estree').ExportNamedDeclaration|import('estree').ExportDefaultDeclaration} */
1363
+ node.declaration);
1364
+ }
1365
+ return jsdocUtils.hasYieldValue(/** @type {Node} */node);
1366
+ };
1367
+
1368
+ /** @type {HasYieldReturnValue} */
1369
+ utils.hasYieldReturnValue = () => {
1370
+ return jsdocUtils.hasYieldValue(/** @type {Node} */node, true);
1371
+ };
1372
+
1373
+ /** @type {HasThrowValue} */
1374
+ utils.hasThrowValue = () => {
1375
+ return jsdocUtils.hasThrowValue(node);
1376
+ };
1377
+
1378
+ /** @type {IsAsync} */
1379
+ utils.isAsync = () => {
1380
+ return Boolean(node && 'async' in node && node.async);
1381
+ };
1382
+
1383
+ /** @type {GetTags} */
1384
+ utils.getTags = tagName => {
1385
+ return jsdocUtils.getTags(jsdoc, tagName);
1386
+ };
1387
+
1388
+ /** @type {GetPresentTags} */
1389
+ utils.getPresentTags = tagList => {
1390
+ return jsdocUtils.filterTags(jsdoc, tag => {
1391
+ return tagList.includes(tag.tag);
1392
+ });
1393
+ };
1394
+
1395
+ /** @type {FilterTags} */
1396
+ utils.filterTags = filter => {
1397
+ return jsdocUtils.filterTags(jsdoc, tag => {
1398
+ return filter(tag);
1399
+ });
1400
+ };
1401
+
1402
+ /** @type {FilterAllTags} */
1403
+ utils.filterAllTags = filter => {
1404
+ const tags = jsdocUtils.getAllTags(jsdoc);
1405
+ return tags.filter(tag => {
1406
+ return filter(tag);
1407
+ });
1408
+ };
1409
+
1410
+ /** @type {GetTagsByType} */
1411
+ utils.getTagsByType = tags => {
1412
+ return jsdocUtils.getTagsByType(context, mode, tags);
1413
+ };
1414
+
1415
+ /** @type {HasOptionTag} */
1416
+ utils.hasOptionTag = tagName => {
1417
+ const {
1418
+ tags
1419
+ } = context.options[0] ?? {};
1420
+ return Boolean(tags && tags.includes(tagName));
1421
+ };
1422
+
1423
+ /** @type {GetClassNode} */
1424
+ utils.getClassNode = () => {
1425
+ return [...ancestors, node].reverse().find(parent => {
1426
+ return parent && ['ClassDeclaration', 'ClassExpression'].includes(parent.type);
1427
+ }) ?? null;
1428
+ };
1429
+
1430
+ /** @type {GetClassJsdoc} */
1431
+ utils.getClassJsdoc = () => {
1432
+ const classNode = utils.getClassNode();
1433
+ if (!classNode) {
1434
+ return null;
1435
+ }
1436
+ const classJsdocNode = (0, _jsdoccomment.getJSDocComment)(sourceCode, classNode, {
1437
+ maxLines,
1438
+ minLines
1439
+ });
1440
+ if (classJsdocNode) {
1441
+ return (0, _jsdoccomment.parseComment)(classJsdocNode, '');
1442
+ }
1443
+ return null;
1444
+ };
1445
+
1446
+ /** @type {ClassHasTag} */
1447
+ utils.classHasTag = tagName => {
1448
+ const classJsdoc = utils.getClassJsdoc();
1449
+ return classJsdoc !== null && jsdocUtils.hasTag(classJsdoc, tagName);
1450
+ };
1451
+
1452
+ /** @type {ForEachPreferredTag} */
1453
+ utils.forEachPreferredTag = (tagName, arrayHandler, skipReportingBlockedTag) => {
1454
+ return jsdocUtils.forEachPreferredTag(jsdoc, tagName, arrayHandler, {
1455
+ context,
1456
+ mode,
1457
+ report,
1458
+ skipReportingBlockedTag,
1459
+ tagNamePreference
1460
+ });
1461
+ };
1462
+
1463
+ /** @type {FindContext} */
1464
+ utils.findContext = (contexts, comment) => {
1465
+ const foundContext = contexts.find(cntxt => {
1466
+ return typeof cntxt === 'string' ? _esquery.default.matches(/** @type {Node} */node, _esquery.default.parse(cntxt), undefined, {
1467
+ visitorKeys: sourceCode.visitorKeys
1468
+ }) : (!cntxt.context || cntxt.context === 'any' || _esquery.default.matches(/** @type {Node} */node, _esquery.default.parse(cntxt.context), undefined, {
1469
+ visitorKeys: sourceCode.visitorKeys
1470
+ })) && comment === cntxt.comment;
1471
+ });
1472
+ const contextStr = typeof foundContext === 'object' ? foundContext.context ?? 'any' : String(foundContext);
1473
+ return {
1474
+ contextStr,
1475
+ foundContext
1476
+ };
1477
+ };
1478
+ return utils;
1139
1479
  };
1480
+
1140
1481
  /**
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
- */
1482
+ * @typedef {{
1483
+ * [key: string]: false|string|{
1484
+ * message: string,
1485
+ * replacement?: false|string
1486
+ * skipRootChecking?: boolean
1487
+ * }
1488
+ * }} PreferredTypes
1489
+ */
1490
+ /**
1491
+ * @typedef {{
1492
+ * [key: string]: {
1493
+ * name?: "text"|"namepath-defining"|"namepath-referencing"|false,
1494
+ * type?: boolean|string[],
1495
+ * required?: ("name"|"type"|"typeOrNameRequired")[]
1496
+ * }
1497
+ * }} StructuredTags
1498
+ */
1499
+ /**
1500
+ * Settings from ESLint types.
1501
+ * @typedef {{
1502
+ * maxLines: Integer,
1503
+ * minLines: Integer,
1504
+ * tagNamePreference: import('./jsdocUtils.js').TagNamePreference,
1505
+ * mode: import('./jsdocUtils.js').ParserMode,
1506
+ * preferredTypes: PreferredTypes,
1507
+ * structuredTags: StructuredTags,
1508
+ * [name: string]: any,
1509
+ * contexts?: Context[]
1510
+ * }} Settings
1511
+ */
1512
+
1171
1513
  /**
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
- */
1514
+ * @typedef {{
1515
+ * settings?: {
1516
+ * jsdoc?: {
1517
+ * ignorePrivate: boolean,
1518
+ * ignoreInternal: boolean,
1519
+ * maxLines: Integer,
1520
+ * minLines: Integer,
1521
+ * tagNamePreference: import('./jsdocUtils.js').TagNamePreference,
1522
+ * preferredTypes: PreferredTypes,
1523
+ * structuredTags: StructuredTags,
1524
+ * overrideReplacesDocs: boolean,
1525
+ * ignoreReplacesDocs: boolean,
1526
+ * implementsReplacesDocs: boolean,
1527
+ * augmentsExtendsReplacesDocs: boolean,
1528
+ * exemptDestructuredRootsFromChecks: boolean,
1529
+ * mode: import('./jsdocUtils.js').ParserMode,
1530
+ * contexts: Context[],
1531
+ * }
1532
+ * }
1533
+ * }} JSDocSettings
1534
+ */
1535
+
1193
1536
  /**
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;
1537
+ * @param {import('eslint').Rule.RuleContext & JSDocSettings} context
1538
+ * @returns {Settings|false}
1539
+ */
1540
+ const getSettings = context => {
1541
+ /* eslint-disable perfectionist/sort-objects */
1542
+ const settings = {
1543
+ // All rules
1544
+ ignorePrivate: Boolean(context.settings.jsdoc?.ignorePrivate),
1545
+ ignoreInternal: Boolean(context.settings.jsdoc?.ignoreInternal),
1546
+ maxLines: Number(context.settings.jsdoc?.maxLines ?? 1),
1547
+ minLines: Number(context.settings.jsdoc?.minLines ?? 0),
1548
+ // `check-tag-names` and many returns/param rules
1549
+ tagNamePreference: context.settings.jsdoc?.tagNamePreference ?? {},
1550
+ // `check-types` and `no-undefined-types`
1551
+ preferredTypes: context.settings.jsdoc?.preferredTypes ?? {},
1552
+ // `check-types`, `no-undefined-types`, `valid-types`
1553
+ structuredTags: context.settings.jsdoc?.structuredTags ?? {},
1554
+ // `require-param`, `require-description`, `require-example`,
1555
+ // `require-returns`, `require-throw`, `require-yields`
1556
+ overrideReplacesDocs: context.settings.jsdoc?.overrideReplacesDocs,
1557
+ ignoreReplacesDocs: context.settings.jsdoc?.ignoreReplacesDocs,
1558
+ implementsReplacesDocs: context.settings.jsdoc?.implementsReplacesDocs,
1559
+ augmentsExtendsReplacesDocs: context.settings.jsdoc?.augmentsExtendsReplacesDocs,
1560
+ // `require-param-type`, `require-param-description`
1561
+ exemptDestructuredRootsFromChecks: context.settings.jsdoc?.exemptDestructuredRootsFromChecks,
1562
+ // Many rules, e.g., `check-tag-names`
1563
+ mode: context.settings.jsdoc?.mode ?? 'typescript',
1564
+ // Many rules
1565
+ contexts: context.settings.jsdoc?.contexts
1566
+ };
1567
+ /* eslint-enable perfectionist/sort-objects */
1568
+
1569
+ jsdocUtils.setTagStructure(settings.mode);
1570
+ try {
1571
+ jsdocUtils.overrideTagStructure(settings.structuredTags);
1572
+ } catch (error) {
1573
+ context.report({
1574
+ loc: {
1575
+ end: {
1576
+ column: 1,
1577
+ line: 1
1578
+ },
1579
+ start: {
1580
+ column: 1,
1581
+ line: 1
1582
+ }
1583
+ },
1584
+ message: /** @type {Error} */error.message
1585
+ });
1586
+ return false;
1587
+ }
1588
+ return settings;
1234
1589
  };
1590
+
1235
1591
  /**
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
- */
1592
+ * Create the report function
1593
+ * @callback MakeReport
1594
+ * @param {import('eslint').Rule.RuleContext} context
1595
+ * @param {import('estree').Node} commentNode
1596
+ * @returns {Report}
1597
+ */
1598
+
1242
1599
  /** @type {MakeReport} */
1600
+ exports.getSettings = getSettings;
1243
1601
  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;
1602
+ /** @type {Report} */
1603
+ const report = (message, fix = null, jsdocLoc = null, data = undefined) => {
1604
+ let loc;
1605
+ if (jsdocLoc) {
1606
+ if (!('line' in jsdocLoc)) {
1607
+ jsdocLoc.line = /** @type {import('comment-parser').Spec & {line?: Integer}} */jsdocLoc.source[0].number;
1608
+ }
1609
+ const lineNumber = /** @type {import('eslint').AST.SourceLocation} */commentNode.loc.start.line + (/** @type {Integer} */jsdocLoc.line);
1610
+ loc = {
1611
+ end: {
1612
+ column: 0,
1613
+ line: lineNumber
1614
+ },
1615
+ start: {
1616
+ column: 0,
1617
+ line: lineNumber
1618
+ }
1619
+ };
1620
+ if ('column' in jsdocLoc && typeof jsdocLoc.column === 'number') {
1621
+ const colNumber = /** @type {import('eslint').AST.SourceLocation} */commentNode.loc.start.column + jsdocLoc.column;
1622
+ loc.end.column = colNumber;
1623
+ loc.start.column = colNumber;
1624
+ }
1625
+ }
1626
+ context.report({
1627
+ data,
1628
+ fix,
1629
+ loc,
1630
+ message,
1631
+ node: commentNode
1632
+ });
1633
+ };
1634
+ return report;
1275
1635
  };
1636
+
1276
1637
  /**
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
- */
1638
+ * @typedef {(
1639
+ * arg: {
1640
+ * context: import('eslint').Rule.RuleContext,
1641
+ * sourceCode: import('eslint').SourceCode,
1642
+ * indent?: string,
1643
+ * info?: {
1644
+ * comment?: string|undefined,
1645
+ * lastIndex?: Integer|undefined
1646
+ * },
1647
+ * state?: StateObject,
1648
+ * globalState?: Map<string, Map<string, string>>,
1649
+ * jsdoc?: JsdocBlockWithInline,
1650
+ * jsdocNode?: import('eslint').Rule.Node & {
1651
+ * range: [number, number]
1652
+ * },
1653
+ * node?: Node,
1654
+ * allComments?: import('estree').Node[]
1655
+ * report?: Report,
1656
+ * makeReport?: MakeReport,
1657
+ * settings: Settings,
1658
+ * utils: BasicUtils,
1659
+ * }
1660
+ * ) => any } JsdocVisitorBasic
1661
+ */
1662
+ /**
1663
+ * @typedef {(
1664
+ * arg: {
1665
+ * context: import('eslint').Rule.RuleContext,
1666
+ * sourceCode: import('eslint').SourceCode,
1667
+ * indent: string,
1668
+ * info: {
1669
+ * comment?: string|undefined,
1670
+ * lastIndex?: Integer|undefined
1671
+ * },
1672
+ * state: StateObject,
1673
+ * globalState: Map<string, Map<string, string>>,
1674
+ * jsdoc: JsdocBlockWithInline,
1675
+ * jsdocNode: import('eslint').Rule.Node & {
1676
+ * range: [number, number]
1677
+ * },
1678
+ * node: Node|null,
1679
+ * allComments?: import('estree').Node[]
1680
+ * report: Report,
1681
+ * makeReport?: MakeReport,
1682
+ * settings: Settings,
1683
+ * utils: Utils,
1684
+ * }
1685
+ * ) => any } JsdocVisitor
1686
+ */
1687
+
1326
1688
  /**
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
- */
1689
+ * @param {{
1690
+ * comment?: string,
1691
+ * lastIndex?: Integer,
1692
+ * selector?: string,
1693
+ * isFunctionContext?: boolean,
1694
+ * }} info
1695
+ * @param {string} indent
1696
+ * @param {JsdocBlockWithInline} jsdoc
1697
+ * @param {RuleConfig} ruleConfig
1698
+ * @param {import('eslint').Rule.RuleContext} context
1699
+ * @param {import('@es-joy/jsdoccomment').Token} jsdocNode
1700
+ * @param {Node|null} node
1701
+ * @param {Settings} settings
1702
+ * @param {import('eslint').SourceCode} sourceCode
1703
+ * @param {JsdocVisitor} iterator
1704
+ * @param {StateObject} state
1705
+ * @param {boolean} [iteratingAll]
1706
+ * @returns {void}
1707
+ */
1346
1708
  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
- });
1709
+ const jsdocNde = /** @type {unknown} */jsdocNode;
1710
+ const report = makeReport(context, /** @type {import('estree').Node} */
1711
+ jsdocNde);
1712
+ const utils = getUtils(node, jsdoc, /** @type {import('eslint').AST.Token} */
1713
+ jsdocNode, settings, report, context, sourceCode, iteratingAll, ruleConfig, indent);
1714
+ if (!ruleConfig.checkInternal && settings.ignoreInternal && utils.hasTag('internal')) {
1715
+ return;
1716
+ }
1717
+ if (!ruleConfig.checkPrivate && settings.ignorePrivate && (utils.hasTag('private') || jsdocUtils.filterTags(jsdoc, ({
1718
+ tag
1719
+ }) => {
1720
+ return tag === 'access';
1721
+ }).some(({
1722
+ description
1723
+ }) => {
1724
+ return description === 'private';
1725
+ }))) {
1726
+ return;
1727
+ }
1728
+ iterator({
1729
+ context,
1730
+ globalState,
1731
+ indent,
1732
+ info,
1733
+ jsdoc,
1734
+ jsdocNode: (
1735
+ /**
1736
+ * @type {import('eslint').Rule.Node & {
1737
+ * range: [number, number];}}
1738
+ */
1739
+ jsdocNde),
1740
+ node,
1741
+ report,
1742
+ settings,
1743
+ sourceCode,
1744
+ state,
1745
+ utils
1746
+ });
1370
1747
  };
1748
+
1371
1749
  /**
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];
1750
+ * @param {string[]} lines
1751
+ * @param {import('estree').Comment} jsdocNode
1752
+ * @returns {[indent: string, jsdoc: JsdocBlockWithInline]}
1753
+ */
1754
+ const getIndentAndJSDoc = function (lines, jsdocNode) {
1755
+ const sourceLine = lines[/** @type {import('estree').SourceLocation} */
1756
+ jsdocNode.loc.start.line - 1];
1757
+ let indentChar = sourceLine.charAt(0);
1758
+ if (indentChar !== ' ' && indentChar !== '\t') {
1759
+ indentChar = ' ';
1760
+ }
1761
+ const indnt = indentChar.repeat(/** @type {import('estree').SourceLocation} */
1762
+ jsdocNode.loc.start.column);
1763
+ const jsdc = (0, _jsdoccomment.parseComment)(jsdocNode, '');
1764
+ return [indnt, jsdc];
1386
1765
  };
1766
+
1387
1767
  /**
1388
- *
1389
- * @typedef {{node: Node & {
1390
- * range: [number, number]
1391
- * }, state: StateObject}} NonCommentArgs
1392
- */
1768
+ *
1769
+ * @typedef {{node: Node & {
1770
+ * range: [number, number]
1771
+ * }, state: StateObject}} NonCommentArgs
1772
+ */
1773
+
1393
1774
  /**
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
- */
1775
+ * @typedef {object} RuleConfig
1776
+ * @property {EslintRuleMeta} meta ESLint rule meta
1777
+ * @property {import('./jsdocUtils.js').DefaultContexts} [contextDefaults] Any default contexts
1778
+ * @property {true} [contextSelected] Whether to force a `contexts` check
1779
+ * @property {true} [iterateAllJsdocs] Whether to iterate all JSDoc blocks by default
1780
+ * regardless of context
1781
+ * @property {true} [checkPrivate] Whether to check `@private` blocks (normally exempted)
1782
+ * @property {true} [checkInternal] Whether to check `@internal` blocks (normally exempted)
1783
+ * @property {true} [checkFile] Whether to iterates over all JSDoc blocks regardless of attachment
1784
+ * @property {true} [nonGlobalSettings] Whether to avoid relying on settings for global contexts
1785
+ * @property {true} [noTracking] Whether to disable the tracking of visited comment nodes (as
1786
+ * non-tracked may conduct further actions)
1787
+ * @property {true} [matchContext] Whether the rule expects contexts to be based on a match option
1788
+ * @property {(args: {
1789
+ * context: import('eslint').Rule.RuleContext,
1790
+ * state: StateObject,
1791
+ * settings: Settings,
1792
+ * utils: BasicUtils
1793
+ * }) => void} [exit] Handler to be executed upon exiting iteration of program AST
1794
+ * @property {(nca: NonCommentArgs) => void} [nonComment] Handler to be executed if rule wishes
1795
+ * to be supplied nodes without comments
1796
+ */
1797
+
1416
1798
  /**
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
- */
1799
+ * Create an eslint rule that iterates over all JSDocs, regardless of whether
1800
+ * they are attached to a function-like node.
1801
+ * @param {JsdocVisitor} iterator
1802
+ * @param {RuleConfig} ruleConfig The rule's configuration
1803
+ * @param {ContextObject[]|null} [contexts] The `contexts` containing relevant `comment` info.
1804
+ * @param {boolean} [additiveCommentContexts] If true, will have a separate
1805
+ * iteration for each matching comment context. Otherwise, will iterate
1806
+ * once if there is a single matching comment context.
1807
+ * @returns {import('eslint').Rule.RuleModule}
1808
+ */
1427
1809
  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
- };
1810
+ const trackedJsdocs = new Set();
1811
+
1812
+ /** @type {import('@es-joy/jsdoccomment').CommentHandler} */
1813
+ let handler;
1814
+
1815
+ /** @type {Settings|false} */
1816
+ let settings;
1817
+
1818
+ /**
1819
+ * @param {import('eslint').Rule.RuleContext} context
1820
+ * @param {Node|null} node
1821
+ * @param {import('estree').Comment[]} jsdocNodes
1822
+ * @param {StateObject} state
1823
+ * @param {boolean} [lastCall]
1824
+ * @returns {void}
1825
+ */
1826
+ const callIterator = (context, node, jsdocNodes, state, lastCall) => {
1827
+ /* c8 ignore next -- Fallback to deprecated method */
1828
+ const {
1829
+ sourceCode = context.getSourceCode()
1830
+ } = context;
1831
+ const {
1832
+ lines
1833
+ } = sourceCode;
1834
+ const utils = getBasicUtils(context, /** @type {Settings} */settings);
1835
+ for (const jsdocNode of jsdocNodes) {
1836
+ const jsdocNde = /** @type {unknown} */jsdocNode;
1837
+ if (!/^\/\*\*\s/v.test(sourceCode.getText(/** @type {import('estree').Node} */
1838
+ jsdocNde))) {
1839
+ continue;
1840
+ }
1841
+ const [indent, jsdoc] = getIndentAndJSDoc(lines, jsdocNode);
1842
+ if (additiveCommentContexts) {
1843
+ for (const [idx, {
1844
+ comment
1845
+ }] of /** @type {ContextObject[]} */contexts.entries()) {
1846
+ if (comment && handler(comment, jsdoc) === false) {
1847
+ continue;
1848
+ }
1849
+ iterate({
1850
+ comment,
1851
+ lastIndex: idx,
1852
+ selector: node?.type
1853
+ }, indent, jsdoc, ruleConfig, context, jsdocNode, /** @type {Node} */
1854
+ node, /** @type {Settings} */
1855
+ settings, sourceCode, iterator, state, true);
1856
+ }
1857
+ continue;
1858
+ }
1859
+ let lastComment;
1860
+ let lastIndex;
1861
+ // eslint-disable-next-line no-loop-func
1862
+ if (contexts && contexts.every(({
1863
+ comment
1864
+ }, idx) => {
1865
+ lastComment = comment;
1866
+ lastIndex = idx;
1867
+ return comment && handler(comment, jsdoc) === false;
1868
+ })) {
1869
+ continue;
1870
+ }
1871
+ iterate(lastComment ? {
1872
+ comment: lastComment,
1873
+ lastIndex,
1874
+ selector: node?.type
1875
+ } : {
1876
+ lastIndex,
1877
+ selector: node?.type
1878
+ }, indent, jsdoc, ruleConfig, context, jsdocNode, node, /** @type {Settings} */
1879
+ settings, sourceCode, iterator, state, true);
1880
+ }
1881
+ const settngs = /** @type {Settings} */settings;
1882
+ if (lastCall && ruleConfig.exit) {
1883
+ ruleConfig.exit({
1884
+ context,
1885
+ settings: settngs,
1886
+ state,
1887
+ utils
1888
+ });
1889
+ }
1890
+ };
1891
+ return {
1892
+ create(context) {
1893
+ /* c8 ignore next -- Fallback to deprecated method */
1894
+ const {
1895
+ sourceCode = context.getSourceCode()
1896
+ } = context;
1897
+ settings = getSettings(context);
1898
+ if (!settings) {
1899
+ return {};
1900
+ }
1901
+ if (contexts) {
1902
+ handler = (0, _jsdoccomment.commentHandler)(settings);
1903
+ }
1904
+ const state = {};
1905
+ return {
1906
+ /**
1907
+ * @param {import('eslint').Rule.Node & {
1908
+ * range: [Integer, Integer];
1909
+ * }} node
1910
+ * @returns {void}
1911
+ */
1912
+ '*:not(Program)'(node) {
1913
+ const commentNode = (0, _jsdoccomment.getJSDocComment)(sourceCode, node, /** @type {Settings} */settings);
1914
+ if (!ruleConfig.noTracking && trackedJsdocs.has(commentNode)) {
1915
+ return;
1916
+ }
1917
+ if (!commentNode) {
1918
+ if (ruleConfig.nonComment) {
1919
+ const ste = /** @type {StateObject} */state;
1920
+ ruleConfig.nonComment({
1921
+ node,
1922
+ state: ste
1923
+ });
1924
+ }
1925
+ return;
1926
+ }
1927
+ trackedJsdocs.add(commentNode);
1928
+ callIterator(context, node, [(/** @type {import('estree').Comment} */
1929
+ commentNode)], /** @type {StateObject} */state);
1930
+ },
1931
+ 'Program:exit'() {
1932
+ const allComments = sourceCode.getAllComments();
1933
+ const untrackedJSdoc = allComments.filter(node => {
1934
+ return !trackedJsdocs.has(node);
1935
+ });
1936
+ callIterator(context, null, untrackedJSdoc, /** @type {StateObject} */
1937
+ state, true);
1938
+ }
1939
+ };
1940
+ },
1941
+ meta: ruleConfig.meta
1942
+ };
1521
1943
  };
1944
+
1522
1945
  /**
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
- */
1946
+ * Create an eslint rule that iterates over all JSDocs, regardless of whether
1947
+ * they are attached to a function-like node.
1948
+ * @param {JsdocVisitorBasic} iterator
1949
+ * @param {RuleConfig} ruleConfig
1950
+ * @returns {import('eslint').Rule.RuleModule}
1951
+ */
1529
1952
  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
- };
1953
+ return {
1954
+ create(context) {
1955
+ /* c8 ignore next -- Fallback to deprecated method */
1956
+ const {
1957
+ sourceCode = context.getSourceCode()
1958
+ } = context;
1959
+ const settings = getSettings(context);
1960
+ if (!settings) {
1961
+ return {};
1962
+ }
1963
+ return {
1964
+ 'Program:exit'() {
1965
+ const allComms = /** @type {unknown} */sourceCode.getAllComments();
1966
+ const utils = getBasicUtils(context, settings);
1967
+ iterator({
1968
+ allComments: (/** @type {import('estree').Node[]} */allComms),
1969
+ context,
1970
+ makeReport,
1971
+ settings,
1972
+ sourceCode,
1973
+ utils
1974
+ });
1975
+ }
1976
+ };
1977
+ },
1978
+ meta: ruleConfig.meta
1979
+ };
1551
1980
  };
1552
1981
  /**
1553
- * @param {JsdocVisitor} iterator
1554
- * @param {RuleConfig} ruleConfig
1555
- * @returns {import('eslint').Rule.RuleModule}
1556
- */
1982
+ * @param {JsdocVisitor} iterator
1983
+ * @param {RuleConfig} ruleConfig
1984
+ * @returns {import('eslint').Rule.RuleModule}
1985
+ */
1557
1986
  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;
1987
+ const metaType = ruleConfig?.meta?.type;
1988
+ if (!metaType || !['layout', 'problem', 'suggestion'].includes(metaType)) {
1989
+ throw new TypeError('Rule must include `meta.type` option (with value "problem", "suggestion", or "layout")');
1635
1990
  }
1636
- });
1991
+ if (typeof iterator !== 'function') {
1992
+ throw new TypeError('The iterator argument must be a function.');
1993
+ }
1994
+ if (ruleConfig.checkFile) {
1995
+ return checkFile(/** @type {JsdocVisitorBasic} */iterator, ruleConfig);
1996
+ }
1997
+ if (ruleConfig.iterateAllJsdocs) {
1998
+ return iterateAllJsdocs(iterator, ruleConfig);
1999
+ }
2000
+
2001
+ /** @type {import('eslint').Rule.RuleModule} */
2002
+ return {
2003
+ /**
2004
+ * The entrypoint for the JSDoc rule.
2005
+ * @param {import('eslint').Rule.RuleContext} context
2006
+ * a reference to the context which hold all important information
2007
+ * like settings and the sourcecode to check.
2008
+ * @returns {import('eslint').Rule.RuleListener}
2009
+ * a listener with parser callback function.
2010
+ */
2011
+ create(context) {
2012
+ const settings = getSettings(context);
2013
+ if (!settings) {
2014
+ return {};
2015
+ }
2016
+
2017
+ /**
2018
+ * @type {Context[]|undefined}
2019
+ */
2020
+ let contexts;
2021
+ if (ruleConfig.contextDefaults || ruleConfig.contextSelected || ruleConfig.matchContext) {
2022
+ contexts = ruleConfig.matchContext && context.options[0]?.match ? context.options[0].match : jsdocUtils.enforcedContexts(context, ruleConfig.contextDefaults, ruleConfig.nonGlobalSettings ? {} : settings);
2023
+ if (contexts) {
2024
+ contexts = contexts.map(obj => {
2025
+ if (typeof obj === 'object' && !obj.context) {
2026
+ return {
2027
+ ...obj,
2028
+ context: 'any'
2029
+ };
2030
+ }
2031
+ return obj;
2032
+ });
2033
+ }
2034
+ const hasPlainAny = contexts?.includes('any');
2035
+ const hasObjectAny = !hasPlainAny && contexts?.find(ctxt => {
2036
+ if (typeof ctxt === 'string') {
2037
+ return false;
2038
+ }
2039
+ return ctxt?.context === 'any';
2040
+ });
2041
+ if (hasPlainAny || hasObjectAny) {
2042
+ return iterateAllJsdocs(iterator, ruleConfig, hasObjectAny ? (/** @type {ContextObject[]} */contexts) : null, ruleConfig.matchContext).create(context);
2043
+ }
2044
+ }
2045
+
2046
+ /* c8 ignore next -- Fallback to deprecated method */
2047
+ const {
2048
+ sourceCode = context.getSourceCode()
2049
+ } = context;
2050
+ const {
2051
+ lines
2052
+ } = sourceCode;
2053
+
2054
+ /** @type {Partial<StateObject>} */
2055
+ const state = {};
2056
+
2057
+ /** @type {CheckJsdoc} */
2058
+ const checkJsdoc = (info, handler, node) => {
2059
+ const jsdocNode = (0, _jsdoccomment.getJSDocComment)(sourceCode, node, settings);
2060
+ if (!jsdocNode) {
2061
+ return;
2062
+ }
2063
+ const [indent, jsdoc] = getIndentAndJSDoc(lines, /** @type {import('estree').Comment} */
2064
+ jsdocNode);
2065
+ if (
2066
+ // Note, `handler` should already be bound in its first argument
2067
+ // with these only to be called after the value of
2068
+ // `comment`
2069
+ handler && handler(jsdoc) === false) {
2070
+ return;
2071
+ }
2072
+ iterate(info, indent, jsdoc, ruleConfig, context, jsdocNode, node, settings, sourceCode, iterator, /** @type {StateObject} */
2073
+ state);
2074
+ };
2075
+
2076
+ /** @type {import('eslint').Rule.RuleListener} */
2077
+ let contextObject = {};
2078
+ if (contexts && (ruleConfig.contextDefaults || ruleConfig.contextSelected || ruleConfig.matchContext)) {
2079
+ contextObject = jsdocUtils.getContextObject(contexts, checkJsdoc, (0, _jsdoccomment.commentHandler)(settings));
2080
+ } else {
2081
+ for (const prop of ['ArrowFunctionExpression', 'FunctionDeclaration', 'FunctionExpression', 'TSDeclareFunction']) {
2082
+ contextObject[prop] = checkJsdoc.bind(null, {
2083
+ selector: prop
2084
+ }, null);
2085
+ }
2086
+ }
2087
+ if (typeof ruleConfig.exit === 'function') {
2088
+ contextObject['Program:exit'] = () => {
2089
+ const ste = /** @type {StateObject} */state;
2090
+
2091
+ // @ts-expect-error `utils` not needed at this point
2092
+ /** @type {Required<RuleConfig>} */
2093
+ ruleConfig.exit({
2094
+ context,
2095
+ settings,
2096
+ state: ste
2097
+ });
2098
+ };
2099
+ }
2100
+ return contextObject;
2101
+ },
2102
+ meta: ruleConfig.meta
2103
+ };
2104
+ }
1637
2105
  //# sourceMappingURL=iterateJsdoc.cjs.map