Add configuration help

lib/command/common/run-with-cover.js

@@ -21,6 +21,7 @@ var Module = require('module'),
     DEFAULT_REPORT_FORMAT = 'lcov';
 
 function usage(arg0, command) {
+
     console.error('\nUsage: ' + arg0 + ' ' + command + ' [<options>] <executable-js-file-or-command> [-- <arguments-to-jsfile>]\n\nOptions are:\n\n'
         + [
             formatOption('--config <path-to-config>', 'the configuration file to use, defaults to .istanbul.yml'),
@@ -29,7 +30,7 @@ function usage(arg0, command) {
             formatOption('--[no-]default-excludes', 'apply default excludes [ **/node_modules/**, **/test/**, **/tests/** ], defaults to true'),
             formatOption('--hook-run-in-context', 'hook vm.runInThisContext in addition to require (supports RequireJS), defaults to false'),
             formatOption('--post-require-hook <file> | <module>', 'JS module that exports a function for post-require processing'),
-            formatOption('--report <report-type>', 'report type, one of html, lcov, lcovonly, none, defaults to lcov (= lcov.info + HTML)'),
+            formatOption('--report <format> [--report <format>] ', 'report format, defaults to lcov (= lcov.info + HTML)'),
             formatOption('--dir <report-dir>', 'report directory, defaults to ./coverage'),
             formatOption('--print <type>', 'type of report to print to console, one of summary (default), detail, both or none'),
             formatOption('--verbose, -v', 'verbose mode')

lib/command/help.js

@@ -6,7 +6,28 @@
 var Command = require('./index.js'),
     util = require('util'),
     formatOption = require('../util/help-formatter').formatOption,
-    VERSION = require('../../index').VERSION;
+    VERSION = require('../../index').VERSION,
+    configuration = require('../configuration'),
+    yaml = require('js-yaml');
+
+function showConfigHelp(toolName) {
+
+    console.error('\nConfiguring ' + toolName);
+    console.error('====================');
+    console.error('\n' + toolName + ' can be configured globally using a .istanbul.yml YAML file at the root of your source tree');
+    console.error('\nEvery command also accepts a --config=<config-file> argument to customize its location per command');
+    console.error('The alternate config file can be in YAML, JSON or node.js (exporting the config object).');
+    console.error('\nThe config file currently has three sections for instrumentation, reporting and hooks.');
+    console.error('Note that certain commands (like cover) use information from multiple sections.');
+    console.error('\nKeys in the config file usually correspond to command line parameters with the same name');
+    console.error('The verbose option for every command shows you the exact configuration used');
+    console.error('\nThe default configuration is as follows:\n');
+
+    console.error(yaml.safeDump(configuration.defaultConfig(), { indent: 4, flowLevel: 3 }));
+    console.error('\nThe `watermarks` section does not have a command line equivalent');
+    console.error('This allows you to set up low and high watermark percentages for reporting');
+    console.error('These are honored by all reporters that colorize their output based on low/ medium/ high coverage');
+}
 
 function HelpCommand() {
     Command.call(this);
@@ -22,7 +43,8 @@ Command.mix(HelpCommand, {
 
     usage: function () {
 
-        console.error('\nUsage: ' + this.toolName() + ' ' + this.type() + ' <command>\n');
+        console.error('\nUsage: ' + this.toolName() + ' ' + this.type() + ' config | <command>\n');
+        console.error('config provides help with istanbul configuration\n');
         console.error('Available commands are:\n');
 
         var commandObj;
@@ -40,12 +62,16 @@ Command.mix(HelpCommand, {
         if (args.length === 0) {
             this.usage();
         } else {
-            try {
-                command = Command.create(args[0]);
-                command.usage('istanbul', Command.resolveCommandName(args[0]));
-            } catch (ex) {
-                console.error('Invalid command: ' + args[0]);
-                this.usage();
+            if (args[0] === 'config') {
+                showConfigHelp(this.toolName());
+            } else {
+                try {
+                    command = Command.create(args[0]);
+                    command.usage('istanbul', Command.resolveCommandName(args[0]));
+                } catch (ex) {
+                    console.error('Invalid command: ' + args[0]);
+                    this.usage();
+                }
             }
         }
         return callback();

lib/configuration.js

@@ -28,11 +28,6 @@ function defaultConfig() {
         hooks: {
             'hook-run-in-context': false,
             'post-require-hook': null
-        },
-        thresholds: {
-            statements: 0,
-            branches: 0,
-            functions: 0
         }
     };
     ret.reporting.watermarks = defaults.watermarks();
@@ -175,7 +170,7 @@ function Configuration(obj, overrides) {
     if (config.verbose) {
         console.error('Using configuration');
         console.error('-------------------');
-        console.error(yaml.dump(config));
+        console.error(yaml.safeDump(config, { indent: 4, flowLevel: 3 }));
         console.error('-------------------\n');
     }
     this.verbose = config.verbose;
@@ -215,6 +210,7 @@ function loadObject(obj, overrides) {
 
 module.exports = {
     loadFile: loadFile,
-    loadObject: loadObject
+    loadObject: loadObject,
+    defaultConfig: defaultConfig
 };
 

test/cli/test-base-cli.js

@@ -35,5 +35,12 @@ module.exports = {
             test.ok(results.grepError(/ENOENT/));
             test.done();
         });
+    },
+    "should provide configuration help": function (test) {
+        helper.runCommand('help', [ 'config' ], function (results) {
+            test.ok(results.succeeded());
+            test.ok(results.grepError(/Configuring istanbul/));
+            test.done();
+        });
     }
 };