istanbul - npm Package Compare versions

Comparing version 0.2.16 to 0.3.0

CHANGELOG.md

@@ -6,2 +6,18 @@ Changelog
 <tr>
+<td>v0.3.0</td>
+<td>
+    The *reports* release. **Potentially backwards-incompatible** if you are using
+    undocumented features or custom report implementations.
+    <ul>
+        <li>Change report command line to support multiple reports, add back-compat processing with warnings</li>
+        <li>Enable `report` command to read report list from config, thanks to @piuccio</li>
+        <li>Support multiple reports for `cover` and `report` commands</li>
+        <li>Support per-report config options in configuration file</li>
+        <li>Turn reports into event emitters so they can signal `done`</li>
+        <li>Add `Reporter` class to be able to generate multiple reports</li>
+        <li>Add a bunch of API docs, refactor README</li>
+    </ul>
+</td>
+</tr>
+<tr>
 <td>v0.2.16</td><td>Make YUI links https-always since relative links break local
@@ -8,0 +24,0 @@ filesystem use-case

index.js

@@ -6,9 +6,2 @@ /*
 
-/**
- * provides access to the key libraries in istanbul so you can write
- * your own tools using `istanbul` as a library.
- *
- * @module istanbul
- */
-
 /*jslint nomen: true */
@@ -24,3 +17,4 @@ var path = require('path'),
 /**
- * the top-level API for `istanbul`.
+ * the top-level API for `istanbul`. provides access to the key libraries in
+ * istanbul so you can write your own tools using `istanbul` as a library.
  *
@@ -33,3 +27,6 @@ * Usage
  *
- * @class API
+ * @class Istanbul
+ * @static
+ * @module main
+ * @main main
  */
@@ -40,3 +37,4 @@
      * the Instrumenter class.
-     * @property {Instrumenter} Instrumenter
+     * @property Instrumenter
+     * @type Instrumenter
      * @static
@@ -47,3 +45,4 @@ */
      * the Store class.
-     * @property {Store} Store
+     * @property  Store
+     * @type Store
      * @static
@@ -54,3 +53,4 @@ */
      * the Collector class
-     * @property {Collector} Collector
+     * @property  Collector
+     * @type Collector
      * @static
@@ -61,3 +61,4 @@ */
      * the hook module
-     * @property {Hook} hook
+     * @property hook
+     * @type Hook
      * @static
@@ -68,3 +69,4 @@ */
      * the Report class
-     * @property {Report} Report
+     * @property Report
+     * @type Report
      * @static
@@ -74,4 +76,19 @@ */
     /**
+     * the config module
+     * @property config
+     * @type Config
+     * @static
+     */
+    config: require('./lib/config'),
+    /**
+     * the Reporter class
+     * @property Reporter
+     * @type Reporter
+     * @static
+     */
+    Reporter: require('./lib/reporter'),
+    /**
      * utility for processing coverage objects
-     * @property {ObjectUtils} utils
+     * @property utils
+     * @type ObjectUtils
      * @static
@@ -111,6 +128,28 @@ */
      * the version of the library
-     * @property {String} VERSION
+     * @property VERSION
+     * @type String
      * @static
      */
     VERSION: meta.VERSION,
+    /**
+     * the abstract Writer class
+     * @property Writer
+     * @type Writer
+     * @static
+     */
+    Writer: require('./lib/util/writer').Writer,
+    /**
+     * the abstract ContentWriter class
+     * @property ContentWriter
+     * @type ContentWriter
+     * @static
+     */
+    ContentWriter: require('./lib/util/writer').ContentWriter,
+    /**
+     * the concrete FileWriter class
+     * @property FileWriter
+     * @type FileWriter
+     * @static
+     */
+    FileWriter: require('./lib/util/file-writer'),
     //undocumented
@@ -117,0 +156,0 @@ _yuiLoadHook: require('./lib/util/yui-load-hook'),

lib/cli.js

@@ -65,2 +65,3 @@ #!/usr/bin/env node
 
