@depup/eslint-plugin-jsdoc 63.3.2-depup.1 → 64.0.0-depup.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (272) hide show
  1. package/README.md +3 -11
  2. package/changes.json +3 -16
  3. package/dist/index.d.ts +7 -4
  4. package/package.json +29 -67
  5. package/src/index.js +7 -8
  6. package/dist/WarnSettings.cjs +0 -38
  7. package/dist/WarnSettings.cjs.map +0 -1
  8. package/dist/alignTransform.cjs +0 -402
  9. package/dist/alignTransform.cjs.map +0 -1
  10. package/dist/buildForbidRuleDefinition.cjs +0 -101
  11. package/dist/buildForbidRuleDefinition.cjs.map +0 -1
  12. package/dist/buildRejectOrPreferRuleDefinition.cjs +0 -352
  13. package/dist/buildRejectOrPreferRuleDefinition.cjs.map +0 -1
  14. package/dist/cjs/WarnSettings.d.ts +0 -16
  15. package/dist/cjs/alignTransform.d.ts +0 -33
  16. package/dist/cjs/buildForbidRuleDefinition.d.ts +0 -14
  17. package/dist/cjs/buildRejectOrPreferRuleDefinition.d.ts +0 -8
  18. package/dist/cjs/defaultTagOrder.d.ts +0 -4
  19. package/dist/cjs/exportParser.d.ts +0 -40
  20. package/dist/cjs/getDefaultTagStructureForMode.d.ts +0 -10
  21. package/dist/cjs/getJsdocProcessorPlugin.d.cts +0 -5
  22. package/dist/cjs/getJsdocProcessorPlugin.d.ts +0 -66
  23. package/dist/cjs/index-cjs.d.ts +0 -23
  24. package/dist/cjs/index.cjs.d.cts +0 -2
  25. package/dist/cjs/iterateJsdoc.d.cts +0 -7
  26. package/dist/cjs/iterateJsdoc.d.ts +0 -495
  27. package/dist/cjs/jsdocUtils.d.ts +0 -500
  28. package/dist/cjs/rules/checkAccess.d.ts +0 -2
  29. package/dist/cjs/rules/checkAlignment.d.ts +0 -2
  30. package/dist/cjs/rules/checkExamples.d.ts +0 -3
  31. package/dist/cjs/rules/checkIndentation.d.ts +0 -2
  32. package/dist/cjs/rules/checkLineAlignment.d.ts +0 -9
  33. package/dist/cjs/rules/checkParamNames.d.ts +0 -2
  34. package/dist/cjs/rules/checkPropertyNames.d.ts +0 -2
  35. package/dist/cjs/rules/checkSyntax.d.ts +0 -2
  36. package/dist/cjs/rules/checkTagNames.d.ts +0 -2
  37. package/dist/cjs/rules/checkTemplateNames.d.ts +0 -2
  38. package/dist/cjs/rules/checkTypes.d.ts +0 -7
  39. package/dist/cjs/rules/checkValues.d.ts +0 -2
  40. package/dist/cjs/rules/convertToJsdocComments.d.ts +0 -266
  41. package/dist/cjs/rules/emptyTags.d.ts +0 -2
  42. package/dist/cjs/rules/escapeInlineTags.d.ts +0 -2
  43. package/dist/cjs/rules/implementsOnClasses.d.ts +0 -2
  44. package/dist/cjs/rules/importsAsDependencies.d.ts +0 -2
  45. package/dist/cjs/rules/informativeDocs.d.ts +0 -2
  46. package/dist/cjs/rules/linesBeforeBlock.d.ts +0 -2
  47. package/dist/cjs/rules/matchDescription.d.ts +0 -2
  48. package/dist/cjs/rules/matchName.d.ts +0 -2
  49. package/dist/cjs/rules/multilineBlocks.d.ts +0 -2
  50. package/dist/cjs/rules/noBadBlocks.d.ts +0 -2
  51. package/dist/cjs/rules/noBlankBlockDescriptions.d.ts +0 -2
  52. package/dist/cjs/rules/noBlankBlocks.d.ts +0 -2
  53. package/dist/cjs/rules/noDefaults.d.ts +0 -2
  54. package/dist/cjs/rules/noMissingSyntax.d.ts +0 -9
  55. package/dist/cjs/rules/noMultiAsterisks.d.ts +0 -2
  56. package/dist/cjs/rules/noRestrictedSyntax.d.ts +0 -2
  57. package/dist/cjs/rules/noTypes.d.ts +0 -2
  58. package/dist/cjs/rules/noUndefinedTypes.d.ts +0 -2
  59. package/dist/cjs/rules/normalizeSeeLinks.d.ts +0 -2
  60. package/dist/cjs/rules/preferImportTag.d.ts +0 -2
  61. package/dist/cjs/rules/requireAsteriskPrefix.d.ts +0 -2
  62. package/dist/cjs/rules/requireDescription.d.ts +0 -2
  63. package/dist/cjs/rules/requireDescriptionCompleteSentence.d.ts +0 -2
  64. package/dist/cjs/rules/requireExample.d.ts +0 -2
  65. package/dist/cjs/rules/requireFileOverview.d.ts +0 -2
  66. package/dist/cjs/rules/requireHyphenBeforeParamDescription.d.ts +0 -2
  67. package/dist/cjs/rules/requireJsdoc.d.ts +0 -24
  68. package/dist/cjs/rules/requireParam.d.ts +0 -3
  69. package/dist/cjs/rules/requireParamDescription.d.ts +0 -2
  70. package/dist/cjs/rules/requireParamName.d.ts +0 -2
  71. package/dist/cjs/rules/requireParamType.d.ts +0 -2
  72. package/dist/cjs/rules/requireProperty.d.ts +0 -2
  73. package/dist/cjs/rules/requirePropertyDescription.d.ts +0 -2
  74. package/dist/cjs/rules/requirePropertyName.d.ts +0 -2
  75. package/dist/cjs/rules/requirePropertyType.d.ts +0 -2
  76. package/dist/cjs/rules/requireRejects.d.ts +0 -2
  77. package/dist/cjs/rules/requireReturns.d.ts +0 -2
  78. package/dist/cjs/rules/requireReturnsCheck.d.ts +0 -2
  79. package/dist/cjs/rules/requireReturnsDescription.d.ts +0 -2
  80. package/dist/cjs/rules/requireReturnsType.d.ts +0 -2
  81. package/dist/cjs/rules/requireTags.d.ts +0 -2
  82. package/dist/cjs/rules/requireTemplate.d.ts +0 -2
  83. package/dist/cjs/rules/requireThrows.d.ts +0 -2
  84. package/dist/cjs/rules/requireYields.d.ts +0 -2
  85. package/dist/cjs/rules/requireYieldsCheck.d.ts +0 -2
  86. package/dist/cjs/rules/sortTags.d.ts +0 -2
  87. package/dist/cjs/rules/tagLines.d.ts +0 -2
  88. package/dist/cjs/rules/textEscaping.d.ts +0 -2
  89. package/dist/cjs/rules/tsMethodSignatureStyle.d.ts +0 -2
  90. package/dist/cjs/rules/tsNoEmptyObjectType.d.ts +0 -2
  91. package/dist/cjs/rules/tsNoUnnecessaryTemplateExpression.d.ts +0 -2
  92. package/dist/cjs/rules/tsPreferFunctionType.d.ts +0 -2
  93. package/dist/cjs/rules/typeFormatting.d.ts +0 -2
  94. package/dist/cjs/rules/validTypes.d.ts +0 -2
  95. package/dist/cjs/tagNames.d.ts +0 -15
  96. package/dist/cjs/utils/hasReturnValue.d.ts +0 -19
  97. package/dist/defaultTagOrder.cjs +0 -46
  98. package/dist/defaultTagOrder.cjs.map +0 -1
  99. package/dist/exportParser.cjs +0 -732
  100. package/dist/exportParser.cjs.map +0 -1
  101. package/dist/generateDocs.cjs +0 -342
  102. package/dist/generateDocs.cjs.map +0 -1
  103. package/dist/generateOptions.cjs +0 -62
  104. package/dist/generateOptions.cjs.map +0 -1
  105. package/dist/generateRule.cjs +0 -248
  106. package/dist/generateRule.cjs.map +0 -1
  107. package/dist/generateRuleTypes.cjs +0 -24
  108. package/dist/generateRuleTypes.cjs.map +0 -1
  109. package/dist/getDefaultTagStructureForMode.cjs +0 -289
  110. package/dist/getDefaultTagStructureForMode.cjs.map +0 -1
  111. package/dist/getJsdocProcessorPlugin.cjs +0 -587
  112. package/dist/getJsdocProcessorPlugin.cjs.map +0 -1
  113. package/dist/getJsdocProcessorPlugin.cts +0 -5
  114. package/dist/index-cjs.cjs +0 -598
  115. package/dist/index-cjs.cjs.map +0 -1
  116. package/dist/index-cjs.d.ts +0 -24
  117. package/dist/index-esm.cjs +0 -162
  118. package/dist/index-esm.cjs.map +0 -1
  119. package/dist/index-esm.d.ts +0 -72
  120. package/dist/index.cjs +0 -746
  121. package/dist/index.cjs.cts +0 -3
  122. package/dist/index.cjs.map +0 -1
  123. package/dist/iterateJsdoc.cjs +0 -2150
  124. package/dist/iterateJsdoc.cjs.map +0 -1
  125. package/dist/iterateJsdoc.cts +0 -7
  126. package/dist/jsdocUtils.cjs +0 -1786
  127. package/dist/jsdocUtils.cjs.map +0 -1
  128. package/dist/rules/checkAccess.cjs +0 -40
  129. package/dist/rules/checkAccess.cjs.map +0 -1
  130. package/dist/rules/checkAlignment.cjs +0 -78
  131. package/dist/rules/checkAlignment.cjs.map +0 -1
  132. package/dist/rules/checkExamples.cjs +0 -521
  133. package/dist/rules/checkExamples.cjs.map +0 -1
  134. package/dist/rules/checkIndentation.cjs +0 -170
  135. package/dist/rules/checkIndentation.cjs.map +0 -1
  136. package/dist/rules/checkLineAlignment.cjs +0 -398
  137. package/dist/rules/checkLineAlignment.cjs.map +0 -1
  138. package/dist/rules/checkParamNames.cjs +0 -407
  139. package/dist/rules/checkParamNames.cjs.map +0 -1
  140. package/dist/rules/checkPropertyNames.cjs +0 -135
  141. package/dist/rules/checkPropertyNames.cjs.map +0 -1
  142. package/dist/rules/checkSyntax.cjs +0 -38
  143. package/dist/rules/checkSyntax.cjs.map +0 -1
  144. package/dist/rules/checkTagNames.cjs +0 -312
  145. package/dist/rules/checkTagNames.cjs.map +0 -1
  146. package/dist/rules/checkTemplateNames.cjs +0 -192
  147. package/dist/rules/checkTemplateNames.cjs.map +0 -1
  148. package/dist/rules/checkTypes.cjs +0 -111
  149. package/dist/rules/checkTypes.cjs.map +0 -1
  150. package/dist/rules/checkValues.cjs +0 -166
  151. package/dist/rules/checkValues.cjs.map +0 -1
  152. package/dist/rules/convertToJsdocComments.cjs +0 -356
  153. package/dist/rules/convertToJsdocComments.cjs.map +0 -1
  154. package/dist/rules/emptyTags.cjs +0 -98
  155. package/dist/rules/emptyTags.cjs.map +0 -1
  156. package/dist/rules/escapeInlineTags.cjs +0 -234
  157. package/dist/rules/escapeInlineTags.cjs.map +0 -1
  158. package/dist/rules/implementsOnClasses.cjs +0 -74
  159. package/dist/rules/implementsOnClasses.cjs.map +0 -1
  160. package/dist/rules/importsAsDependencies.cjs +0 -104
  161. package/dist/rules/importsAsDependencies.cjs.map +0 -1
  162. package/dist/rules/informativeDocs.cjs +0 -187
  163. package/dist/rules/informativeDocs.cjs.map +0 -1
  164. package/dist/rules/linesBeforeBlock.cjs +0 -120
  165. package/dist/rules/linesBeforeBlock.cjs.map +0 -1
  166. package/dist/rules/matchDescription.cjs +0 -356
  167. package/dist/rules/matchDescription.cjs.map +0 -1
  168. package/dist/rules/matchName.cjs +0 -160
  169. package/dist/rules/matchName.cjs.map +0 -1
  170. package/dist/rules/multilineBlocks.cjs +0 -431
  171. package/dist/rules/multilineBlocks.cjs.map +0 -1
  172. package/dist/rules/noBadBlocks.cjs +0 -100
  173. package/dist/rules/noBadBlocks.cjs.map +0 -1
  174. package/dist/rules/noBlankBlockDescriptions.cjs +0 -63
  175. package/dist/rules/noBlankBlockDescriptions.cjs.map +0 -1
  176. package/dist/rules/noBlankBlocks.cjs +0 -54
  177. package/dist/rules/noBlankBlocks.cjs.map +0 -1
  178. package/dist/rules/noDefaults.cjs +0 -102
  179. package/dist/rules/noDefaults.cjs.map +0 -1
  180. package/dist/rules/noMissingSyntax.cjs +0 -196
  181. package/dist/rules/noMissingSyntax.cjs.map +0 -1
  182. package/dist/rules/noMultiAsterisks.cjs +0 -126
  183. package/dist/rules/noMultiAsterisks.cjs.map +0 -1
  184. package/dist/rules/noRestrictedSyntax.cjs +0 -68
  185. package/dist/rules/noRestrictedSyntax.cjs.map +0 -1
  186. package/dist/rules/noTypes.cjs +0 -101
  187. package/dist/rules/noTypes.cjs.map +0 -1
  188. package/dist/rules/noUndefinedTypes.cjs +0 -616
  189. package/dist/rules/noUndefinedTypes.cjs.map +0 -1
  190. package/dist/rules/normalizeSeeLinks.cjs +0 -271
  191. package/dist/rules/normalizeSeeLinks.cjs.map +0 -1
  192. package/dist/rules/preferImportTag.cjs +0 -362
  193. package/dist/rules/preferImportTag.cjs.map +0 -1
  194. package/dist/rules/requireAsteriskPrefix.cjs +0 -190
  195. package/dist/rules/requireAsteriskPrefix.cjs.map +0 -1
  196. package/dist/rules/requireDescription.cjs +0 -164
  197. package/dist/rules/requireDescription.cjs.map +0 -1
  198. package/dist/rules/requireDescriptionCompleteSentence.cjs +0 -321
  199. package/dist/rules/requireDescriptionCompleteSentence.cjs.map +0 -1
  200. package/dist/rules/requireExample.cjs +0 -136
  201. package/dist/rules/requireExample.cjs.map +0 -1
  202. package/dist/rules/requireFileOverview.cjs +0 -194
  203. package/dist/rules/requireFileOverview.cjs.map +0 -1
  204. package/dist/rules/requireHyphenBeforeParamDescription.cjs +0 -166
  205. package/dist/rules/requireHyphenBeforeParamDescription.cjs.map +0 -1
  206. package/dist/rules/requireJsdoc.cjs +0 -721
  207. package/dist/rules/requireJsdoc.cjs.map +0 -1
  208. package/dist/rules/requireParam.cjs +0 -772
  209. package/dist/rules/requireParam.cjs.map +0 -1
  210. package/dist/rules/requireParamDescription.cjs +0 -105
  211. package/dist/rules/requireParamDescription.cjs.map +0 -1
  212. package/dist/rules/requireParamName.cjs +0 -68
  213. package/dist/rules/requireParamName.cjs.map +0 -1
  214. package/dist/rules/requireParamType.cjs +0 -104
  215. package/dist/rules/requireParamType.cjs.map +0 -1
  216. package/dist/rules/requireProperty.cjs +0 -63
  217. package/dist/rules/requireProperty.cjs.map +0 -1
  218. package/dist/rules/requirePropertyDescription.cjs +0 -29
  219. package/dist/rules/requirePropertyDescription.cjs.map +0 -1
  220. package/dist/rules/requirePropertyName.cjs +0 -29
  221. package/dist/rules/requirePropertyName.cjs.map +0 -1
  222. package/dist/rules/requirePropertyType.cjs +0 -29
  223. package/dist/rules/requirePropertyType.cjs.map +0 -1
  224. package/dist/rules/requireRejects.cjs +0 -226
  225. package/dist/rules/requireRejects.cjs.map +0 -1
  226. package/dist/rules/requireReturns.cjs +0 -262
  227. package/dist/rules/requireReturns.cjs.map +0 -1
  228. package/dist/rules/requireReturnsCheck.cjs +0 -225
  229. package/dist/rules/requireReturnsCheck.cjs.map +0 -1
  230. package/dist/rules/requireReturnsDescription.cjs +0 -72
  231. package/dist/rules/requireReturnsDescription.cjs.map +0 -1
  232. package/dist/rules/requireReturnsType.cjs +0 -68
  233. package/dist/rules/requireReturnsType.cjs.map +0 -1
  234. package/dist/rules/requireTags.cjs +0 -74
  235. package/dist/rules/requireTags.cjs.map +0 -1
  236. package/dist/rules/requireTemplate.cjs +0 -220
  237. package/dist/rules/requireTemplate.cjs.map +0 -1
  238. package/dist/rules/requireThrows.cjs +0 -118
  239. package/dist/rules/requireThrows.cjs.map +0 -1
  240. package/dist/rules/requireYields.cjs +0 -224
  241. package/dist/rules/requireYields.cjs.map +0 -1
  242. package/dist/rules/requireYieldsCheck.cjs +0 -179
  243. package/dist/rules/requireYieldsCheck.cjs.map +0 -1
  244. package/dist/rules/sortTags.cjs +0 -656
  245. package/dist/rules/sortTags.cjs.map +0 -1
  246. package/dist/rules/tagLines.cjs +0 -374
  247. package/dist/rules/tagLines.cjs.map +0 -1
  248. package/dist/rules/textEscaping.cjs +0 -141
  249. package/dist/rules/textEscaping.cjs.map +0 -1
  250. package/dist/rules/tsMethodSignatureStyle.cjs +0 -240
  251. package/dist/rules/tsMethodSignatureStyle.cjs.map +0 -1
  252. package/dist/rules/tsNoEmptyObjectType.cjs +0 -62
  253. package/dist/rules/tsNoEmptyObjectType.cjs.map +0 -1
  254. package/dist/rules/tsNoUnnecessaryTemplateExpression.cjs +0 -104
  255. package/dist/rules/tsNoUnnecessaryTemplateExpression.cjs.map +0 -1
  256. package/dist/rules/tsPreferFunctionType.cjs +0 -110
  257. package/dist/rules/tsPreferFunctionType.cjs.map +0 -1
  258. package/dist/rules/typeFormatting.cjs +0 -607
  259. package/dist/rules/typeFormatting.cjs.map +0 -1
  260. package/dist/rules/validTypes.cjs +0 -324
  261. package/dist/rules/validTypes.cjs.map +0 -1
  262. package/dist/tagNames.cjs +0 -244
  263. package/dist/tagNames.cjs.map +0 -1
  264. package/dist/to-valid-identifier.cjs +0 -263
  265. package/dist/utils/hasReturnValue.cjs +0 -495
  266. package/dist/utils/hasReturnValue.cjs.map +0 -1
  267. package/rollup.config.js +0 -16
  268. package/src/getJsdocProcessorPlugin.cts +0 -5
  269. package/src/index-cjs.js +0 -758
  270. package/src/index-esm.js +0 -196
  271. package/src/index.cjs.cts +0 -3
  272. package/src/iterateJsdoc.cts +0 -7
