Merge pull request #31 from ariatemplates/debug-tweak

Help diagnose faults by writing out json data when exception thrown

.editorconfig

@@ -0,0 +1,12 @@
+[*]
+charset=utf-8
+end_of_line=lf
+trim_trailing_whitespace=true
+insert_final_newline=true
+indent_style=tab
+indent_size=2
+spaces_around_brackets=both
+
+[{.eslintrc,.babelrc,.stylelintrc,.firebaserc,*.bowerrc,*.jsb3,*.jsb2,*.json,*.config,*.yml,*.yaml}]
+indent_style=space
+indent_size=2

README.md

@@ -113,6 +113,7 @@ module.exports = function(data, callback) {
    *   commits: [], // the array of commits as described above
    *   range: '<since>..<until>',
    *   dateFnsFormat: function () {},
+   *   debug: function() {}, // utility function to log debug messages
    * }
    *
    * Do all the processing you need and when ready call the callback passing the new data structure
@@ -130,13 +131,17 @@ The object passed to the callback will be merged with the input data and passed
 For an example check `samples/post-processing.js`
 
 ### Debug
+If your post processing script or template throws an exception, the JSON data will be written to the file system in the same folder as the processing script.
 
-If the output is not what you expect, set the DEBUG environment variable:
+The DEBUG environment variable can also be useful for fault diagnosis:
 
 #### Linux
-    DEBUG=release-notes:* git-release-notes ...
+    DEBUG=release-notes:*
+    git-release-notes ...
 
 #### Windows
 
-    SET DEBUG=release-notes:*
+    SET DEBUG=release-notes:cli,release-notes:externalscript
     git-release-notes ...
+
+Note the filtering options available: `release-notes:cli`, `release-notes:externalscript`, `release-notes:data`

index.js

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-var argv = require("optimist").usage("release-notes [<options>] <since>..<until> <template>")
+var argv = require("optimist").usage("git-release-notes [<options>] <since>..<until> <template>")
 .options("f", {
 	"alias": "file"
 })
@@ -44,6 +44,7 @@ var fs = require("fs");
 var ejs = require("ejs");
 var path = require("path");
 var debug = require("debug")("release-notes:cli");
+var debugData = require("debug")("release-notes:data");
 var dateFnsFormat = require('date-fns/format')
 
 var template = argv._[1];
@@ -123,25 +124,33 @@ function postProcess(templateContent, commits) {
 	debug("Got %d commits", commits.length);
 	if (commits.length) {
 		if (argv.s) {
+			var externalScriptPath = path.join(process.cwd(), argv.s);
 			try {
-				var externalScript = require(path.join(process.cwd(), argv.s));
+				var externalScript = require(externalScriptPath);
 			} catch (ex) {
-				debug("Exception while reading external script '%s'", ex.message);
+				debug("Exception while reading external script '%s': '%s'", externalScriptPath, ex.message);
 				console.error('Unable to read external script');
 				process.exit(7);
 			}
 			debug("Trying to run the external script");
+			var inputData;
+			var outputData;
 			try {
-				externalScript({
+				inputData = {
 					commits: commits,
 					range: argv._[0],
 					dateFnsFormat: dateFnsFormat,
-				}, function (data) {
+					debug: require("debug")("release-notes:externalscript")
+				};
+				externalScript(inputData, function (data) {
+					outputData = data;
 					render(templateContent, data);
 				});
 				debug("Waiting for external script to call the callback");
 			} catch (ex) {
 				debug("Exception while running external script '%s'", ex.message);
+				debugData("Input data passed to the external script `%s`", JSON.stringify(inputData, null, '  '));
+				debugData("Output data received from the external script `%s`", outputData ? JSON.stringify(outputData, null, '  ') : '');
 				console.error('Error while processing external script', ex);
 				process.exit(8);
 			}

package.json

@@ -14,7 +14,8 @@
     "posttest": "npm run lint",
     "test-html": "node index.js -- 32a369f..0419636 ./templates/html.ejs > ./samples/output-html.html",
     "test-html-bootstrap": "cross-env DEBUG=* node index.js -- 32a369f..0419636 ./templates/html-bootstrap.ejs > ./samples/output-html-bootstrap.html",
-    "test-markdown": "node index.js -- 32a369f..0419636 ./templates/markdown.ejs > ./samples/output-markdown.md"
+    "test-markdown": "node index.js -- 32a369f..0419636 ./templates/markdown.ejs > ./samples/output-markdown.md",
+    "test-script": "node index.js -s ./samples/post-processing.js 32a369f..0419636 ./templates/markdown.ejs"
   },
   "version": "1.1.0",
   "dependencies": {