monocart-coverage-reports 2.0.9 → 2.1.0

package/README.md

@@ -3,6 +3,8 @@
 [![](https://img.shields.io/npm/v/monocart-coverage-reports)](https://www.npmjs.com/package/monocart-coverage-reports)
 [![](https://badgen.net/npm/dw/monocart-coverage-reports)](https://www.npmjs.com/package/monocart-coverage-reports)
 ![](https://img.shields.io/github/license/cenfun/monocart-coverage-reports)
+![](https://img.shields.io/github/actions/workflow/status/cenfun/monocart-coverage-reports/static.yml)
+
 
 > Code coverage tool to generate native [V8](https://v8.dev/blog/javascript-code-coverage) reports or [Istanbul](https://istanbul.js.org/) reports.
 
@@ -28,12 +30,12 @@
 
 ## Usage
 ```js
-const CoverageReport = require('monocart-coverage-reports');
+const MCR = require('monocart-coverage-reports');
 const options = {
     outputDir: './coverage-reports',
     reports: "v8"
 }
-const coverageReport = new CoverageReport(options);
+const coverageReport = MCR(options);
 await coverageReport.add(coverageData1);
 await coverageReport.add(coverageData2);
 const coverageResults = await coverageReport.generate();
@@ -80,7 +82,7 @@ console.log(coverageResults.summary);
 - `text-summary`
 
 ```js
-const CoverageReport = require('monocart-coverage-reports');
+const MCR = require('monocart-coverage-reports');
 const options = {
     outputDir: './coverage-reports',
     reports: [
@@ -95,7 +97,7 @@ const options = {
         'lcovonly'
     ]
 }
-const coverageReport = new CoverageReport(options);
+const coverageReport = MCR(options);
 ```
 
 ## Integration
@@ -107,26 +109,26 @@ const coverageReport = new CoverageReport(options);
 The data will be added to `[outputDir]/.cache`, and the cache will be removed after reports generated.
 - sub process 1
 ```js
-const CoverageReport = require('monocart-coverage-reports');
+const MCR = require('monocart-coverage-reports');
 const options = require('path-to/same-options.js');
-const coverageReport = new CoverageReport(options);
+const coverageReport = MCR(options);
 await coverageReport.add(coverageData1);
 ```
 
 - sub process 2
 ```js
-const CoverageReport = require('monocart-coverage-reports');
+const MCR = require('monocart-coverage-reports');
 const options = require('path-to/same-options.js');
-const coverageReport = new CoverageReport(options);
+const coverageReport = MCR(options);
 await coverageReport.add(coverageData2);
 ```
 
 - main process
 ```js
 // after all sub processes finished
-const CoverageReport = require('monocart-coverage-reports');
+const MCR = require('monocart-coverage-reports');
 const options = require('path-to/same-options.js');
-const coverageReport = new CoverageReport(options);
+const coverageReport = MCR(options);
 const coverageResults = await coverageReport.generate();
 console.log(coverageResults.summary);
 ```
@@ -221,9 +223,6 @@ const coverageOptions = {
     - example:
     > 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.
    - Taking coverage data and adding to the report after your application runs.
@@ -326,7 +325,7 @@ const os = platform === 'wind32' ? 'Windows' : 'Other';
 
 const os = platform === 'wind32' ? 'Windows' /* v8 ignore next */ : 'Other';
 
-/* v8 ignore next 3 */
+// v8 ignore next 3
 if (platform === 'linux') {
     console.info('hello linux');
 }
@@ -379,7 +378,7 @@ export interface ScriptCoverage {
 
 export type V8CoverageData = ScriptCoverage[];
 ```
-see devtools-protocol [ScriptCoverage](https://chromedevtools.github.io/devtools-protocol/tot/Profiler/#type-ScriptCoverage)
+see devtools-protocol [ScriptCoverage](https://chromedevtools.github.io/devtools-protocol/tot/Profiler/#type-ScriptCoverage) and [v8-coverage](https://github.com/bcoe/v8-coverage)
 
 
 ## Istanbul Introduction

package/lib/converter/converter.js

@@ -24,7 +24,7 @@ const Util = require('../utils/util.js');
 const decodeMappings = require('../utils/decode-mappings.js');
 
 // position mapping for conversion between offset and line/column
-const { Locator } = require('monocart-formatter/node');
+const { Locator } = require('monocart-formatter');
 const findOriginalRange = require('./find-original-range.js');
 const { getJsAstInfo, getCssAstInfo } = require('./ast.js');
 const { getIgnoredRanges } = require('./ignore.js');

package/lib/default/options.js

@@ -1,13 +1,13 @@
 module.exports = {
 
-    // (String) logging levels: off, error, info, debug
+    // {string} logging levels: off, error, info, debug
     logging: 'info',
 
-    // (String) output dir
+    // {string} output dir
     outputDir: './coverage-reports',
 
-    // (String) v8 or html for istanbul by default
-    // (Array) multiple reports with options
+    // {string} v8 or html for istanbul by default
+    // {array} multiple reports with options
     // v8 report or istanbul supported reports
     // reports: [
     //     ['v8'],
@@ -18,19 +18,19 @@ module.exports = {
     // ],
     reports: '',
 
-    // (String) Report name. Defaults to "Coverage Report".
+    // {string} Report name. Defaults to "Coverage Report".
     name: 'Coverage Report',
 
-    // [V8 only](String) Output [sub dir/]filename. Defaults to "index.html"
+    // (V8 only) {string} Output [sub dir/]filename. Defaults to "index.html"
     outputFile: 'index.html',
 
-    // [V8 only](Boolean) Inline all scripts to the single HTML file. Defaults to false.
+    // (V8 only) {boolean} Inline all scripts to the single HTML file. Defaults to false.
     inline: false,
 
-    // [V8 only](String) Assets path if not inline. Defaults to "./assets"
+    // (V8 only) {string} Assets path if not inline. Defaults to "./assets"
     assetsPath: './assets',
 
-    // [V8 only](Function) A filter function to execute for each element in the V8 list.
+    // (V8 only) {function} A filter function to execute for each element in the V8 list.
     // entryFilter: (entry) => {
     //     if (entry.url.indexOf('googleapis.com') !== -1) {
     //         return false;
@@ -39,30 +39,30 @@ module.exports = {
     // },
     entryFilter: null,
 
-    // [V8 only](Function) A filter function to execute for each element in the sources which unpacked from the source map.
+    // (V8 only) {function} A filter function to execute for each element in the sources which unpacked from the source map.
     // sourceFilter: (sourcePath) => sourcePath.search(/src\/.+/) !== -1,
     sourceFilter: null,
 
-    // [V8 only](Boolean) Enable/Disable ignoring uncovered codes with the special comments: /* v8 ignore next/next N/start/stop */
+    // (V8 only) {boolean} Enable/Disable ignoring uncovered codes with the special comments: v8 ignore next/next N/start/stop
     v8Ignore: true,
 
-    // [Istanbul only] defaultSummarizer, sourceFinder
+    // (Istanbul only) defaultSummarizer, sourceFinder
 
-    // (Boolean) Generate lcov.info file, same as lcovonly report. Defaults to false.
+    // {boolean} Generate lcov.info file, same as lcovonly report. Defaults to false.
     lcov: false,
 
-    // (Function) Source path handler.
+    // {function} Source path handler.
     // sourcePath: (filePath) => `wwwroot/${filePath}`,
     sourcePath: null,
 
-    // (String|Function) Specify the report path, especially when there are multiple reports. Defaults to outputDir/index.html.
+    // {string|function} Specify the report path, especially when there are multiple reports. Defaults to outputDir/index.html.
     reportPath: null,
 
-    // (Array) watermarks for low/medium/high. Defaults to [50, 80]
-    // (Object) Istanbul: { statements:[50,80], functions:[50,80], branches:[50,80], lines:[50,80] }, V8: { bytes:[50,80] }.
+    // {array} watermarks for low/medium/high. Defaults to [50, 80]
+    // {object} Istanbul: { statements:[50,80], functions:[50,80], branches:[50,80], lines:[50,80] }, V8: { bytes:[50,80] }.
     watermarks: [50, 80],
 
-    // (Function) onEnd hook
+    // {function} onEnd hook
     // onEnd: async (reportData) => {}
     onEnd: null
 };

package/lib/index.d.ts

@@ -1,167 +1,240 @@
+declare namespace MCR {
+
+    export interface V8CoverageEntry {
+        url: string;
+        /** css only */
+        text?: string;
+        /** css only */
+        ranges?: any[];
+        /** js only */
+        scriptId?: string;
+        /** js only */
+        source?: string;
+        /** js only */
+        functions?: any[];
+    }
+
+    export type Watermarks = [number, number] | {
+        functions?: [number, number];
+        branches?: [number, number];
+        lines?: [number, number];
+        /** V8 only */
+        bytes?: [number, number];
+        /** Istanbul only */
+        statements?: [number, number];
+    }
+
+    export type ReportDescription =
+        ['v8'] | ["v8", {
+            outputFile?: string;
+            inline?: boolean;
+            assetsPath?: string;
+            metrics?: Array<"bytes" | "functions" | "branches" | "lines">;
+        }] |
+        ['v8-json'] | ["v8-json", {
+            outputFile?: string;
+        }] |
+        ['console-summary'] | ['console-summary', {
+            metrics?: Array<"bytes" | "functions" | "branches" | "lines" | "statements">;
+        }] |
+        ['clover'] | ['clover', {
+            file?: string;
+        }] |
+        ['cobertura'] | ['cobertura', {
+            file?: string;
+            timestamp?: string;
+            projectRoot?: string;
+        }] |
+        ['html'] | ['html', {
+            subdir?: string;
+            verbose?: boolean;
+            linkMapper?: any;
+            skipEmpty?: boolean;
+        }] |
+        ['html-spa'] | ['html-spa', {
+            subdir?: string;
+            verbose?: boolean;
+            linkMapper?: any;
+            skipEmpty?: boolean;
+            metricsToShow?: Array<"lines" | "branches" | "functions" | "statements">;
+        }] |
+        ['json'] | ['json', {
+            file?: string;
+        }] |
+        ['json-summary'] | ['json-summary', {
+            file?: string;
+        }] |
+        ['lcov'] | ['lcov', {
+            file?: string;
+            projectRoot?: string;
+        }] |
+        ['lcovonly'] | ['lcovonly', {
+            file?: string;
+            projectRoot?: string;
+        }] |
+        ['none'] |
+        ['teamcity'] | ['teamcity', {
+            file?: string;
+            blockName?: string;
+        }] |
+        ['text'] | ['text', {
+            file?: string;
+            maxCols?: number;
+            skipEmpty?: boolean;
+            skipFull?: boolean;
+        }] |
+        ['text-lcov'] | ['text-lcov', {
+            projectRoot?: string;
+        }] |
+        ['text-summary'] | ['text-summary', {
+            file?: string;
+        }];
+
+    export type AddedResults = {
+        id: string;
+        path: string;
+        type: "v8" | "istanbul";
+        data: any;
+    } | undefined;
+
+
+    export interface MetricsSummary {
+        covered: number;
+        uncovered?: number;
+        total: number;
+        pct: number | "";
+        status: "low" | "medium" | "high" | "unknown";
+    }
+
+    export interface LinesSummary extends MetricsSummary {
+        /** V8 only */
+        blank?: number;
+        /** V8 only */
+        comment?: number;
+    }
+
+    export interface CoverageSummary {
+        functions: MetricsSummary;
+        branches: MetricsSummary;
+        lines: LinesSummary;
+        /** V8 only */
+        bytes?: MetricsSummary;
+        /** Istanbul only */
+        statements?: MetricsSummary;
+    }
+
+    /** V8 only */
+    export interface CoverageRange {
+        start: number;
+        end: number;
+        count: number;
+        ignored?: boolean;
+        none?: boolean;
+    }
+
+    export interface CoverageFile {
+        sourcePath: string;
+        summary: CoverageSummary;
+        /** V8 only */
+        url?: string;
+        /** V8 only */
+        id?: string;
+        /** V8 only */
+        type?: string;
+        /** V8 only */
+        source?: string;
+        /** V8 only */
+        distFile?: string;
+        /** V8 only */
+        js?: boolean;
+        /** V8 only */
+        data?: {
+            bytes: CoverageRange[];
+            functions: CoverageRange[];
+            branches: CoverageRange[];
+        }
+    }
+
+    export type CoverageResults = {
+        type: "v8" | "istanbul";
+        reportPath: string;
+        name: string;
+        watermarks: Watermarks;
+        summary: CoverageSummary;
+        files: CoverageFile[];
+    } | undefined;
+
+    export interface CoverageReportOptions {
+
+        /** {string} logging levels: off, error, info, debug */
+        logging?: string;
+
+        /** {string} output dir */
+        outputDir?: string;
+
+        /** {string} v8 or html for istanbul by default
+        * {array} multiple reports with options
+        * v8 report or istanbul supported reports */
+        reports?: string | ReportDescription[];
+
+        /** {string} Report name. Defaults to "Coverage Report". */
+        name?: string;
+
+        /** (V8 only) {string} Output [sub dir/]filename. Defaults to "index.html" */
+        outputFile?: string;
+        /** (V8 only) {boolean} Inline all scripts to the single HTML file. Defaults to false. */
+        inline?: boolean;
+        /** (V8 only) {string} Assets path if not inline. Defaults to "./assets" */
+        assetsPath?: string;
+
+        /** (V8 only) {function} A filter function to execute for each element in the V8 list. */
+        entryFilter?: (entry: V8CoverageEntry) => boolean;
+
+        /** (V8 only) {function} A filter function to execute for each element in the sources which unpacked from the source map. */
+        sourceFilter?: (sourcePath: string) => boolean;
+
+        /** (V8 only) {boolean} Enable/Disable ignoring uncovered codes with the special comments: v8 ignore next/next N/start/stop */
+        v8Ignore?: boolean;
+
+        /** (Istanbul only) defaultSummarizer, sourceFinder  */
+
+        /** {boolean} Generate lcov.info file, same as lcovonly report. Defaults to false.  */
+        lcov?: boolean;
+
+        /** {function} Source path handler. */
+        sourcePath?: (filePath: string) => string;
+
+        /** {string|function} Specify the report path, especially when there are multiple reports. Defaults to outputDir/index.html. */
+        reportPath?: string | (() => string);
+
+        /** {array} watermarks for low/medium/high. Defaults to [50, 80]
+        * {object} { statements:[50,80], functions:[50,80], branches:[50,80], lines:[50,80] }, V8: { bytes:[50,80] } */
+        watermarks?: Watermarks;
+
+        /** {function} onEnd hook */
+        onEnd?: (reportData: CoverageResults) => Promise<void>;
+    }
+
+    export class CoverageReport {
+
+        constructor(options?: CoverageReportOptions);
+
+        /** add coverage data: {array} V8 format, {object} Istanbul format */
+        add: (coverageData: any[] | any) => Promise<AddedResults>;
+
+        /** generate report */
+        generate: () => Promise<CoverageResults>;
+
+        /** check if cache exists */
+        hasCache: () => boolean;
+
+        /** clean previous cache, return `false` if no cache */
+        cleanCache: () => boolean;
+    }
 
-// https://playwright.dev/docs/api/class-coverage
-export type V8CoverageEntry = {
-    url: string,
-    // css
-    text?: string,
-    ranges?: any[]
-    // js
-    scriptId?: string,
-    source?: string,
-    functions?: any[]
 }
 
-export type Watermarks = [number, number] | {
-    statements?: [number, number],
-    functions?: [number, number],
-    branches?: [number, number],
-    lines?: [number, number],
-    bytes?: [number, number]
-}
-
-export type ReportDescription =
-    ['v8'] | ["v8", {
-        outputFile?: string,
-        inline?: boolean,
-        assetsPath?: string,
-        metrics?: Array<"bytes" | "functions" | "branches" | "lines">
-    }] |
-    ['v8-json'] | ["v8-json", {
-        outputFile?: string
-    }] |
-    ['console-summary'] | ['console-summary', {
-        metrics?: Array<"bytes" | "functions" | "branches" | "lines" | "statements">
-    }] |
-    ['clover'] | ['clover', {
-        file?: string
-    }] |
-    ['cobertura'] | ['cobertura', {
-        file?: string,
-        timestamp?: string,
-        projectRoot?: string
-    }] |
-    ['html'] | ['html', {
-        subdir?: string,
-        verbose?: boolean,
-        linkMapper?: any,
-        skipEmpty?: boolean
-    }] |
-    ['html-spa'] | ['html-spa', {
-        subdir?: string,
-        verbose?: boolean,
-        linkMapper?: any,
-        skipEmpty?: boolean,
-        metricsToShow?: Array<"lines" | "branches" | "functions" | "statements">
-    }] |
-    ['json'] | ['json', {
-        file?: string
-    }] |
-    ['json-summary'] | ['json-summary', {
-        file?: string
-    }] |
-    ['lcov'] | ['lcov', {
-        file?: string,
-        projectRoot?: string
-    }] |
-    ['lcovonly'] | ['lcovonly', {
-        file?: string,
-        projectRoot?: string
-    }] |
-    ['none'] |
-    ['teamcity'] | ['teamcity', {
-        file?: string,
-        blockName?: string
-    }] |
-    ['text'] | ['text', {
-        file?: string,
-        maxCols?: number,
-        skipEmpty?: boolean,
-        skipFull?: boolean
-    }] |
-    ['text-lcov'] | ['text-lcov', {
-        projectRoot?: string
-    }] |
-    ['text-summary'] | ['text-summary', {
-        file?: string
-    }];
-
-export type CoverageResults = {
-    type: "v8" | "istanbul",
-    reportPath: string,
-    name: string,
-    watermarks: Watermarks,
-    summary: any,
-    files: any
-}
-
-export type CoverageReportOptions = {
-
-    // (String) logging levels: off, error, info, debug
-    logging?: string,
-
-    // (String) output dir
-    outputDir?: string,
-
-    // (String) v8 or html for istanbul by default
-    // (Array) multiple reports with options
-    // v8 report or istanbul supported reports
-    reports?: string | ReportDescription[],
-
-    // (String) Report name. Defaults to "Coverage Report".
-    name?: string,
-
-    // [V8 only](String) Output [sub dir/]filename. Defaults to "index.html"
-    outputFile?: string,
-    // [V8 only](Boolean) Inline all scripts to the single HTML file. Defaults to false.
-    inline?: boolean,
-    // [V8 only](String) Assets path if not inline. Defaults to "./assets"
-    assetsPath?: string
-
-    // [V8 only](Function) A filter function to execute for each element in the V8 list.
-    entryFilter?: (entry: V8CoverageEntry) => boolean,
-
-    // [V8 only](Function) A filter function to execute for each element in the sources which unpacked from the source map.
-    sourceFilter?: (sourcePath: string) => boolean,
-
-    // [V8 only](Boolean) Enable/Disable ignoring uncovered codes with the special comments: /* v8 ignore next/next N/start/stop */
-    v8Ignore?: boolean,
-
-    // [Istanbul only] defaultSummarizer, sourceFinder
-
-    // (Boolean) Generate lcov.info file, same as lcovonly report. Defaults to false.
-    lcov?: boolean,
-
-    // (Function) Source path handler.
-    sourcePath?: (filePath: string) => string,
-
-    // (String|Function) Specify the report path, especially when there are multiple reports. Defaults to outputDir/index.html.
-    reportPath?: string | (() => string),
-
-    // (Array) watermarks for low/medium/high. Defaults to [50, 80]
-    // (Object) Istanbul: { statements:[50,80], functions:[50,80], branches:[50,80], lines:[50,80] }, V8: { bytes:[50,80] }.
-    watermarks?: Watermarks,
-
-    // (Function) onEnd hook
-    onEnd?: (reportData: CoverageResults) => Promise<void>
-}
-
-export class CoverageReport {
-    constructor(options?: CoverageReportOptions);
-
-    // add coverage data: (Array) V8 format, (Object) Istanbul format
-    add: (coverageData: any[] | any) => Promise<any>;
-
-    // generate report
-    generate: () => Promise<CoverageResults>;
-
-    // check if cache exists
-    hasCache: () => boolean;
-
-    // clean cache
-    cleanCache: () => boolean;
-
-}
-
-export default CoverageReport;
+/** create coverage report */
+declare function MCR(options?: MCR.CoverageReportOptions): MCR.CoverageReport;
 
-export function createCoverageReport(options?: CoverageReportOptions): CoverageReport;
+export = MCR;

package/lib/index.js

@@ -8,10 +8,6 @@ const { getCoverageDataList, generateCoverageReports } = require('./generate.js'
 
 class CoverageReport {
 
-    static createCoverageReport = (options) => {
-        return new CoverageReport(options);
-    };
-
     constructor(options = {}) {
         this.cacheDirName = '.cache';
         this.options = {
@@ -42,7 +38,7 @@ class CoverageReport {
         this.fixedOptions = true;
     }
 
-    // add coverage data: (Array) V8 format, (Object) Istanbul format
+    // add coverage data: {array} V8 format, {object} Istanbul format
     async add(data) {
 
         this.initOptions();
@@ -133,4 +129,10 @@ class CoverageReport {
 
 }
 
-module.exports = CoverageReport;
+/** create coverage report */
+const MCR = function(options) {
+    return new CoverageReport(options);
+};
+MCR.CoverageReport = CoverageReport;
+
+module.exports = MCR;

package/lib/index.mjs

@@ -1,6 +1,3 @@
-import CoverageReport from './index.js';
-
-export default CoverageReport;
-export { CoverageReport };
-
-export const createCoverageReport = CoverageReport.createCoverageReport;
+import MCR from './index.js';
+export default MCR;
+export const CoverageReport = MCR.CoverageReport;

package/lib/istanbul/istanbul-summary.js

@@ -28,8 +28,11 @@ class IstanbulSummary extends ReportBase {
     onDetail(node) {
         const fileSummary = node.getCoverageSummary().data;
         this.addStatus(fileSummary);
-        fileSummary.name = node.getRelativeName();
-        this.files.push(fileSummary);
+        const sourcePath = node.getQualifiedName();
+        this.files.push({
+            sourcePath,
+            summary: fileSummary
+        });
     }
 
     onEnd() {