Add debug option (#46)

Add debug option to pass an postcss-debug instance.
Fixes #39

Author: giuseppeg

CHANGELOG.md

@@ -1,5 +1,6 @@
 ### HEAD
 
+* Add `debug` option to pass an `postcss-debug` instance
 * Allow usage of `transform` and `onImport` in `postcss-easy-import`
 * Remove `beforeLint` feature
 * Add default browsers list for autoprefixer

README.md

@@ -94,6 +94,35 @@ preprocessor(css, {
 
 Where to resolve imports from. Passed to [`postcss-import`](https://github.com/postcss/postcss-import/blob/master/README.md#root).
 
+##### `debug`
+
+* Type: `Function`
+* Default: identity (it does nothing)
+
+Before preprocessing `debug` is invoked on the postcss `plugins` array.
+This allows you to pass a [`postcss-debug`](https://www.npmjs.com/package/postcss-debug) instance.
+
+```javascript
+var preprocessor = require('suitcss-preprocessor');
+var createDebugger = require('postcss-debug').createDebugger;
+var debug = createDebugger();
+
+preprocessor(css, {
+  debug: debug
+}).then(function () {
+  debug.inspect();
+});
+```
+
+N.B. `debug` should always take one argument that is `plugins` and eventually return it:
+
+```javascript
+function debug(plugins) {
+  // do something with plugins here
+  return plugins;
+}
+```
+
 ##### `lint`
 
 * Type: `Boolean`

lib/index.js

@@ -11,12 +11,14 @@ var stylelintConfigSuit = require('stylelint-config-suitcss');
 module.exports = preprocessor;
 
 /**
- * Default options to PostCSS plugins
+ * Default configuration
+ * and options to PostCSS plugins
  */
 
 var defaults = {
-  minify: false,
+  debug: identity,
   lint: false,
+  minify: false,
   use: [
     'postcss-easy-import',
     'postcss-custom-properties',
@@ -62,7 +64,7 @@ function preprocessor(css, options) {
     return settings ? plugin(settings) : plugin;
   });
 
-  var processor = postcss(plugins);
+  var processor = postcss(options.debug(plugins));
 
   if (options.minify) {
     processor.use(cssnano(options.cssnano));

test/test.js

@@ -41,15 +41,7 @@ describe('suitcss', function() {
     });
 
     it('should use default options when nothing is passed', function() {
-      var keys = [
-        'autoprefixer',
-        'minify',
-        'use',
-        'lint',
-        'postcss-easy-import',
-        'postcss-reporter',
-        'cssnano'
-      ];
+      var keys = Object.keys(defaults);
       expect(mergeOptions({})).to.have.keys(keys);
       expect(mergeOptions()).to.have.keys(keys);
       expect(mergeOptions({}).use).to.eql(defaults.use);
@@ -61,6 +53,19 @@ describe('suitcss', function() {
       expect(opts['postcss-easy-import'].root).to.equal('test/root');
     });
 
+    it('should allow a debug function to be ran on plugins', function (done) {
+      var debug = sinon.spy(function (plugins) {
+        return plugins;
+      });
+
+      suitcss('body {}', {
+        debug: debug
+      }).then(function () {
+        expect(debug.calledOnce).to.be.true;
+        done();
+      }).catch(done);
+    });
+
     it('should allow stylelint to be enabled', function() {
       var opts = mergeOptions({lint: true});
       expect(opts.lint).to.be.true;