eslint-plugin-jsdoc/dist/rules/requireReturnsCheck.cjs.map

JSDoc linting rules for ESLint.

{"version":3,"file":"requireReturnsCheck.cjs","names":["_iterateJsdoc","_interopRequireDefault","require","_jsdocUtils","e","__esModule","default","canSkip","utils","settings","voidingTags","mode","push","hasATag","isConstructor","classHasTag","_default","exports","iterateJsdoc","context","node","report","exemptAsync","exemptGenerators","noNativeTypes","reportMissingReturnForUndefinedTypes","options","isAsync","tagName","getPreferredTagName","tags","getTags","length","tag","type","trim","test","returnNever","hasValueOrExecutorHasNonEmptyResolveValue","strictNativeTypes","includes","mayBeUndefinedTypeTag","Boolean","generator","meta","docs","description","url","schema","additionalProperties","properties","module"],"sources":["../../src/rules/requireReturnsCheck.js"],"sourcesContent":["import iterateJsdoc from '../iterateJsdoc.js';\nimport {\n  strictNativeTypes,\n} from '../jsdocUtils.js';\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\nexport default iterateJsdoc(({\n  context,\n  node,\n  report,\n  settings,\n  utils,\n}) => {\n  const {\n    exemptAsync = true,\n    exemptGenerators = settings.mode === 'typescript',\n    noNativeTypes = true,\n    reportMissingReturnForUndefinedTypes = false,\n  } = context.options[0] || {};\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\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      !utils.mayBeUndefinedTypeTag(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":[]}