Add debug information (#148)

README.md

@@ -198,6 +198,21 @@ Use [metalsmith-rename](https://www.npmjs.com/package/metalsmith-rename).
 
 Use [metalsmith-filenames](https://www.npmjs.com/package/metalsmith-filenames).
 
+## Errors and debugging
+
+If you're encountering problems you can use [debug](https://www.npmjs.com/package/debug) to enable verbose logging. To enable `debug` prefix your build command with `DEBUG=metalsmith-layouts`. So if you normally run `metalsmith` to build, use `DEBUG=metalsmith-layouts metalsmith` (on windows the syntax is [slightly different](https://www.npmjs.com/package/debug#windows-note)).
+
+### No files to process
+
+There are several things that might cause you to get a `no files to process` error:
+
+* Your [pattern](#pattern) does not match any files
+* None of your files pass validation, validation fails for files that:
+  * Have no layout
+  * Have a layout without an extension
+  * Are not utf-8
+  * Have a layout that needs a jstransformer that hasn't been installed
+
 ## Credits
 
 * [Ian Storm Taylor](https://github.com/ianstormtaylor) for creating [metalsmith-templates](https://github.com/segmentio/metalsmith-templates), on which this plugin was based

lib/__snapshots__/index.test.js.snap

@@ -1,5 +1,5 @@
 // Jest Snapshot v1, https://goo.gl/fbAQLP
 
-exports[`metalsmith-layouts should return an error for an invalid pattern 1`] = `"invalid pattern, the pattern option should be a string or array."`;
+exports[`metalsmith-layouts should return an error for an invalid pattern 1`] = `"invalid pattern, the pattern option should be a string or array of strings. See https://www.npmjs.com/package/metalsmith-layouts#pattern"`;
 
-exports[`metalsmith-layouts should return an error when there are no valid files to process 1`] = `"no files to process, check whether you have a jstransformer installed."`;
+exports[`metalsmith-layouts should return an error when there are no valid files to process 1`] = `"no files to process. See https://www.npmjs.com/package/metalsmith-layouts#no-files-to-process"`;

lib/index.js

@@ -1,3 +1,4 @@
+const debug = require('debug')('metalsmith-layouts');
 const match = require('multimatch');
 const path = require('path');
 const isUtf8 = require('is-utf8');
@@ -40,11 +41,14 @@ function getLayout({ file, settings }) {
  * Engine, renders file with the appropriate layout
  */
 
-function render({ file, metadata, settings, metalsmith }) {
+function render({ filename, files, metadata, settings, metalsmith }) {
   return new Promise(resolve => {
+    const file = files[filename];
     const layout = getLayout({ file, settings });
     const extension = layout.split('.').pop();
 
+    debug(`rendering ${filename} with layout ${layout}`);
+
     // Stringify file contents
     let contents = file.contents.toString();
 
@@ -58,6 +62,8 @@ function render({ file, metadata, settings, metalsmith }) {
     // Update file with results
     // eslint-disable-next-line no-param-reassign
     file.contents = Buffer.from(contents);
+
+    debug(`done rendering ${filename}`);
     return resolve();
   });
 }
@@ -66,27 +72,39 @@ function render({ file, metadata, settings, metalsmith }) {
  * Validate, checks whether a file should be processed
  */
 
-function validate({ file, settings }) {
+function validate({ filename, files, settings }) {
+  const file = files[filename];
   const layout = getLayout({ file, settings });
 
+  debug(`validating ${filename}`);
+
   // Files without a layout cannot be processed
   if (!layout) {
+    debug(`validation failed, ${filename} does not have a layout set`);
     return false;
   }
 
   // Layouts without an extension cannot be processed
   if (!layout.includes('.')) {
+    debug(`validation failed, layout for ${filename} does not have an extension`);
     return false;
   }
 
   // Files that are not utf8 are ignored
   if (!isUtf8(file.contents)) {
+    debug(`validation failed, ${filename} is not utf-8`);
     return false;
   }
 
   // Files without an applicable jstransformer are ignored
   const extension = layout.split('.').pop();
-  return getTransformer(extension);
+  const transformer = getTransformer(extension);
+
+  if (!transformer) {
+    debug(`validation failed, no jstransformer found for layout for ${filename}`);
+  }
+
+  return transformer;
 }
 
 /**
@@ -104,30 +122,31 @@ module.exports = options => (files, metalsmith, done) => {
 
   // Check whether the pattern option is valid
   if (!(typeof settings.pattern === 'string' || Array.isArray(settings.pattern))) {
-    done(new Error('invalid pattern, the pattern option should be a string or array.'));
+    done(
+      new Error(
+        'invalid pattern, the pattern option should be a string or array of strings. See https://www.npmjs.com/package/metalsmith-layouts#pattern'
+      )
+    );
   }
 
   // Filter files by the pattern
   const matchedFiles = match(Object.keys(files), settings.pattern);
 
   // Filter files by validity
-  const validFiles = matchedFiles.filter(filename => validate({ file: files[filename], settings }));
+  const validFiles = matchedFiles.filter(filename => validate({ filename, files, settings }));
 
-  // Let the user know when there are no files to process, usually caused by missing jstransformer
+  // Let the user know when there are no files to process
   if (validFiles.length === 0) {
-    done(new Error('no files to process, check whether you have a jstransformer installed.'));
+    done(
+      new Error(
+        'no files to process. See https://www.npmjs.com/package/metalsmith-layouts#no-files-to-process'
+      )
+    );
   }
 
   // Map all files that should be processed to an array of promises and call done when finished
   Promise.all(
-    validFiles.map(filename =>
-      render({
-        file: files[filename],
-        metadata,
-        settings,
-        metalsmith
-      })
-    )
+    validFiles.map(filename => render({ filename, files, metadata, settings, metalsmith }))
   )
     .then(() => done())
     .catch(/* istanbul ignore next */ error => done(error));

package.json

@@ -40,6 +40,7 @@
     "rimraf": "^2.6.2"
   },
   "dependencies": {
+    "debug": "^3.1.0",
     "inputformat-to-jstransformer": "^1.2.1",
     "is-utf8": "^0.2.1",
     "jstransformer": "^1.0.0",