+/* istanbul ignore if: untestable */
 if (require.main === module) {
@@ -67,0 +68,0 @@ var args = Array.prototype.slice.call(process.argv, 2);

lib/collector.js

@@ -46,2 +46,3 @@ /*
  * @class Collector
+ * @module main
  * @constructor
@@ -48,0 +49,0 @@ * @param {Object} options Optional. Configuration options.

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

@@ -18,5 +18,5 @@ /*
     hook = require('../../hook'),
-    Report = require('../../report'),
+    Reporter = require('../../reporter'),
     resolve = require('resolve'),
-    configuration = require('../../configuration');
+    configuration = require('../../config');
 
@@ -82,4 +82,2 @@ function usage(arg0, command) {
         config = configuration.loadFile(opts.config, overrides),
-        watermarks = config.reporting.watermarks(),
-        reportOpts,
         verbose = config.verbose,
@@ -91,3 +89,3 @@ cmdAndArgs = opts.argv.remain,
         reportingDir,
-        reports = [],
+        reporter = new Reporter(config),
         runFn,
@@ -126,18 +124,15 @@ excludes;
         reportingDir = path.resolve(config.reporting.dir());
-        reportOpts = { dir: reportingDir, watermarks: watermarks };
         mkdirp.sync(reportingDir); //ensure we fail early if we cannot do this
-        reports.push.apply(reports, config.reporting.reports().map(function (r) {
-            return Report.create(r, reportOpts);
-        }));
+        reporter.addAll(config.reporting.reports());
         if (config.reporting.print() !== 'none') {
             switch (config.reporting.print()) {
             case 'detail':
-                reports.push(Report.create('text', reportOpts));
+                reporter.add('text');
                 break;
             case 'both':
-                reports.push(Report.create('text', reportOpts));
-                reports.push(Report.create('text-summary', reportOpts));
+                reporter.add('text');
+                reporter.add('text-summary');
                 break;
             default:
-                reports.push(Report.create('text-summary', reportOpts));
+                reporter.add('text-summary');
                 break;
@@ -226,6 +221,3 @@ }
                     }
-                    reports.forEach(function (report) {
-                        report.writeReport(collector, true);
-                    });
-                    return callback();
+                    reporter.write(collector, true, callback);
                 });
@@ -232,0 +224,0 @@ if (config.instrumentation.preloadSources()) {

lib/command/help.js

@@ -10,3 +10,3 @@ /*
     VERSION = require('../../index').VERSION,
-    configuration = require('../configuration'),
+    configuration = require('../config'),
     yaml = require('js-yaml'),
@@ -29,4 +29,8 @@ formatPara = require('../util/help-formatter').formatPara;
         formatPara('Keys in the config file usually correspond to command line parameters with the same name. ' +
-            'The verbose option for every command shows you the exact configuration used'));
+            'The verbose option for every command shows you the exact configuration used. See the api ' +
+            'docs for an explanation of each key.'));
 
+    console.error('\n' +
+        formatPara('You only need to specify the keys that you want to override. Your overrides will be merged ' +
+            'with the default config.'));
     console.error('\nThe default configuration is as follows:\n');
@@ -37,3 +41,7 @@ console.error(yaml.safeDump(configuration.defaultConfig(), { indent: 4, flowLevel: 3 }));
             'low and high watermark percentages for reporting. These are honored by all reporters that colorize ' +
-            'their output based on low/ medium/ high coverage'));
+            'their output based on low/ medium/ high coverage.'));
+    console.error('\n' +
+        formatPara('The `reportConfig` section allows you to configure each report format independently ' +
+            'and has no command-line equivalent either.'));
+    console.error('');
 }
@@ -40,0 +48,0 @@

lib/command/instrument.js

@@ -8,2 +8,3 @@ /*
     mkdirp = require('mkdirp'),
+    once = require('once'),
     async = require('async'),
@@ -19,8 +20,7 @@ fs = require('fs'),
     Collector = require('../collector'),
-    flowControl = require('../util/flow-control'),
-    configuration = require('../configuration'),
+    configuration = require('../config'),
     verbose;
 
 
-/**
+/*
  * Chunk file size to use when reading non JavaScript files in memory
@@ -66,3 +66,3 @@ * and copying them over when using complete-copy flag.
 
-            callback = flowControl.callOnce(callback);
+            callback = once(callback);
             mkdirp.sync(oDir);
@@ -69,0 +69,0 @@

lib/command/report.js

@@ -8,11 +8,13 @@ /*
     Report = require('../report'),
+    Reporter = require('../reporter'),
     path = require('path'),
     fs = require('fs'),
     Collector = require('../collector'),
-    inputError = require('../util/input-error'),
-    formatOption = require('../util/help-formatter').formatOption,
+    helpFormatter = require('../util/help-formatter'),
+    formatOption = helpFormatter.formatOption,
+    formatPara = helpFormatter.formatPara,
     filesFor = require('../util/file-matcher').filesFor,
     util = require('util'),
     Command = require('./index'),
-    configuration = require('../configuration');
+    configuration = require('../config');
 
@@ -26,2 +28,10 @@ function ReportCommand() {
 
+function printDeprecationMessage(pat, fmt) {
+    console.error('**********************************************************************');
+    console.error('DEPRECATION WARNING! You are probably using the old format of the report command');
+    console.error('This will stop working soon, see `istanbul help report` for the new command format');
+    console.error('Assuming you meant: istanbul report --include=' + pat + ' ' + fmt);
+    console.error('**********************************************************************');
+}
+
 Command.mix(ReportCommand, {
@@ -33,3 +43,3 @@ synopsis: function () {
     usage: function () {
-        console.error('\nUsage: ' + this.toolName() + ' ' + this.type() + ' <options> [ <format> [<include-pattern>] ]\n\nOptions are:\n\n' +
+        console.error('\nUsage: ' + this.toolName() + ' ' + this.type() + ' <options> [ <format> ... ]\n\nOptions are:\n\n' +
             [
@@ -39,12 +49,17 @@ formatOption('--config <path-to-config>', 'the configuration file to use, defaults to .istanbul.yml'),
                 formatOption('--dir <report-directory>', 'The output directory where files will be written. This defaults to ./coverage/'),
+                formatOption('--include <glob>', 'The fileset pattern to select one or more coverage files, defaults to **/coverage*.json'),
                 formatOption('--verbose, -v', 'verbose mode')
-            ].join('\n\n') + '\n');
+            ].join('\n\n'));
 
         console.error('\n');
-
-        console.error('<format> is one of html, lcovonly, lcov (html + lcovonly), cobertura, text-summary, text, ' +
-            'teamcity, or clover. Default is lcov');
-        console.error('<include-pattern> is a fileset pattern that can be used to select one or more coverage files ' +
-            'for merged reporting. This defaults to "**/coverage*.json"');
-
+        console.error('<format> is one of ');
+        Report.getReportList().forEach(function (name) {
+           console.error(formatOption(name, Report.create(name).synopsis()));
+        });
+        console.error("");
+        console.error(formatPara([
+            'Default format is lcov unless otherwise specified in the config file.',
+            'In addition you can tweak the file names for various reports using the config file.',
+            'Type `istanbul help config` to see what can be tweaked.'
+        ].join(' ')));
         console.error('\n');
