Feature: Evaluate Logical Truthiness

.gitignore

@@ -4,7 +4,6 @@ node_modules/*
 packages/*/node_modules/*
 coverage
 npm-debug.log
-docs/
 .nyc_output
 dist
 lerna-debug.log

docs/raw-output.md

@@ -0,0 +1,85 @@
+# Coverage Format for opts.coverageVariable or coverage-final.json
+
+This file describes the output raw output format of the IstanbulJS libraries.
+
+## Format
+
+-   `output` **[Object][1]** root.
+    -   `output.<absolute path>` **[Object][1]** coverage object for a file.
+        -   `<absolute path>.path` **[string][2]** the absolute path of the covered object.
+        -   `<absolute path>.statementMap` **[Object][1]** the object that maps statements to code.
+            -   `statementMap.<index>` **[Object][1]** the statement's location object; 0-based.
+                -   `<index>.start` **[Object][1]** the statement's start location object.
+                    -   `start.line` **[number][3]** the statement's start location line number.
+                    -   `start.column` **[number][3]** the statement's start location column number.
+                -   `<index>.end` **[Object][1]** the statement's end location object.
+                    -   `end.line` **[number][3]** the statement's end location line number.
+                    -   `end.column` **[number][3]** the statement's end location column number.
+        -   `<absolute path>.fnMap` **[Object][1]** the object that maps functions to code.
+            -   `fnMap.<index>` **[Object][1]** the function's map object; 0-based.
+                -   `<index>.name` **[string][2]** the function's name.
+                -   `<index>.line` **[number][3]** the function declaration start location line number.
+                -   `<index>.decl` **[Object][1]** the function declaration location object.
+                    -   `decl.start` **[Object][1]** the function declaration start location object.
+                        -   `start.line` **[number][3]** the function declaration start location line number.
+                        -   `start.column` **[number][3]** the function declaration start location column number.
+                    -   `decl.end` **[Object][1]** the function declaration end location object.
+                        -   `end.line` **[number][3]** the function declaration end location line number.
+                        -   `end.column` **[number][3]** the function declaration end location column number.
+                -   `<index>.loc` **[Object][1]** the function body location object.
+                    -   `loc.start` **[Object][1]** the function body start location object.
+                        -   `start.line` **[number][3]** the function body start location line number.
+                        -   `start.column` **[number][3]** the function body start location column number.
+                    -   `loc.end` **[Object][1]** the function body end location object.
+                        -   `end.line` **[number][3]** the function body end location line number.
+                        -   `end.column` **[number][3]** the function body end location column number.
+        -   `<absolute path>.branchMap` **[Object][1]** the object that maps branches to code.
+            -   `branchMap.<index>` **[Object][1]** the branch map object; 0-based.
+                -   `<index>.line` **[number][3]** the branch declaration start location line number.
+                -   `<index>.type` **[string][2]** the branch type; see [branch types][5].
+                -   `<index>.loc` **[Object][1]** the branch location object.
+                    -   `loc.start` **[Object][1]** the branch start location object.
+                        -   `start.line` **[number][3]** the branch start location line number.
+                        -   `start.column` **[number][3]** the branch start location column number.
+                    -   `loc.end` **[Object][1]** the branch end location object.
+                        -   `end.line` **[number][3]** the branch end location line number.
+                        -   `end.column` **[number][3]** the branch end location column number.
+                -   `<index>.locations` **[Array][4]** the location objects for component branches or binary expressions.
+                    -   `locations[index]` **[Object][1]** the location object for the component branch or binary expression.
+                        -   `locations[index].start` **[Object][1]** the branch component start location object. (`{}` for if branch without else)
+                            -   `start.line` **[number][3]** the branch component start location line number.
+                            -   `start.column` **[number][3]** the branch component start location column number.
+                        -   `locations[index].end` **[Object][1]** the branch component end location object. (`{}` for if branch without else)
+                            -   `end.line` **[number][3]** the branch component end location line number.
+                            -   `end.column` **[number][3]** the branch component end location column number.
+        -   `<absolute path>.s` **[Object][1]** the object that reports the aggregated statement-level counters.
+            -   `s.<index>` **[number][3]** The aggregated statement-level counter; 0-based.
+        -   `<absolute path>.f` **[Object][1]** the object that reports the aggregated function-level counters.
+            -   `f.<index>` **[number][3]** The aggregated function-level counter; 0-based.
+        -   `<absolute path>.b` **[Object][1]** the object that reports the aggregated branch-level counters.
+            -   `b.<index>` **[Array][4]** The array for branch component counters.
+                -   `<index>[component index]` **[number][3]** The aggregated branch component counter.
+        -   `<absolute path>.bT` **[Object][1]** the object that reports the aggregated branch-level, evaluated logical truthiness counters.
+            -   `bT.<index>` **[Array][4]** The array for branch component truthiness counters.
+                -   `<index>[component index]` **[number][3]** The aggregated branch component counter. Only evaluated with the `reportLogic=true` option. (optional, default `0`)
+        -   `<absolute path>._coverageSchema` **[string][2]** the coverage schema.
+        -   `<absolute path>.hash` **[string][2]** the hash.
+        -   `<absolute path>.contentHash` **[string][2]** the hash of the files. (only in the .json report)
+
+## Branch Types
+
+- `if`  an if statement; can also be `else if`.
+- `binary-expr`  a logical expression with a binary operand. e.g.: `x && y`
+- `cond-expr`  a ternary expression. e.g.: `x ? y : z`
+- `switch`  a switch statement.
+- `default-arg`  assignment logic. e.g.: `x &= y`
+
+[1]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object
+
+[2]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String
+
+[3]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number
+
+[4]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array
+
+[5]: #branch-types

packages/istanbul-lib-coverage/lib/coverage-summary.js

@@ -19,7 +19,8 @@ function blankSummary() {
         lines: empty(),
         statements: empty(),
         functions: empty(),
-        branches: empty()
+        branches: empty(),
+        branchesTrue: empty()
     };
 }
 
@@ -94,7 +95,8 @@ dataProperties(CoverageSummary, [
     'lines',
     'statements',
     'functions',
-    'branches'
+    'branches',
+    'branchesTrue'
 ]);
 
 module.exports = {

packages/istanbul-lib-coverage/lib/file-coverage.js

@@ -17,7 +17,8 @@ function emptyCoverage(filePath) {
         branchMap: {},
         s: {},
         f: {},
-        b: {}
+        b: {},
+        bT: {}
     };
 }
 
@@ -31,7 +32,8 @@ function assertValidObject(obj) {
         obj.branchMap &&
         obj.s &&
         obj.f &&
-        obj.b;
+        obj.b &&
+        obj.bT;
     if (!valid) {
         throw new Error(
             'Invalid file coverage object, missing keys, found:' +
@@ -158,6 +160,7 @@ class FileCoverage {
         return ret;
     }
 
+    // STARK TODO
     /**
      * returns a map of branch coverage by source line number.
      * @returns {Object} an object keyed by line number. Each object
@@ -192,6 +195,7 @@ class FileCoverage {
         return this.data;
     }
 
+    // STARK TODO
     /**
      * merges a second coverage object into this one, updating hit counts
      * @param {FileCoverage} other - the coverage object to be merged into this one.
@@ -238,6 +242,15 @@ class FileCoverage {
         );
         this.data.b = hits;
         this.data.branchMap = map;
+
+        [hits, map] = mergeProp(
+          this.bT,
+          this.branchMap,
+          other.bT,
+          other.branchMap,
+          keyFromLocationsProp
+      );
+      this.data.bT = hits;
     }
 
     computeSimpleTotals(property) {
@@ -256,8 +269,8 @@ class FileCoverage {
         return ret;
     }
 
-    computeBranchTotals() {
-        const stats = this.b;
+    computeBranchTotals(property) {
+        const stats = this[property];
         const ret = { total: 0, covered: 0, skipped: 0 };
 
         Object.values(stats).forEach(branches => {
@@ -276,6 +289,7 @@ class FileCoverage {
         const statements = this.s;
         const functions = this.f;
         const branches = this.b;
+        const branchesTrue = this.bT;
         Object.keys(statements).forEach(s => {
             statements[s] = 0;
         });
@@ -285,6 +299,9 @@ class FileCoverage {
         Object.keys(branches).forEach(b => {
             branches[b].fill(0);
         });
+        Object.keys(branchesTrue).forEach(bT => {
+          branchesTrue[bT].fill(0);
+        });
     }
 
     /**
@@ -296,7 +313,8 @@ class FileCoverage {
         ret.lines = this.computeSimpleTotals('getLineCoverage');
         ret.functions = this.computeSimpleTotals('f', 'fnMap');
         ret.statements = this.computeSimpleTotals('s', 'statementMap');
-        ret.branches = this.computeBranchTotals();
+        ret.branches = this.computeBranchTotals('b');
+        ret.branchesTrue = this.computeBranchTotals('bT');
         return new CoverageSummary(ret);
     }
 }
@@ -310,6 +328,7 @@ dataProperties(FileCoverage, [
     's',
     'f',
     'b',
+    'bT',
     'all'
 ]);
 

packages/istanbul-lib-coverage/package.json

@@ -1,6 +1,6 @@
 {
   "name": "istanbul-lib-coverage",
-  "version": "3.0.1",
+  "version": "3.1.0",
   "description": "Data library for istanbul coverage objects",
   "author": "Krishnan Anantheswaran <kananthmail-github@yahoo.com>",
   "main": "index.js",

packages/istanbul-lib-coverage/test/file.test.js

@@ -12,6 +12,7 @@ describe('coverage summary', () => {
         assert.ok(cs.lines);
         assert.ok(cs.functions);
         assert.ok(cs.branches);
+        assert.ok(cs.branchesTrue);
     });
 
     it('allows another summary in constructor', () => {
@@ -70,13 +71,15 @@ describe('coverage summary', () => {
             statements: basic(),
             functions: basic(),
             lines: basic(),
-            branches: empty()
+            branches: empty(),
+            branchesTrue: empty()
         });
         const cs2 = new CoverageSummary({
             statements: basic(),
             functions: basic(),
             lines: basic(),
-            branches: empty()
+            branches: empty(),
+            branchesTrue: empty()
         });
         cs2.statements.covered = 5;
         cs1.merge(cs2);
@@ -87,6 +90,7 @@ describe('coverage summary', () => {
             pct: 90
         });
         assert.equal(cs1.branches.pct, 100);
+        assert.equal(cs1.branchesTrue.pct, 100);
         const data = JSON.parse(JSON.stringify(cs1));
         assert.deepEqual(data.statements, {
             total: 10,
@@ -95,6 +99,7 @@ describe('coverage summary', () => {
             pct: 90
         });
         assert.equal(data.branches.pct, 100);
+        assert.equal(data.branchesTrue.pct, 100);
     });
 
     it('isEmpty() by default', () => {
@@ -124,6 +129,7 @@ describe('base coverage', () => {
         assert.ok(bc.s);
         assert.ok(bc.f);
         assert.ok(bc.b);
+        assert.ok(bc.bT);
         assert.ok(bc.getLineCoverage());
         assert.equal(bc.path, '/path/to/file');
     });
@@ -183,6 +189,9 @@ describe('base coverage', () => {
             },
             b: {
                 0: [0, 0]
+            },
+            bT: {
+                0: [0, 0]
             }
         });
         const clone = function(obj) {
@@ -195,10 +204,12 @@ describe('base coverage', () => {
         c1.s[0] = 1;
         c1.f[0] = 1;
         c1.b[0][0] = 1;
-
+        c1.bT[0][0] = 1;
+
         c2.s[1] = 1;
         c2.f[0] = 1;
         c2.b[0][1] = 2;
+        c2.bT[0][1] = 2;
         summary = c1.toSummary();
         assert.ok(summary instanceof CoverageSummary);
         assert.deepEqual(summary.statements, {
@@ -225,6 +236,12 @@ describe('base coverage', () => {
             skipped: 0,
             pct: 50
         });
+        assert.deepEqual(summary.branchesTrue, {
+            total: 2,
+            covered: 1,
+            skipped: 0,
+            pct: 50
+        });
 
         c1.merge(c2);
         summary = c1.toSummary();
@@ -252,6 +269,12 @@ describe('base coverage', () => {
             skipped: 0,
             pct: 100
         });
+        assert.deepEqual(summary.branchesTrue, {
+            total: 2,
+            covered: 2,
+            skipped: 0,
+            pct: 100
+        });
 
         assert.equal(c1.s[0], 1);
         assert.equal(c1.s[1], 1);
@@ -300,6 +323,9 @@ describe('base coverage', () => {
             },
             b: {
                 1: [0, 0]
+            },
+            bT: {
+                1: [0, 0]
             }
         });
         const clone = function(obj) {
@@ -313,6 +339,7 @@ describe('base coverage', () => {
                 data.s[1] = 1;
                 data.f[1] = 1;
                 data.b[1][0] = 1;
+                data.bT[1][0] = 1;
             }
 
             return new FileCoverage(data);
@@ -369,12 +396,16 @@ describe('base coverage', () => {
             },
             b: {
                 1: [1, 50]
+            },
+            bT: {
+                1: [1, 50]
             }
         });
         fc.resetHits();
         assert.deepEqual({ 1: 0, 2: 0, 3: 0, 4: 0 }, fc.s);
         assert.deepEqual({ 1: 0 }, fc.f);
         assert.deepEqual({ 1: [0, 0] }, fc.b);
+        assert.deepEqual({ 1: [0, 0] }, fc.bT);
     });
 
     it('returns uncovered lines', () => {
@@ -398,6 +429,7 @@ describe('base coverage', () => {
             branchMap: {},
             s: { 1: 0, 2: 1, 3: 0 },
             b: {},
+            bT: {},
             f: {}
         });
         assert.deepEqual(['2'], c.getUncoveredLines());
@@ -417,6 +449,10 @@ describe('base coverage', () => {
                 1: [1, 0],
                 2: [0, 0, 0, 1]
             },
+            bT: {
+                1: [1, 0],
+                2: [0, 0, 0, 1]
+            },
             f: {}
         });
         const bcby = c.getBranchCoverageByLine();
@@ -457,6 +493,10 @@ describe('base coverage', () => {
                 1: [1, 0],
                 2: [0, 0, 0, 1]
             },
+            bT: {
+                1: [1, 0],
+                2: [0, 0, 0, 1]
+            },
             f: {}
         });
         const bcby = c.getBranchCoverageByLine();