fix(require-returns-check): throw statements to be exempted from final check if elsewhere in function; fixes #892

Author: brettz9

README.md

@@ -17552,6 +17552,18 @@ function quux () {
   }
 }
 // Message: JSDoc @returns declaration present but return expression not available in function.
+
+/**
+ * @returns {true}
+ */
+function quux () {
+  if (true) {
+    throw new Error('abc');
+  }
+
+  throw new Error('def');
+}
+// Message: JSDoc @returns declaration present but return expression not available in function.
 ````
 
 The following patterns are not considered problems:
@@ -18003,6 +18015,17 @@ const quux = function () {
     resolve(3);
   });
 };
+
+/**
+ * @returns {true}
+ */
+function quux () {
+  if (true) {
+    return true;
+  }
+
+  throw new Error('Fail');
+}
 ````
 
 

src/utils/hasReturnValue.js

@@ -84,6 +84,10 @@ const allBrancheshaveReturnValues = (node, promFilter) => {
     );
   }
 
+  case 'ThrowStatement': {
+    return true;
+  }
+
   case 'ReturnStatement': {
     // void return does not count.
     if (node.argument === null) {
@@ -418,8 +422,9 @@ const hasNonEmptyResolverCall = (node, resolverName) => {
 const hasValueOrExecutorHasNonEmptyResolveValue = (node, anyPromiseAsReturn, allBranches) => {
   const hasReturnMethod = allBranches ?
     (nde, promiseFilter) => {
+      let hasReturn;
       try {
-        hasReturnValue(nde, true, promiseFilter);
+        hasReturn = hasReturnValue(nde, true, promiseFilter);
       } catch (error) {
         // istanbul ignore else
         if (error.message === 'Null return') {
@@ -430,7 +435,9 @@ const hasValueOrExecutorHasNonEmptyResolveValue = (node, anyPromiseAsReturn, all
         throw error;
       }
 
-      return allBrancheshaveReturnValues(nde, promiseFilter);
+      // `hasReturn` check needed since `throw` treated as valid return by
+      //   `allBrancheshaveReturnValues`
+      return hasReturn && allBrancheshaveReturnValues(nde, promiseFilter);
     } :
     (nde, promiseFilter) => {
       return hasReturnValue(nde, false, promiseFilter);

test/rules/assertions/requireReturnsCheck.js

@@ -589,6 +589,47 @@ export default {
         },
       ],
     },
+    {
+      code: `
+          /**
+           * @returns {true}
+           */
+          function quux () {
+            if (true) {
+              throw new Error('abc');
+            }
+
+            throw new Error('def');
+          }
+      `,
+      errors: [
+        {
+          line: 2,
+          message: 'JSDoc @returns declaration present but return expression not available in function.',
+        },
+      ],
+    },
+    {
+      code: `
+          /**
+           * @returns {true}
+           */
+          function quux () {
+            if (true) {
+              return true;
+            }
+
+            const a = () => {};
+          }
+      `,
+      errors: [
+        {
+          line: 2,
+          message: 'JSDoc @returns declaration present but return expression not available in function.',
+        },
+      ],
+      ignoreReadme: true,
+    },
   ],
   valid: [
     {
@@ -1260,5 +1301,19 @@ export default {
       };
       `,
     },
+    {
+      code: `
+          /**
+           * @returns {true}
+           */
+          function quux () {
+            if (true) {
+              return true;
+            }
+
+            throw new Error('Fail');
+          }
+      `,
+    },
   ],
 };