@@ -59,9 +74,7 @@ },
                 dir: path,
+                include: String,
                 verbose: Boolean
             },
             opts = nopt(template, { v : '--verbose' }, args, 0),
-            fmtAndArgs = opts.argv.remain,
-            fmt = 'lcov',
-            includePattern = '**/coverage*.json',
-            reporter,
+            includePattern = opts.include || '**/coverage*.json',
             root,
@@ -75,21 +88,21 @@ collector = new Collector(),
             }),
-            reportOpts = {
-                verbose: config.verbose,
-                dir: config.reporting.dir(),
-                watermarks: config.reporting.watermarks()
-            };
+            formats = opts.argv.remain,
+            reporter = new Reporter(config);
 
-        if (fmtAndArgs.length > 0) {
-            fmt = fmtAndArgs[0];
+        // Start: backward compatible processing
+        if (formats.length === 2 &&
+                Report.getReportList().indexOf(formats[1]) < 0) {
+            includePattern = formats[1];
+            formats = [ formats[0] ];
+            printDeprecationMessage(includePattern, formats[0]);
         }
+        // End: backward compatible processing
 
-        if (fmtAndArgs.length > 1) {
-            includePattern = fmtAndArgs[1];
+        if (formats.length === 0) {
+            formats = config.reporting.reports();
         }
-
-        try {
-            reporter = Report.create(fmt, reportOpts);
-        } catch (ex) {
-            return callback(inputError.create('Invalid report format [' + fmt + ']'));
+        if (formats.length === 0) {
+            formats = [ 'lcov' ];
         }
+        reporter.addAll(formats);
 
@@ -106,6 +119,6 @@ root = opts.root || process.cwd();
             });
-            console.log('Using reporter [' + fmt + ']');
-            reporter.writeReport(collector);
-            console.log('Done');
-            return callback();
+            reporter.write(collector, false, function (err) {
+                console.log('Done');
+                return callback(err);
+            });
         });
@@ -112,0 +125,0 @@ }

lib/hook.js

@@ -32,2 +32,3 @@ /*
  * @class Hook
+ * @module main
  */
@@ -34,0 +35,0 @@ var path = require('path'),

lib/instrumenter.js

@@ -553,2 +553,3 @@ /*
          * counts for mainline code).
+         * @method lastFileCoverage
          * @return {Object} a "zero-coverage" file coverage object for the code last instrumented
@@ -563,2 +564,3 @@ * by this instrumenter
          * just before calling this method.
+         * @method lastSourceMap
          * @return {Object} a source map object for the code last instrumented
@@ -565,0 +567,0 @@ * by this instrumenter

lib/object-utils.js

@@ -36,2 +36,3 @@ /*
  * @class ObjectUtils
+ * @module main
  * @static
@@ -38,0 +39,0 @@ */

lib/report/clover.js

 var path = require('path'),
+    util = require('util'),
     Report = require('./index'),
@@ -7,2 +8,18 @@ FileWriter = require('../util/file-writer'),
 
+/**
+ * a `Report` implementation that produces a clover-style XML file.
+ *
+ * Usage
+ * -----
+ *
+ *      var report = require('istanbul').Report.create('clover');
+ *
+ * @class CloverReport
+ * @module report
+ * @extends Report
+ * @constructor
+ * @param {Object} opts optional
+ * @param {String} [opts.dir] the directory in which to the clover.xml will be written
+ * @param {String} [opts.file] the file name, defaulted to config attribute or 'clover.xml'
+ */
 function CloverReport(opts) {
@@ -13,3 +30,3 @@ Report.call(this);
     this.dir = opts.dir || this.projectRoot;
-    this.file = opts.file || 'clover.xml';
+    this.file = opts.file || this.getDefaultConfig().file;
     this.opts = opts;
@@ -19,2 +36,3 @@ }
 CloverReport.TYPE = 'clover';
+util.inherits(CloverReport, Report);
 
