fix(require-returns-check, require-yields-check): check for undef…

…ined/void within union; fixes #925

README.md

@@ -18141,6 +18141,16 @@ function getTrue() {
     console.log('returning...');
   }
 }
+
+/**
+ * Maybe return a boolean.
+ * @returns {boolean|void} true, or undefined.
+ */
+function maybeTrue() {
+  if (Math.random() > 0.5) {
+    return true;
+  }
+}
 ````
 
 

src/iterateJsdoc.js

@@ -676,7 +676,7 @@ const getUtils = (
   };
 
   utils.hasDefinedTypeTag = (tag) => {
-    return jsdocUtils.hasDefinedTypeTag(tag);
+    return jsdocUtils.hasDefinedTypeTag(tag, settings.mode);
   };
 
   utils.hasValueOrExecutorHasNonEmptyResolveValue = (anyPromiseAsReturn, allBranches) => {

src/jsdocUtils.js

@@ -1,5 +1,8 @@
 /* eslint-disable jsdoc/no-undefined-types */
 
+import {
+  tryParse,
+} from '@es-joy/jsdoccomment';
 import WarnSettings from './WarnSettings';
 import getDefaultTagStructureForMode from './getDefaultTagStructureForMode';
 import {
@@ -465,21 +468,47 @@ const hasATag = (jsdoc, targetTagNames) => {
  *
  * @param {JsDocTag} tag
  *   the tag which should be checked.
+ * @param {"jsdoc"|"closure"|"typescript"} mode
  * @returns {boolean}
  *   true in case a defined type is declared; otherwise false.
  */
-const hasDefinedTypeTag = (tag) => {
+const hasDefinedTypeTag = (tag, mode) => {
   // The function should not continue in the event the type is not defined...
   if (typeof tag === 'undefined' || tag === null) {
     return false;
   }
 
   // .. same applies if it declares an `{undefined}` or `{void}` type
   const tagType = tag.type.trim();
+
+  // Exit early if matching
   if (tagType === 'undefined' || tagType === 'void') {
     return false;
   }
 
+  let parsedTypes;
+  try {
+    parsedTypes = tryParse(
+      tagType,
+      mode === 'permissive' ? undefined : [
+        mode,
+      ],
+    );
+  } catch {
+    // Ignore
+  }
+
+  if (
+    // We do not traverse deeply as it could be, e.g., `Promise<void>`
+    parsedTypes &&
+    parsedTypes.type === 'JsdocTypeUnion' &&
+    parsedTypes.elements.find((elem) => {
+      return elem.type === 'JsdocTypeUndefined' ||
+        elem.type === 'JsdocTypeName' && elem.value === 'void';
+    })) {
+    return false;
+  }
+
   // In any other case, a type is present
   return true;
 };

test/rules/assertions/requireReturnsCheck.js

@@ -1426,5 +1426,37 @@ export default {
       }
       `,
     },
+    {
+      code: `
+      /**
+       * Maybe return a boolean.
+       * @returns {boolean|void} true, or undefined.
+       */
+      function maybeTrue() {
+        if (Math.random() > 0.5) {
+          return true;
+        }
+      }
+      `,
+    },
+    {
+      code: `
+      /**
+       * Maybe return a boolean.
+       * @return {boolean|void} true, or undefined.
+       */
+      function maybeTrue() {
+        if (Math.random() > 0.5) {
+          return true;
+        }
+      }
+      `,
+      ignoreReadme: true,
+      settings: {
+        jsdoc: {
+          mode: 'permissive',
+        },
+      },
+    },
   ],
 };