Merge pull request #283 from interfaced/no-undefined-types-add-gcc-templates

feat(no-undefined-types): treat GCC generic types as defined

Author: brettz9

README.md

@@ -2784,6 +2784,35 @@ function quux(foo, bar, baz) {
 // Settings: {"jsdoc":{"preferredTypes":{"hertype":{"replacement":false},"histype":"HisType"}}}
 // Options: [{"definedTypes":["MyType"],"preferredTypesDefined":true}]
 // Message: The type 'HerType' is undefined.
+
+class Foo {
+  /**
+   * @return {TEMPLATE_TYPE}
+   */
+  bar () {
+  }
+}
+// Message: The type 'TEMPLATE_TYPE' is undefined.
+
+class Foo {
+  /**
+   * @return {TEMPLATE_TYPE}
+   */
+  invalidTemplateReference () {
+  }
+}
+
+/**
+ * @template TEMPLATE_TYPE
+ */
+class Bar {
+  /**
+   * @return {TEMPLATE_TYPE}
+   */
+  validTemplateReference () {
+  }
+}
+// Message: The type 'TEMPLATE_TYPE' is undefined.
 ````
 
 The following patterns are not considered problems:
@@ -2934,6 +2963,29 @@ function quux(foo, bar, baz) {
 }
 // Settings: {"jsdoc":{"preferredTypes":{"hertype":{"replacement":"HerType<>"},"histype":"HisType.<>"}}}
 // Options: [{"definedTypes":["MyType"],"preferredTypesDefined":true}]
+
+/**
+ * @template TEMPLATE_TYPE
+ */
+class Foo {
+  /**
+   * @return {TEMPLATE_TYPE}
+   */
+  bar () {
+  }
+}
+
+/**
+ * @template TEMPLATE_TYPE_A, TEMPLATE_TYPE_B
+ */
+class Foo {
+  /**
+   * @param {TEMPLATE_TYPE_A} baz
+   * @return {TEMPLATE_TYPE_B}
+   */
+  bar (baz) {
+  }
+}
 ````
 
 

src/iterateJsdoc.js

@@ -189,20 +189,23 @@ const curryUtils = (
     return false;
   };
 
-  utils.classHasTag = (tagName) => {
+  utils.getClassJsdoc = () => {
     const classNode = utils.getClassNode();
     const classJsdocNode = getJSDocComment(sourceCode, classNode);
 
     if (classJsdocNode) {
       const indent = _.repeat(' ', classJsdocNode.loc.start.column);
-      const classJsdoc = parseComment(classJsdocNode, indent);
 
-      if (jsdocUtils.hasTag(classJsdoc, tagName)) {
-        return true;
-      }
+      return parseComment(classJsdocNode, indent);
     }
 
-    return false;
+    return null;
+  };
+
+  utils.classHasTag = (tagName) => {
+    const classJsdoc = utils.getClassJsdoc();
+
+    return classJsdoc && jsdocUtils.hasTag(classJsdoc, tagName);
   };
 
   utils.forEachTag = (tagName, arrayHandler) => {

src/jsdocUtils.js

@@ -461,6 +461,22 @@ const isInlineTag = (tag) => {
 };
 */
 
+/**
+ * Parses GCC Generic/Template types
+ *
+ * @see {https://github.com/google/closure-compiler/wiki/Generic-Types}
+ * @param {JsDocTag} tag
+ * @returns {Array<string>}
+ */
+const parseClosureTemplateTag = (tag) => {
+  return tag.source
+    .split('@template')[1]
+    .split(',')
+    .map((type) => {
+      return type.trim();
+    });
+};
+
 export default {
   getFunctionParameterNames,
   getJsdocParameterNames,
@@ -474,5 +490,6 @@ export default {
   isNamepathTag,
   isPotentiallyEmptyNamepathTag,
   isTagWithType,
-  isValidTag
+  isValidTag,
+  parseClosureTemplateTag
 };

src/rules/noUndefinedTypes.js

@@ -3,6 +3,7 @@ import 'flat-map-polyfill';
 import _ from 'lodash';
 import {parse as parseType, traverse} from 'jsdoctypeparser';
 import iterateJsdoc, {parseComment} from '../iterateJsdoc';
+import jsdocUtils from '../jsdocUtils';
 
 const extraTypes = [
   'null', 'undefined', 'string', 'boolean', 'object',
@@ -67,6 +68,18 @@ export default iterateJsdoc(({
     })
     .value();
 
+  let closureGenericTypes = [];
+  const classJsdoc = utils.getClassJsdoc();
+  if (classJsdoc && classJsdoc.tags) {
+    closureGenericTypes = classJsdoc.tags
+      .filter((tag) => {
+        return tag.tag === 'template';
+      })
+      .flatMap((tag) => {
+        return jsdocUtils.parseClosureTemplateTag(tag);
+      });
+  }
+
   const allDefinedTypes = globalScope.variables.map((variable) => {
     return variable.name;
   })
@@ -89,7 +102,8 @@ export default iterateJsdoc(({
     .concat(extraTypes)
     .concat(typedefDeclarations)
     .concat(definedTypes)
-    .concat(definedPreferredTypes);
+    .concat(definedPreferredTypes)
+    .concat(closureGenericTypes);
 
   const jsdocTags = utils.filterTags((tag) => {
     return utils.isTagWithType(tag.tag);

test/rules/assertions/noUndefinedTypes.js

@@ -154,6 +154,51 @@ export default {
           }
         }
       }
+    },
+    {
+      code: `
+      class Foo {
+        /**
+         * @return {TEMPLATE_TYPE}
+         */
+        bar () {
+        }
+      }
+      `,
+      errors: [
+        {
+          line: 4,
+          message: 'The type \'TEMPLATE_TYPE\' is undefined.'
+        }
+      ]
+    },
+    {
+      code: `
+      class Foo {
+        /**
+         * @return {TEMPLATE_TYPE}
+         */
+        invalidTemplateReference () {
+        }
+      }
+      
+      /**
+       * @template TEMPLATE_TYPE
+       */
+      class Bar {
+        /**
+         * @return {TEMPLATE_TYPE}
+         */
+        validTemplateReference () {
+        }
+      }
+      `,
+      errors: [
+        {
+          line: 4,
+          message: 'The type \'TEMPLATE_TYPE\' is undefined.'
+        }
+      ]
     }
   ],
   valid: [
@@ -393,6 +438,35 @@ export default {
           }
         }
       }
+    },
+    {
+      code: `
+      /**
+       * @template TEMPLATE_TYPE
+       */
+      class Foo {
+        /**
+         * @return {TEMPLATE_TYPE}
+         */
+        bar () {
+        }
+      }
+      `
+    },
+    {
+      code: `
+      /**
+       * @template TEMPLATE_TYPE_A, TEMPLATE_TYPE_B
+       */
+      class Foo {
+        /**
+         * @param {TEMPLATE_TYPE_A} baz
+         * @return {TEMPLATE_TYPE_B}
+         */
+        bar (baz) {
+        }
+      }
+      `
     }
   ]
 };