@@ -182,2 +200,8 @@ function asJavaPackage(node) {
 Report.mix(CloverReport, {
+    synopsis: function () {
+        return 'XML coverage report that can be consumed by the clover tool';
+    },
+    getDefaultConfig: function () {
+        return { file: 'clover.xml' };
+    },
     writeReport: function (collector, sync) {
@@ -188,2 +212,3 @@ var summarizer = new TreeSummarizer(),
             projectRoot = this.projectRoot,
+            that = this,
             tree,
@@ -197,4 +222,6 @@ root;
         root = tree.root;
+        writer.on('done', function () { that.emit('done'); });
         writer.writeFile(outputFile, function (contentWriter) {
             walk(root, collector, contentWriter, 0, projectRoot);
+            writer.done();
         });
@@ -201,0 +228,0 @@ }

lib/report/cobertura.js

@@ -7,2 +7,3 @@ /*
 var path = require('path'),
+    util = require('util'),
     Report = require('./index'),
@@ -23,2 +24,3 @@ FileWriter = require('../util/file-writer'),
  * @class CoberturaReport
+ * @module report
  * @extends Report
@@ -34,3 +36,3 @@ * @constructor
     this.dir = opts.dir || this.projectRoot;
-    this.file = opts.file || 'cobertura-coverage.xml';
+    this.file = opts.file || this.getDefaultConfig().file;
     this.opts = opts;
@@ -40,2 +42,3 @@ }
 CoberturaReport.TYPE = 'cobertura';
+util.inherits(CoberturaReport, Report);
 
@@ -192,2 +195,8 @@ function asJavaPackage(node) {
 Report.mix(CoberturaReport, {
+    synopsis: function () {
+        return 'XML coverage report that can be consumed by the cobertura tool';
+    },
+    getDefaultConfig: function () {
+        return { file: 'cobertura-coverage.xml' };
+    },
     writeReport: function (collector, sync) {
@@ -198,2 +207,3 @@ var summarizer = new TreeSummarizer(),
             projectRoot = this.projectRoot,
+            that = this,
             tree,
@@ -207,4 +217,6 @@ root;
         root = tree.root;
+        writer.on('done', function () { that.emit('done'); });
         writer.writeFile(outputFile, function (contentWriter) {
             walk(root, collector, contentWriter, 0, projectRoot);
+            writer.done();
         });
@@ -211,0 +223,0 @@ }

lib/report/common/defaults.js

@@ -5,2 +5,5 @@ /*
  */
+
+var Report  = require('../index');
+
 module.exports = {
@@ -32,4 +35,16 @@ watermarks: function () {
         return str;
+    },
+
+    defaultReportConfig: function () {
+        var cfg = {};
+        Report.getReportList().forEach(function (type) {
+            var rpt = Report.create(type),
+                c = rpt.getDefaultConfig();
+            if (c) {
+                cfg[type] = c;
+            }
+        });
+        return cfg;
     }
 };
 

lib/report/html.js

@@ -320,2 +320,3 @@ /*
  * @extends Report
+ * @module report
  * @constructor
@@ -341,2 +342,6 @@ * @param {Object} opts optional
 
+    synopsis: function () {
+        return 'Navigable HTML coverage report for every file and directory';
+    },
+
     getPathHtml: function (node, linkMapper) {
@@ -516,2 +521,3 @@ var parent = node.parent,
             writer = opts.writer || new FileWriter(sync),
+            that = this,
             tree;
@@ -535,4 +541,6 @@
         });
+        writer.on('done', function () { that.emit('done'); });
         //console.log(JSON.stringify(tree.root, undefined, 4));
         this.writeFiles(writer, tree.root, dir, collector);
+        writer.done();
     }
@@ -539,0 +547,0 @@ });

lib/report/index.js

@@ -6,7 +6,15 @@ /*
 
-var Factory = require('../util/factory'),
+var util = require('util'),
+    EventEmitter = require('events').EventEmitter,
+    Factory = require('../util/factory'),
     factory = new Factory('report', __dirname, false);
 /**
- * abstract report class for producing coverage reports.
+ * An abstraction for producing coverage reports.
+ * This class is both the base class as well as a factory for `Report` implementations.
+ * All reports are event emitters and are expected to emit a `done` event when
+ * the report writing is complete.
  *
+ * See also the `Reporter` class for easily producing multiple coverage reports
+ * with a single call.
+ *
  * Usage
@@ -20,5 +28,8 @@ * -----
  *      collector.add(coverageObject);
+ *      report.on('done', function () { console.log('done'); });
  *      report.writeReport(collector);
  *
  * @class Report
+ * @module report
+ * @main report
  * @constructor
@@ -28,4 +39,9 @@ * @protected
  */
-function Report(/* options */) {}
-//add register, create, mix, loadAll, getStoreList as class methods
+function Report(/* options */) {
+    EventEmitter.call(this);
+}
+
+util.inherits(Report, EventEmitter);
+
+//add register, create, mix, loadAll, getReportList as class methods
 factory.bindClassMethods(Report);
@@ -48,5 +64,29 @@
  */
+/**
+ * returns the list of available reports as an array of strings
+ * @method getReportList
+ * @static
+ * @return an array of supported report formats
+ */
 
-Report.prototype = {
+var proto = {
     /**
+     * returns a one-line summary of the report
+     * @method synopsis
+     * @return {String} a description of what the report is about
+     */
+    synopsis: function () {
+        throw new Error('synopsis must be overridden');
+    },
+    /**
+     * returns a config object that has override-able keys settable via config
+     * @method getDefaultConfig
+     * @return {Object|null} an object representing keys that can be overridden via
+     *  the istanbul configuration where the values are the defaults used when
+     *  not specified. A null return implies no config attributes
+     */
+    getDefaultConfig: function () {
+        return null;
+    },
+    /**
      * writes the report for a set of coverage objects added to a collector.
@@ -62,4 +102,8 @@ * @method writeReport
 
+Object.keys(proto).forEach(function (k) {
+    Report.prototype[k] = proto[k];
+});
+
 module.exports = Report;
 
 

lib/report/json.js

@@ -21,2 +21,3 @@ /*
  * @extends Report
+ * @module report
  * @constructor
@@ -29,2 +30,3 @@ * @param {Object} opts optional
     this.opts.dir = this.opts.dir || process.cwd();
+    this.opts.file = this.opts.file || this.getDefaultConfig().file;
     this.opts.writer = this.opts.writer || null;
@@ -36,5 +38,16 @@ }
 Report.mix(JsonReport, {
+    synopsis: function () {
+        return 'prints the coverage object as JSON to a file';
+    },
+    getDefaultConfig: function () {
+        return {
+            file: 'coverage-final.json'
+        };
+    },
     writeReport: function (collector, sync) {
-        var outputFile = path.resolve(this.opts.dir, 'coverage-final.json'),
-            writer = this.opts.writer || new Writer(sync);
+        var outputFile = path.resolve(this.opts.dir, this.opts.file),
+            writer = this.opts.writer || new Writer(sync),
+            that = this;
+
+        writer.on('done', function () { that.emit('done'); });
         writer.writeFile(outputFile, function (contentWriter) {
@@ -55,2 +68,3 @@ var first = true;
         });
+        writer.done();
     }
@@ -57,0 +71,0 @@ });

lib/report/lcov.js

@@ -7,2 +7,3 @@ /*
 var path = require('path'),
+    util = require('util'),
     mkdirp = require('mkdirp'),
@@ -25,2 +26,3 @@ Report = require('./index'),
  * @extends Report
+ * @module report
  * @constructor
@@ -43,7 +45,21 @@ * @param {Object} opts optional
 LcovReport.TYPE = 'lcov';
+util.inherits(LcovReport, Report);
 
 Report.mix(LcovReport, {
+    synopsis: function () {
+        return 'combined lcovonly and html report that generates an lcov.info file as well as HTML';
+    },
     writeReport: function (collector, sync) {
+        var handler = this.handleDone.bind(this);
+        this.inProgress = 2;
+        this.lcov.on('done', handler);
+        this.html.on('done', handler);
         this.lcov.writeReport(collector, sync);
         this.html.writeReport(collector, sync);
+    },
+    handleDone: function () {
+        this.inProgress -= 1;
+        if (this.inProgress === 0) {
+            this.emit('done');
+        }
     }
@@ -50,0 +66,0 @@ });

lib/report/lcovonly.js

@@ -22,2 +22,3 @@ /*
  * @extends Report
+ * @module report
  * @constructor
@@ -30,2 +31,3 @@ * @param {Object} opts optional
     this.opts.dir = this.opts.dir || process.cwd();
+    this.opts.file = this.opts.file || this.getDefaultConfig().file;
     this.opts.writer = this.opts.writer || null;
@@ -37,2 +39,8 @@ }
 Report.mix(LcovOnlyReport, {
+    synopsis: function () {
+        return 'lcov coverage report that can be consumed by the lcov tool';
+    },
+    getDefaultConfig: function () {
+        return { file: 'lcov.info' };
+    },
     writeFileCoverage: function (writer, fc) {
@@ -85,5 +93,6 @@ var functions = fc.f,
     writeReport: function (collector, sync) {
-        var outputFile = path.resolve(this.opts.dir, 'lcov.info'),
+        var outputFile = path.resolve(this.opts.dir, this.opts.file),
             writer = this.opts.writer || new Writer(sync),
             that = this;
+        writer.on('done', function () { that.emit('done'); });
         writer.writeFile(outputFile, function (contentWriter) {
@@ -94,5 +103,6 @@ collector.files().forEach(function (key) {
         });
+        writer.done();
     }
 });
 
-module.exports = LcovOnlyReport;
+module.exports = LcovOnlyReport;

lib/report/none.js

@@ -6,4 +6,20 @@ /*
 
-var Report = require('./index');
+var util = require('util'),
+    Report = require('./index');
 
+/**
+ * a `Report` implementation that does nothing. Use to specify that no reporting
+ * is needed.
+ *
+ * Usage
+ * -----
+ *
+ *      var report = require('istanbul').Report.create('none');
+ *
+ *
+ * @class NoneReport
+ * @extends Report
+ * @module report
+ * @constructor
+ */
 function NoneReport() {
@@ -14,6 +30,11 @@ Report.call(this);
 NoneReport.TYPE = 'none';
+util.inherits(NoneReport, Report);
 
 Report.mix(NoneReport, {
+    synopsis: function () {
+        return 'Does nothing. Useful to override default behavior and suppress reporting entirely';
+    },
     writeReport: function (/* collector, sync */) {
         //noop
+        this.emit('done');
     }
@@ -20,0 +41,0 @@ });

lib/report/teamcity.js

@@ -7,2 +7,3 @@ /*
 var path = require('path'),
+    util = require('util'),
     mkdirp = require('mkdirp'),
@@ -23,2 +24,3 @@ fs = require('fs'),
  * @extends Report
+ * @module report
  * @constructor
@@ -37,2 +39,3 @@ * @param {Object} opts optional
 TeamcityReport.TYPE = 'teamcity';
+util.inherits(TeamcityReport, Report);
 
@@ -44,2 +47,8 @@ function lineForKey(value, teamcityVar) {
 Report.mix(TeamcityReport, {
+    synopsis: function () {
+        return 'report with system messages that can be interpreted with TeamCity';
+    },
+    getDefaultConfig: function () {
+        return { file: null };
+    },
     writeReport: function (collector /*, sync */) {
@@ -78,3 +87,2 @@ var summaries = [],
             mkdirp.sync(this.dir);
-            console.log(path.join(this.dir, this.file));
             fs.writeFileSync(path.join(this.dir, this.file), text, 'utf8');
@@ -84,2 +92,3 @@ } else {
         }
+        this.emit('done');
     }
@@ -86,0 +95,0 @@ });

lib/report/text-summary.js

@@ -7,2 +7,3 @@ /*
 var path = require('path'),
+    util = require('util'),
     mkdirp = require('mkdirp'),
@@ -24,2 +25,3 @@ defaults = require('./common/defaults'),
  * @extends Report
+ * @module report
  * @constructor
@@ -39,2 +41,3 @@ * @param {Object} opts optional
 TextSummaryReport.TYPE = 'text-summary';
+util.inherits(TextSummaryReport, Report);
 
@@ -57,2 +60,8 @@ function lineForKey(summary, key, watermarks) {
 Report.mix(TextSummaryReport, {
+    synopsis: function () {
+        return 'text report that prints a coverage summary across all files, typically to console';
+    },
+    getDefaultConfig: function () {
+        return { file: null };
+    },
     writeReport: function (collector /*, sync */) {
@@ -84,2 +93,3 @@ var summaries = [],
         }
+        this.emit('done');
     }
