feat(require-returns-check): add noNativeTypes option to assert async functions do not have native types as return types; fixes #1345

Author: brettz9

.README/rules/require-returns-check.md

@@ -11,6 +11,8 @@ Will also report `@returns {void}` and `@returns {undefined}` if `exemptAsync`
 is set to `false` and a non-`undefined` value is returned or a resolved value
 is found. Also reports if `@returns {never}` is discovered with a return value.
 
+Will report if native types are specified for `@returns` on an async function.
+
 Will also report if multiple `@returns` tags are present.
 
 ## Options
@@ -24,7 +26,7 @@ Will also report if multiple `@returns` tags are present.
 |Context|`ArrowFunctionExpression`, `FunctionDeclaration`, `FunctionExpression`|
 |Tags|`returns`|
 |Aliases|`return`|
-|Options|`exemptAsync`, `exemptGenerators`, `reportMissingReturnForUndefinedTypes`|
+|Options|`exemptAsync`, `exemptGenerators`, `noNativeTypes`, `reportMissingReturnForUndefinedTypes`|
 |Recommended|true|
 
 ## Failing examples

docs/rules/require-returns-check.md

@@ -5,6 +5,7 @@
 * [Options](#user-content-require-returns-check-options)
     * [`exemptAsync`](#user-content-require-returns-check-options-exemptasync)
     * [`exemptGenerators`](#user-content-require-returns-check-options-exemptgenerators)
+    * [`noNativeTypes`](#user-content-require-returns-check-options-nonativetypes)
     * [`reportMissingReturnForUndefinedTypes`](#user-content-require-returns-check-options-reportmissingreturnforundefinedtypes)
 * [Context and settings](#user-content-require-returns-check-context-and-settings)
 * [Failing examples](#user-content-require-returns-check-failing-examples)
@@ -20,6 +21,8 @@ Will also report `@returns {void}` and `@returns {undefined}` if `exemptAsync`
 is set to `false` and a non-`undefined` value is returned or a resolved value
 is found. Also reports if `@returns {never}` is discovered with a return value.
 
+Will report if native types are specified for `@returns` on an async function.
+
 Will also report if multiple `@returns` tags are present.
 
 <a name="user-content-require-returns-check-options"></a>
@@ -54,6 +57,13 @@ option is therefore `true` by default in `typescript` mode (in "jsdoc" mode,
 one might be more likely to take advantage of `@yields`). Set it to `false`
 if you wish for a missing `return` to be flagged regardless.
 
+<a name="user-content-require-returns-check-options-nonativetypes"></a>
+<a name="require-returns-check-options-nonativetypes"></a>
+### <code>noNativeTypes</code>
+
+Whether to check that async functions do not
+indicate they return non-native types. Defaults to `true`.
+
 <a name="user-content-require-returns-check-options-reportmissingreturnforundefinedtypes"></a>
 <a name="require-returns-check-options-reportmissingreturnforundefinedtypes"></a>
 ### <code>reportMissingReturnForUndefinedTypes</code>
@@ -74,7 +84,7 @@ Unlike `require-returns`, with this option in the rule, one can
 |Context|`ArrowFunctionExpression`, `FunctionDeclaration`, `FunctionExpression`|
 |Tags|`returns`|
 |Aliases|`return`|
-|Options|`exemptAsync`, `exemptGenerators`, `reportMissingReturnForUndefinedTypes`|
+|Options|`exemptAsync`, `exemptGenerators`, `noNativeTypes`, `reportMissingReturnForUndefinedTypes`|
 |Recommended|true|
 
 <a name="user-content-require-returns-check-failing-examples"></a>
@@ -206,7 +216,7 @@ function quux() {
 
 /**
  * Description.
- * @returns {string}
+ * @returns {SomeType}
  */
 async function foo() {
   return new Promise(resolve => resolve());
@@ -401,6 +411,15 @@ function foo() {
   }
 }
 // Message: JSDoc @returns declaration present but return expression not available in function.
+
+/**
+ * @returns {number}
+ */
+async function quux (foo) {
+
+}
+// "jsdoc/require-returns-check": ["error"|"warn", {"exemptAsync":false}]
+// Message: Function is async or otherwise returns a Promise but the return type is a native type.
 ````
 
 

src/jsdocUtils.js

@@ -962,7 +962,7 @@ const mayBeUndefinedTypeTag = (tag, mode) => {
     // We do not traverse deeply as it could be, e.g., `Promise<void>`
     parsedTypes &&
     parsedTypes.type === 'JsdocTypeUnion' &&
-    parsedTypes.elements.find((elem) => {
+    parsedTypes.elements.some((elem) => {
       return elem.type === 'JsdocTypeUndefined' ||
         elem.type === 'JsdocTypeName' && elem.value === 'void';
     })) {
@@ -1845,6 +1845,21 @@ const getRegexFromString = (regexString, requiredFlags) => {
   return new RegExp(regex, flags);
 };
 
+const strictNativeTypes = [
+  'undefined',
+  'null',
+  'boolean',
+  'number',
+  'bigint',
+  'string',
+  'symbol',
+  'object',
+  'Array',
+  'Function',
+  'Date',
+  'RegExp',
+];
+
 export {
   comparePaths,
   dropPathSegmentQuotes,
@@ -1885,6 +1900,7 @@ export {
   parseClosureTemplateTag,
   pathDoesNotBeginWith,
   setTagStructure,
+  strictNativeTypes,
   tagMightHaveEitherTypeOrNamePosition,
   tagMightHaveNamepath,
   tagMightHaveNamePosition,

src/rules.d.ts

@@ -2317,6 +2317,11 @@ export interface Rules {
            * if you wish for a missing `return` to be flagged regardless.
            */
           exemptGenerators?: boolean;
+          /**
+           * Whether to check that async functions do not
+           * indicate they return non-native types. Defaults to `true`.
+           */
+          noNativeTypes?: boolean;
           /**
            * If `true` and no return or
            * resolve value is found, this setting will even insist that reporting occur

src/rules/checkTypes.js

@@ -1,21 +1,9 @@
 import {
   buildRejectOrPreferRuleDefinition,
 } from '../buildRejectOrPreferRuleDefinition.js';
-
-const strictNativeTypes = [
-  'undefined',
-  'null',
-  'boolean',
-  'number',
-  'bigint',
-  'string',
-  'symbol',
-  'object',
-  'Array',
-  'Function',
-  'Date',
-  'RegExp',
-];
+import {
+  strictNativeTypes,
+} from '../jsdocUtils.js';
 
 /**
  * @callback CheckNativeTypes

src/rules/requireReturnsCheck.js

@@ -1,4 +1,7 @@
 import iterateJsdoc from '../iterateJsdoc.js';
+import {
+  strictNativeTypes,
+} from '../jsdocUtils.js';
 
 /**
  * @param {import('../iterateJsdoc.js').Utils} utils
@@ -43,14 +46,16 @@ export default iterateJsdoc(({
   const {
     exemptAsync = true,
     exemptGenerators = settings.mode === 'typescript',
+    noNativeTypes = true,
     reportMissingReturnForUndefinedTypes = false,
   } = context.options[0] || {};
 
   if (canSkip(utils, settings)) {
     return;
   }
 
-  if (exemptAsync && utils.isAsync()) {
+  const isAsync = utils.isAsync();
+  if (exemptAsync && isAsync) {
     return;
   }
 
@@ -92,6 +97,11 @@ export default iterateJsdoc(({
     return;
   }
 
+  if (noNativeTypes && isAsync && strictNativeTypes.includes(type)) {
+    report('Function is async or otherwise returns a Promise but the return type is a native type.');
+    return;
+  }
+
   // In case a return value is declared in JSDoc, we also expect one in the code.
   if (
     !returnNever &&
@@ -147,6 +157,11 @@ one might be more likely to take advantage of \`@yields\`). Set it to \`false\`
 if you wish for a missing \`return\` to be flagged regardless.`,
             type: 'boolean',
           },
+          noNativeTypes: {
+            description: `Whether to check that async functions do not
+indicate they return non-native types. Defaults to \`true\`.`,
+            type: 'boolean',
+          },
           reportMissingReturnForUndefinedTypes: {
             default: false,
             description: `If \`true\` and no return or

test/rules/assertions/requireReturnsCheck.js

@@ -277,7 +277,7 @@ export default /** @type {import('../index.js').TestCases} */ ({
       code: `
         /**
          * Description.
-         * @returns {string}
+         * @returns {SomeType}
          */
         async function foo() {
           return new Promise(resolve => resolve());
@@ -664,7 +664,27 @@ export default /** @type {import('../index.js').TestCases} */ ({
         },
       ],
     },
+    {
+      code: `
+          /**
+           * @returns {number}
+           */
+          async function quux (foo) {
 
+          }
+      `,
+      errors: [
+        {
+          line: 2,
+          message: 'Function is async or otherwise returns a Promise but the return type is a native type.',
+        },
+      ],
+      options: [
+        {
+          exemptAsync: false,
+        },
+      ],
+    },
   ],
   valid: [
     {