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

.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/prefer-import-tag.md

@@ -294,6 +294,14 @@ The following patterns are considered problems:
  */
 // "jsdoc/prefer-import-tag": ["error"|"warn", {"exemptTypedefs":true}]
 // Message: Inline `import()` found; using `@typedef`
+
+/** @type {import('foo')} */
+let foo;
+// Message: Inline `import()` found; prefer `@import`
+
+/** @type {import('foo')} */
+let foo;
+// Message: Inline `import()` found; prefer `@import`
 ````
 
 

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.
 ````
 
 

package.json

@@ -5,7 +5,7 @@
     "url": "http://gajus.com"
   },
   "dependencies": {
-    "@es-joy/jsdoccomment": "~0.64.0",
+    "@es-joy/jsdoccomment": "~0.65.2",
     "are-docs-informative": "^0.0.2",
     "comment-parser": "1.4.1",
     "debug": "^4.4.3",
@@ -41,7 +41,7 @@
     "@types/estree": "^1.0.8",
     "@types/json-schema": "^7.0.15",
     "@types/mocha": "^10.0.10",
-    "@types/node": "^24.6.0",
+    "@types/node": "^24.6.1",
     "@types/semver": "^7.7.1",
     "@types/spdx-expression-parse": "^3.0.5",
     "@typescript-eslint/types": "^8.45.0",
@@ -58,7 +58,7 @@
     "glob": "^11.0.3",
     "globals": "^16.4.0",
     "husky": "^9.1.7",
-    "jsdoc-type-pratt-parser": "^6.0.1",
+    "jsdoc-type-pratt-parser": "^6.1.2",
     "json-schema": "^0.4.0",
     "json-schema-to-typescript": "^15.0.4",
     "lint-staged": "^16.2.3",
@@ -67,7 +67,7 @@
     "replace": "^1.2.2",
     "rimraf": "^6.0.1",
     "semantic-release": "^24.2.9",
-    "typescript": "5.9.2",
+    "typescript": "5.9.3",
     "typescript-eslint": "^8.45.0"
   },
   "engines": {