Use vfile-reporter to format error output

Author: tmcw

bin/documentation.js

@@ -8,8 +8,7 @@ var documentation = require('../'),
   streamArray = require('stream-array'),
   fs = require('fs'),
   vfs = require('vinyl-fs'),
-  walk = require('../lib/walk'),
-  formatError = require('../lib/format_error'),
+  lint = require('../lib/lint'),
   args = require('../lib/args.js');
 
 var parsedArgs = args(process.argv.slice(2)),
@@ -22,11 +21,15 @@ documentation(parsedArgs.inputs, parsedArgs.options, function (err, comments) {
     throw err;
   }
 
-  walk(comments, function (comment) {
-    comment.errors.forEach(function (error) {
-      console.error(formatError(comment, error));
-    });
-  });
+  if (parsedArgs.options.lint) {
+    var lintOutput = lint.format(comments);
+    if (lintOutput) {
+      console.log(lintOutput);
+      process.exit(1);
+    } else {
+      process.exit(0);
+    }
+  }
 
   formatter(comments, formatterOptions, function (err, output) {
     if (outputLocation !== 'stdout') {

index.js

@@ -92,7 +92,7 @@ module.exports = function (indexes, options, callback) {
                 return memo.concat(parseFn(file));
               }, [])
               .map(pipeline(
-                lint,
+                lint.lint,
                 inferName(),
                 inferKind(),
                 inferParams(),

lib/args.js

@@ -15,7 +15,10 @@ function parse(args) {
     choices: ['json', 'md', 'html']
   })
 
-  .describe('lint', 'check output for common style and uniformity mistakes')
+  .option('lint', {
+    describe: 'check output for common style and uniformity mistakes',
+    type: 'boolean'
+  })
 
   .describe('t', 'specify a theme: this must be a valid theme module')
   .alias('t', 'theme')
@@ -112,6 +115,7 @@ module.exports = function (args) {
     options: {
       private: argv.private,
       transform: transform,
+      lint: argv.lint,
       github: argv.github,
       polyglot: argv.polyglot,
       order: config.order || [],

lib/format_error.js

@@ -1,5 +1,11 @@
 'use strict';
 
+var VFile = require('vfile'),
+  walk = require('../lib/walk'),
+  parseFilepath = require('parse-filepath'),
+  vfileSort = require('vfile-sort'),
+  reporter = require('vfile-reporter');
+
 var CANONICAL = {
   'String': 'string',
   'Boolean': 'boolean',
@@ -17,7 +23,7 @@ var CANONICAL = {
  * @param {Object} comment parsed comment
  * @returns {Array<Object>} array of errors
  */
-module.exports = function (comment) {
+function lint(comment) {
   comment.tags.forEach(function (tag) {
     function nameInvariant(name) {
       if (CANONICAL[name]) {
@@ -46,4 +52,27 @@ module.exports = function (comment) {
     }
   });
   return comment;
-};
+}
+
+function format(comments) {
+  var vFiles = {};
+  walk(comments, function (comment) {
+    comment.errors.forEach(function (error) {
+      var p = comment.context.file;
+      var parts = parseFilepath(p);
+      vFiles[p] = vFiles[p] || new VFile({
+        directory: parts.dirname,
+        filename: parts.basename
+      });
+      vFiles[p].warn(error.message, {
+        line: comment.loc.start.line + error.commentLineNumber || 0
+      });
+    });
+  });
+  return reporter(Object.keys(vFiles).map(function (p) {
+    return vfileSort(vFiles[p]);
+  }));
+}
+
+module.exports.lint = lint;
+module.exports.format = format;

lib/lint.js

@@ -43,6 +43,9 @@
     "strip-json-comments": "^1.0.2",
     "traverse": "^0.6.6",
     "unist-builder": "^1.0.0",
+    "vfile": "^1.1.2",
+    "vfile-reporter": "^1.4.1",
+    "vfile-sort": "^1.0.0",
     "vinyl": "^0.5.0",
     "vinyl-fs": "^1.0.0",
     "yargs": "^3.5.4"

package.json

@@ -101,6 +101,27 @@ test('html with no destination', function (t) {
   });
 });
 
+test('--lint option', function (t) {
+  documentation(['--lint fixture/lint/lint.input.js'], function (err, data) {
+    var output = path.join(__dirname, 'fixture/lint/lint.output.js');
+    data = data.toString().split('\n').slice(2).join('\n');
+    if (process.env.UPDATE) {
+      fs.writeFileSync(output, data);
+    }
+    t.equal(err.code, 1);
+    t.equal(data, fs.readFileSync(output, 'utf8'), 'outputs lint');
+    t.end();
+  });
+});
+
+test('--lint option on good file', function (t) {
+  documentation(['--lint fixture/simple.input.js'], {}, function (err, data) {
+    t.equal(err, null);
+    t.equal(data, '', 'no output');
+    t.end();
+  }, false);
+});
+
 test('given no files', function (t) {
   documentation([''], function (err) {
     t.ok(err.toString()

test/bin.js

@@ -0,0 +1,4 @@
+/**
+ * @param {String} foo bar
+ * @memberof notfound
+ */

test/fixture/lint/lint.input.js

@@ -0,0 +1,5 @@
+        1:1  warning  could not determine @name for hierarchy
+        2:1  warning  type String found, string is standard
+        3:1  warning  @memberof reference to notfound not found
+
+⚠ 3 warnings