fix(check-types, no-undefined-types, valid-types): look within …

…curly brackets of `this` and `define` tags (and if present within `export`) when in Closure mode; fixes #430
gajus · Dec 1, 2019 · 7022f65 · 7022f65
1 parent 471302a
commit 7022f65
Show file tree

Hide file tree

Showing 5 changed files with 277 additions and 3 deletions.
diff --git a/README.md b/README.md
@@ -3009,6 +3009,20 @@ function quux (foo) {
 
 /** @typedef {String} foo */
 // Message: Invalid JSDoc @typedef "foo" type "String"; prefer: "string".
+
+/**
+ * @this {array}
+ */
+function quux () {}
+// Settings: {"jsdoc":{"mode":"closure"}}
+// Message: Invalid JSDoc @this type "array"; prefer: "Array".
+
+/**
+ * @export {array}
+ */
+function quux () {}
+// Settings: {"jsdoc":{"mode":"closure"}}
+// Message: Invalid JSDoc @export type "array"; prefer: "Array".
 ````
 
 The following patterns are not considered problems:
@@ -3217,6 +3231,18 @@ function quux (foo) {
 
 /** @param {function(...)} callback The function to invoke. */
 var subscribe = function(callback) {};
+
+/**
+ * @this {Array}
+ */
+function quux () {}
+// Settings: {"jsdoc":{"mode":"closure"}}
+
+/**
+ * @export {Array}
+ */
+function quux () {}
+// Settings: {"jsdoc":{"mode":"closure"}}
 ````
 
 
@@ -4811,6 +4837,20 @@ class Foo {
 function quux (varargs) {
 }
 // Message: The type 'VAR_TYPE' is undefined.
+
+/**
+ * @this {Navigator}
+ */
+function quux () {}
+// Settings: {"jsdoc":{"mode":"closure"}}
+// Message: The type 'Navigator' is undefined.
+
+/**
+ * @export {SomeType}
+ */
+function quux () {}
+// Settings: {"jsdoc":{"mode":"closure"}}
+// Message: The type 'SomeType' is undefined.
 ````
 
 The following patterns are not considered problems:
@@ -5029,6 +5069,20 @@ function quux (varargs) {
  */
 function quux (varargs) {
 }
+
+class Navigator {}
+/**
+ * @this {Navigator}
+ */
+function quux () {}
+// Settings: {"jsdoc":{"mode":"closure"}}
+
+class SomeType {}
+/**
+ * @export {SomeType}
+ */
+function quux () {}
+// Settings: {"jsdoc":{"mode":"closure"}}
 ````
 
 
@@ -8997,6 +9051,13 @@ function quux (foo, bar, baz) {}
 function quux () {}
 // Settings: {"jsdoc":{"mode":"closure"}}
 // Message: Syntax error in type: BadTypeChecked<
+
+/**
+ * @this {BadTypeChecked<}
+ */
+function quux () {}
+// Settings: {"jsdoc":{"mode":"closure"}}
+// Message: Syntax error in type: BadTypeChecked<
 ````
 
 The following patterns are not considered problems:
@@ -9148,6 +9209,24 @@ function quux (foo, bar, baz) {}
  * @private {BadTypeNotCheckedInJsdoc<}
  */
 function quux () {}
+
+/**
+ * @this {Navigator}
+ */
+function quux () {}
+// Settings: {"jsdoc":{"mode":"closure"}}
+
+/**
+ * @export {SomeType}
+ */
+function quux () {}
+// Settings: {"jsdoc":{"mode":"closure"}}
+
+/**
+ * @define {boolean}
+ */
+function quux () {}
+// Settings: {"jsdoc":{"mode":"closure"}}
 ````
 
 
diff --git a/src/jsdocUtils.js b/src/jsdocUtils.js
@@ -183,6 +183,12 @@ const tagsWithMandatoryTypePosition = [
   'type',
 ];
 
+const tagsWithMandatoryTypePositionClosure = [
+  ...tagsWithMandatoryTypePosition,
+  'this',
+  'define',
+];
+
 // All of these have a signature with "type" except for
 //  `augments`/`extends` ("namepath")
 //  `param`/`arg`/`argument` (no signature)
@@ -224,6 +230,8 @@ const tagsWithOptionalTypePosition = [
 const tagsWithOptionalTypePositionClosure = [
   ...tagsWithOptionalTypePosition,
 
+  'export',
+
   // Shows the signature with curly brackets but not in the example
   // "typeExpression"
   'package',
@@ -328,9 +336,13 @@ const isNamepathDefiningTag = (tagName) => {
 };
 
 const tagMightHaveTypePosition = (mode, tag) => {
-  return tagsWithMandatoryTypePosition.includes(tag) || (mode === 'closure' ?
-    tagsWithOptionalTypePositionClosure.includes(tag) :
-    tagsWithOptionalTypePosition.includes(tag));
+  if (mode === 'closure') {
+    return tagsWithMandatoryTypePositionClosure.includes(tag) ||
+      tagsWithOptionalTypePositionClosure.includes(tag);
+  }
+
+  return tagsWithMandatoryTypePosition.includes(tag) ||
+    tagsWithOptionalTypePosition.includes(tag);
 };
 
 const tagMustHaveTypePosition = (tag) => {

diff --git a/test/rules/assertions/checkTypes.js b/test/rules/assertions/checkTypes.js
@@ -1703,6 +1703,40 @@ export default {
       ],
       output: '/** @typedef {string} foo */',
     },
+    {
+      code: `
+      /**
+       * @this {array}
+       */
+      function quux () {}
+      `,
+      errors: [{
+        line: 3,
+        message: 'Invalid JSDoc @this type "array"; prefer: "Array".',
+      }],
+      settings: {
+        jsdoc: {
+          mode: 'closure',
+        },
+      },
+    },
+    {
+      code: `
+      /**
+       * @export {array}
+       */
+      function quux () {}
+      `,
+      errors: [{
+        line: 3,
+        message: 'Invalid JSDoc @export type "array"; prefer: "Array".',
+      }],
+      settings: {
+        jsdoc: {
+          mode: 'closure',
+        },
+      },
+    },
   ],
   valid: [
     {
@@ -2089,5 +2123,31 @@ export default {
       var subscribe = function(callback) {};
       `,
     },
+    {
+      code: `
+      /**
+       * @this {Array}
+       */
+      function quux () {}
+      `,
+      settings: {
+        jsdoc: {
+          mode: 'closure',
+        },
+      },
+    },
+    {
+      code: `
+      /**
+       * @export {Array}
+       */
+      function quux () {}
+      `,
+      settings: {
+        jsdoc: {
+          mode: 'closure',
+        },
+      },
+    },
   ],
 };
diff --git a/test/rules/assertions/noUndefinedTypes.js b/test/rules/assertions/noUndefinedTypes.js
@@ -276,6 +276,44 @@ export default {
         },
       ],
     },
+    {
+      code: `
+      /**
+       * @this {Navigator}
+       */
+      function quux () {}
+      `,
+      errors: [
+        {
+          line: 3,
+          message: 'The type \'Navigator\' is undefined.',
+        },
+      ],
+      settings: {
+        jsdoc: {
+          mode: 'closure',
+        },
+      },
+    },
+    {
+      code: `
+      /**
+       * @export {SomeType}
+       */
+      function quux () {}
+      `,
+      errors: [
+        {
+          line: 3,
+          message: 'The type \'SomeType\' is undefined.',
+        },
+      ],
+      settings: {
+        jsdoc: {
+          mode: 'closure',
+        },
+      },
+    },
   ],
   valid: [
     {
@@ -616,5 +654,33 @@ export default {
      }
      `,
     },
+    {
+      code: `
+      class Navigator {}
+      /**
+       * @this {Navigator}
+       */
+      function quux () {}
+      `,
+      settings: {
+        jsdoc: {
+          mode: 'closure',
+        },
+      },
+    },
+    {
+      code: `
+      class SomeType {}
+      /**
+       * @export {SomeType}
+       */
+      function quux () {}
+      `,
+      settings: {
+        jsdoc: {
+          mode: 'closure',
+        },
+      },
+    },
   ],
 };
diff --git a/test/rules/assertions/validTypes.js b/test/rules/assertions/validTypes.js
@@ -286,6 +286,24 @@ export default {
         },
       },
     },
+    {
+      code: `
+      /**
+       * @this {BadTypeChecked<}
+       */
+      function quux () {}
+      `,
+      errors: [
+        {
+          message: 'Syntax error in type: BadTypeChecked<',
+        },
+      ],
+      settings: {
+        jsdoc: {
+          mode: 'closure',
+        },
+      },
+    },
   ],
   valid: [
     {
@@ -509,5 +527,44 @@ export default {
 
       `,
     },
+    {
+      code: `
+      /**
+       * @this {Navigator}
+       */
+      function quux () {}
+      `,
+      settings: {
+        jsdoc: {
+          mode: 'closure',
+        },
+      },
+    },
+    {
+      code: `
+      /**
+       * @export {SomeType}
+       */
+      function quux () {}
+      `,
+      settings: {
+        jsdoc: {
+          mode: 'closure',
+        },
+      },
+    },
+    {
+      code: `
+      /**
+       * @define {boolean}
+       */
+      function quux () {}
+      `,
+      settings: {
+        jsdoc: {
+          mode: 'closure',
+        },
+      },
+    },
   ],
 };