feat: add a type parser and two new rules for types in JSdoc comments (#67)

* Added type parser and support for nested types in checkTypes

* Added rule: valid-types

* update readme

* Added no-undefined-types rule

* Added rule no-undefined-types

* add support for @typedef, document no-unused-vars

Author: bary12

.README/README.md

@@ -27,6 +27,8 @@ This table maps the rules between `eslint-plugin-jsdoc` and `jscs-jsdoc`.
 | [`require-param-type`](https://github.com/gajus/eslint-plugin-jsdoc#eslint-plugin-jsdoc-rules-require-param-type) | [`requireParamTypes`](https://github.com/jscs-dev/jscs-jsdoc#requireparamtypes) |
 | [`require-returns-description`](https://github.com/gajus/eslint-plugin-jsdoc#eslint-plugin-jsdoc-rules-require-returns-description) | [`requireReturnDescription`](https://github.com/jscs-dev/jscs-jsdoc#requirereturndescription) |
 | [`require-returns-type`](https://github.com/gajus/eslint-plugin-jsdoc#eslint-plugin-jsdoc-rules-require-returns-type) | [`requireReturnTypes`](https://github.com/jscs-dev/jscs-jsdoc#requirereturntypes) |
+| [`valid-types`](https://github.com/gajus/eslint-plugin-jsdoc#eslint-plugin-jsdoc-rules-valid-types) | N/A |
+| [`no-undefined-types`](https://github.com/gajus/eslint-plugin-jsdoc#eslint-plugin-jsdoc-rules-no-undefined-types) | N/A |
 | N/A | [`checkReturnTypes`](https://github.com/jscs-dev/jscs-jsdoc#checkreturntypes) |
 | N/A | [`checkRedundantParams`](https://github.com/jscs-dev/jscs-jsdoc#checkredundantparams) |
 | N/A | [`checkReturnTypes`](https://github.com/jscs-dev/jscs-jsdoc#checkreturntypes) |
@@ -69,6 +71,7 @@ Finally, enable all of the rules that you would like to use.
         "jsdoc/check-tag-names": 1,
         "jsdoc/check-types": 1,
         "jsdoc/newline-after-description": 1,
+        "jsdoc/no-undefined-types": 1,
         "jsdoc/require-description-complete-sentence": 1,
         "jsdoc/require-example": 1,
         "jsdoc/require-hyphen-before-param-description": 1,
@@ -77,7 +80,8 @@ Finally, enable all of the rules that you would like to use.
         "jsdoc/require-param-name": 1,
         "jsdoc/require-param-type": 1,
         "jsdoc/require-returns-description": 1,
-        "jsdoc/require-returns-type": 1
+        "jsdoc/require-returns-type": 1,
+        "jsdoc/valid-types": 1
     }
 }
 ```
@@ -126,6 +130,7 @@ Use `settings.jsdoc.additionalTagNames` to configure additional, allowed JSDoc t
 {"gitdown": "include", "file": "./rules/check-tag-names.md"}
 {"gitdown": "include", "file": "./rules/check-types.md"}
 {"gitdown": "include", "file": "./rules/newline-after-description.md"}
+{"gitdown": "include", "file": "./rules/no-undefined-types.md"}
 {"gitdown": "include", "file": "./rules/require-description-complete-sentence.md"}
 {"gitdown": "include", "file": "./rules/require-example.md"}
 {"gitdown": "include", "file": "./rules/require-hyphen-before-param-description.md"}
@@ -135,3 +140,4 @@ Use `settings.jsdoc.additionalTagNames` to configure additional, allowed JSDoc t
 {"gitdown": "include", "file": "./rules/require-param-type.md"}
 {"gitdown": "include", "file": "./rules/require-returns-description.md"}
 {"gitdown": "include", "file": "./rules/require-returns-type.md"}
+{"gitdown": "include", "file": "./rules/valid-types.md"}

.README/rules/no-undefined-types.md

@@ -0,0 +1,13 @@
+### `no-undefined-types`
+
+Checks that types in jsdoc comments are defined. This can be used to check unimported types.
+
+When enabling this rule, types in jsdoc comments will resolve as used variables, i.e. will not be marked as unused by `no-unused-vars`.
+
+
+|||
+|---|---|
+|Context|`ArrowFunctionExpression`, `FunctionDeclaration`, `FunctionExpression`|
+|Tags|`param`, `returns`|
+
+<!-- assertions noUndefinedTypes -->

.README/rules/valid-types.md

@@ -0,0 +1,10 @@
+### `valid-types`
+
+Requires all types to be valid JSDoc or Closure compiler types without syntax errors.
+
+|||
+|---|---|
+|Context|`ArrowFunctionExpression`, `FunctionDeclaration`, `FunctionExpression`|
+|Tags|`param`, `returns`|
+
+<!-- assertions validTypes -->

package.json

@@ -6,6 +6,7 @@
   },
   "dependencies": {
     "comment-parser": "^0.4.2",
+    "jsdoctypeparser": "^2.0.0-alpha-8",
     "lodash": "^4.17.4"
   },
   "description": "JSDoc linting rules for ESLint.",
@@ -17,7 +18,7 @@
     "babel-preset-es2015": "^6.24.1",
     "babel-register": "^6.26.0",
     "chai": "^4.1.2",
-    "eslint": "^4.7.2",
+    "eslint": "^4.19.1",
     "eslint-config-canonical": "^9.3.1",
     "gitdown": "^2.5.1",
     "globby": "^6.1.0",

src/index.js

@@ -1,7 +1,9 @@
+/* eslint-disable import/max-dependencies */
 import checkParamNames from './rules/checkParamNames';
 import checkTagNames from './rules/checkTagNames';
 import checkTypes from './rules/checkTypes';
 import newlineAfterDescription from './rules/newlineAfterDescription';
+import noUndefinedTypes from './rules/noUndefinedTypes';
 import requireDescriptionCompleteSentence from './rules/requireDescriptionCompleteSentence';
 import requireExample from './rules/requireExample';
 import requireHyphenBeforeParamDescription from './rules/requireHyphenBeforeParamDescription';
@@ -11,6 +13,7 @@ import requireParamDescription from './rules/requireParamDescription';
 import requireParamType from './rules/requireParamType';
 import requireReturnsDescription from './rules/requireReturnsDescription';
 import requireReturnsType from './rules/requireReturnsType';
+import validTypes from './rules/validTypes';
 
 export default {
   configs: {
@@ -20,6 +23,7 @@ export default {
         'jsdoc/check-tag-names': 'warn',
         'jsdoc/check-types': 'warn',
         'jsdoc/newline-after-description': 'warn',
+        'jsdoc/no-undefined-types': 'warn',
         'jsdoc/require-description-complete-sentence': 'off',
         'jsdoc/require-example': 'off',
         'jsdoc/require-hyphen-before-param-description': 'off',
@@ -28,7 +32,8 @@ export default {
         'jsdoc/require-param-name': 'warn',
         'jsdoc/require-param-type': 'warn',
         'jsdoc/require-returns-description': 'warn',
-        'jsdoc/require-returns-type': 'warn'
+        'jsdoc/require-returns-type': 'warn',
+        'jsdoc/valid-types': 'warn'
       }
     }
   },
@@ -37,6 +42,7 @@ export default {
     'check-tag-names': checkTagNames,
     'check-types': checkTypes,
     'newline-after-description': newlineAfterDescription,
+    'no-undefined-types': noUndefinedTypes,
     'require-description-complete-sentence': requireDescriptionCompleteSentence,
     'require-example': requireExample,
     'require-hyphen-before-param-description': requireHyphenBeforeParamDescription,
@@ -45,13 +51,15 @@ export default {
     'require-param-name': requireParamName,
     'require-param-type': requireParamType,
     'require-returns-description': requireReturnsDescription,
-    'require-returns-type': requireReturnsType
+    'require-returns-type': requireReturnsType,
+    'valid-types': validTypes
   },
   rulesConfig: {
     'check-param-names': 'off',
     'check-tag-names': 'off',
     'check-types': 'off',
     'newline-after-description': 'off',
+    'no-undefined-types': 'off',
     'require-description-complete-sentence': 'off',
     'require-example': 'off',
     'require-hyphen-before-param-description': 'off',
@@ -60,6 +68,7 @@ export default {
     'require-param-name': 'off',
     'require-param-type': 'off',
     'require-returns-description': 'off',
-    'require-returns-type': 'off'
+    'require-returns-type': 'off',
+    'valid-types': 'off'
   }
 };

src/iterateJsdoc.js

@@ -32,6 +32,27 @@ const curryUtils = (functionNode, jsdoc, tagNamePreference, additionalTagNames)
   return utils;
 };
 
+export const parseComment = (commentNode) => {
+  // Preserve JSDoc block start/end indentation.
+  const indent = _.repeat(' ', commentNode.loc.start.column);
+
+  return commentParser(indent + '/*' + commentNode.value + indent + '*/', {
+    // @see https://github.com/yavorskiy/comment-parser/issues/21
+    parsers: [
+      commentParser.PARSERS.parse_tag,
+      commentParser.PARSERS.parse_type,
+      (str, data) => {
+        if (_.includes(['return', 'returns'], data.tag)) {
+          return null;
+        }
+
+        return commentParser.PARSERS.parse_name(str, data);
+      },
+      commentParser.PARSERS.parse_description
+    ]
+  })[0] || {};
+};
+
 export default (iterator) => {
   return (context) => {
     const sourceCode = context.getSourceCode();
@@ -45,23 +66,9 @@ export default (iterator) => {
         return;
       }
 
-      // Preserve JSDoc block start/end indentation.
       const indent = _.repeat(' ', jsdocNode.loc.start.column);
-      const jsdoc = commentParser(indent + '/*' + jsdocNode.value + indent + '*/', {
-        // @see https://github.com/yavorskiy/comment-parser/issues/21
-        parsers: [
-          commentParser.PARSERS.parse_tag,
-          commentParser.PARSERS.parse_type,
-          (str, data) => {
-            if (_.includes(['return', 'returns'], data.tag)) {
-              return null;
-            }
-
-            return commentParser.PARSERS.parse_name(str, data);
-          },
-          commentParser.PARSERS.parse_description
-        ]
-      })[0] || {};
+
+      const jsdoc = parseComment(jsdocNode);
 
       const report = (message, fixer = null) => {
         if (fixer === null) {

src/rules/checkTypes.js

@@ -1,4 +1,5 @@
 import _ from 'lodash';
+import {parse, traverse, publish} from 'jsdoctypeparser';
 import iterateJsdoc from './../iterateJsdoc';
 
 let targetTags = [
@@ -51,18 +52,36 @@ export default iterateJsdoc(({
   });
 
   _.forEach(jsdocTags, (jsdocTag) => {
-    _.some(strictNativeTypes, (strictNativeType) => {
-      if (strictNativeType.toLowerCase() === jsdocTag.type.toLowerCase() && strictNativeType !== jsdocTag.type) {
-        const fix = (fixer) => {
-          return fixer.replaceText(jsdocNode, sourceCode.getText(jsdocNode).replace('{' + jsdocTag.type + '}', '{' + strictNativeType + '}'));
-        };
+    const invalidTypes = [];
+    let typeAst;
 
-        report('Invalid JSDoc @' + jsdocTag.tag + ' "' + jsdocTag.name + '" type "' + jsdocTag.type + '".', fix);
+    try {
+      typeAst = parse(jsdocTag.type);
+    } catch (error) {
+      return;
+    }
 
-        return true;
+    traverse(typeAst, (node) => {
+      if (node.type === 'NAME') {
+        for (const strictNativeType of strictNativeTypes) {
+          if (strictNativeType.toLowerCase() === node.name.toLowerCase() && strictNativeType !== node.name) {
+            invalidTypes.push(node.name);
+            node.name = strictNativeType;
+          }
+        }
       }
-
-      return false;
     });
+
+    if (invalidTypes) {
+      const fixedType = publish(typeAst);
+
+      _.forEach(invalidTypes, (invalidType) => {
+        const fix = (fixer) => {
+          return fixer.replaceText(jsdocNode, sourceCode.getText(jsdocNode).replace('{' + jsdocTag.type + '}', '{' + fixedType + '}'));
+        };
+
+        report('Invalid JSDoc @' + jsdocTag.tag + ' "' + jsdocTag.name + '" type "' + invalidType + '".', fix);
+      });
+    }
   });
 });

src/rules/noUndefinedTypes.js

@@ -0,0 +1,50 @@
+import _ from 'lodash';
+import {parse as parseType, traverse} from 'jsdoctypeparser';
+import iterateJsdoc, {parseComment} from '../iterateJsdoc';
+
+const extraTypes = ['string', 'number', 'boolean', 'any', '*'];
+
+export default iterateJsdoc(({
+  context,
+  jsdoc,
+  report,
+  sourceCode
+}) => {
+  const scopeManager = sourceCode.scopeManager;
+  const globalScope = scopeManager.isModule() ? scopeManager.globalScope.childScopes[0] : scopeManager.globalScope;
+
+  const typedefDeclarations = _(context.getAllComments())
+    .filter((comment) => {
+      return _.startsWith(comment.value, '*');
+    })
+    .map(parseComment)
+    .flatMap((doc) => {
+      return doc.tags.filter((tag) => {
+        return tag.tag === 'typedef';
+      });
+    })
+    .map((tag) => {
+      return tag.name;
+    })
+    .value();
+
+  const definedTypes = globalScope.variables.map((variable) => {
+    return variable.name;
+  })
+    .concat(extraTypes)
+    .concat(typedefDeclarations);
+
+  _.forEach(jsdoc.tags, (tag) => {
+    const parsedType = parseType(tag.type);
+
+    traverse(parsedType, (node) => {
+      if (node.type === 'NAME') {
+        if (!_.includes(definedTypes, node.name)) {
+          report('The type \'' + node.name + '\' is undefined.');
+        } else if (!_.includes(extraTypes, node.name)) {
+          context.markVariableAsUsed(node.name);
+        }
+      }
+    });
+  });
+});

src/rules/validTypes.js

@@ -0,0 +1,20 @@
+import _ from 'lodash';
+import {parse} from 'jsdoctypeparser';
+import iterateJsdoc from '../iterateJsdoc';
+
+export default iterateJsdoc(({
+  jsdoc,
+  report
+}) => {
+  _.forEach(jsdoc.tags, (tag) => {
+    if (tag.type) {
+      try {
+        parse(tag.type);
+      } catch (error) {
+        if (error.name === 'SyntaxError') {
+          report('Syntax error in type: ' + tag.type);
+        }
+      }
+    }
+  });
+});