eslint-plugin-jsdoc 63.0.1 → 63.0.3

package/src/rules/noUndefinedTypes.js

@@ -1,6 +1,10 @@
 import iterateJsdoc, {
   parseComment,
 } from '../iterateJsdoc.js';
+import {
+  getDocumentNamepathDefiningTags,
+  getJSDocCommentBlocks,
+} from '../jsdocUtils.js';
 import {
   getJSDocComment,
   parse as parseType,
@@ -123,13 +127,7 @@ export default iterateJsdoc(({
   }
 
   const allComments = sourceCode.getAllComments();
-  const comments = allComments
-    .filter((comment) => {
-      return (/^\*(?!\*)/v).test(comment.value);
-    })
-    .map((commentNode) => {
-      return parseComment(commentNode, '');
-    });
+  const comments = getJSDocCommentBlocks(sourceCode);
 
   const globals = allComments
     .filter((comment) => {
@@ -138,20 +136,7 @@ export default iterateJsdoc(({
       return commentNode.value.replace(/^\s*globals/v, '').trim().split(/,\s*/v);
     }).concat(Object.keys(context.languageOptions.globals ?? []));
 
-  const typedefs = comments
-    .flatMap((doc) => {
-      return doc.tags.filter(({
-        tag,
-      }) => {
-        return utils.isNameOrNamepathDefiningTag(tag) && ![
-          'arg',
-          'argument',
-          'param',
-          'prop',
-          'property',
-        ].includes(tag);
-      });
-    });
+  const typedefs = getDocumentNamepathDefiningTags(sourceCode);
 
   const typedefDeclarations = typedefs
     .map((tag) => {
@@ -355,6 +340,17 @@ export default iterateJsdoc(({
   /** @type {Set<string>} */
   const closedTypes = new Set();
 
+  const tsModuleVariables = scopeManager.scopes.find(({
+    type,
+  }) => {
+    // @ts-expect-error TS
+    return type === 'tsModule';
+  })?.variables.map(({
+    name,
+  }) => {
+    return name;
+  }) ?? [];
+
   const allDefinedTypes = new Set(globalScope.variables.map(({
     name,
   }) => {
@@ -446,6 +442,7 @@ export default iterateJsdoc(({
     .concat(typedefDeclarations)
     .concat(importTags)
     .concat(definedTypes)
+    .concat(tsModuleVariables)
     .concat(/** @type {string[]} */ (definedPreferredTypes))
     .concat((() => {
       // Other methods are not in scope, but we need them, and we grab them here

package/src/rules/requireReturnsCheck.js

@@ -1,7 +1,27 @@
 import iterateJsdoc from '../iterateJsdoc.js';
 import {
+  getDocumentNamepathDefiningTags,
   strictNativeTypes,
 } from '../jsdocUtils.js';
+import {
+  traverse,
+  tryParse as tryParseType,
+} from '@es-joy/jsdoccomment';
+
+/**
+ * @type {Partial<Record<import('../jsdocUtils.js').ParserMode, import('jsdoc-type-pratt-parser').ParseMode[]>>}
+ */
+const parseTypeModes = {
+  closure: [
+    'closure',
+  ],
+  jsdoc: [
+    'jsdoc',
+  ],
+  typescript: [
+    'typescript',
+  ],
+};
 
 /**
  * @param {import('../iterateJsdoc.js').Utils} utils
@@ -36,11 +56,35 @@ const canSkip = (utils, settings) => {
     settings.mode === 'closure' && utils.classHasTag('record');
 };
 
+/**
+ * @param {import('jsdoc-type-pratt-parser').RootResult} parsedType
+ * @returns {import('jsdoc-type-pratt-parser').RootResult}
+ */
+const getReturnTypeLevelNode = (parsedType) => {
+  return parsedType.type === 'JsdocTypeParenthesis' ?
+    parsedType.element :
+    parsedType;
+};
+
+/**
+ * @param {import('eslint').Rule.RuleContext} context
+ * @param {import('../jsdocUtils.js').ParserMode} mode
+ * @returns {import('../jsdocUtils.js').ParserMode}
+ */
+const getParseMode = (context, mode) => {
+  const {
+    jsdoc,
+  } = /** @type {{jsdoc?: {mode?: import('../jsdocUtils.js').ParserMode}}} */ (context.settings);
+
+  return jsdoc?.mode ?? mode;
+};
+
 export default iterateJsdoc(({
   context,
   node,
   report,
   settings,
+  sourceCode,
   utils,
 }) => {
   const {
@@ -49,6 +93,10 @@ export default iterateJsdoc(({
     noNativeTypes = true,
     reportMissingReturnForUndefinedTypes = false,
   } = context.options[0] || {};
+  const {
+    mode,
+  } = settings;
+  const parseMode = getParseMode(context, mode);
 
   if (canSkip(utils, settings)) {
     return;
@@ -90,6 +138,67 @@ export default iterateJsdoc(({
   }
 
   const returnNever = type === 'never';
+  const typedefs = getDocumentNamepathDefiningTags(sourceCode);
+
+  /**
+   * @param {import('comment-parser').Spec} returnTag
+   * @returns {boolean}
+   */
+  const mayReturnUndefined = (returnTag) => {
+    if (utils.mayBeUndefinedTypeTag(returnTag)) {
+      return true;
+    }
+
+    const returnType = returnTag.type.trim();
+    let parsedType;
+    try {
+      parsedType = tryParseType(returnType, parseTypeModes[parseMode]);
+    } catch {
+      return false;
+    }
+
+    const returnTypeLevelNode = getReturnTypeLevelNode(parsedType);
+    let returnIsUndefined = false;
+    traverse(returnTypeLevelNode, (nde, parentNode) => {
+      const isReturnLevelNode = !parentNode ||
+        returnTypeLevelNode.type === 'JsdocTypeUnion' && parentNode === returnTypeLevelNode;
+      if (!isReturnLevelNode) {
+        return;
+      }
+
+      const {
+        type: nodeType,
+      } = /** @type {import('jsdoc-type-pratt-parser').RootResult} */ (nde);
+
+      if (nodeType === 'JsdocTypeUndefined') {
+        returnIsUndefined = true;
+        return;
+      }
+
+      if (nodeType !== 'JsdocTypeName') {
+        return;
+      }
+
+      const {
+        value,
+      } = /** @type {import('jsdoc-type-pratt-parser').NameResult} */ (nde);
+
+      if (value === 'void') {
+        returnIsUndefined = true;
+        return;
+      }
+
+      const referencedTypedef = typedefs.find((typedefTag) => {
+        return typedefTag.name === value;
+      });
+
+      if (referencedTypedef && utils.mayBeUndefinedTypeTag(referencedTypedef)) {
+        returnIsUndefined = true;
+      }
+    });
+
+    return returnIsUndefined;
+  };
 
   if (returnNever && utils.hasValueOrExecutorHasNonEmptyResolveValue(false)) {
     report(`JSDoc @${tagName} declaration set with "never" but return expression is present in function.`);
@@ -107,7 +216,7 @@ export default iterateJsdoc(({
     !returnNever &&
     (
       reportMissingReturnForUndefinedTypes ||
-      !utils.mayBeUndefinedTypeTag(tag)
+      !mayReturnUndefined(tag)
     ) &&
     (tag.type === '' && !utils.hasValueOrExecutorHasNonEmptyResolveValue(
       exemptAsync,