@@ -1,226 +0,0 @@
1
- "use strict";
2
-
3
- Object.defineProperty(exports, "__esModule", {
4
- value: true
5
- });
6
- exports.default = void 0;
7
- var _iterateJsdoc = _interopRequireDefault(require("../iterateJsdoc.cjs"));
8
- function _interopRequireDefault(e) { return e && e.__esModule ? e : { default: e }; }
9
- /**
10
- * Checks if a node or its children contain Promise rejection patterns
11
- * @param {import('eslint').Rule.Node} node
12
- * @param {boolean} [innerFunction]
13
- * @param {boolean} [isAsync]
14
- * @returns {boolean}
15
- */
16
- // eslint-disable-next-line complexity -- Temporary
17
- const hasRejectValue = (node, innerFunction, isAsync) => {
18
- if (!node) {
19
- return false;
20
- }
21
- switch (node.type) {
22
- case 'ArrowFunctionExpression':
23
- case 'FunctionDeclaration':
24
- case 'FunctionExpression':
25
- {
26
- // For inner functions in async contexts, check if they throw
27
- // (they could be called and cause rejection)
28
- if (innerFunction) {
29
- // Check inner functions for throws - if called from async context, throws become rejections
30
- const innerIsAsync = node.async;
31
- // Pass isAsync=true if the inner function is async OR if we're already in an async context
32
- return hasRejectValue(/** @type {import('eslint').Rule.Node} */node.body, false, innerIsAsync || isAsync);
33
- }
34
-
35
- // This is the top-level function we're checking
36
- return hasRejectValue(/** @type {import('eslint').Rule.Node} */node.body, true, node.async);
37
- }
38
- case 'BlockStatement':
39
- {
40
- return node.body.some(bodyNode => {
41
- return hasRejectValue(/** @type {import('eslint').Rule.Node} */bodyNode, innerFunction, isAsync);
42
- });
43
- }
44
- case 'CallExpression':
45
- {
46
- // Check for Promise.reject()
47
- if (node.callee.type === 'MemberExpression' && node.callee.object.type === 'Identifier' && node.callee.object.name === 'Promise' && node.callee.property.type === 'Identifier' && node.callee.property.name === 'reject') {
48
- return true;
49
- }
50
-
51
- // Check for reject() call (in Promise executor context)
52
- if (node.callee.type === 'Identifier' && node.callee.name === 'reject') {
53
- return true;
54
- }
55
-
56
- // Check if this is calling an inner function that might reject
57
- if (innerFunction && node.callee.type === 'Identifier') {
58
- // We found a function call inside - check if it could be calling a function that rejects
59
- // We'll handle this in function body traversal
60
- return false;
61
- }
62
- return false;
63
- }
64
- case 'DoWhileStatement':
65
- case 'ForInStatement':
66
- case 'ForOfStatement':
67
- case 'ForStatement':
68
- case 'LabeledStatement':
69
- case 'WhileStatement':
70
- case 'WithStatement':
71
- {
72
- return hasRejectValue(/** @type {import('eslint').Rule.Node} */node.body, innerFunction, isAsync);
73
- }
74
- case 'ExpressionStatement':
75
- {
76
- return hasRejectValue(/** @type {import('eslint').Rule.Node} */node.expression, innerFunction, isAsync);
77
- }
78
- case 'IfStatement':
79
- {
80
- return hasRejectValue(/** @type {import('eslint').Rule.Node} */node.consequent, innerFunction, isAsync) || hasRejectValue(/** @type {import('eslint').Rule.Node} */node.alternate, innerFunction, isAsync);
81
- }
82
- case 'NewExpression':
83
- {
84
- // Check for new Promise((resolve, reject) => { reject(...) })
85
- if (node.callee.type === 'Identifier' && node.callee.name === 'Promise' && node.arguments.length > 0) {
86
- const executor = node.arguments[0];
87
- if (executor.type === 'ArrowFunctionExpression' || executor.type === 'FunctionExpression') {
88
- // Check if the executor has reject() calls
89
- return hasRejectValue(/** @type {import('eslint').Rule.Node} */executor.body, false, false);
90
- }
91
- }
92
- return false;
93
- }
94
- case 'ReturnStatement':
95
- {
96
- if (node.argument) {
97
- return hasRejectValue(/** @type {import('eslint').Rule.Node} */node.argument, innerFunction, isAsync);
98
- }
99
- return false;
100
- }
101
- case 'SwitchStatement':
102
- {
103
- return node.cases.some(someCase => {
104
- return someCase.consequent.some(nde => {
105
- return hasRejectValue(/** @type {import('eslint').Rule.Node} */nde, innerFunction, isAsync);
106
- });
107
- });
108
- }
109
-
110
- // Throw statements in async functions become rejections
111
- case 'ThrowStatement':
112
- {
113
- return isAsync === true;
114
- }
115
- case 'TryStatement':
116
- {
117
- return hasRejectValue(/** @type {import('eslint').Rule.Node} */node.handler && node.handler.body, innerFunction, isAsync) || hasRejectValue(/** @type {import('eslint').Rule.Node} */node.finalizer, innerFunction, isAsync);
118
- }
119
- default:
120
- {
121
- return false;
122
- }
123
- }
124
- };
125
-
126
- /**
127
- * We can skip checking for a rejects value, in case the documentation is inherited
128
- * or the method is abstract.
129
- * @param {import('../iterateJsdoc.js').Utils} utils
130
- * @returns {boolean}
131
- */
132
- const canSkip = utils => {
133
- return utils.hasATag(['abstract', 'virtual', 'type']) || utils.avoidDocs();
134
- };
135
- var _default = exports.default = (0, _iterateJsdoc.default)(({
136
- node,
137
- report,
138
- utils
139
- }) => {
140
- if (canSkip(utils)) {
141
- return;
142
- }
143
- const tagName = /** @type {string} */utils.getPreferredTagName({
144
- tagName: 'rejects'
145
- });
146
- if (!tagName) {
147
- return;
148
- }
149
- const tags = utils.getTags(tagName);
150
- const iteratingFunction = utils.isIteratingFunction();
151
- const [tag] = tags;
152
- const missingRejectsTag = typeof tag === 'undefined' || tag === null;
153
- const shouldReport = () => {
154
- if (!missingRejectsTag) {
155
- return false;
156
- }
157
-
158
- // Check if this is an async function or returns a Promise
159
- const isAsync = utils.isAsync();
160
- if (!isAsync && !iteratingFunction) {
161
- return false;
162
- }
163
-
164
- // For async functions, check for throw statements
165
- // For regular functions, check for Promise.reject or reject calls
166
- return hasRejectValue(/** @type {import('eslint').Rule.Node} */node);
167
- };
168
- if (shouldReport()) {
169
- report('Promise-rejecting function requires `@rejects` tag');
170
- }
171
- }, {
172
- contextDefaults: true,
173
- meta: {
174
- docs: {
175
- description: 'Requires that Promise rejections are documented with `@rejects` tags.',
176
- url: 'https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/require-rejects.md#repos-sticky-header'
177
- },
178
- schema: [{
179
- additionalProperties: false,
180
- properties: {
181
- contexts: {
182
- description: `Set this to an array of strings representing the AST context
183
- (or objects with optional \`context\` and \`comment\` properties) where you wish
184
- the rule to be applied.
185
-
186
- \`context\` defaults to \`any\` and \`comment\` defaults to no specific comment context.
187
-
188
- Overrides the default contexts (\`ArrowFunctionExpression\`, \`FunctionDeclaration\`,
189
- \`FunctionExpression\`).`,
190
- items: {
191
- anyOf: [{
192
- type: 'string'
193
- }, {
194
- additionalProperties: false,
195
- properties: {
196
- comment: {
197
- type: 'string'
198
- },
199
- context: {
200
- type: 'string'
201
- }
202
- },
203
- type: 'object'
204
- }]
205
- },
206
- type: 'array'
207
- },
208
- exemptedBy: {
209
- description: `Array of tags (e.g., \`['type']\`) whose presence on the
210
- document block avoids the need for a \`@rejects\`. Defaults to an array
211
- with \`abstract\`, \`virtual\`, and \`type\`. If you set this array, it will overwrite the default,
212
- so be sure to add back those tags if you wish their presence to cause
213
- exemption of the rule.`,
214
- items: {
215
- type: 'string'
216
- },
217
- type: 'array'
218
- }
219
- },
220
- type: 'object'
221
- }],
222
- type: 'suggestion'
223
- }
224
- });
225
- module.exports = exports.default;
226
- //# sourceMappingURL=requireRejects.cjs.map
@@ -1 +0,0 @@
1
- {"version":3,"file":"requireRejects.cjs","names":["iterateJsdoc"],"sources":["../../src/rules/requireRejects.js"],"sourcesContent":["import iterateJsdoc from '../iterateJsdoc.js';\n\n/**\n * Checks if a node or its children contain Promise rejection patterns\n * @param {import('eslint').Rule.Node} node\n * @param {boolean} [innerFunction]\n * @param {boolean} [isAsync]\n * @returns {boolean}\n */\n// eslint-disable-next-line complexity -- Temporary\nconst hasRejectValue = (node, innerFunction, isAsync) => {\n if (!node) {\n return false;\n }\n\n switch (node.type) {\n case 'ArrowFunctionExpression':\n case 'FunctionDeclaration':\n case 'FunctionExpression': {\n // For inner functions in async contexts, check if they throw\n // (they could be called and cause rejection)\n if (innerFunction) {\n // Check inner functions for throws - if called from async context, throws become rejections\n const innerIsAsync = node.async;\n // Pass isAsync=true if the inner function is async OR if we're already in an async context\n return hasRejectValue(/** @type {import('eslint').Rule.Node} */ (node.body), false, innerIsAsync || isAsync);\n }\n\n // This is the top-level function we're checking\n return hasRejectValue(/** @type {import('eslint').Rule.Node} */ (node.body), true, node.async);\n }\n\n case 'BlockStatement': {\n return node.body.some((bodyNode) => {\n return hasRejectValue(/** @type {import('eslint').Rule.Node} */ (bodyNode), innerFunction, isAsync);\n });\n }\n\n case 'CallExpression': {\n // Check for Promise.reject()\n if (node.callee.type === 'MemberExpression' &&\n node.callee.object.type === 'Identifier' &&\n node.callee.object.name === 'Promise' &&\n node.callee.property.type === 'Identifier' &&\n node.callee.property.name === 'reject') {\n return true;\n }\n\n // Check for reject() call (in Promise executor context)\n if (node.callee.type === 'Identifier' && node.callee.name === 'reject') {\n return true;\n }\n\n // Check if this is calling an inner function that might reject\n if (innerFunction && node.callee.type === 'Identifier') {\n // We found a function call inside - check if it could be calling a function that rejects\n // We'll handle this in function body traversal\n return false;\n }\n\n return false;\n }\n\n case 'DoWhileStatement':\n case 'ForInStatement':\n case 'ForOfStatement':\n case 'ForStatement':\n case 'LabeledStatement':\n case 'WhileStatement':\n\n case 'WithStatement': {\n return hasRejectValue(/** @type {import('eslint').Rule.Node} */ (node.body), innerFunction, isAsync);\n }\n\n case 'ExpressionStatement': {\n return hasRejectValue(/** @type {import('eslint').Rule.Node} */ (node.expression), innerFunction, isAsync);\n }\n\n case 'IfStatement': {\n return hasRejectValue(/** @type {import('eslint').Rule.Node} */ (node.consequent), innerFunction, isAsync) || hasRejectValue(/** @type {import('eslint').Rule.Node} */ (node.alternate), innerFunction, isAsync);\n }\n\n case 'NewExpression': {\n // Check for new Promise((resolve, reject) => { reject(...) })\n if (node.callee.type === 'Identifier' && node.callee.name === 'Promise' && node.arguments.length > 0) {\n const executor = node.arguments[0];\n if (executor.type === 'ArrowFunctionExpression' || executor.type === 'FunctionExpression') {\n // Check if the executor has reject() calls\n return hasRejectValue(/** @type {import('eslint').Rule.Node} */ (executor.body), false, false);\n }\n }\n\n return false;\n }\n\n case 'ReturnStatement': {\n if (node.argument) {\n return hasRejectValue(/** @type {import('eslint').Rule.Node} */ (node.argument), innerFunction, isAsync);\n }\n\n return false;\n }\n\n case 'SwitchStatement': {\n return node.cases.some(\n (someCase) => {\n return someCase.consequent.some((nde) => {\n return hasRejectValue(/** @type {import('eslint').Rule.Node} */ (nde), innerFunction, isAsync);\n });\n },\n );\n }\n\n // Throw statements in async functions become rejections\n case 'ThrowStatement': {\n return isAsync === true;\n }\n\n case 'TryStatement': {\n return hasRejectValue(/** @type {import('eslint').Rule.Node} */ (node.handler && node.handler.body), innerFunction, isAsync) ||\n hasRejectValue(/** @type {import('eslint').Rule.Node} */ (node.finalizer), innerFunction, isAsync);\n }\n\n default: {\n return false;\n }\n }\n};\n\n/**\n * We can skip checking for a rejects value, in case the documentation is inherited\n * or the method is abstract.\n * @param {import('../iterateJsdoc.js').Utils} utils\n * @returns {boolean}\n */\nconst canSkip = (utils) => {\n return utils.hasATag([\n 'abstract',\n 'virtual',\n 'type',\n ]) ||\n utils.avoidDocs();\n};\n\nexport default iterateJsdoc(({\n node,\n report,\n utils,\n}) => {\n if (canSkip(utils)) {\n return;\n }\n\n const tagName = /** @type {string} */ (utils.getPreferredTagName({\n tagName: 'rejects',\n }));\n if (!tagName) {\n return;\n }\n\n const tags = utils.getTags(tagName);\n const iteratingFunction = utils.isIteratingFunction();\n\n const [\n tag,\n ] = tags;\n const missingRejectsTag = typeof tag === 'undefined' || tag === null;\n\n const shouldReport = () => {\n if (!missingRejectsTag) {\n return false;\n }\n\n // Check if this is an async function or returns a Promise\n const isAsync = utils.isAsync();\n if (!isAsync && !iteratingFunction) {\n return false;\n }\n\n // For async functions, check for throw statements\n // For regular functions, check for Promise.reject or reject calls\n return hasRejectValue(/** @type {import('eslint').Rule.Node} */ (node));\n };\n\n if (shouldReport()) {\n report('Promise-rejecting function requires `@rejects` tag');\n }\n}, {\n contextDefaults: true,\n meta: {\n docs: {\n description: 'Requires that Promise rejections are documented with `@rejects` tags.',\n url: 'https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/require-rejects.md#repos-sticky-header',\n },\n schema: [\n {\n additionalProperties: false,\n properties: {\n contexts: {\n description: `Set this to an array of strings representing the AST context\n(or objects with optional \\`context\\` and \\`comment\\` properties) where you wish\nthe rule to be applied.\n\n\\`context\\` defaults to \\`any\\` and \\`comment\\` defaults to no specific comment context.\n\nOverrides the default contexts (\\`ArrowFunctionExpression\\`, \\`FunctionDeclaration\\`,\n\\`FunctionExpression\\`).`,\n items: {\n anyOf: [\n {\n type: 'string',\n },\n {\n additionalProperties: false,\n properties: {\n comment: {\n type: 'string',\n },\n context: {\n type: 'string',\n },\n },\n type: 'object',\n },\n ],\n },\n type: 'array',\n },\n exemptedBy: {\n description: `Array of tags (e.g., \\`['type']\\`) whose presence on the\ndocument block avoids the need for a \\`@rejects\\`. Defaults to an array\nwith \\`abstract\\`, \\`virtual\\`, and \\`type\\`. If you set this array, it will overwrite the default,\nso be sure to add back those tags if you wish their presence to cause\nexemption of the rule.`,\n items: {\n type: 'string',\n },\n type: 'array',\n },\n },\n type: 'object',\n },\n ],\n type: 'suggestion',\n },\n});\n"],"mappings":"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","ignoreList":[]}
@@ -1,262 +0,0 @@
1
- "use strict";
2
-
3
- Object.defineProperty(exports, "__esModule", {
4
- value: true
5
- });
6
- exports.default = void 0;
7
- var _exportParser = _interopRequireDefault(require("../exportParser.cjs"));
8
- var _iterateJsdoc = _interopRequireDefault(require("../iterateJsdoc.cjs"));
9
- function _interopRequireDefault(e) { return e && e.__esModule ? e : { default: e }; }
10
- /**
11
- * We can skip checking for a return value, in case the documentation is inherited
12
- * or the method is either a constructor or an abstract method.
13
- *
14
- * In either of these cases the return value is optional or not defined.
15
- * @param {import('../iterateJsdoc.js').Utils} utils
16
- * a reference to the utils which are used to probe if a tag is present or not.
17
- * @returns {boolean}
18
- * true in case deep checking can be skipped; otherwise false.
19
- */
20
- const canSkip = utils => {
21
- return utils.hasATag([
22
- // inheritdoc implies that all documentation is inherited
23
- // see https://jsdoc.app/tags-inheritdoc.html
24
- //
25
- // Abstract methods are by definition incomplete,
26
- // so it is not an error if it declares a return value but does not implement it.
27
- 'abstract', 'virtual',
28
- // Constructors do not have a return value by definition (https://jsdoc.app/tags-class.html)
29
- // So we can bail out here, too.
30
- 'class', 'constructor',
31
- // Return type is specified by type in @type
32
- 'type',
33
- // This seems to imply a class as well
34
- 'interface']) || utils.avoidDocs();
35
- };
36
- var _default = exports.default = (0, _iterateJsdoc.default)(({
37
- context,
38
- info: {
39
- comment
40
- },
41
- node,
42
- report,
43
- settings,
44
- utils
45
- }) => {
46
- const {
47
- contexts,
48
- enableFixer = false,
49
- forceRequireReturn = false,
50
- forceReturnsWithAsync = false,
51
- publicOnly = false
52
- } = context.options[0] || {};
53
-
54
- // A preflight check. We do not need to run a deep check
55
- // in case the @returns comment is optional or undefined.
56
- if (canSkip(utils)) {
57
- return;
58
- }
59
-
60
- /** @type {boolean|undefined} */
61
- let forceRequireReturnContext;
62
- if (contexts) {
63
- const {
64
- foundContext
65
- } = utils.findContext(contexts, comment);
66
- if (typeof foundContext === 'object') {
67
- forceRequireReturnContext = foundContext.forceRequireReturn;
68
- }
69
- }
70
- const tagName = /** @type {string} */utils.getPreferredTagName({
71
- tagName: 'returns'
72
- });
73
- if (!tagName) {
74
- return;
75
- }
76
- const tags = utils.getTags(tagName);
77
- if (tags.length > 1) {
78
- report(`Found more than one @${tagName} declaration.`);
79
- }
80
- const iteratingFunction = utils.isIteratingFunction();
81
-
82
- // In case the code returns something, we expect a return value in JSDoc.
83
- const [tag] = tags;
84
- const missingReturnTag = typeof tag === 'undefined' || tag === null;
85
- const shouldReport = () => {
86
- if (!missingReturnTag) {
87
- return false;
88
- }
89
- if (publicOnly) {
90
- /** @type {import('./requireJsdoc.js').RequireJsdocOpts} */
91
- const opt = {
92
- ancestorsOnly: Boolean(publicOnly?.ancestorsOnly ?? false),
93
- esm: Boolean(publicOnly?.esm ?? true),
94
- initModuleExports: Boolean(publicOnly?.cjs ?? true),
95
- initWindow: Boolean(publicOnly?.window ?? false)
96
- };
97
- /* c8 ignore next -- Fallback to deprecated method */
98
- const {
99
- // @ts-expect-error ESLint < 10
100
- sourceCode = context.getSourceCode()
101
- } = context;
102
- const exported = _exportParser.default.isUncommentedExport(/** @type {import('eslint').Rule.Node} */node, sourceCode, opt, settings);
103
- if (!exported) {
104
- return false;
105
- }
106
- }
107
- if ((forceRequireReturn || forceRequireReturnContext) && (iteratingFunction || utils.isVirtualFunction())) {
108
- return true;
109
- }
110
- const isAsync = !iteratingFunction && utils.hasTag('async') || iteratingFunction && utils.isAsync();
111
- if (forceReturnsWithAsync && isAsync) {
112
- return true;
113
- }
114
- return iteratingFunction && utils.hasValueOrExecutorHasNonEmptyResolveValue(forceReturnsWithAsync);
115
- };
116
- if (shouldReport()) {
117
- utils.reportJSDoc(`Missing JSDoc @${tagName} declaration.`, null, enableFixer ? () => {
118
- utils.addTag(tagName);
119
- } : null);
120
- }
121
- }, {
122
- contextDefaults: true,
123
- meta: {
124
- docs: {
125
- description: 'Requires that returns are documented with `@returns`.',
126
- url: 'https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/require-returns.md#repos-sticky-header'
127
- },
128
- fixable: 'code',
129
- schema: [{
130
- additionalProperties: false,
131
- properties: {
132
- checkConstructors: {
133
- default: false,
134
- description: `A value indicating whether \`constructor\`s should
135
- be checked for \`@returns\` tags. Defaults to \`false\`.`,
136
- type: 'boolean'
137
- },
138
- checkGetters: {
139
- default: true,
140
- description: `Boolean to determine whether getter methods should
141
- be checked for \`@returns\` tags. Defaults to \`true\`.`,
142
- type: 'boolean'
143
- },
144
- contexts: {
145
- description: `Set this to an array of strings representing the AST context
146
- (or objects with optional \`context\` and \`comment\` properties) where you wish
147
- the rule to be applied.
148
-
149
- \`context\` defaults to \`any\` and \`comment\` defaults to no specific comment context.
150
-
151
- Overrides the default contexts (\`ArrowFunctionExpression\`, \`FunctionDeclaration\`,
152
- \`FunctionExpression\`). Set to \`"any"\` if you want
153
- the rule to apply to any JSDoc block throughout your files (as is necessary
154
- for finding function blocks not attached to a function declaration or
155
- expression, i.e., \`@callback\` or \`@function\` (or its aliases \`@func\` or
156
- \`@method\`) (including those associated with an \`@interface\`). This
157
- rule will only apply on non-default contexts when there is such a tag
158
- present and the \`forceRequireReturn\` option is set or if the
159
- \`forceReturnsWithAsync\` option is set with a present \`@async\` tag
160
- (since we are not checking against the actual \`return\` values in these
161
- cases).`,
162
- items: {
163
- anyOf: [{
164
- type: 'string'
165
- }, {
166
- additionalProperties: false,
167
- properties: {
168
- comment: {
169
- type: 'string'
170
- },
171
- context: {
172
- type: 'string'
173
- },
174
- forceRequireReturn: {
175
- type: 'boolean'
176
- }
177
- },
178
- type: 'object'
179
- }]
180
- },
181
- type: 'array'
182
- },
183
- enableFixer: {
184
- description: `Whether to enable the fixer to add a blank \`@returns\`.
185
- Defaults to \`false\`.`,
186
- type: 'boolean'
187
- },
188
- exemptedBy: {
189
- description: `Array of tags (e.g., \`['type']\`) whose presence on the
190
- document block avoids the need for a \`@returns\`. Defaults to an array
191
- with \`inheritdoc\`. If you set this array, it will overwrite the default,
192
- so be sure to add back \`inheritdoc\` if you wish its presence to cause
193
- exemption of the rule.`,
194
- items: {
195
- type: 'string'
196
- },
197
- type: 'array'
198
- },
199
- forceRequireReturn: {
200
- default: false,
201
- description: `Set to \`true\` to always insist on
202
- \`@returns\` documentation regardless of implicit or explicit \`return\`'s
203
- in the function. May be desired to flag that a project is aware of an
204
- \`undefined\`/\`void\` return. Defaults to \`false\`.`,
205
- type: 'boolean'
206
- },
207
- forceReturnsWithAsync: {
208
- default: false,
209
- description: `By default \`async\` functions that do not explicitly
210
- return a value pass this rule as an \`async\` function will always return a
211
- \`Promise\`, even if the \`Promise\` resolves to void. You can force all
212
- \`async\` functions (including ones with an explicit \`Promise\` but no
213
- detected non-\`undefined\` \`resolve\` value) to require \`@return\`
214
- documentation by setting \`forceReturnsWithAsync\` to \`true\` on the options
215
- object. This may be useful for flagging that there has been consideration
216
- of return type. Defaults to \`false\`.`,
217
- type: 'boolean'
218
- },
219
- publicOnly: {
220
- description: `This option will insist that missing \`@returns\` are only reported for
221
- function bodies / class declarations that are exported from the module.
222
- May be a boolean or object. If set to \`true\`, the defaults below will be
223
- used. If unset, \`@returns\` reporting will not be limited to exports.
224
-
225
- This object supports the following optional boolean keys (\`false\` unless
226
- otherwise noted):
227
-
228
- - \`ancestorsOnly\` - Optimization to only check node ancestors to check if node is exported
229
- - \`esm\` - ESM exports are checked for \`@returns\` JSDoc comments (Defaults to \`true\`)
230
- - \`cjs\` - CommonJS exports are checked for \`@returns\` JSDoc comments (Defaults to \`true\`)
231
- - \`window\` - Window global exports are checked for \`@returns\` JSDoc comments`,
232
- oneOf: [{
233
- default: false,
234
- type: 'boolean'
235
- }, {
236
- additionalProperties: false,
237
- default: {},
238
- properties: {
239
- ancestorsOnly: {
240
- type: 'boolean'
241
- },
242
- cjs: {
243
- type: 'boolean'
244
- },
245
- esm: {
246
- type: 'boolean'
247
- },
248
- window: {
249
- type: 'boolean'
250
- }
251
- },
252
- type: 'object'
253
- }]
254
- }
255
- },
256
- type: 'object'
257
- }],
258
- type: 'suggestion'
259
- }
260
- });
261
- module.exports = exports.default;
262
- //# sourceMappingURL=requireReturns.cjs.map
@@ -1 +0,0 @@
1
- {"version":3,"file":"requireReturns.cjs","names":["iterateJsdoc","exportParser"],"sources":["../../src/rules/requireReturns.js"],"sourcesContent":["import exportParser from '../exportParser.js';\nimport iterateJsdoc from '../iterateJsdoc.js';\n\n/**\n * We can skip checking for a return value, in case the documentation is inherited\n * or the method is either a constructor or an abstract method.\n *\n * In either of these cases the return value is optional or not defined.\n * @param {import('../iterateJsdoc.js').Utils} utils\n * a reference to the utils which are used to probe if a tag is present or not.\n * @returns {boolean}\n * true in case deep checking can be skipped; otherwise false.\n */\nconst canSkip = (utils) => {\n return utils.hasATag([\n // inheritdoc implies that all documentation is inherited\n // see https://jsdoc.app/tags-inheritdoc.html\n //\n // Abstract methods are by definition incomplete,\n // so it is not an error if it declares a return value but does not implement it.\n 'abstract',\n 'virtual',\n\n // Constructors do not have a return value by definition (https://jsdoc.app/tags-class.html)\n // So we can bail out here, too.\n 'class',\n 'constructor',\n\n // Return type is specified by type in @type\n 'type',\n\n // This seems to imply a class as well\n 'interface',\n ]) ||\n utils.avoidDocs();\n};\n\nexport default iterateJsdoc(({\n context,\n info: {\n comment,\n },\n node,\n report,\n settings,\n utils,\n}) => {\n const {\n contexts,\n enableFixer = false,\n forceRequireReturn = false,\n forceReturnsWithAsync = false,\n publicOnly = false,\n } = context.options[0] || {};\n\n // A preflight check. We do not need to run a deep check\n // in case the @returns comment is optional or undefined.\n if (canSkip(utils)) {\n return;\n }\n\n /** @type {boolean|undefined} */\n let forceRequireReturnContext;\n if (contexts) {\n const {\n foundContext,\n } = utils.findContext(contexts, comment);\n if (typeof foundContext === 'object') {\n forceRequireReturnContext = foundContext.forceRequireReturn;\n }\n }\n\n const tagName = /** @type {string} */ (utils.getPreferredTagName({\n tagName: 'returns',\n }));\n if (!tagName) {\n return;\n }\n\n const tags = utils.getTags(tagName);\n\n if (tags.length > 1) {\n report(`Found more than one @${tagName} declaration.`);\n }\n\n const iteratingFunction = utils.isIteratingFunction();\n\n // In case the code returns something, we expect a return value in JSDoc.\n const [\n tag,\n ] = tags;\n const missingReturnTag = typeof tag === 'undefined' || tag === null;\n\n const shouldReport = () => {\n if (!missingReturnTag) {\n return false;\n }\n\n if (publicOnly) {\n /** @type {import('./requireJsdoc.js').RequireJsdocOpts} */\n const opt = {\n ancestorsOnly: Boolean(publicOnly?.ancestorsOnly ?? false),\n esm: Boolean(publicOnly?.esm ?? true),\n initModuleExports: Boolean(publicOnly?.cjs ?? true),\n initWindow: Boolean(publicOnly?.window ?? false),\n };\n /* c8 ignore next -- Fallback to deprecated method */\n const {\n // @ts-expect-error ESLint < 10\n sourceCode = context.getSourceCode(),\n } = context;\n const exported = exportParser.isUncommentedExport(\n /** @type {import('eslint').Rule.Node} */ (node), sourceCode, opt, settings,\n );\n\n if (!exported) {\n return false;\n }\n }\n\n if ((forceRequireReturn || forceRequireReturnContext) && (\n iteratingFunction || utils.isVirtualFunction()\n )) {\n return true;\n }\n\n const isAsync = !iteratingFunction && utils.hasTag('async') ||\n iteratingFunction && utils.isAsync();\n\n if (forceReturnsWithAsync && isAsync) {\n return true;\n }\n\n return iteratingFunction && utils.hasValueOrExecutorHasNonEmptyResolveValue(\n forceReturnsWithAsync,\n );\n };\n\n if (shouldReport()) {\n utils.reportJSDoc(`Missing JSDoc @${tagName} declaration.`, null, enableFixer ? () => {\n utils.addTag(tagName);\n } : null);\n }\n}, {\n contextDefaults: true,\n meta: {\n docs: {\n description: 'Requires that returns are documented with `@returns`.',\n url: 'https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/require-returns.md#repos-sticky-header',\n },\n fixable: 'code',\n schema: [\n {\n additionalProperties: false,\n properties: {\n checkConstructors: {\n default: false,\n description: `A value indicating whether \\`constructor\\`s should\nbe checked for \\`@returns\\` tags. Defaults to \\`false\\`.`,\n type: 'boolean',\n },\n checkGetters: {\n default: true,\n description: `Boolean to determine whether getter methods should\nbe checked for \\`@returns\\` tags. Defaults to \\`true\\`.`,\n type: 'boolean',\n },\n contexts: {\n description: `Set this to an array of strings representing the AST context\n(or objects with optional \\`context\\` and \\`comment\\` properties) where you wish\nthe rule to be applied.\n\n\\`context\\` defaults to \\`any\\` and \\`comment\\` defaults to no specific comment context.\n\nOverrides the default contexts (\\`ArrowFunctionExpression\\`, \\`FunctionDeclaration\\`,\n\\`FunctionExpression\\`). Set to \\`\"any\"\\` if you want\nthe rule to apply to any JSDoc block throughout your files (as is necessary\nfor finding function blocks not attached to a function declaration or\nexpression, i.e., \\`@callback\\` or \\`@function\\` (or its aliases \\`@func\\` or\n\\`@method\\`) (including those associated with an \\`@interface\\`). This\nrule will only apply on non-default contexts when there is such a tag\npresent and the \\`forceRequireReturn\\` option is set or if the\n\\`forceReturnsWithAsync\\` option is set with a present \\`@async\\` tag\n(since we are not checking against the actual \\`return\\` values in these\ncases).`,\n items: {\n anyOf: [\n {\n type: 'string',\n },\n {\n additionalProperties: false,\n properties: {\n comment: {\n type: 'string',\n },\n context: {\n type: 'string',\n },\n forceRequireReturn: {\n type: 'boolean',\n },\n },\n type: 'object',\n },\n ],\n },\n type: 'array',\n },\n enableFixer: {\n description: `Whether to enable the fixer to add a blank \\`@returns\\`.\nDefaults to \\`false\\`.`,\n type: 'boolean',\n },\n exemptedBy: {\n description: `Array of tags (e.g., \\`['type']\\`) whose presence on the\ndocument block avoids the need for a \\`@returns\\`. Defaults to an array\nwith \\`inheritdoc\\`. If you set this array, it will overwrite the default,\nso be sure to add back \\`inheritdoc\\` if you wish its presence to cause\nexemption of the rule.`,\n items: {\n type: 'string',\n },\n type: 'array',\n },\n forceRequireReturn: {\n default: false,\n description: `Set to \\`true\\` to always insist on\n\\`@returns\\` documentation regardless of implicit or explicit \\`return\\`'s\nin the function. May be desired to flag that a project is aware of an\n\\`undefined\\`/\\`void\\` return. Defaults to \\`false\\`.`,\n type: 'boolean',\n },\n forceReturnsWithAsync: {\n default: false,\n description: `By default \\`async\\` functions that do not explicitly\nreturn a value pass this rule as an \\`async\\` function will always return a\n\\`Promise\\`, even if the \\`Promise\\` resolves to void. You can force all\n\\`async\\` functions (including ones with an explicit \\`Promise\\` but no\ndetected non-\\`undefined\\` \\`resolve\\` value) to require \\`@return\\`\ndocumentation by setting \\`forceReturnsWithAsync\\` to \\`true\\` on the options\nobject. This may be useful for flagging that there has been consideration\nof return type. Defaults to \\`false\\`.`,\n type: 'boolean',\n },\n publicOnly: {\n description: `This option will insist that missing \\`@returns\\` are only reported for\nfunction bodies / class declarations that are exported from the module.\nMay be a boolean or object. If set to \\`true\\`, the defaults below will be\nused. If unset, \\`@returns\\` reporting will not be limited to exports.\n\nThis object supports the following optional boolean keys (\\`false\\` unless\notherwise noted):\n\n- \\`ancestorsOnly\\` - Optimization to only check node ancestors to check if node is exported\n- \\`esm\\` - ESM exports are checked for \\`@returns\\` JSDoc comments (Defaults to \\`true\\`)\n- \\`cjs\\` - CommonJS exports are checked for \\`@returns\\` JSDoc comments (Defaults to \\`true\\`)\n- \\`window\\` - Window global exports are checked for \\`@returns\\` JSDoc comments`,\n oneOf: [\n {\n default: false,\n type: 'boolean',\n },\n {\n additionalProperties: false,\n default: {},\n properties: {\n ancestorsOnly: {\n type: 'boolean',\n },\n cjs: {\n type: 'boolean',\n },\n esm: {\n type: 'boolean',\n },\n window: {\n type: 'boolean',\n },\n },\n type: 'object',\n },\n ],\n },\n },\n type: 'object',\n },\n ],\n type: 'suggestion',\n },\n});\n"],"mappings":"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","ignoreList":[]}