gulp-coffeelint

gulp-coffeelint

CoffeeLint plugin for gulp 3.

Usage

First, install gulp-coffeelint as a development dependency:

npm install --save-dev gulp-coffeelint

Then, add it to your gulpfile.js:

var gulp = require('gulp');
var coffeelint = require('gulp-coffeelint');

gulp.task('lint', function () {
    gulp.src('./src/*.coffee')
        .pipe(coffeelint())
        .pipe(coffeelint.reporter())
});

API

coffeelint([optFile,] [opt,] [literate,] [rules])

All arguments are optional. By default gulp-coffeelint will walk up the directory tree looking for a coffeelint.json (per file, i.e. dirname) or a package.json that has a coffeelintConfig object (as the cli does). Also, .litcoffee and .coffee.md files will be treated as Literate CoffeeScript.

optFile

Type: String

Absolute path of a json file containing options for coffeelint.

opt

Type: Object

Options you wish to send to coffeelint. If optFile is given, this will be ignored.

literate

Type: Boolean

Are we dealing with Literate CoffeeScript?

rules

Type: Array[Function] Default: []

Add custom rules to coffeelint.

Results

Adds the following properties to the file object:

file.coffeelint.success = true; // if no errors were found, false otherwise
file.coffeelint.errorCount = 0; // number of errors returned by `coffeelint`
file.coffeelint.warningCount = 0; // number of warnings returned by `coffeelint`
file.coffeelint.results = ErrorReport Object; // instance of `Coffeelint::ErrorReport` , see https://github.com/clutchski/coffeelint/blob/master/src/error_report.coffee
file.coffeelint.opt = {}; // the options used by `coffeelint`
file.coffeelint.literate = false; // you guessed it

Reporters

name

Type: String, Function Default: 'coffeelint-stylish'

CoffeeLint reporters

Built-in

You can choose any CoffeeLint reporter when you call

stuff
  .pipe(coffeelint())
  .pipe(coffeelint.reporter('csv'))

External

Let's use coffeelint-stylish as an example. External modules can be referenced either as the reporter's constructor function or as its module name.

var stylish = require('coffeelint-stylish');

gulp.src('./src/*.coffee')
  .pipe(coffeelint())
  .pipe(coffeelint.reporter(stylish))

-- OR --

gulp.src('./src/*.coffee')
  .pipe(coffeelint())
  .pipe(coffeelint.reporter('coffelint-stylish'))

Any module following the CoffeeLint Reporter module format should work. These modules have a constructor accepting a CoffeeLint::ErrorReport Object, and provide a publish function.

Fail and FailOnWarning Reporters

Do you want the task to fail when a CoffeeLint error or warning happens? gulp-coffeelint includes fail and failOnWarning reporters for this.

This example will log the errors using the stylish reporter, then fail if CoffeeLint was not a success.

gulp.src('./src/*.coffee')
  .pipe(coffeelint())
  .pipe(coffeelint.reporter('coffeelint-stylish'))
  .pipe(coffeelint.reporter('fail'))

Custom Reporters

Specify your own downstream Reporter for CoffeeLint results.

var coffeelint = require('gulp-coffeelint');

var myReporter = (function() {
  function MyReporter(errorReport) {
    this.errorReport = errorReport;
  }

  MyReporter.prototype.publish = function() {
    var hasError = this.errorReport.hasError();
    if (hasError) {
      return console.log('Oh no!');
    }
    return console.log('Oh yeah!');
  }

  return MyReporter;
})();

gulp.task('lint', function() {
  return gulp.src('./src/*.coffee')
    .pipe(coffeelint())
    .pipe(coffeelint.reporter(myReporter));
});

Contributing

In lieu of a formal styleguide, take care to maintain the existing coding style. Add unit tests for any new or changed functionality. Lint and test your code using gulp and npm-test. Plus, make sure to adhere to these commit message conventions.

License

MIT License © Jan Raasch

Changelog

0.5.0 (2015-05-14)

Features

• custom-reporters: allow external and custom Reporters (c14be0f9)
• reporter-publish: use Reporter.publish instead of .reporter (4b3231f9)

Breaking Changes

• results: the results-key now holds an instance of Coffeelint::ErrorReport (see https://github.com/clutchski/coffeelint/blob/master/src/error_report.coffee) instead of an Array. You may call results.getErrors(filename) to get the old Array back
• reporter: running coffeelint.reporter('default') now uses the default CoffeeLint reporter instead of the coffeelint-stylish reporter. You may run coffeelint.reporter() or coffeelint.reporter('coffeelint-stylish') to use the stylish reporter