feat(reporter): add deprecation warning

`reporter()` will be deprecated as of version 1.0.0. This commit shows a
warning notifying the user of the upcoming change in the output. It also
offers a quick migration guide for those interested in switching over to
the latest version of the plugin.

#48

CHANGELOG.md

@@ -2,6 +2,14 @@
 All notable changes to this project will be documented in this file.
 This project adheres to [Semantic Versioning](http://semver.org/).
 
+## [0.7.0] - 2018-11-04
+### Added
+- Deprecation warning for version `1.0.0`
+- Migration guide to the README
+
+### Deprecated
+- Separate `reporter()` stream handler including the `'fail'` flag
+
 ## [0.6.0] - 2018-08-05
 ### Added
 - Greenkeeper to automatically keep dependencies up to date

README.md

@@ -12,6 +12,68 @@ Gulp plugin to lint Pug (nee Jade) files
 [![Code Style](https://img.shields.io/badge/code%20style-standard-brightgreen.svg)](http://standardjs.com/)
 [![Greenkeeper badge](https://badges.greenkeeper.io/ilyakam/gulp-pug-linter.svg)](https://greenkeeper.io/)
 
+## :warning: Warning :warning:
+
+**Breaking API Changes as of version `1.0.0`:**  
+`.reporter()` is being deprecated.
+
+### Migration Guide
+
+#### Built-in Reporter
+
+##### From:
+
+```js
+.pipe(pugLinter())
+.pipe(pugLinter.reporter())
+```
+
+##### To:
+
+```js
+.pipe(pugLinter({ reporter: 'default' }))
+```
+
+#### Break on Error
+
+##### From:
+
+```js
+.pipe(pugLinter())
+.pipe(pugLinter.reporter('fail'))
+```
+
+##### To:
+
+```js
+.pipe(pugLinter({
+  failAfterError: true,
+  reporter: 'default'
+}))
+```
+
+#### Custom Reporter
+
+##### From:
+
+```js
+.pipe(pugLinter())
+.pipe(pugLinter.reporter(myPugLintReporter))
+// OR
+.pipe(pugLinter.reporter('my-pug-lint-reporter'))
+```
+
+##### To:
+
+```js
+.pipe(pugLinter({
+  failAfterError: true,
+  reporter: myPugLintReporter
+  // OR
+  reporter: 'my-pug-lint-reporter'
+}))
+```
+
 ## About
 
 ![Screenshot from Terminal](readme-about-terminal-screenshot.png "The helpful arrow is included!")

index.js

@@ -35,7 +35,7 @@ function gulpPugLinter () {
 
     errors = checkFile(file)
 
-    file.pugLinter = {errors: errors}
+    file.pugLinter = { errors: errors }
 
     return callback(null, file)
   })

package.json

@@ -42,9 +42,10 @@
   "scripts": {
     "coverage": "istanbul cover _mocha -- -R spec",
     "coveralls": "npm run coverage && coveralls < coverage/lcov.info",
+    "dev": "gulp",
     "pretest": "standard",
     "test": "npm run coveralls",
     "watch": "mocha --watch || exit 0"
   },
-  "version": "0.6.0"
+  "version": "0.7.0"
 }

reporter.js

@@ -78,6 +78,12 @@ module.exports = function (type) {
   var errors = []
   var reporter = loadReporter(type)
 
+  fancyLog.warn([
+    'DEPRECATION WARNING: `',
+    PLUGIN_NAME,
+    '.reporter()` is removed in version 1.0.0'
+  ].join(''))
+
   return throughObj(function (file, encoding, callback) {
     if (file.pugLinter && file.pugLinter.errors.length) {
       errors = [].concat(errors, file.pugLinter.errors)

test/index.spec.js

@@ -13,7 +13,7 @@ describe('gulp-pug-linter', function () {
     var gulpPugLinter
 
     beforeEach(function () {
-      configFile = {load: sinon.stub()}
+      configFile = { load: sinon.stub() }
 
       gulpPugLinter = proxyquire('../index', {
         'pug-lint/lib/config-file': configFile
@@ -32,7 +32,7 @@ describe('gulp-pug-linter', function () {
     })
 
     describe('when file is null', function () {
-      var nullFile = {isNull: function () { return true }}
+      var nullFile = { isNull: function () { return true } }
 
       it('should pass the file', function () {
         stream.on('data', function (data) {
@@ -72,7 +72,7 @@ describe('gulp-pug-linter', function () {
         configure: sinon.stub()
       })
 
-      gulpPugLinter = proxyquire('../index', {'pug-lint': mockPugLint})
+      gulpPugLinter = proxyquire('../index', { 'pug-lint': mockPugLint })
 
       file = new Vinyl({
         base: 'base',
@@ -112,11 +112,11 @@ describe('gulp-pug-linter', function () {
 
     beforeEach(function () {
       mockPugLint = sinon.stub().returns({
-        checkFile: sinon.stub().returns([{message: 'some error'}]),
+        checkFile: sinon.stub().returns([{ message: 'some error' }]),
         configure: sinon.stub()
       })
 
-      gulpPugLinter = proxyquire('../index', {'pug-lint': mockPugLint})
+      gulpPugLinter = proxyquire('../index', { 'pug-lint': mockPugLint })
 
       file = new Vinyl({
         base: 'base',
@@ -137,7 +137,7 @@ describe('gulp-pug-linter', function () {
     it('should stream a file that contains errors', function () {
       stream.on('data', function (processedFile) {
         expect(processedFile.pugLinter.errors)
-          .to.deep.include({message: 'some error'})
+          .to.deep.include({ message: 'some error' })
       })
     })
   })

test/reporter.spec.js

@@ -11,6 +11,16 @@ describe('#reporter()', function () {
   var mockReporter
   var stream
 
+  it('should throw a deprecation warning', function () {
+    mockFancyLog = { warn: sinon.spy() }
+    reporter = proxyquire('../reporter', { 'fancy-log': mockFancyLog })
+
+    reporter()
+
+    expect(mockFancyLog.warn.calledWith(sinon.match(/DEPRECATION WARNING/)))
+      .to.be.ok
+  })
+
   describe('when the stream contains PugLinter errors', function () {
     var streamFile
 
@@ -22,13 +32,13 @@ describe('#reporter()', function () {
         path: 'path.pug'
       })
 
-      streamFile.pugLinter = {errors: [{message: 'some error'}]}
+      streamFile.pugLinter = { errors: [{ message: 'some error' }] }
     })
 
     it('should print the error for default reporter', function () {
       mockFancyLog = sinon.stub()
 
-      reporter = proxyquire('../reporter', {'fancy-log': mockFancyLog})
+      reporter = proxyquire('../reporter', { 'fancy-log': mockFancyLog })
 
       stream = reporter()
 
@@ -49,7 +59,7 @@ describe('#reporter()', function () {
 
       reporter = proxyquire(
         '../reporter',
-        {'pug-mock-reporter': mockReporter}
+        { 'pug-mock-reporter': mockReporter }
       )
 
       stream = reporter('pug-mock-reporter')
@@ -58,7 +68,7 @@ describe('#reporter()', function () {
 
       stream.end()
 
-      expect(mockReporter.calledWith([{message: 'some error'}]))
+      expect(mockReporter.calledWith([{ message: 'some error' }]))
         .to.be.ok
     })
 
@@ -75,7 +85,7 @@ describe('#reporter()', function () {
 
       stream.end()
 
-      expect(spy.calledWith([{message: 'some error'}]))
+      expect(spy.calledWith([{ message: 'some error' }]))
         .to.be.ok
     })
 
@@ -125,7 +135,7 @@ describe('#reporter()', function () {
     it('should print no errors for default reporter', function () {
       mockFancyLog = sinon.stub()
 
-      reporter = proxyquire('../reporter', {'fancy-log': mockFancyLog})
+      reporter = proxyquire('../reporter', { 'fancy-log': mockFancyLog })
 
       stream = reporter()