eslint-plugin-jsdoc 52.0.4 → 53.0.1

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