monocart-coverage-reports 2.0.7 → 2.0.9

package/README.md

@@ -10,6 +10,7 @@
 * [Default Options](#default-options)
 * [Available Reports](#available-reports)
 * [Multiprocessing Support](#multiprocessing-support)
+* [onEnd Hook](#onend-hook)
 * [Compare Reports](#compare-reports)
 * [Compare Workflows](#compare-workflows)
 * [Collecting Istanbul Coverage Data](#collecting-istanbul-coverage-data)
@@ -19,7 +20,9 @@
 * [How to convert V8 to Istanbul](#how-to-convert-v8-to-istanbul)
     - [Using `v8-to-istanbul`](#using-v8-to-istanbul)
     - [How Monocart Works](#how-monocart-works)
+* [Ignoring Uncovered Lines](#ignoring-uncovered-lines)
 * [Chromium Coverage API](#chromium-coverage-api)
+* [V8 Coverage Data Format](#v8-coverage-data-format)
 * [Istanbul Introduction](#istanbul-introduction)
 * [Thanks](#thanks)
 
@@ -128,11 +131,42 @@ const coverageResults = await coverageReport.generate();
 console.log(coverageResults.summary);
 ```
 
+## onEnd Hook
+For example, checking thresholds:
+```js
+const EC = require('eight-colors');
+const coverageOptions = {
+    name: 'My Coverage Report',
+    outputDir: './coverage-reports',
+    onEnd: (coverageResults) => {
+        const thresholds = {
+            bytes: 80,
+            lines: 60
+        };
+        console.log('check thresholds ...', thresholds);
+        const errors = [];
+        const { summary } = coverageResults;
+        Object.keys(thresholds).forEach((k) => {
+            const pct = summary[k].pct;
+            if (pct < thresholds[k]) {
+                errors.push(`Coverage threshold for ${k} (${pct} %) not met: ${thresholds[k]} %`);
+            }
+        });
+        if (errors.length) {
+            const errMsg = errors.join('\n');
+            console.log(EC.red(errMsg));
+            // throw new Error(errMsg);
+            // process.exit(1);
+        }
+    }
+}
+```
+
 ## Compare Reports
 | | Istanbul | V8 | V8 to Istanbul |
 | :--------------| :------ | :------ | :----------------------  |
-| Coverage data | Istanbul (Object) | V8 (Array) | V8 (Array) |
-| Output | [Istanbul reports](#istanbul-reports) | [V8 reports](#v8-reports)  | [Istanbul reports](#istanbul-reports) |
+| Coverage data | [Istanbul](https://github.com/gotwarlost/istanbul/blob/master/coverage.json.md) (Object) | [V8](#v8-coverage-data-format) (Array) | [V8](#v8-coverage-data-format) (Array) |
+| Output | [Istanbul reports](#available-reports) | [V8 reports](#available-reports)  | [Istanbul reports](#available-reports) |
 | - Bytes | ❌ | ✅ | ❌ |
 | - Statements | ✅ | ❌ | ☑️❔ |
 | - Branches | ✅ | ☑️❔ | ☑️❔ |
@@ -166,8 +200,9 @@ console.log(coverageResults.summary);
 
 ## Collecting V8 Coverage Data
 - For source code: enable `sourcemap` and do not compress/minify:
-    - Webpack: with `source-map` [devtool](https://webpack.js.org/configuration/devtool/) and `development` [mode](https://webpack.js.org/configuration/mode/), example [webpack.config-v8.js](https://github.com/cenfun/monocart-coverage-reports/blob/main/test/webpack.config-v8.js)
-    - Rollup: [options](https://rollupjs.org/configuration-options/) `sourcemap: true`
+    - Webpack: build with `source-map` [devtool](https://webpack.js.org/configuration/devtool/) and `development` [mode](https://webpack.js.org/configuration/mode/), example [webpack.config-v8.js](https://github.com/cenfun/monocart-coverage-reports/blob/main/test/webpack.config-v8.js)
+    - Rollup: build with [options](https://rollupjs.org/configuration-options/) `sourcemap: true`
+    - Vite: build with [options](https://vitejs.dev/config/build-options.html) `sourcemap: true` and `minify: false` 
 - Browser (Chromium Only)
     > Collecting coverage data with [Chromium Coverage API](#chromium-coverage-api), see [example](https://github.com/cenfun/monocart-coverage-reports/blob/main/test/test-v8.js)
 - Node.js
@@ -179,12 +214,15 @@ console.log(coverageResults.summary);
     - Before running your Node.js application, set env `NODE_V8_COVERAGE`=`dir`. After the application runs and exits, the coverage data will be saved to the `dir` directory in JSON file format
     - Read the json file(s) from the `dir` and generate coverage report
     - example:
-    > cross-env NODE_V8_COVERAGE=`.temp/v8-coverage` node [./test/test-node-env.js](./test/test-node-env.js) && node [./test/generate-node-report.js](./test/generate-node-report.js)
+    > cross-env NODE_V8_COVERAGE=`.temp/v8-coverage-env` node [./test/test-node-env.js](./test/test-node-env.js) && node [./test/generate-node-report.js](./test/generate-node-report.js)
 
-- Using [V8](https://nodejs.org/docs/latest/api/v8.html#v8takecoverage) API
+- Using [V8](https://nodejs.org/docs/latest/api/v8.html#v8takecoverage) API + NODE_V8_COVERAGE
     - Writing the coverage started by NODE_V8_COVERAGE to disk on demand with `v8.takeCoverage()` and stopping with `v8.stopCoverage()`. 
     - example:
-    > cross-env NODE_V8_COVERAGE=`.temp/v8-coverage` node [./test/test-node-api.js](./test/test-node-api.js)
+    > cross-env NODE_V8_COVERAGE=`.temp/v8-coverage-api` node [./test/test-node-api.js](./test/test-node-api.js)
+
+- Using [foreground-child](https://github.com/tapjs/foreground-child) + NODE_V8_COVERAGE
+    - example: [./test/test-node-fgc.js](./test/test-node-fgc.js)
 
 - Using [Inspector](https://nodejs.org/docs/latest/api/inspector.html) API (or module [collect-v8-coverage](https://github.com/SimenB/collect-v8-coverage))
    - Connecting to the V8 inspector and enable V8 coverage.
@@ -199,24 +237,24 @@ console.log(coverageResults.summary);
 ## Using `entryFilter` and `sourceFilter` to filter the results for V8 report
 When V8 coverage data collected, it actually contains the data of all entry files, for example:
 ```
-1, dist/main.js
-2, dist/vendor.js
-3, dist/something-else.js
+dist/main.js
+dist/vendor.js
+dist/something-else.js
 ```
 We can use `entryFilter` to filter the entry files. For example, we should remove `vendor.js` and `something-else.js` if they are not in our coverage scope. 
 ```
-1, dist/main.js
+dist/main.js
 ```
 When inline or linked sourcemap exists to the entry file, the source files will be extracted from the sourcemap for the entry file, and the entry file will be removed if `logging` is not `debug`.
 ```
-1, src/index.js
-2, src/components/app.js
-3, node_modules/dependency/dist/dependency.js
+> src/index.js
+> src/components/app.js
+> node_modules/dependency/dist/dependency.js
 ```
 We can use `sourceFilter` to filter the source files. For example, we should remove `dependency.js` if it is not in our coverage scope.
 ```
-1, src/index.js
-2, src/components/app.js
+> src/index.js
+> src/components/app.js
 ```
 Example:
 ```js
@@ -243,15 +281,15 @@ And also there are some problems about counting the functions and branches:
 functions.forEach(block => {
     block.ranges.forEach((range, i) => {
         if (block.isBlockCoverage) {
-            // v8-to-istanbul: count range as branch here. 
+            // v8-to-istanbul: new CovBranch() 
             // Problem: not every block is branch, and the first block is actually function.
             if (block.functionName && i === 0) {
-                // v8-to-istanbul: count range as function here. 
-                // Problem: there is no function name if the function is anonymous or expression.
+                // v8-to-istanbul: new CovFunction()
+                // Problem: no anonymous function
             }
         } else if (block.functionName) {
-            // v8-to-istanbul: count range as function here. 
-            // Problem: same as above function.
+            // v8-to-istanbul: new CovFunction()
+            // Problem: no anonymous function
         }
     }
 });
@@ -272,12 +310,78 @@ We have removed `v8-to-istanbul` because of the two major problems and implement
 | LogicalExpression | ✔ Not Perfect | 
 | SwitchStatement | ✔ Not Perfect | 
 
+## Ignoring Uncovered Codes
+To ignore codes, use the special comment which starts with `v8 ignore `:
+- ignoring all until told
+```js
+/* v8 ignore start */
+function uncovered() {
+}
+/* v8 ignore stop */
+```
+- ignoring the next line or next N lines
+```js
+/* v8 ignore next */
+const os = platform === 'wind32' ? 'Windows' : 'Other';
+
+const os = platform === 'wind32' ? 'Windows' /* v8 ignore next */ : 'Other';
+
+/* v8 ignore next 3 */
+if (platform === 'linux') {
+    console.info('hello linux');
+}
+```
+
 ## Chromium Coverage API
 - [V8 coverage report](https://v8.dev/blog/javascript-code-coverage) - Native support for JavaScript code coverage to V8. (Chromium only)
 - [Puppeteer Coverage Class](https://pptr.dev/api/puppeteer.coverage)
 - [Playwright Coverage Class](https://playwright.dev/docs/api/class-coverage)
 - [DevTools Protocol for Coverage](https://chromedevtools.github.io/devtools-protocol/tot/Profiler/#method-startPreciseCoverage)
 
+## V8 Coverage Data Format
+```js
+// Coverage data for a source range.
+export interface CoverageRange {
+    // JavaScript script source offset for the range start.
+    startOffset: integer;
+    // JavaScript script source offset for the range end.
+    endOffset: integer;
+    // Collected execution count of the source range.
+    count: integer;
+}
+
+// Coverage data for a JavaScript function.
+/**
+ * @functionName can be an empty string.
+ * @ranges is always non-empty. The first range is called the "root range".
+ * @isBlockCoverage indicates if the function has block coverage information.
+    If this is false, it usually means that the functions was never called.
+    It seems to be equivalent to ranges.length === 1 && ranges[0].count === 0.
+*/
+export interface FunctionCoverage {
+    // JavaScript function name.
+    functionName: string;
+    // Source ranges inside the function with coverage data.
+    ranges: CoverageRange[];
+    // Whether coverage data for this function has block granularity.
+    isBlockCoverage: boolean;
+}
+
+// Coverage data for a JavaScript script.
+export interface ScriptCoverage {
+    // JavaScript script id.
+    scriptId: Runtime.ScriptId;
+    // JavaScript script name or url.
+    url: string;
+    // Functions contained in the script that has coverage data.
+    functions: FunctionCoverage[];
+}
+
+export type V8CoverageData = ScriptCoverage[];
+```
+see devtools-protocol [ScriptCoverage](https://chromedevtools.github.io/devtools-protocol/tot/Profiler/#type-ScriptCoverage)
+
+
 ## Istanbul Introduction
 - [Istanbul coverage report](https://istanbul.js.org/) - Instrumenting source codes and generating coverage reports
 - [babel-plugin-istanbul](https://github.com/istanbuljs/babel-plugin-istanbul)

package/lib/converter/ast.js

@@ -3,9 +3,8 @@ const {
 } = require('../packages/monocart-coverage-vendor.js');
 const Util = require('../utils/util.js');
 
-const {
-    createBranches, collectBranches, findInRanges
-} = require('./branches.js');
+const { createBranches, collectBranches } = require('./branches.js');
+const findInRanges = require('./find-in-ranges.js');
 
 const getFunctionRange = (start, end, state) => {
 

package/lib/converter/branches.js

@@ -1,40 +1,5 @@
 const Util = require('../utils/util.js');
-
-const quickFindRange = (position, ranges) => {
-    let start = 0;
-    let end = ranges.length - 1;
-    while (end - start > 1) {
-        const i = Math.floor((start + end) * 0.5);
-        const item = ranges[i];
-        if (position < item.startOffset) {
-            end = i;
-            continue;
-        }
-        if (position > item.endOffset) {
-            start = i;
-            continue;
-        }
-        return ranges[i];
-    }
-    // last two items, less is start
-    const endItem = ranges[end];
-    if (position < endItem.startOffset) {
-        return ranges[start];
-    }
-    return ranges[end];
-};
-
-
-const findInRanges = (start, end, ranges) => {
-    if (!Util.isList(ranges)) {
-        return;
-    }
-    const range = quickFindRange(start, ranges);
-    if (start >= range.startOffset && end <= range.endOffset) {
-        return range;
-    }
-};
-
+const findInRanges = require('./find-in-ranges.js');
 
 const findBranchBlock = (start, end, functionInfo) => {
     const { range } = functionInfo;
@@ -65,11 +30,11 @@ const createBranchGroup = (type, branchStart, parents, branchMap, functionInfo)
     const reverseParents = [].concat(parents).reverse();
     const group = {
         type,
-        loc: {
-            start: branchStart,
-            // could be updated if multiple locations
-            end: branchStart
-        },
+
+        start: branchStart,
+        // could be updated if multiple locations
+        end: branchStart,
+
         locations: [],
         reverseParents,
         functionInfo
@@ -81,7 +46,7 @@ const createBranchGroup = (type, branchStart, parents, branchMap, functionInfo)
 const addBranch = (group, node, locationMap, functionInfo) => {
     const { start, end } = node;
 
-    const branchStart = group.loc.start;
+    const branchStart = group.start;
 
     // the block is not exact correct, if there is a block wrapped
     // [x8]{ var a = b || [x4]c }, b is no block, but it can be found in x8 block
@@ -101,7 +66,7 @@ const addBranch = (group, node, locationMap, functionInfo) => {
     group.locations.push(branchInfo);
 
     // update group end
-    group.loc.end = end;
+    group.end = end;
 
     locationMap.set(start, branchInfo);
 
@@ -259,12 +224,12 @@ const createBranches = (ast, functionInfo, branchMap) => {
             // first, left a and right c
             // then, left a and right b
             if (prevLocation) {
-                const { loc, locations } = group;
+                const { locations } = group;
                 locations.sort((a, b) => {
                     return a.start - b.start;
                 });
                 // update group end after sorted
-                loc.end = locations[locations.length - 1].end;
+                group.end = locations[locations.length - 1].end;
             }
         },
 
@@ -307,7 +272,7 @@ const IfStatement = (group, parentCount, noBlockList, blockCount) => {
     if (!noBlockList.length) {
         return;
     }
-    // console.log(parentCount, 'uncovered list', noBlockList.length, group.loc.start);
+    // console.log(parentCount, 'uncovered list', noBlockList.length, group.start);
     let count = parentCount - blockCount;
     noBlockList.forEach((item) => {
         item.count = count;
@@ -326,7 +291,7 @@ const LogicalExpression = (group, parentCount, noBlockList, blockCount) => {
         item.count = count;
     });
 
-    // const start = group.loc.start;
+    // const start = group.start;
     // if (start > 7874 && start < 7922) {
     //     console.log(group.type, parentCount, 'locations', group.locations);
     // }
@@ -416,23 +381,32 @@ const collectBranches = (branchMap) => {
     // init branches
     const branches = [];
     branchMap.forEach((group) => {
+
+        // add start/end for none with group start/end
+        group.locations.forEach((item) => {
+            if (item.none) {
+                item.start = group.start;
+                item.end = group.end;
+            }
+        });
+
         branches.push({
             type: group.type,
-            loc: group.loc,
+            start: group.start,
+            end: group.end,
             locations: group.locations
         });
     });
 
     // sort branches
     branches.sort((a, b) => {
-        return a.loc.start - b.loc.start;
+        return a.start - b.start;
     });
 
     return branches;
 };
 
 module.exports = {
-    findInRanges,
     createBranches,
     collectBranches
 };