monocart-coverage-reports 2.6.2 → 2.6.4

package/lib/index.d.ts

@@ -2,16 +2,35 @@ declare namespace MCR {
 
     export interface V8CoverageEntry {
         url: string;
+
+        /** entry type */
+        type?: "js" | "css";
+
         /** css only */
         text?: string;
         /** css only */
         ranges?: any[];
-        /** js only */
-        scriptId?: string;
+
         /** js only */
         source?: string;
         /** js only */
+        scriptId?: string;
+        /** js only */
         functions?: any[];
+
+        /** js only */
+        sourceMap?: any;
+        /** js only */
+        scriptOffset?: number;
+        /** js only */
+        distFile?: string;
+
+        /** empty coverage */
+        empty?: boolean;
+        /** fake source */
+        fake?: boolean;
+
+        [key: string]: any;
     }
 
     export type Watermarks = [number, number] | {
@@ -166,10 +185,10 @@ declare namespace MCR {
         js?: boolean;
         /** V8 only */
         data?: {
-            bytes: CoverageRange[];
-            statements: CoverageRange[];
-            branches: CoverageRange[];
-            functions: CoverageRange[];
+            bytes?: CoverageRange[];
+            statements?: CoverageRange[];
+            branches?: CoverageRange[];
+            functions?: CoverageRange[];
             ignores?: IgnoredRange[];
             /** codecov json format */
             lines: {
@@ -192,11 +211,8 @@ declare namespace MCR {
         /** {string} logging levels: off, error, info, debug */
         logging?: string;
 
-        /** {string} output dir */
-        outputDir?: string;
-
-        /** {string|string[]} input raw dir(s) */
-        inputDir?: string | string[];
+        /** {string} Report name. Defaults to "Coverage Report". */
+        name?: string;
 
         /** 
          * 
@@ -205,25 +221,21 @@ declare namespace MCR {
          * {array} ['v8'], ['v8', ['console-details', { skipPercent: 80 }]]
          * 
          * By default, `v8` for V8 data, `html` for Istanbul data
-        */
-        reports?: string | ReportDescription[];
+         */
+        reports?: string | string[] | ReportDescription[];
 
-        /** {string} Report name. Defaults to "Coverage Report". */
-        name?: string;
+        /** {string} output dir */
+        outputDir?: 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;
+        /** {string|string[]} input raw dir(s) */
+        inputDir?: string | string[];
 
         /** (V8 only) 
          * 
          * {string} `minimatch` pattern for entry url; {object} multiple patterns;
          * 
          * {function} A filter function for each entry file in the V8 list.
-         * */
+         */
         entryFilter?: string | {
             [pattern: string]: boolean;
         } | ((entry: V8CoverageEntry) => boolean);
@@ -233,11 +245,33 @@ declare namespace MCR {
          * {string} `minimatch` pattern for source path; {object} multiple patterns;
          * 
          * {function} A filter function for each source path when the source is unpacked from the source map. 
-         * */
+         */
         sourceFilter?: string | {
             [pattern: string]: boolean;
         } | ((sourcePath: string) => boolean);
 
+        /** 
+         * {function} Source path handler. 
+         * 
+         * {object} Replace key with value.
+         * */
+        sourcePath?: ((filePath: string) => string) | {
+            [key: string]: 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;
+
+        /** (Istanbul only) defaultSummarizer, sourceFinder  */
+
+        /** {boolean} Generate lcov.info file, same as lcovonly report. Defaults to false.  */
+        lcov?: boolean;
+
         /**
          * options for adding empty coverage for all files
          */
@@ -259,20 +293,6 @@ declare namespace MCR {
         /** (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. 
-         * 
-         * {object} Replace key with value.
-         * */
-        sourcePath?: ((filePath: string) => string) | {
-            [key: string]: string;
-        };
-
         /** {string|function} Specify the report path, especially when there are multiple reports. Defaults to outputDir/index.html. */
         reportPath?: string | (() => string);
 
@@ -280,30 +300,51 @@ declare namespace MCR {
         * {object} { bytes:[50,80], statements:[50,80], branches:[50,80], functions:[50,80], lines:[50,80] } */
         watermarks?: Watermarks;
 
-        /** {boolean} Indicates whether to clean previous files in output dir before generating report. Defaults to true. */
+        /** 
+         * {boolean} Indicates whether to clean previous reports in output dir before generating new reports. Defaults to true. 
+         * 
+         * If true, the API `clean()` will execute automatically.
+         * */
         clean?: boolean;
 
         /**
-         * {boolean} Indicates whether to clean previous cache in output dir before generating report. Defaults to false. 
+         * {boolean} Indicates whether to clean previous cache in output dir on start. Defaults to false. 
          * 
          * If true, the API `cleanCache()` will execute automatically.
         */
         cleanCache?: boolean;
 
+        /** (V8 only) {function} onEntry hook */
+        onEntry?: (entry: V8CoverageEntry) => Promise<void>;
+
         /** {function} onEnd hook */
         onEnd?: (coverageResults: CoverageResults) => Promise<void>;
+
     }
 
     export interface McrCliOptions extends CoverageReportOptions {
-        /** {function} onStart hook */
+
+        /** (CLI only) {function} onStart hook */
         onStart?: (coverageReport: CoverageReport) => Promise<void>;
+
+        /** (CLI only) {function} onReady hook before adding coverage data.
+         * 
+         * Sometimes, the child process has not yet finished writing the coverage data, and it needs to wait here.
+        */
+        onReady?: (coverageReport: CoverageReport, nodeV8CoverageDir: string, subprocess: any) => Promise<void>;
+
     }
 
     export class CoverageReport {
 
+        /**
+         * @param options coverage report options
+         */
         constructor(options?: CoverageReportOptions);
 
-        /** add coverage data: {array} V8 format, {object} Istanbul format */
+        /** add coverage data
+         * 
+         * @param coverageData {array} V8 format, {object} Istanbul format */
         add: (coverageData: any[] | any) => Promise<AddedResults>;
 
         /** generate report */
@@ -314,6 +355,27 @@ declare namespace MCR {
 
         /** clean previous cache, return `false` if no cache */
         cleanCache: () => boolean;
+
+        /** clean previous reports except cache dir and v8 coverage dir */
+        clean: () => void;
+
+        /** get entry filter handler, it can be used to filter the coverage data list before adding it. */
+        getEntryFilter: () => ((entry: V8CoverageEntry) => boolean);
+
+        /** load config file. 
+         * 
+         * @param configFile custom config file path
+         * 
+         * Supports loading default config file if no custom config specified: 
+            'mcr.config.js',
+            'mcr.config.cjs',
+            'mcr.config.mjs',
+            'mcr.config.json',
+            '.mcrrc.js',
+            '.mcrrc',
+            'mcr.config.ts'
+         */
+        loadConfig: (configFile?: string) => Promise<void>;
     }
 
     export interface CoverageSnapshot {

package/lib/index.js

@@ -1,5 +1,8 @@
 const fs = require('fs');
 const path = require('path');
+const { pathToFileURL } = require('url');
+const EC = require('eight-colors');
+
 const defaultOptions = require('./default/options.js');
 const Util = require('./utils/util.js');
 
@@ -7,26 +10,46 @@ const { initV8ListAndSourcemap, getEntryFilter } = require('./v8/v8.js');
 const { getInputData, generateCoverageReports } = require('./generate.js');
 const { getSnapshot, diffSnapshot } = require('./utils/snapshot.js');
 
+const resolveConfigOptions = async (configPath) => {
+    // json format
+    const ext = path.extname(configPath);
+    if (ext === '.json' || configPath.slice(-2) === 'rc') {
+        return JSON.parse(Util.readFileSync(configPath));
+    }
+
+    let configOptions;
+    let err;
+    try {
+        configOptions = await import(pathToFileURL(configPath));
+    } catch (ee) {
+        err = ee;
+    }
+
+    if (err || !configOptions) {
+        Util.logError(`ERROR: failed to load config "${configPath}": ${err && err.message} `);
+        return;
+    }
+
+    configOptions = configOptions.default || configOptions;
+
+    return configOptions;
+};
+
 class CoverageReport {
 
     constructor(options = {}) {
         this.cacheDirName = '.cache';
+        this.constructorOptions = options;
         this.options = {
             ... defaultOptions,
             ... options
         };
-
         this.initOptions();
-        // If true, the API `cleanCache()` will execute automatically.
-        if (this.options.cleanCache) {
-            this.cleanCache();
-        }
-
     }
 
-    initOptions() {
+    initOptions(force) {
 
-        if (this.fixedOptions) {
+        if (this.fixedOptions && !force) {
             return;
         }
 
@@ -43,6 +66,11 @@ class CoverageReport {
         const cacheDir = path.resolve(outputDir, this.cacheDirName);
         this.options.cacheDir = cacheDir;
 
+        // If true, the API `cleanCache()` will execute automatically.
+        if (this.options.cleanCache) {
+            this.cleanCache();
+        }
+
         this.fixedOptions = true;
     }
 
@@ -125,12 +153,7 @@ class CoverageReport {
         if (fs.existsSync(outputDir)) {
             // if assets dir is out of output dir will be ignore
             if (this.options.clean) {
-                fs.readdirSync(outputDir).forEach((itemName) => {
-                    if (itemName === this.cacheDirName) {
-                        return;
-                    }
-                    Util.rmSync(path.resolve(outputDir, itemName));
-                });
+                this.clean();
             }
         } else {
             fs.mkdirSync(outputDir, {
@@ -160,7 +183,7 @@ class CoverageReport {
         return fs.existsSync(this.options.cacheDir);
     }
 
-    // cache clean
+    // cache clean dir
     cleanCache() {
         // clean previous artifacts
         if (this.hasCache()) {
@@ -170,10 +193,75 @@ class CoverageReport {
         return false;
     }
 
+    // clean previous reports except cache dir and v8 coverage dir
+    clean() {
+        const outputDir = this.options.outputDir;
+        let v8DirName;
+        const nodeV8CoverageDir = process.env.NODE_V8_COVERAGE;
+        if (nodeV8CoverageDir) {
+            v8DirName = path.relative(outputDir, nodeV8CoverageDir);
+        }
+        fs.readdirSync(outputDir).forEach((itemName) => {
+            if (itemName === this.cacheDirName) {
+                return;
+            }
+            if (itemName === v8DirName) {
+                return;
+            }
+            Util.rmSync(path.resolve(outputDir, itemName));
+        });
+    }
+
+    // get entry filter handler
     getEntryFilter() {
         return getEntryFilter(this.options);
     }
 
+    // load config file
+    async loadConfig(customConfigFile) {
+
+        // order by priority
+        const configList = customConfigFile ? [customConfigFile] : [
+            'mcr.config.js',
+            'mcr.config.cjs',
+            'mcr.config.mjs',
+            'mcr.config.json',
+            '.mcrrc.js',
+            '.mcrrc',
+            'mcr.config.ts'
+        ];
+
+        const existsList = configList.filter((p) => p && fs.existsSync(p));
+        if (!existsList.length) {
+            if (customConfigFile) {
+                Util.logError(`The config file does not exist: ${customConfigFile}`);
+            }
+            // no config
+            return;
+        }
+
+        // first one, high priority
+        const configPath = existsList[0];
+        const configOptions = await resolveConfigOptions(configPath);
+        if (!configOptions) {
+            // failed to load config options
+            if (customConfigFile) {
+                Util.logError(`Failed to load config file: ${customConfigFile}`);
+            }
+            return;
+        }
+
+        Util.logInfo(`Loaded config: ${EC.cyan(configPath)}`);
+        // init options again
+        this.options = {
+            ... defaultOptions,
+            ... configOptions,
+            ... this.constructorOptions
+        };
+        this.initOptions(true);
+
+    }
+
 }
 
 /** create coverage report */