Merge pull request #59 from zxqfox/feature/checkType-primitives-case

checkTypes: new mode strictNativeCase

Author: qfox

README.md

@@ -300,9 +300,11 @@ function method() {}
 
 Reports invalid types for bunch of tags
 
-Type: `Boolean`
+In `strictNativeCase` mode ensures that case of natives is the same as in this list: `boolean`, `number`, `string`, `null`, `Object`, `Array`, `Date`, `RegExp`.
 
-Values: `true`
+Type: `Boolean` or `String`
+
+Values: `true` or `"strictNativeCase"`
 
 Context: `*`
 
@@ -344,6 +346,21 @@ function method(x) {}
 
 ##### Invalid
 
+```js
+/** @type {some~number} */
+var x = 1;
+
+/**
+ * @param {function(redundantName: Number)} x
+ */
+function method(x) {}
+
+/**
+ * @param {Number|Boolean|object|array} x invalid for strictNativeCase
+ */
+function method(x) {}
+```
+
 ```js
 /** @type {some~number} */
 var x = 1;

lib/jsdoc.js

@@ -126,7 +126,7 @@ function DocType(type, loc) {
     this.valid = parsed.valid;
 
     if (parsed.valid && parsed.variable) {
-        this.loc.column = this.loc.column + 3;
+        this.loc.column = this.loc.column + 3; // ' * '.length
     }
 
     /**
@@ -137,6 +137,17 @@ function DocType(type, loc) {
     this.match = function(node) {
         return jsDocMatchType(data, node);
     };
+
+    /**
+     * @param {function(TypeBuilder)} cb Calling for each node
+     * @returns {Array}
+     */
+    this.iterate = function(cb) {
+        if (!parsed.valid) {
+            return [];
+        }
+        return _iterateDocTypes(parsed, cb);
+    };
 }
 
 /**
@@ -296,6 +307,96 @@ function _parseDocType(typeString) {
     return node;
 }
 
+function _iterateDocTypes(node, cb) {
+    var res;
+
+    switch (true) {
+    case node instanceof TypeBuilder.TypeUnion:
+        // optional: boolean,
+        // nullable: boolean,
+        // variable: boolean,
+        // nonNullable: boolean,
+        // all: boolean,
+        // unknown: boolean,
+        // types: Array.<TypeName|GenericType|FunctionType|RecordType>
+        res = node.types.map(function(subnode) {
+            if (node.selfNode) {
+                subnode.parentNode = node.selfNode;
+            }
+            return _iterateDocTypes(subnode, cb);
+        });
+        break;
+
+    case node instanceof TypeBuilder.TypeName:
+        // name: string
+        node.typeName = node.name;
+        res = cb(node);
+        break;
+
+    case node instanceof TypeBuilder.GenericType:
+        // genericTypeName: string,
+        // parameterTypeUnions: Array.<TypeUnion>
+        node.typeName = node.genericTypeName;
+        res = cb(node);
+        if (node.parameterTypeUnions) {
+            node.parameterTypeUnions.selfNode = node;
+            res.concat(_iterateDocTypes(node.parameterTypeUnions, cb));
+        }
+        break;
+
+    case node instanceof TypeBuilder.FunctionType:
+        // parameterTypeUnions: Array.<TypeUnion>,
+        // returnTypeUnion: TypeUnion|null,
+        // isConstructor: boolean,
+        // contextTypeUnion: TypeUnion|null
+        node.typeName = 'Function';
+        res = cb(node) || [];
+        res.concat(node.parameterTypeUnions.map(function(subnode) {
+            subnode.parentNode = node;
+            _iterateDocTypes(subnode, cb);
+        }));
+        if (node.returnTypeUnion) {
+            node.returnTypeUnion.selfNode = node;
+            res.concat(_iterateDocTypes(node.returnTypeUnion, cb));
+        }
+        if (node.contextTypeUnion) {
+            node.contextTypeUnion.selfNode = node;
+            res.concat(_iterateDocTypes(node.contextTypeUnion, cb));
+        }
+        break;
+
+    case node instanceof TypeBuilder.RecordType:
+        // entries: Array.<RecordEntry>
+        node.typeName = 'Object';
+        res = cb(node) || [];
+        if (node.entries) {
+            res.concat(node.entries.map(function(subnode) {
+                subnode.parentNode = node;
+                _iterateDocTypes(subnode, cb);
+            }));
+        }
+        break;
+
+    case node instanceof TypeBuilder.RecordType.Entry:
+        // name: string,
+        // typeUnion: TypeUnion
+        node.typeUnion.selfNode = node;
+        res = _iterateDocTypes(node.typeUnion, cb);
+        break;
+
+    case node instanceof TypeBuilder.ModuleName:
+        node.typeName = node.name;
+        node.module = true;
+        res = cb(node);
+        break;
+
+    default:
+        throw new Error('DocType: Unsupported doc node');
+    }
+
+    return res;
+}
+
 /**
  * Converts AST jsDoc node to simple object
  * @param {Object} node

lib/rules/validate-jsdoc/check-types.js

@@ -3,7 +3,7 @@ var jsdoc = require('../../jsdoc');
 module.exports = validateTypesInTags;
 module.exports.scopes = ['file'];
 module.exports.options = {
-    checkTypes: {allowedValues: [true]}
+    checkTypes: {allowedValues: [true, 'strictNativeCase']}
 };
 
 var allowedTags = {
@@ -32,12 +32,27 @@ var allowedTags = {
     define: true
 };
 
+var strictNatives = {
+    // lowercased
+    boolean: 'boolean',
+    number: 'number',
+    string: 'string',
+    'null': 'null',
+    // titlecased
+    array: 'Array',
+    object: 'Object',
+    regexp: 'RegExp',
+    date: 'Date',
+    'function': 'Function'
+};
+
 /**
  * validator for types in tags
  * @param {JSCS.JSFile} file
  * @param {JSCS.Errors} errors
  */
 function validateTypesInTags(file, errors) {
+    var strictNativeCase = this._options.checkTypes === 'strictNativeCase';
     var comments = file.getComments();
     comments.forEach(function(commentNode) {
         if (commentNode.type !== 'Block' || commentNode.value[0] !== '*') {
@@ -59,6 +74,22 @@ function validateTypesInTags(file, errors) {
                 // throw an error if not valid
                 errors.add('expects valid type instead of ' + tag.type.value, tag.type.loc);
             }
+            if (strictNativeCase) {
+                tag.type.iterate(function(node) {
+                    // it shouldn't be!
+                    if (!node.typeName) {
+                        // skip untyped unknown things
+                        return;
+                    }
+
+                    // is native?
+                    var type = node.typeName;
+                    var lowerType = type.toLowerCase();
+                    if (lowerType in strictNatives && type !== strictNatives[lowerType]) {
+                        errors.add('invalid case of type `' + type + '`', tag.type.loc);
+                    }
+                });
+            }
         });
     });
 }

test/lib/rules/validate-jsdoc/check-types.js

@@ -23,7 +23,7 @@ describe('lib/rules/validate-jsdoc/check-types', function() {
         checker.rules({checkTypes: true});
 
         checker.cases([
-            /* jshint ignore:start */
+            /* jshint ignore:start *//* jscs: disable */
             {
                 it: 'should not report',
                 code: function() {
@@ -156,7 +156,82 @@ describe('lib/rules/validate-jsdoc/check-types', function() {
                     }
                 }
             }
-            /* jshint ignore:end */
+            /* jshint ignore:end *//* jscs: enable */
+        ]);
+
+    });
+
+    describe('with strictNativeCase', function() {
+        checker.rules({checkTypes: 'strictNativeCase'});
+
+        checker.cases([
+            /* jshint ignore:start *//* jscs: disable */
+            {
+                it: 'should not report strict natives',
+                code: function() {
+                    /**
+                     * @param {number}
+                     * @param {string}
+                     * @param {boolean}
+                     * @param {null}
+                     * @param {Array}
+                     * @param {Object}
+                     * @param {Date}
+                     * @param {Function}
+                     */
+                    function _f () {}
+                }
+            }, {
+                it: 'should not report joined strict natives',
+                code: function() {
+                    /**
+                     * @param {number|string|boolean|null|Array|Object|Date}
+                     */
+                    function _f () {}
+                }
+            }, {
+                it: 'should not report strict natives declared as function arguments',
+                code: function() {
+                    /**
+                     * @param {function(number, Array)}
+                     */
+                    function _f () {}
+                }
+            }, {
+                it: 'should report strict natives',
+                errors: 6,
+                code: function() {
+                    /**
+                     * @param {Number}
+                     * @param {String}
+                     * @param {Boolean}
+                     * @param {array}
+                     * @param {object}
+                     * @param {date}
+                     */
+                    function _f () {}
+                }
+            }, {
+                it: 'should report joined wrong cased strict natives',
+                errors: 7,
+                code: function() {
+                    /**
+                     * @param {Number|String|Boolean|Null}
+                     * @param {array|object|date}
+                     */
+                    function _f () {}
+                }
+            }, {
+                it: 'should report joined strict wrong cased natives',
+                code: function() {
+                    /**
+                     * @param {Number|String|Boolean|Null|array|object|date|regexp|function}
+                     */
+                    function _f () {}
+                },
+                errors: 9
+            }
+            /* jshint ignore:end *//* jscs: enable */
         ]);
 
     });