@@ -86,0 +96,0 @@ });

lib/report/text.js

@@ -8,2 +8,3 @@ /*
     mkdirp = require('mkdirp'),
+    util = require('util'),
     fs = require('fs'),
@@ -29,2 +30,3 @@ defaults = require('./common/defaults'),
  * @extends Report
+ * @module report
  * @constructor
@@ -34,3 +36,3 @@ * @param {Object} opts optional
  * @param {String} [opts.file] the filename for the report. When omitted, the report is written to console
- * @param {Number} [opts.maxcols] the max column width of the report. By default, the width of the report is adjusted based on the length of the paths
+ * @param {Number} [opts.maxCols] the max column width of the report. By default, the width of the report is adjusted based on the length of the paths
  *              to be reported.
@@ -49,2 +51,3 @@ */
 TextReport.TYPE = 'text';
+util.inherits(TextReport, Report);
 
@@ -173,2 +176,8 @@ function padding(num, ch) {
 Report.mix(TextReport, {
+    synopsis: function () {
+        return 'text report that prints a coverage line for every file, typically to console';
+    },
+    getDefaultConfig: function () {
+        return { file: null, maxCols: 0 };
+    },
     writeReport: function (collector /*, sync */) {
@@ -204,2 +213,3 @@ var summarizer = new TreeSummarizer(),
         }
+        this.emit('done');
     }
@@ -206,0 +216,0 @@ });

