monocart-coverage-reports 2.13.1 → 3.0.0

package/lib/assets.js

@@ -1,8 +1,8 @@
-const fs = require('fs');
-const path = require('path');
-const { deflateSync } = require('lz-utils');
-const Util = require('./utils/util.js');
-const assetsMap = require('./packages/monocart-coverage-assets.js');
+import fs from 'node:fs';
+import path from 'node:path';
+import { deflateSync } from 'lz-utils';
+import { Util } from './utils/util.js';
+import { assetsMap } from './packages/monocart-coverage-assets.js';
 
 const Assets = {
 
@@ -95,4 +95,4 @@ const Assets = {
     }
 };
 
-module.exports = Assets;
+export { Assets };

package/lib/cli.js

@@ -1,29 +1,27 @@
 #!/usr/bin/env node
 
-const path = require('path');
-const { pathToFileURL } = require('url');
-const EC = require('eight-colors');
+import path from 'node:path';
+import { constants } from 'node:os';
+import { pathToFileURL } from 'node:url';
+import EC from 'eight-colors';
 
-const { program } = require('commander');
-const { foregroundChild } = require('foreground-child');
+import { program } from 'commander';
+import { execa } from 'execa';
 
-const MCR = require('./index.js');
-const Util = require('./utils/util.js');
+import { MCR } from './index.js';
+import { Util } from './utils/util.js';
+import pkg from '../package.json' with { type: 'json' };
 
-const version = require('../package.json').version;
+const version = pkg.version;
 
 // quote NODE_OPTIONS argument if it contains whitespace so child processes
 // inheriting the env var can parse it correctly
