new rules: enforce, trailingUndersoreAccess, strict

Alexej Yaroshevich · Alexej Yaroshevich · commit 9acd8388a803 · 2014-08-23T00:07:35.000+04:00
some tests refactoring, new tests, readme update closes #4, closes #5
diff --git a/README.md b/README.md
@@ -51,6 +51,10 @@ Values:
  - "requireReturnTypes" ensures returns in jsdoc contains type
  - "checkRedundantReturns" reports redundant returns in jsdoc
  - "checkTypes" reports invalid types in jsdoc
+ - "enforce" reports empty and jsdoc
+ - "strict" reports for invalid jsdoc definitions
+ - "leadingUnderscoreAccess" reports not set @access for `_underscored` function names
+ - "trailingUnderscoreAccess" reports not set @access for `underscored`_ function names
 
 #### Example
 
@@ -62,7 +66,10 @@ Values:
     "checkReturnTypes": true,
     "checkRedundantReturns": true,
     "requireReturnTypes": true,
-    "checkTypes": true
+    "checkTypes": true,
+    "strict": true,
+    "enforce": true,
+    "leadingUnderscoreAccess": 'private'
 }
 ```
 
@@ -72,12 +79,13 @@ Values:
 /**
  * Adds style error to the list
  *
+ * @private
  * @param {String} message
  * @param {Number|Object} line
  * @param {Number} [column]
  * @returns {String[]}
  */
-add: function(message, line, column) {
+_add: function(message, line, column) {
     return ['foo', 'bar'];
 }
 ```