lib/store/fslookup.js

@@ -25,2 +25,3 @@ /*
  * @extends Store
+ * @module store
  * @constructor
@@ -27,0 +28,0 @@ */

lib/store/index.js

@@ -38,4 +38,5 @@ /*
  * @constructor
- * @protected
+ * @module store
  * @param {Object} options Optional. The options supported by a specific store implementation.
+ * @main store
  */
@@ -42,0 +43,0 @@ function Store(/* options */) {}

lib/store/memory.js

@@ -20,2 +20,3 @@ /*
  * @extends Store
+ * @module store
  * @constructor
@@ -22,0 +23,0 @@ */

lib/store/tmp.js

@@ -29,2 +29,3 @@ /*
  * @extends Store
+ * @module store
  * @param {Object} opts Optional.
@@ -31,0 +32,0 @@ * @param {String} [opts.tmp] a pre-existing directory to use as the `tmp` directory. When not specified, a random directory

lib/util/file-writer.js

@@ -107,3 +107,26 @@ /*
 });
-
+/**
+ * a concrete writer implementation that can write files synchronously or
+ * asynchronously based on the constructor argument passed to it.
+ *
+ * Usage
+ * -----
+ *
+ *      var sync = true,
+ *          fileWriter = new require('istanbul').FileWriter(sync);
+ *
+ *      fileWriter.on('done', function () { console.log('done'); });
+ *      fileWriter.copyFile('/foo/bar.jpg', '/baz/bar.jpg');
+ *      fileWriter.writeFile('/foo/index.html', function (contentWriter) {
+ *          contentWriter.println('<html>');
+ *          contentWriter.println('</html>');
+ *      });
+ *      fileWriter.done(); // will emit the `done` event when all files are written
+ *
+ * @class FileWriter
+ * @extends Writer
+ * @module io
+ * @param sync
+ * @constructor
+ */
 function FileWriter(sync) {
@@ -110,0 +133,0 @@ Writer.call(this);

lib/util/writer.js

@@ -15,2 +15,9 @@ /*
 
+/**
+ * abstract interfaces for writing content
+ * @class ContentWriter
+ * @module io
+ * @main io
+ * @constructor
+ */
 //abstract interface for writing content
@@ -21,9 +28,27 @@ function ContentWriter() {
 ContentWriter.prototype = {
+    /**
+     * writes the specified string as-is
+     * @method write
+     * @param {String} str the string to write
+     */
     write: /* istanbul ignore next: abstract method */ function (/* str */) {
         throw new Error('write: must be overridden');
     },
+    /**
+     * writes the specified string with a newline at the end
+     * @method println
+     * @param {String} str the string to write
+     */
     println: function (str) { this.write(str); this.write('\n'); }
 };
 
-//abstract interface for writing files and assets
+/**
+ * abstract interface for writing files and assets. The caller is expected to
+ * call `done` on the writer after it has finished writing all the required
+ * files. The writer is an event-emitter that emits a `done` event when `done`
+ * is called on it *and* all files have successfully been written.
+ *
+ * @class Writer
+ * @constructor
+ */
 function Writer() {
@@ -38,4 +63,5 @@ EventEmitter.call(this);
      * allows writing content to a file using a callback that is passed a content writer
-     * @param file the name of the file to write
-     * @param callback the callback that is called as `callback(contentWriter)`
+     * @method writeFile
+     * @param {String} file the name of the file to write
+     * @param {Function} callback the callback that is called as `callback(contentWriter)`
      */
@@ -47,4 +73,5 @@ writeFile: /* istanbul ignore next: abstract method */ function (/* file, callback */) {
      * copies a file from source to destination
-     * @param source the file to copy, found on the file system
-     * @param dest the destination path
+     * @method copyFile
+     * @param {String} source the file to copy, found on the file system
+     * @param {String} dest the destination path
      */
@@ -58,2 +85,3 @@ copyFile: /* istanbul ignore next: abstract method */ function (/* source, dest */) {
      * and it is truly done.
+     * @method done
      */
@@ -60,0 +88,0 @@ done: /* istanbul ignore next: abstract method */ function () {

package.json

 {
     "name": "istanbul",
-    "version": "0.2.16",
+    "version": "0.3.0",
     "description": "Yet another JS code coverage tool that computes statement, line, function and branch coverage with module loader hooks to transparently add coverage when running tests. Supports all JS coverage use cases including unit tests, server side functional tests and browser tests. Built for scale",
@@ -64,3 +64,4 @@ "keywords": [ "coverage", "code coverage", "JS code coverage", "JS coverage" ],
         "resolve": "0.7.x",
-        "js-yaml": "3.x"
+        "js-yaml": "3.x",
+        "once": "1.x"
     },
@@ -67,0 +68,0 @@ "devDependencies": {

README.md

@@ -1,3 +0,2 @@
-Istanbul - a JS code coverage tool written in JS
-================================================
+## Istanbul - a JS code coverage tool written in JS
 
@@ -10,24 +9,35 @@ [![Build Status](https://secure.travis-ci.org/gotwarlost/istanbul.png)](http://travis-ci.org/gotwarlost/istanbul)
 
-Features
---------
+* [Features and use cases](#features)
+* [Getting started and configuration](#getting-started)
+* [The command line](#the-command-line)
+* [Ignoring code for coverage](#ignoring-code-for-coverage)
+* [API](#api)
+* [Changelog](https://github.com/gotwarlost/istanbul/blob/master/CHANGELOG.md)
+* [License and credits](#license)
 
+### Features
+
 * All-javascript instrumentation library that tracks **statement, branch,
-and function coverage** and reverse-engineers **line coverage** with 100% fidelity.
+and function coverage**.
 * **Module loader hooks** to instrument code on the fly
 * **Command line tools** to run node unit tests "with coverage turned on" and no cooperation
 whatsoever from the test runner
-* **HTML**, **LCOV**, **Cobertura**, **TeamCity**, and **Clover** reporting.
-* Ability to use as **middleware** when serving JS files that need to be tested on the browser.
+* Multiple report formats: **HTML**, **LCOV**, **Cobertura** and more.
+* Ability to use as [middleware](https://github.com/gotwarlost/istanbul-middleware) when serving JS files that need to be tested on the browser.
 * Can be used on the **command line** as well as a **library**
 * Based on the awesome `esprima` parser and the equally awesome `escodegen` code generator
-* Well-tested on node 0.4.x, 0.6.x, 0.8.x and the browser (instrumentation library only)
+* Well-tested on node (prev, current and next versions) and the browser (instrumentation library only)
 
-Installing
-----------
+### Use cases
 
+Supports the following use cases and more
+
+* transparent coverage of nodejs unit tests
+* instrumentation/ reporting of files in batch mode for browser tests
+* Server side code coverage for nodejs by embedding it as [custom middleware](https://github.com/gotwarlost/istanbul-middleware)
+
+### Getting started
+
     $ npm install -g istanbul
 
-Getting started
----------------
-
 The best way to see it in action is to run node unit tests. Say you have a test
@@ -45,27 +55,12 @@ script `test.js` that runs all tests for your node project without coverage.
 
-* [HTML reports](http://gotwarlost.github.com/istanbul/public/coverage/lcov-report/index.html)
-* [Standard LCOV reports](http://gotwarlost.github.com/istanbul/public/coverage/std-lcov/index.html) (using `genhtml` on the lcov trace file)
+[HTML reports](http://gotwarlost.github.com/istanbul/public/coverage/lcov-report/index.html)
 
-Use cases
----------
 
-Supports the following use cases and more
+### Configuring
 
-* transparent coverage of nodejs unit tests
-* ability to use in an <code>npm test</code> script for conditional coverage
-* instrumentation of files in batch mode for browser tests (using yeti for example)
-* Server side code coverage for nodejs by embedding it as custom middleware
+Drop a `.istanbul.yml` file at the top of the source tree to configure istanbul.
+`istanbul help config` tells you more about the config file format.
 
+### The command line
 
-Ignoring code for coverage
---------------------------
-
-* Skip an `if` or `else` path with `/* istanbul ignore if */` or `/* istanbul ignore else */` respectively.
-* For all other cases, skip the next 'thing' in the source with: `/* istanbul ignore next */`
-
-See [ignoring-code-for-coverage.md](ignoring-code-for-coverage.md) for the spec.
-
-The command line
-----------------
-
     $ istanbul help
@@ -75,4 +70,7 @@
 
-Usage: istanbul help <command>
+```
+Usage: istanbul help config | <command>
 
+`config` provides help with istanbul configuration
+
 Available commands are:
@@ -106,5 +104,5 @@
 Command names can be abbreviated as long as the abbreviation is unambiguous
+```
 
-The `cover` command
--------------------
+#### The `cover` command
 
@@ -118,6 +116,7 @@ $ istanbul cover my-test-script.js -- my test args
 
-The `cover` command can also be passed an optional `--handle-sigint` flag to enable writing reports when a user triggers a manual SIGINT of the process that is being covered. This can be useful when you are generating coverage for a long lived process.
+The `cover` command can also be passed an optional `--handle-sigint` flag to 
+enable writing reports when a user triggers a manual SIGINT of the process that is 
+being covered. This can be useful when you are generating coverage for a long lived process.
 
-The `test` command
--------------------
+#### The `test` command
 
@@ -127,70 +126,71 @@ The `test` command has almost the same behavior as the `cover` command, except that
 
-This helps you set up conditional coverage for tests. In this case you would
-have a `package.json` that looks as follows.
+**This command is deprecated** since the latest versions of npm do not seem to
+set the `npm_config_coverage` variable.
 
-    {
-        "name": "my-awesome-lib",
-        "version": "1.0",
-        "script": {
-            "test": "istanbul test my-test-file.js"
-        }
-    }
+#### The `instrument` command
 
-Then:
+Instruments a single JS file or an entire directory tree and produces an output 
+directory tree with instrumented code. This should not be required for running node 
+unit tests but is useful for tests to be run on the browser.
 
-    $ npm test # will run tests without coverage
+#### The `report` command
 
-And:
+Writes reports using `coverage*.json` files as the source of coverage information. 
+Reports are available in multiple formats and can be individually configured
+using the istanbul config file. See `istanbul help report` for more details.
 
-    $ npm test --coverage # will run tests with coverage
+#### The `check-coverage` command
 
-**Note**: This needs `node 0.6` or better to work. `npm` for `node 0.4.x` does
-not support the `--coverage` flag.
+Checks the coverage of statements, functions, branches, and lines against the
+provided thresholds. Positive thresholds are taken to be the minimum percentage
+required and negative numbers are taken to be the number of uncovered entities
+allowed.
 
-The `instrument` command
-------------------------
+### Ignoring code for coverage
 
-Instruments a single JS file or an entire directory tree and produces an output directory tree with instrumented code. This should not be required for running node unit tests but is useful for tests to be run on the browser (using `yeti` for example).
+* Skip an `if` or `else` path with `/* istanbul ignore if */` or `/* istanbul ignore else */` respectively.
+* For all other cases, skip the next 'thing' in the source with: `/* istanbul ignore next */`
 
-The `report` command
--------------------
+See [ignoring-code-for-coverage.md](ignoring-code-for-coverage.md) for the spec.
 
-Writes reports using `coverage*.json` files as the source of coverage information. Reports are available in the following formats:
 
-* html - produces a bunch of HTML files with annotated source code
-* lcovonly - produces an lcov.info file
-* lcov - produces html + lcov files. This is the default format
-* cobertura - produces a cobertura-coverage.xml file for easy Hudson integration
-* text-summary - produces a compact text summary of coverage, typically to console
-* text - produces a detailed text table with coverage for all files
-* teamcity - produces service messages to report code coverage to TeamCity
-* clover - produces a clover.xml file to integrate with Atlassian Clover
+### API
 
-Additional report formats may be plugged in at the library level.
+All the features of istanbul can be accessed as a library.
+ 
+#### Instrument code
 
-The `check-coverage` command
-----------------------------
+```javascript
+    var instrumenter = new require('istanbul').Instrumenter();
+    
+    var generatedCode = instrumenter.instrumentSync('function meaningOfLife() { return 42; }',
+        'filename.js');
+```
 
-Checks the coverage of statements, functions, branches, and lines against the
-provided thresholds. Postive thresholds are taken to be the minimum percentage
-required and negative numbers are taken to be the number of uncovered entities
-allowed.
+#### Generate reports given a bunch of coverage JSON objects
 
-Library usage
--------------
+```javascript
+    var istanbul = require('istanbul'), 
+        collector = new istanbul.Collector(),
+        reporter = new istanbul.Reporter(),
+        sync = false;
 
-All the features of istanbul can be accessed as a library using its [public API](http://gotwarlost.github.com/istanbul/public/apidocs/index.html)
+    collector.add(obj1);
+    collector.add(obj2); //etc.
 
-Changelog
----------
+    reporter.add('text');
+    reporter.addAll([ 'lcov', 'clover' ]);
+    reporter.writeReport(collector, sync, function () {
+        console.log('All reports generated');
+    });
+```
 
-Changelog has been moved [here](https://github.com/gotwarlost/istanbul/blob/master/CHANGELOG.md).
+For the gory details consult the [public API](http://gotwarlost.github.com/istanbul/public/apidocs/index.html)
 
-License
--------
 
+### License
+
 istanbul is licensed under the [BSD License](http://github.com/gotwarlost/istanbul/raw/master/LICENSE).
 
-Third-party libraries
----------------------
+### Third-party libraries
 
@@ -209,2 +209,3 @@ The following third-party libraries are used by this module:
 * nopt: https://github.com/isaacs/nopt - for option parsing
+* once: https://github.com/isaacs/once - to ensure callbacks are called once
 * resolve: https://github.com/substack/node-resolve - for resolving a post-require hook module name into its main file.
@@ -216,4 +217,3 @@ * rimraf - https://github.com/isaacs/rimraf - dev dependency for unit tests
 
-Inspired by
------------
+### Inspired by
 
@@ -223,4 +223,3 @@ * YUI test coverage - https://github.com/yui/yuitest - the grand-daddy of JS coverage tools. Istanbul has been specifically designed to offer an alternative to this library with an easy migration path.
 
-Shout out to
-------------
+### Shout out to
 
@@ -230,5 +229,6 @@ * [mfncooper](https://github.com/mfncooper) - for great brainstorming discussions
 
-Why the funky name?
--------------------
+### Why the funky name?
 
-Since all the good ones are taken. Comes from the loose association of ideas across coverage, carpet-area coverage, the country that makes good carpets and so on...
+Since all the good ones are taken. Comes from the loose association of ideas across 
+coverage, carpet-area coverage, the country that makes good carpets and so on...
+

New alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Fixed alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

280795

increased by9.13%

Number of package files

53

increased by1.92%

Lines of code

5878

increased by13.06%

Worsened metrics

Dependency count

13

increased by8.33%

Dependency changes

• + Addedonce@1.x

• + Addedonce@1.4.0(transitive)

• + Addedwrappy@1.0.2(transitive)