-const quoteNodeOption = (v) => ((/\s/).test(v) ? `"${v}"` : v);
+const quoteNodeOption = (v) => ((/[\s"\\]/).test(v) ? JSON.stringify(v) : v);
 
 // absolute path so NODE_OPTIONS keeps resolving when child processes are
 // spawned with a different cwd than the mcr parent process
-const getRequirePath = () => {
-    return quoteNodeOption(path.resolve(__dirname, 'register', 'register.js'));
-};
-
 const getImportPath = () => {
-    return quoteNodeOption(pathToFileURL(path.resolve(__dirname, 'register', 'register.mjs')).href);
+    return quoteNodeOption(pathToFileURL(path.resolve(import.meta.dirname, 'register', 'register.js')).href);
 };
 
 const getInitNodeOptions = async (cliOptions) => {
@@ -32,79 +30,34 @@ const getInitNodeOptions = async (cliOptions) => {
         nodeOptions.push(process.env.NODE_OPTIONS);
     }
 
-    if (cliOptions.import) {
-        nodeOptions.push(`--import ${cliOptions.import}`);
-        // for load mcr.config.ts
-        await import(cliOptions.import);
-    } else if (cliOptions.require) {
-        nodeOptions.push(`--require ${cliOptions.require}`);
-        // for load mcr.config.ts
-        await import(cliOptions.require);
+    const name = cliOptions.import || cliOptions.require;
+    if (name) {
+        const specifier = path.isAbsolute(name) || name.startsWith('.') ? pathToFileURL(path.resolve(name)).href : import.meta.resolve(name);
+        nodeOptions.push(`--import ${quoteNodeOption(specifier)}`);
+        // Load before mcr.config.ts. CJS interoperability is handled by Node.
+        await import(specifier);
     }
 
     return nodeOptions;
 };
 
-const getPreloadType = (nodeOptions) => {
-    const hasImport = nodeOptions.find((it) => it.includes('--import'));
-    if (hasImport) {
-        return '--import';
-    }
-    return '--require';
-};
-
-const checkRegisterFeature = () => {
-    const nv = process.versions.node;
-
-    // "module.register" added in Node.js: v20.6.0
-    // if (Util.cmpVersion(nv, '20.6.0') >= 0) {
-    //     return true;
-    // }
-    // but also added in: v18.19.0
-    const requiredNV = '18.19.0';
-    if (Util.cmpVersion(nv, requiredNV) < 0) {
-        Util.logInfo(`The current Node.js version "${nv}" does NOT support "module.register", it requires "${requiredNV}" or higher.`);
-        return false;
-    }
-
-    // could be < 20.6.0 but just ignore it, please using latest minor version
-
-    return true;
-};
-
 const loadEnv = (cliOptions) => {
     if (!cliOptions.env) {
         return;
     }
     const envFile = cliOptions.env === true ? '.env' : cliOptions.env;
-    const loadEnvFile = process.loadEnvFile;
-    if (typeof loadEnvFile === 'function') {
-        loadEnvFile(envFile);
-    }
+    process.loadEnvFile(envFile);
 };
 
 const initNodeOptions = async (cliOptions) => {
 
     loadEnv(cliOptions);
 
-    const supportRegister = checkRegisterFeature();
-    if (!supportRegister) {
-        return;
-    }
-
     const nodeOptions = await getInitNodeOptions(cliOptions);
     // console.log(nodeOptions);
 
-    const preloadType = getPreloadType(nodeOptions);
-
-    // export source after
-    if (preloadType === '--import') {
-        const importPath = getImportPath();
-        nodeOptions.unshift(`--import ${importPath}`);
-    } else {
-        const requirePath = getRequirePath();
-        nodeOptions.unshift(`--require ${requirePath}`);
-    }
+    // Register source capture before other ESM preloads.
+    nodeOptions.unshift(`--import ${getImportPath()}`);
 
     // console.log(nodeOptions);
     const nodeOptionsStr = nodeOptions.join(' ');
@@ -132,9 +85,88 @@ const mergeCoverage = async (cliOptions) => {
     await coverageReport.generate();
 };
 
-const executeCommand = async (command, cliOptions) => {
+// Only check whether targets were supplied. Node owns all target parsing,
+// discovery and validation; preserve each argument exactly as provided.
+const getTestTargets = (test) => {
+    if (!test || (Array.isArray(test) && !test.length)) {
+        Util.logInfo('No test targets configured; skipping tests.');
+        return;
+    }
+
+    return Array.isArray(test) ? test : [test];
+};
 
-    Util.logInfo(`Execute: ${EC.cyan(command)}`);
+// Preserve signals and failing commands even if a hook sets exitCode=0.
+const getExitStatus = (code, signal) => signal || code || process.exitCode || 0;
+
+const applyExitStatus = (status) => {
+    if (typeof status === 'number') {
+        process.exitCode = status;
+        return;
+    }
+    process.exitCode = 128 + (constants.signals[status] || 1);
+    if (process.platform !== 'win32') {
+        // Stay alive until the signal is delivered, after coverage has flushed.
+        const timer = setTimeout(() => {}, 2000);
+        try {
+            process.kill(process.pid, status);
+        } catch {
+            clearTimeout(timer);
+        }
+    }
+};
+
+const proxySignals = (execution) => {
+    const state = {
+        finished: false, signal: null
+    };
+    const listeners = ['SIGINT', 'SIGTERM', 'SIGHUP'].map((signal) => {
+        const listener = () => {
+            state.signal ||= signal;
+            if (!state.finished) {
+                execution.kill(signal);
+            }
+        };
+        process.on(signal, listener);
+        return [signal, listener];
+    });
+    state.dispose = () => {
+        for (const [signal, listener] of listeners) {
+            process.removeListener(signal, listener);
+        }
+    };
+    return state;
+};
+
+const logSpawnFailure = (result) => {
+    if (result.failed && !Number.isInteger(result.exitCode) && !result.signal) {
+        Util.logError(result.shortMessage || result.message);
+    }
+};
+
+const executeSubprocess = async (command, args, onClose) => {
+    const execution = execa(command, args, {
+        stdio: 'inherit',
+        reject: false
+    });
+    const signals = proxySignals(execution);
+    let status;
+    try {
+        const result = await execution;
+        signals.finished = true;
+        logSpawnFailure(result);
+        // Preserve the native ChildProcess API exposed to onReady hooks.
+        status = await onClose(result.exitCode ?? (result.failed ? 1 : 0), result.signal || signals.signal, execution.nodeChildProcess);
+        status = signals.signal || status;
+    } finally {
+        signals.dispose();
+    }
+    applyExitStatus(status);
+};
+
+const executeCommand = async ([command, ... commandArgs], cliOptions, testArgs = []) => {
+
+    Util.logInfo(`Execute: ${EC.cyan([command, ... commandArgs].join(' '))}`);
 
     if (command === 'merge') {
         return mergeCoverage(cliOptions);
@@ -145,11 +177,24 @@ const executeCommand = async (command, cliOptions) => {
 
     // console.log(options);
     const coverageReport = MCR(cliOptions);
+    const isTest = command === 'test';
     await coverageReport.loadConfig(cliOptions.config);
-    coverageReport.cleanCache();
 
     const coverageOptions = coverageReport.options;
+    let childArgs;
+    if (isTest) {
+        const targets = getTestTargets(coverageOptions.test);
+        if (!targets) {
+            return;
+        }
+        childArgs = ['--test', ... testArgs, ... targets];
+    }
+    coverageReport.cleanCache();
     const nodeV8CoverageDir = initNodeV8CoverageDir(coverageOptions);
+    if (isTest) {
+        // Tests may spawn children with a different working directory.
+        process.env.NODE_V8_COVERAGE = path.resolve(nodeV8CoverageDir);
+    }
 
     // =========================================
     // onStart hook
@@ -159,31 +204,39 @@ const executeCommand = async (command, cliOptions) => {
     }
     // =========================================
 
-    const subprocess = foregroundChild(command, {
-        shell: true
-    }, async (code, signal) => {
+    const onClose = async (code, signal, subprocess) => {
 
         // generate coverage even it is failed. code != 0
 
-        // =========================================
-        // onReady hook before adding coverage data.
-        // Sometimes, the child process has not yet finished writing the coverage data, and it needs to wait here.
-        const onReady = coverageOptions.onReady;
-        if (typeof onReady === 'function') {
-            await onReady(coverageReport, nodeV8CoverageDir, subprocess);
+        try {
+            // onReady hook before adding coverage data. Some children need
+            // additional time to finish writing their coverage files.
+            const onReady = coverageOptions.onReady;
+            if (typeof onReady === 'function') {
+                await onReady(coverageReport, nodeV8CoverageDir, subprocess);
+            }
+
+            await coverageReport.addFromDir(nodeV8CoverageDir);
+            const report = await coverageReport.generate();
+            if (isTest && !report) {
+                throw new Error('No coverage report was generated');
+            }
+        } catch (error) {
+            Util.logError(`Coverage report generation failed: ${error.message}`);
+            process.exitCode = 1;
+        } finally {
+            if (!Util.isDebug()) {
+                Util.rmSync(nodeV8CoverageDir);
+            }
         }
-        // =========================================
-
-        await coverageReport.addFromDir(nodeV8CoverageDir);
-        await coverageReport.generate();
 
-        // remove nodeV8CoverageDir
-        if (!Util.isDebug()) {
-            Util.rmSync(nodeV8CoverageDir);
-        }
+        return getExitStatus(code, signal);
+    };
 
-        return process.exitCode;
-    });
+    if (isTest) {
+        return executeSubprocess(process.execPath, childArgs, onClose);
+    }
+    return executeSubprocess(command, commandArgs, onClose);
 
 };
 
@@ -208,11 +261,35 @@ process.argv.forEach((it) => {
     }
 });
 
+// Also recognize `mcr -c config -- test targets -- runner-options` without
+// falling through to the shell's unrelated `test` command. Only MCR options
+// before the first separator are parsed in that form.
+const getTestCommand = (args, subArgs) => {
+    if (args[0] === 'test') {
+        return {
+            targets: args.slice(1), runnerArgs: subArgs.slice(1)
+        };
+    }
+    if (args.length || subArgs[1] !== 'test') {
+        return;
+    }
+    const remaining = subArgs.slice(2);
+    const index = remaining.indexOf('--');
+    if (index === -1) {
+        return {
+            targets: remaining, runnerArgs: []
+        };
+    }
+    return {
+        targets: remaining.slice(0, index), runnerArgs: remaining.slice(index + 1)
+    };
+};
+
 program
     .name('mcr')
     .description('CLI to generate coverage reports')
     .version(version, '-v, --version', 'output the current version')
-    .argument('[command]', 'command to execute')
+    .argument('[command]', 'command to execute, or built-in merge/test')
     .allowUnknownOption()
     .allowExcessArguments()
     .option('-c, --config <path>', 'custom config file path')
@@ -229,6 +306,7 @@ program
 
     .option('--entryFilter <pattern>', 'entry url filter')
     .option('--sourceFilter <pattern>', 'source path filter')
+    .option('--outputFilter <pattern>', 'final source path filter')
     .option('--filter <pattern>', 'the combined filter')
 
     .option('--outputFile <path>', 'output file for v8 report')
@@ -238,22 +316,40 @@ program
     .option('--lcov', 'generate lcov.info file')
 
     .option('--import <module>', 'preload module at startup')
-    .option('--require <module>', 'preload module at startup')
+    .option('--require <module>', 'deprecated alias for --import (ESM resolution)')
 
     .option('--env [path]', 'env file (default: ".env")')
 
     .action((_command, cliOptions) => {
+        const testCommand = getTestCommand(program.args, subArgv);
+        if (testCommand) {
+            // Commander has already removed MCR options and their values.
+            // Positional targets override config; only args after -- are
+            // forwarded unchanged to the Node runner.
+            const { targets, runnerArgs } = testCommand;
+            if (targets.length) {
+                cliOptions.test = targets;
+            }
+            executeCommand(['test'], cliOptions, runnerArgs).catch((error) => {
+                Util.logError(error.message);
+                process.exitCode = 1;
+            });
+            return;
+        }
+
         const args = [].concat(program.args).concat(subArgv);
         if (args[0] === '--') {
             args.shift();
         }
-        const command = args.join(' ').trim();
-        if (!command) {
+        if (!args.length || !args[0]) {
             program.outputHelp();
             return;
         }
 
-        executeCommand(command, cliOptions);
+        executeCommand(args, cliOptions).catch((error) => {
+            Util.logError(error.message);
+            process.exitCode = 1;
+        });
     });
 
 program.parse(argv);

package/lib/client/cdp-client.js

@@ -1,18 +1,19 @@
 
-const EC = require('eight-colors');
+import EC from 'eight-colors';
 
-const { WebSocket } = require('../packages/monocart-coverage-vendor.js');
-const Util = require('../utils/util.js');
+import { Util } from '../utils/util.js';
 
-const WSSession = require('./ws-session.js');
-const CoverageClient = require('./coverage-client.js');
+import { WSSession } from './ws-session.js';
+import { CoverageClient } from './coverage-client.js';
 
 const getDebuggerUrl = async (options) => {
 
     const protocol = options.secure ? 'https' : 'http';
 
     const url = `${protocol}://${options.host}:${options.port}/json/list`;
-    const [err, res] = await Util.request(url);
+    const [err, res] = await Util.request(url, {
+        timeout: options.timeout
+    });
     if (err) {
         return [err];
     }
@@ -46,49 +47,78 @@ const getCDPUrl = async (options) => {
 
 };
 
-const getCDPSession = async (options) => {
-
-    if (options.session) {
-        return [null, options.session];
-    }
-
-    // create session
-    const [err, url] = await getCDPUrl(options);
-
-    return new Promise((resolve) => {
-
-        if (err) {
-            resolve([err]);
-            return;
-        }
-
-        const timeoutId = setTimeout(() => {
-            resolve([new Error(`Timeout to connect: ${url}`)]);
-        }, options.timeout);
-
+const connectWebSocket = (WebSocket, url, options) => new Promise((resolve) => {
+    let ws;
+    try {
         Util.logDebug(`Connect to ${url}`);
-        const ws = new WebSocket(url, [], {
+        ws = new WebSocket(url, [], {
             maxPayload: 256 * 1024 * 1024,
             perMessageDeflate: false,
             followRedirects: true,
             ... options.ws
         });
-
-        ws.once('error', (wsErr) => {
-            clearTimeout(timeoutId);
-            resolve([wsErr]);
-        });
-
-        ws.once('open', () => {
-            clearTimeout(timeoutId);
-            Util.logDebug(`${EC.green('Connected')} ${url}`);
-            const session = new WSSession(ws);
-            resolve([null, session]);
+    } catch (error) {
+        resolve([error]);
+        return;
+    }
+    let settled = false;
+    let timer;
+    const cleanup = () => {
+        clearTimeout(timer);
+        ws.off('open', onOpen);
+        ws.off('error', onError);
+        ws.off('close', onClose);
+    };
+    const fail = (error) => {
+        if (settled) {
+            return;
+        }
+        settled = true;
+        clearTimeout(timer);
+        ws.off('open', onOpen);
+        resolve([error]);
+        // Keep error/close handlers through termination of a pending handshake.
+        if (ws.readyState !== 3) {
+            ws.terminate();
+        }
+    };
+    const onError = (error) => fail(error);
+    const onClose = () => {
+        fail(new Error(`Connection closed before opening: ${url}`));
+        cleanup();
+    };
+    const onOpen = () => {
+        const session = new WSSession(ws, {
+            timeout: options.requestTimeout
         });
+        settled = true;
+        cleanup();
+        Util.logDebug(`${EC.green('Connected')} ${url}`);
+        resolve([null, session]);
+    };
+    ws.on('error', onError);
+    ws.once('close', onClose);
+    ws.once('open', onOpen);
+    if (options.timeout > 0) {
+        timer = setTimeout(() => fail(new Error(`Timeout to connect: ${url}`)), options.timeout);
+    }
+});
 
-    });
-
-
+const getCDPSession = async (options) => {
+    if (options.session) {
+        return [null, options.session];
+    }
+    for (const key of ['timeout', 'requestTimeout']) {
+        if (!Number.isFinite(options[key]) || options[key] < 0) {
+            return [new RangeError(`${key} must be a non-negative finite number`)];
+        }
+    }
+    const [err, url] = await getCDPUrl(options);
+    if (err) {
+        return [err];
+    }
+    const { WebSocket } = await import('ws');
+    return connectWebSocket(WebSocket, url, options);
 };
 
 
@@ -109,7 +139,8 @@ const CDPClient = async (cdpOptions) => {
             return targets.find((it) => it.webSocketDebuggerUrl);
         },
         ws: {},
-        timeout: 10 * 1000
+        timeout: 10 * 1000,
+        requestTimeout: 30 * 1000
     };
 
     if (typeof cdpOptions === 'string') {
@@ -140,4 +171,4 @@ const CDPClient = async (cdpOptions) => {
 
 };
 
-module.exports = CDPClient;
+export { CDPClient };

package/lib/client/coverage-client.js

@@ -1,4 +1,4 @@
-const Util = require('../utils/util.js');
+import { Util } from '../utils/util.js';
 
 const bindEvents = (target, events) => {
     Object.keys(events).forEach((eventType) => {
@@ -80,6 +80,17 @@ class CoverageClient {
         this.session = session;
     }
 
+    // Best-effort background commands return null when a request fails.
+    // Keep critical commands on session.send() so their errors still propagate.
+    async safeSend(method, params) {
+        try {
+            return await this.session.send(method, params);
+        } catch (error) {
+            Util.logDebug(`${method}: ${error?.message || error}`);
+            return null;
+        }
+    }
+
     // =================================================================================================
     async startJSCoverage() {
         if (!this.session || this.enabledJS) {
@@ -90,14 +101,16 @@ class CoverageClient {
         this.jsEvents = {
             'Debugger.scriptParsed': (params) => {
                 const { scriptId } = params;
-                this.session.send('Debugger.getScriptSource', {
+                this.safeSend('Debugger.getScriptSource', {
                     scriptId
                 }).then((res) => {
-                    this.scriptSources.set(scriptId, res && res.scriptSource);
+                    if (res) {
+                        this.scriptSources.set(scriptId, res.scriptSource);
+                    }
                 });
             },
             'Debugger.paused': () => {
-                this.send('Debugger.resume');
+                this.safeSend('Debugger.resume');
             }
         };
 
@@ -169,11 +182,14 @@ class CoverageClient {
 
                 // anonymous url
                 const url = sourceURL || '';
-                this.session.send('CSS.getStyleSheetText', {
+                this.safeSend('CSS.getStyleSheetText', {
                     styleSheetId
                 }).then((res) => {
+                    if (!res) {
+                        return;
+                    }
                     // add source
-                    const text = res && res.text;
+                    const text = res.text;
                     if (!text) {
                         Util.logDebug(`Not found css source: ${url}`);
                     }
@@ -272,7 +288,7 @@ class CoverageClient {
         // write the coverage started by NODE_V8_COVERAGE to disk on demand
         const res = await this.session.send('Runtime.evaluate', {
             expression: `new Promise((resolve) => { 
-                require("v8").takeCoverage();
+                process.getBuiltinModule("v8").takeCoverage();
                 resolve(process.env.NODE_V8_COVERAGE);
             })`,
             includeCommandLineAPI: true,
@@ -319,4 +335,4 @@ class CoverageClient {
     }
 }
 
-module.exports = CoverageClient;
+export { CoverageClient };