@@ -88,12 +96,13 @@ add: function(message, line, column) {
 /**
  * Adds style error to the list
  *
+ * @protected
  * @param {String} message
  * @param {Number,Object} line
  * @param {Number} [column]
  * @returns {String}
  */
-add: function() {
+_add: function() {
 }
 ```
 
diff --git a/lib/jsdoc-helpers.js b/lib/jsdoc-helpers.js
@@ -10,27 +10,30 @@ module.exports = {
 };
 
 function jsDocParseComments (comments) {
-
     /**
      * metaobject for parsing jsdoc comments string
      */
     return {
-        node: getJsDocForNode,
+        forNode: getJsDocForNode,
         parse: parseJsDoc
     };
 
     function getJsDocForNode (node) {
         var jsdoc = getJsDocForLine(node.loc.start.line);
         if (jsdoc) {
-            jsdoc.data = parseJsDoc(jsdoc.value);
-            jsdoc.forEachTag = function (fn) {
-                if (!this.data.tags || !this.data.tags.length) return;
-                this.data.tags.forEach(fn);
-            };
+            jsdoc.data = parseJsDoc(jsdoc.value) || {};
+            jsdoc.invalid = !jsdoc.data.line;
+            jsdoc.data.tags = jsdoc.data.tags || [];
+            jsdoc.forEachTag = jsDocForEachTag;
         }
         return jsdoc;
     }
 
+    function jsDocForEachTag (fn) {
+        if (!this.data.tags || !this.data.tags.length) return;
+        this.data.tags.forEach(fn);
+    }
+
     function getJsDocForLine (line) {
         line--;
         for (var i = 0, l = comments.length; i < l; i++) {
diff --git a/lib/rules/validate-jsdoc.js b/lib/rules/validate-jsdoc.js
@@ -7,17 +7,17 @@ module.exports = function() {};
 
 module.exports.prototype = {
 
-    configure: function(options) {
+    configure: function (options) {
         assert(typeof options === 'object', 'jsDoc option requires object value');
         this._options = options;
         this._optionsList = Object.keys(options);
     },
 
-    getOptionName: function() {
+    getOptionName: function () {
         return 'jsDoc';
     },
 
-    check: function(file, errors) {
+    check: function (file, errors) {
         var validators = this.loadValidators();
 
         // skip if there is nothing to check
@@ -32,14 +32,13 @@ module.exports.prototype = {
             'FunctionDeclaration',
             'FunctionExpression'
 
-        ], function(node) {
-            node.jsDoc = jsDocs.node(node);
-
+        ], function (node) {
+            node.jsDoc = jsDocs.forNode(node);
             for (var j = 0, k = validators.length; j < k; j += 1) {
                 validators[j].call(that, node, addError);
             }
 
-            function addError (text, loc) {
+            function addError(text, loc) {
                 loc = loc || {};
                 loc.line = loc.hasOwnProperty('line') ? loc.line : (node.jsDoc.loc.start.line);
                 loc.column = loc.hasOwnProperty('column') ? loc.column : 0; //node.jsDoc[i].indexOf('@');
@@ -49,7 +48,7 @@ module.exports.prototype = {
 
     },
 
-    loadValidators: function() {
+    loadValidators: function () {
         var passedOptions = this._optionsList;
         var validators = [];
         if (!passedOptions) {
@@ -58,12 +57,16 @@ module.exports.prototype = {
 
         Object.keys(validatorsByName).forEach(function (name) {
             var v = validatorsByName[name];
+
+            // skip unused
             if (!v.coveredOptions) {
                 return;
             }
+
+            // store used
             for (var i = 0, l = v.coveredOptions.length; i < l; i += 1) {
                 if (passedOptions.indexOf(v.coveredOptions[i]) !== -1) {
-                    validators.push(v.bind(this));
+                    validators.push(v);
                     return;
                 }
             }
diff --git a/lib/rules/validate-jsdoc/enforce.js b/lib/rules/validate-jsdoc/enforce.js
@@ -0,0 +1,23 @@
+
+//var jsDocHelpers = require('../../jsdoc-helpers');
+
+module.exports = validateEnforce;
+module.exports.coveredOptions = [
+    'strict',
+    'enforce',
+    'leadingUnderscoreAccess',
+    'trailingUnderscoreAccess'
+];
+
+/**
+ * validator for jsdoc data existance
+ * @param {(FunctionDeclaration|FunctionExpression)} node
+ * @param {Function} err
+ */
+function validateEnforce(node, err) {
+    var options = this._options;
+
+    if (!node.jsDoc && options) {
+        err('jsdoc definition required', node.loc.start);
+    }
+}
diff --git a/lib/rules/validate-jsdoc/index.js b/lib/rules/validate-jsdoc/index.js
@@ -1,4 +1,6 @@
 module.exports = {
+    enforce: require('./enforce'),
     param: require('./param'),
-    returns: require('./returns')
+    returns: require('./returns'),
+    trailingUnderscores: require('./trailing-underscores')
 };
diff --git a/lib/rules/validate-jsdoc/trailing-underscores.js b/lib/rules/validate-jsdoc/trailing-underscores.js
@@ -0,0 +1,69 @@
+
+module.exports = validateTrailingUnderscores;
+module.exports.coveredOptions = [
+    'strict',
+    'leadingUnderscoreAccess',
+    'trailingUnderscoreAccess'
+];
+
+/**
+ * validator for jsdoc data existance
+ * @param {(FunctionDeclaration|FunctionExpression)} node
+ * @param {Function} err
+ */
+function validateTrailingUnderscores(node, err) {
+    var options = this._options;
+    var __strict = options.strict;
+    if (!node.jsDoc) {
+        return;
+    }
+
+    // underscores
+    var leading = options.leadingUnderscoreAccess;
+    var trailing = options.trailingUnderscoreAccess;
+
+    var name;
+    switch (node.parentNode.type) {
+    case 'VariableDeclarator':
+        name = node.parentNode.id.name;
+        break;
+    case 'Property':
+        name = node.parentNode.key.name;
+        break;
+    default: // try to use func name itself (if not anonymous)
+        name = (node.id||{}).name;
+        break;
+    }
+
+    // skip if anonymous or something
+    if (!name) {
+        return;
+    }
+
+    // skip names without underscores at begin/end
+    var nameHasLeading = name[0] === '_';
+    var nameHasTrailing = name.substr(-1) === '_';
+    if (!nameHasLeading && !nameHasTrailing) {
+        return;
+    }
+
+    if (leading || trailing || __strict) {
+        var access;
+        node.jsDoc.data.tags.forEach(function (tag) {
+            if (['private', 'protected', 'public', 'access'].indexOf(tag.tag) !== -1) {
+                if (access && __strict) {
+                    err('Multiple access definition');
+                }
+                if (tag.tag === 'access' && !tag.name && __strict) {
+                    err('Invalid access definition');
+                }
+                access = tag.tag === 'access' ? tag.name : tag.tag || 'public';
+            }
+        });
+
+        if ((leading && nameHasLeading && (!access || [true, access].indexOf(leading) === -1)) ||
+            (trailing && nameHasTrailing && (!access || [true, access].indexOf(trailing) === -1))) {
+            err('Method access doesn\'t match');
+        }
+    }
+}
diff --git a/test/init.js b/test/init.js
@@ -1,7 +1,10 @@
+var Checker = require('jscs/lib/checker');
 var parse = require('comment-parser');
+var expect = require('chai').expect;
 
 global.parse = parse;
 global.fnBody = fnBody;
+global.checker = rulesChecker;
 
 function fnBody(func) {
     var str = func.toString();
@@ -28,3 +31,46 @@ function fnBody(func) {
 
     return out;
 }
+
+function rulesChecker(opts) {
+    var checker;
+
+    beforeEach(function () {
+        checker = new Checker();
+        checker.registerDefaultRules();
+        if (opts) {
+            checker.configure(opts);
+        }
+    });
+
+    return {
+        cases: function (items) {
+            items = items || [];
+            items.forEach(function (test) {
+
+                (test.skip? it.skip : it)(test.it, function () {
+                    if (test.rules) {
+                        checker.configure({ jsDoc: test.rules });
+                    }
+
+                    var body = test.code.call ? fnBody(test.code) : test.code;
+                    var checked = checker.checkString(body);
+                    var errors = checked.getErrorList();
+                    if (errors.length && errors[0].rule === 'parseError') {
+                        console.error(errors[0]);
+                        throw new Error(errors[0].message);
+                    }
+
+                    if (!test.hasOwnProperty('errors') || (typeof test.errors === 'number')) {
+                        expect(checked.getErrorCount())
+                            .to.eq(test.errors || 0);
+                    } else {
+                        expect(errors)
+                            .to.deep.equal(test.errors);
+                    }
+                });
+
+            });
+        }
+    };
+}
diff --git a/test/lib/rules/validate-jsdoc/enforce.js b/test/lib/rules/validate-jsdoc/enforce.js
@@ -0,0 +1,46 @@
+describe('rules/validate-jsdoc enforce', function () {
+    var cases = global.checker({
+        additionalRules: ['lib/rules/validate-jsdoc.js']
+    }).cases;
+
+    describe('enforce-existance', function () {
+
+        cases([
+            /* jshint ignore:start */
+            {
+                it: 'should report jsdoc absence',
+                rules: { enforce: true },
+                errors: 1,
+                code: function () {
+                    var x = 1;
+                    function funcName(p) {}
+                }
+            }, {
+                it: 'still should report jsdoc absence',
+                rules: { enforce: {} },
+                errors: 1,
+                code: function () {
+                    function _funcName(p) {}
+                }
+            }, {
+                it: 'should not report jsdoc absence',
+                rules: { enforce: true },
+                code: function () {
+                    /**
+                     * yolo
+                     */
+                    function funcName(p) {
+                    }
+
+                    /**
+                     * @param {Object} p
+                     */
+                    function funcName(p) {
+                    }
+                }
+            }
+            /* jshint ignore:end */
+        ]);
+
+    });
+});
diff --git a/test/lib/rules/validate-jsdoc/strict.js b/test/lib/rules/validate-jsdoc/strict.js
diff --git a/test/lib/rules/validate-jsdoc/trailing-underscores.js b/test/lib/rules/validate-jsdoc/trailing-underscores.js
diff --git a/test/mocha.opts b/test/mocha.opts
diff --git a/test/test.init.js b/test/test.init.js
