{"version":3,"file":"requireReturnsCheck.cjs","names":["_iterateJsdoc","_interopRequireDefault","require","_jsdocUtils","_jsdoccomment","e","__esModule","default","parseTypeModes","closure","jsdoc","typescript","canSkip","utils","settings","voidingTags","mode","push","hasATag","isConstructor","classHasTag","getReturnTypeLevelNode","parsedType","type","element","getParseMode","context","_default","exports","iterateJsdoc","node","report","sourceCode","exemptAsync","exemptGenerators","noNativeTypes","reportMissingReturnForUndefinedTypes","options","parseMode","isAsync","tagName","getPreferredTagName","tags","getTags","length","tag","trim","test","returnNever","typedefs","getDocumentNamepathDefiningTags","mayReturnUndefined","returnTag","mayBeUndefinedTypeTag","returnType","tryParseType","returnTypeLevelNode","returnIsUndefined","traverse","nde","parentNode","isReturnLevelNode","nodeType","value","referencedTypedef","find","typedefTag","name","hasValueOrExecutorHasNonEmptyResolveValue","strictNativeTypes","includes","Boolean","generator","meta","docs","description","url","schema","additionalProperties","properties","module"],"sources":["../../src/rules/requireReturnsCheck.js"],"sourcesContent":["import iterateJsdoc from '../iterateJsdoc.js';\nimport {\n  getDocumentNamepathDefiningTags,\n  strictNativeTypes,\n} from '../jsdocUtils.js';\nimport {\n  traverse,\n  tryParse as tryParseType,\n} from '@ox-jsdoc/jsdoccomment';\n\n/**\n * @type {Partial<Record<import('../jsdocUtils.js').ParserMode, import('jsdoc-type-pratt-parser').ParseMode[]>>}\n */\nconst parseTypeModes = {\n  closure: [\n    'closure',\n  ],\n  jsdoc: [\n    'jsdoc',\n  ],\n  typescript: [\n    'typescript',\n  ],\n};\n\n/**\n * @param {import('../iterateJsdoc.js').Utils} utils\n * @param {import('../iterateJsdoc.js').Settings} settings\n * @returns {boolean}\n */\nconst canSkip = (utils, settings) => {\n  const voidingTags = [\n    // An abstract function is by definition incomplete\n    // so it is perfectly fine if a return is documented but\n    // not present within the function.\n    // A subclass may inherit the doc and implement the\n    // missing return.\n    'abstract',\n    'virtual',\n\n    // A constructor function returns `this` by default, so may be `@returns`\n    //   tag indicating this but no explicit return\n    'class',\n    'constructor',\n    'interface',\n  ];\n\n  if (settings.mode === 'closure') {\n    // Structural Interface in GCC terms, equivalent to @interface tag as far as this rule is concerned\n    voidingTags.push('record');\n  }\n\n  return utils.hasATag(voidingTags) ||\n    utils.isConstructor() ||\n    utils.classHasTag('interface') ||\n    settings.mode === 'closure' && utils.classHasTag('record');\n};\n\n/**\n * @param {import('jsdoc-type-pratt-parser').RootResult} parsedType\n * @returns {import('jsdoc-type-pratt-parser').RootResult}\n */\nconst getReturnTypeLevelNode = (parsedType) => {\n  return parsedType.type === 'JsdocTypeParenthesis' ?\n    parsedType.element :\n    parsedType;\n};\n\n/**\n * @param {import('eslint').Rule.RuleContext} context\n * @param {import('../jsdocUtils.js').ParserMode} mode\n * @returns {import('../jsdocUtils.js').ParserMode}\n */\nconst getParseMode = (context, mode) => {\n  const {\n    jsdoc,\n  } = /** @type {{jsdoc?: {mode?: import('../jsdocUtils.js').ParserMode}}} */ (context.settings);\n\n  return jsdoc?.mode ?? mode;\n};\n\nexport default iterateJsdoc(({\n  context,\n  node,\n  report,\n  settings,\n  sourceCode,\n  utils,\n}) => {\n  const {\n    exemptAsync = true,\n    exemptGenerators = settings.mode === 'typescript',\n    noNativeTypes = true,\n    reportMissingReturnForUndefinedTypes = false,\n  } = context.options[0] || {};\n  const {\n    mode,\n  } = settings;\n  const parseMode = getParseMode(context, mode);\n\n  if (canSkip(utils, settings)) {\n    return;\n  }\n\n  const isAsync = utils.isAsync();\n  if (exemptAsync && isAsync) {\n    return;\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 === 0) {\n    return;\n  }\n\n  if (tags.length > 1) {\n    report(`Found more than one @${tagName} declaration.`);\n\n    return;\n  }\n\n  const [\n    tag,\n  ] = tags;\n\n  const type = tag.type.trim();\n\n  // https://www.typescriptlang.org/docs/handbook/release-notes/typescript-3-7.html#assertion-functions\n  if (/asserts\\s/v.test(type)) {\n    return;\n  }\n\n  const returnNever = type === 'never';\n  const typedefs = getDocumentNamepathDefiningTags(sourceCode, settings);\n\n  /**\n   * @param {import('comment-parser').Spec} returnTag\n   * @returns {boolean}\n   */\n  const mayReturnUndefined = (returnTag) => {\n    if (utils.mayBeUndefinedTypeTag(returnTag)) {\n      return true;\n    }\n\n    const returnType = returnTag.type.trim();\n    let parsedType;\n    try {\n      parsedType = tryParseType(returnType, parseTypeModes[parseMode]);\n    } catch {\n      return false;\n    }\n\n    const returnTypeLevelNode = getReturnTypeLevelNode(parsedType);\n    let returnIsUndefined = false;\n    traverse(returnTypeLevelNode, (nde, parentNode) => {\n      const isReturnLevelNode = !parentNode ||\n        returnTypeLevelNode.type === 'JsdocTypeUnion' && parentNode === returnTypeLevelNode;\n      if (!isReturnLevelNode) {\n        return;\n      }\n\n      const {\n        type: nodeType,\n      } = /** @type {import('jsdoc-type-pratt-parser').RootResult} */ (nde);\n\n      if (nodeType === 'JsdocTypeUndefined') {\n        returnIsUndefined = true;\n        return;\n      }\n\n      if (nodeType !== 'JsdocTypeName') {\n        return;\n      }\n\n      const {\n        value,\n      } = /** @type {import('jsdoc-type-pratt-parser').NameResult} */ (nde);\n\n      if (value === 'void') {\n        returnIsUndefined = true;\n        return;\n      }\n\n      const referencedTypedef = typedefs.find((typedefTag) => {\n        return typedefTag.name === value;\n      });\n\n      if (referencedTypedef && utils.mayBeUndefinedTypeTag(referencedTypedef)) {\n        returnIsUndefined = true;\n      }\n    });\n\n    return returnIsUndefined;\n  };\n\n  if (returnNever && utils.hasValueOrExecutorHasNonEmptyResolveValue(false)) {\n    report(`JSDoc @${tagName} declaration set with \"never\" but return expression is present in function.`);\n\n    return;\n  }\n\n  if (noNativeTypes && isAsync && strictNativeTypes.includes(type)) {\n    report('Function is async or otherwise returns a Promise but the return type is a native type.');\n    return;\n  }\n\n  // In case a return value is declared in JSDoc, we also expect one in the code.\n  if (\n    !returnNever &&\n    (\n      reportMissingReturnForUndefinedTypes ||\n      !mayReturnUndefined(tag)\n    ) &&\n    (tag.type === '' && !utils.hasValueOrExecutorHasNonEmptyResolveValue(\n      exemptAsync,\n    ) ||\n    tag.type !== '' && !utils.hasValueOrExecutorHasNonEmptyResolveValue(\n      exemptAsync,\n      true,\n    )) &&\n    Boolean(\n      !exemptGenerators || !node ||\n      !('generator' in /** @type {import('../iterateJsdoc.js').Node} */ (node)) ||\n      !(/** @type {import('@typescript-eslint/types').TSESTree.FunctionDeclaration} */ (node)).generator,\n    )\n  ) {\n    report(`JSDoc @${tagName} declaration present but return expression not available in function.`);\n  }\n}, {\n  meta: {\n    docs: {\n      description: 'Requires a return statement in function body if a `@returns` tag is specified in JSDoc comment(and reports if multiple `@returns` tags are present).',\n      url: 'https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/require-returns-check.md#repos-sticky-header',\n    },\n    schema: [\n      {\n        additionalProperties: false,\n        properties: {\n          exemptAsync: {\n            default: true,\n            description: `By default, functions which return a \\`Promise\\` that are not\ndetected as resolving with a non-\\`undefined\\` value and \\`async\\` functions\n(even ones that do not explicitly return a value, as these are returning a\n\\`Promise\\` implicitly) will be exempted from reporting by this rule.\nIf you wish to insist that only \\`Promise\\`'s which resolve to\nnon-\\`undefined\\` values or \\`async\\` functions with explicit \\`return\\`'s will\nbe exempted from reporting (i.e., that \\`async\\` functions can be reported\nif they lack an explicit (non-\\`undefined\\`) \\`return\\` when a \\`@returns\\` is\npresent), you can set \\`exemptAsync\\` to \\`false\\` on the options object.`,\n            type: 'boolean',\n          },\n          exemptGenerators: {\n            description: `Because a generator might be labeled as having a\n\\`IterableIterator\\` \\`@returns\\` value (along with an iterator type\ncorresponding to the type of any \\`yield\\` statements), projects might wish to\nleverage \\`@returns\\` in generators even without a \\`return\\` statement. This\noption is therefore \\`true\\` by default in \\`typescript\\` mode (in \"jsdoc\" mode,\none might be more likely to take advantage of \\`@yields\\`). Set it to \\`false\\`\nif you wish for a missing \\`return\\` to be flagged regardless.`,\n            type: 'boolean',\n          },\n          noNativeTypes: {\n            description: `Whether to check that async functions do not\nindicate they return non-native types. Defaults to \\`true\\`.`,\n            type: 'boolean',\n          },\n          reportMissingReturnForUndefinedTypes: {\n            default: false,\n            description: `If \\`true\\` and no return or\nresolve value is found, this setting will even insist that reporting occur\nwith \\`void\\` or \\`undefined\\` (including as an indicated \\`Promise\\` type).\nUnlike \\`require-returns\\`, with this option in the rule, one can\n*discourage* the labeling of \\`undefined\\` types. Defaults to \\`false\\`.`,\n            type: 'boolean',\n          },\n        },\n        type: 'object',\n      },\n    ],\n    type: 'suggestion',\n  },\n});\n"],"mappings":"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","ignoreList":[]}