superc8 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2016-now coderaiser
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,206 @@
+# superc8 - native V8 code-coverage
+
+[![ci](https://github.com/bcoe/c8/actions/workflows/ci.yaml/badge.svg)](https://github.com/bcoe/c8/actions/workflows/ci.yaml)
+![nycrc config on GitHub](https://img.shields.io/nycrc/bcoe/c8)
+[![Conventional Commits](https://img.shields.io/badge/Conventional%20Commits-1.0.0-yellow.svg)](https://www.conventionalcommits.org/)
+
+## Fork of `c8` contains
+
+- ✅ Fixed TODO ([`parase-args#L176`](https://github.com/bcoe/c8/blob/main/lib/parse-args.js#L176), [`check-coverage#L14`](https://github.com/bcoe/c8/blob/ee2f1cfc5584d41bb2d51b788d0953dab0c798f8/lib/commands/check-coverage.js#L14));
+- ✅ ESM-only code;
+- ✅ Updated dependencies, including `yargs` that makes `node v25` crash (https://github.com/bcoe/c8/issues/582);
+- ✅ Applied 🐊[**Putout**](https://github.com/coderaiser/putout) default suggestions;
+
+Code-coverage using [Node.js' built in functionality](https://nodejs.org/dist/latest-v10.x/docs/api/cli.html#cli_node_v8_coverage_dir)
+that's compatible with [Istanbul's reporters](https://istanbul.js.org/docs/advanced/alternative-reporters/).
+
+Like [nyc](https://github.com/istanbuljs/nyc), c8 just magically works:
+
+```sh
+npm i superc8 -g
+c8 node foo.js
+```
+
+The above example will output coverage metrics for `foo.js`.
+
+## CLI Options / Configuration
+
+c8 can be configured via command-line flags, a `c8` section in `package.json`, or a JSON configuration file on disk.
+
+A configuration file can be specified by passing its path on the command line with `--config` or `-c`. If no config option is provided, c8 searches for files named `.c8rc`, `.c8rc.json`, `.nycrc`, or `.nycrc.json`, starting from
+`cwd` and walking up the filesystem tree.
+
+When using `package.json` configuration or a dedicated configuration file, omit the `--` prefix from the long-form of the desired command-line option.
+
+Here is a list of common options. Run `c8 --help` for the full list and documentation.
+
+| Option | Description | Type | Default |
+| ------ | ----------- | ---- | ------- |
+| `-c`, `--config` | path to JSON configuration file | `string` | See above |
+| `-r`, `--reporter` | coverage reporter(s) to use | `Array<string>` | `['text']` |
+| `-o`, `--reports-dir`, `--report-dir` | directory where coverage reports will be output to | `string` | `./coverage` |
+| `--all` | see [section below](#checking-for-full-source-coverage-using---all) for more info | `boolean` | `false` |
+| `--src` | see [section below](#checking-for-full-source-coverage-using---all) for more info | `Array<string>` | `[process.cwd()]`|
+| `-n`, `--include` | see [section below](#checking-for-full-source-coverage-using---all) for more info | `Array<string>` | `[]` (include all files) |
+| `-x`, `--exclude` | see [section below](#checking-for-full-source-coverage-using---all) for more info | `Array<string>` | [list](https://github.com/istanbuljs/schema/blob/master/default-exclude.js) |
+| `--exclude-after-remap` | see [section below](#exclude-after-remap) for more info | `boolean` | `false` |
+| `-e`, `--extension` | only files matching these extensions will show coverage | `string \| Array<string>` | [list](https://github.com/istanbuljs/schema/blob/master/default-extension.js) |
+| `--skip-full` | do not show files with 100% statement, branch, and function coverage | `boolean` | `false` |
+| `--check-coverage` | check whether coverage is within thresholds provided | `boolean` | `false` |
+| `--per-file` | check thresholds per file | `boolean` | `false` |
+| `--temp-directory` | directory V8 coverage data is written to and read from | `string` | `process.env.NODE_V8_COVERAGE` |
+| `--clean` | should temp files be deleted before script execution | `boolean` | `true` |
+| `--experimental-monocart` | see [section below](#using-monocart-coverage-reports-experimental) for more info | `boolean` | `false` |
+
+## Checking for "full" source coverage using `--all`
+
+By default v8 will only give us coverage for files that were loaded by the engine. If there are source files in your
+project that are flexed in production but not in your tests, your coverage numbers will not reflect this. For example,
+if your project's `main.js` loads `a.js` and `b.js` but your unit tests only load `a.js` your total coverage
+could show as `100%` for `a.js` when in fact both `main.js` and `b.js` are uncovered.
+
+By supplying `--all` to c8, all files in directories specified with `--src` (defaults to `cwd`) that pass the `--include`
+and `--exclude` flag checks, will be loaded into the report. If any of those files remain uncovered they will be factored
+into the report with a default of 0% coverage.
+
+## SourceMap Support
+
+`c8` can handle source-maps, for remapping coverage from generated code to original source files (*useful for TypeScript, JSX, etc*).
+
+### Source map files versus inline source maps
+
+Just-in-time instrumented codebases will often insert source maps inline with the `.js` code they generate at runtime (e.g, `@babel/register` can be configured to insert a source map footer).
+
+Pre-instrumented codebases, e.g., running `tsc` to generate `.js` in a build folder, may generate either inline source maps, or a separate `.map` file stored on disk.
+
+`c8` can handle loading both types of source maps.
+
+### Exclude after remap
+
+Depending on the size and configuration of your project, it may be preferable to apply exclusion logic either before or after source-maps are used to remap compiled to original source files.
+
+`--exclude-after-remap` is used to control this behaviour.
+
+## c8 report
+
+run `c8 report` to regenerate reports after `c8` has already been run.
+
+## Checking coverage
+
+c8 can fail tests if coverage falls below a threshold.
+After running your tests with c8, simply run:
+
+```sh
+c8 check-coverage --lines 95 --functions 95 --branches 95
+```
+
+c8 also accepts a `--check-coverage` shorthand, which can be used to
+both run tests and check that coverage falls within the threshold provided:
+
+```sh
+c8 --check-coverage --lines 100 npm test
+```
+
+The above check fails if coverage falls below 100%.
+
+To check thresholds on a per-file basis run:
+
+```sh
+c8 check-coverage --lines 95 --per-file
+```
+
+If you want to check for 100% coverage across all dimensions, use `--100`:
+
+```sh
+c8 --100 npm test
+```
+
+Is equivalent to
+
+```sh
+c8 --check-coverage --lines 100 --functions 100 --branches 100 --statements 100  npm test
+```
+
+The `--100` flag can be set for the `check-coverage` as well:
+
+```sh
+c8 check-coverage --100
+```
+
+## Using Monocart coverage reports (experimental)
+
+Monocart is an alternate library for outputting [v8 code coverage](https://v8.dev/blog/javascript-code-coverage) data as Istanbul reports.
+
+Monocart also provides reporters based directly on v8's byte-offset-based output. Such as, `console-details` and `v8`. This removes a complex transformation step and may be less bug prone for some environments.
+
+**Example usage:**
+
+```sh
+c8 --experimental-monocart --reporter=v8 --reporter=console-details node foo.js
+```
+
+NOTE: Monocart requires additional `monocart-coverage-reports` to be installed:
+
+```sh
+npm i monocart-coverage-reports@2 --save-dev
+```
+
+## Ignoring Uncovered Lines, Functions, and Blocks
+
+Sometimes you might find yourself wanting to ignore uncovered portions of your
+codebase. For example, perhaps you run your tests on Linux, but
+there's some logic that only executes on Windows.
+
+To ignore lines, blocks, and functions, use the special comment:
+
+`/* c8 ignore next */`.
+
+### Ignoring the next line
+
+```js
+const myVariable = 99;
+
+/* c8 ignore next */
+if (process.platform === 'win32')
+    console.info('hello world');
+```
+
+### Ignoring the next N lines
+
+```js
+const myVariable = 99;
+
+/* c8 ignore next 3 */
+if (process.platform === 'win32') {
+    console.info('hello world');
+}
+```
+
+### Ignoring all lines until told
+
+```js
+/* c8 ignore start */
+function dontMindMe() {
+    // ...
+} /* c8 ignore stop */
+```
+
+### Ignoring a block on the current line
+
+```js
+const myVariable = 99;
+const os = process.platform === 'darwin' ? 'OSXy' /* c8 ignore next */ : 'Windowsy';
+```
+
+## Supported Node.js Versions
+
+c8 uses [native V8 coverage](https://github.com/nodejs/node/pull/22527),
+make sure you're running Node.js `>= 22`.
+
+## Contributing to `c8`
+
+See the [contributing guide here](./CONTRIBUTING.md).
+
+## License
+
+MIT

package/bin/c8.js

@@ -0,0 +1,51 @@
+#!/usr/bin/env node
+
+import {rm, mkdir} from 'node:fs/promises';
+import process from 'node:process';
+import {foregroundChild} from 'foreground-child';
+import {tryToCatch} from 'try-to-catch';
+import {outputReport} from '../lib/commands/report.js';
+import {
+    buildYargs,
+    hideInstrumenteeArgs,
+    hideInstrumenterArgs,
+} from '../lib/parse-args.js';
+
+const instrumenterArgs = hideInstrumenteeArgs();
+let argv = buildYargs().parse(instrumenterArgs);
+
+const [error] = await tryToCatch(run);
+
+if (error) {
+    console.error(error.stack);
+    process.exitCode = 1;
+}
+
+async function run() {
+    if ([
+        'check-coverage',
+        'report',
+    ].includes(argv._[0])) {
+        argv = buildYargs(true).parse(process.argv.slice(2));
+    } else {
+        if (argv.clean)
+            await rm(argv.tempDirectory, {
+                recursive: true,
+                force: true,
+            });
+        
+        await mkdir(argv.tempDirectory, {
+            recursive: true,
+        });
+        process.env.NODE_V8_COVERAGE = argv.tempDirectory;
+        foregroundChild(hideInstrumenterArgs(argv), async () => {
+            try {
+                await outputReport(argv);
+                return process.exitCode;
+            } catch(err) {
+                console.error(err.stack);
+                return 1;
+            }
+        });
+    }
+}

package/index.d.ts

@@ -0,0 +1,32 @@
+export type Watermark = [
+    number,
+    number,
+];
+
+export declare class Report {
+    constructor(opts: {
+        exclude?: string | string[];
+        extension?: string | string[];
+        excludeAfterRemap?: boolean;
+        include?: string | string[];
+        reporter: string[];
+        reportsDirectory?: string;
+        reporterOptions?: Record<string, Record<string, unknown>>;
+        tempDirectory?: string;
+        watermarks?: Partial<{
+            statements: Watermark;
+            functions: Watermark;
+            branches: Watermark;
+            lines: Watermark;
+        }>;
+        omitRelative?: boolean;
+        wrapperLength?: number;
+        resolve?: string;
+        all?: boolean;
+        src?: string[];
+        allowExternal?: boolean;
+        skipFull?: boolean;
+        excludeNodeModules?: boolean;
+    });
+    run(): Promise<void>;
+}

package/index.js

@@ -0,0 +1 @@
+export * as Report from './lib/report.js';

package/lib/commands/check-coverage.js

@@ -0,0 +1,83 @@
+import {relative} from 'node:path';
+import process from 'node:process';
+import {Report} from '../report.js';
+
+const {isArray} = Array;
+const maybeArray = (a) => isArray(a) ? a : [a];
+const consoleError = console.error;
+
+export const command = 'check-coverage';
+
+export const describe = 'check whether coverage is within thresholds provided';
+
+export const builder = function(yargs) {
+    yargs.example('$0 check-coverage --lines 95', `check whether the JSON in c8's output folder meets the thresholds provided`);
+};
+
+export const handler = function(argv) {
+    // TODO: this is a workaround until yargs gets upgraded to v17, see https://github.com/bcoe/c8/pull/332#discussion_r721636191
+    if (argv['100']) {
+        argv.lines = 100;
+        argv.functions = 100;
+        argv.branches = 100;
+        argv.statements = 100;
+    }
+    
+    const report = Report({
+        include: argv.include,
+        exclude: argv.exclude,
+        extension: argv.extension,
+        reporter: maybeArray(argv.reporter),
+        reportsDirectory: argv['reports-dir'],
+        tempDirectory: argv.tempDirectory,
+        watermarks: argv.watermarks,
+        resolve: argv.resolve,
+        omitRelative: argv.omitRelative,
+        wrapperLength: argv.wrapperLength,
+        all: argv.all,
+    });
+    
+    checkCoverages(argv, report);
+};
+
+export const checkCoverages = async function(argv, report) {
+    const thresholds = {
+        lines: argv.lines,
+        functions: argv.functions,
+        branches: argv.branches,
+        statements: argv.statements,
+    };
+    
+    const map = await report.getCoverageMapFromAllCoverageFiles();
+    
+    if (argv.perFile)
+        for (const file of map.files()) {
+            checkCoverage(
+                map
+                    .fileCoverageFor(file)
+                    .toSummary(),
+                thresholds,
+                file,
+            );
+        }
+    
+    else
+        checkCoverage(map.getCoverageSummary(), thresholds);
+};
+
+function checkCoverage(summary, thresholds, file) {
+    for (const key of Object.keys(thresholds)) {
+        const coverage = summary[key].pct;
+        
+        if (coverage < thresholds[key]) {
+            process.exitCode = 1;
+            
+            if (file) {
+                // standardize path for Windows.
+                consoleError('ERROR: Coverage for ' + key + ' (' + coverage + '%) does not meet threshold (' + thresholds[key] + '%) for ' + relative('./', file).replace(/\\/g, '/'));
+            } else {
+                consoleError('ERROR: Coverage for ' + key + ' (' + coverage + '%) does not meet global threshold (' + thresholds[key] + '%)');
+            }
+        }
+    }
+}

package/lib/commands/report.js

@@ -0,0 +1,43 @@
+import process from 'node:process';
+import {checkCoverages} from './check-coverage.js';
+import {Report} from '../report.js';
+
+const {isArray} = Array;
+const maybeArray = (a) => isArray(a) ? a : [a];
+
+export const command = 'report';
+
+export const describe = 'read V8 coverage data from temp and output report';
+
+export const handler = async function(argv) {
+    await outputReport(argv);
+};
+
+export const outputReport = async function(argv) {
+    const report = Report({
+        include: argv.include,
+        exclude: argv.exclude,
+        extension: argv.extension,
+        excludeAfterRemap: argv.excludeAfterRemap,
+        reporter: maybeArray(argv.reporter),
+        reportsDirectory: argv['reports-dir'],
+        reporterOptions: argv.reporterOptions || {},
+        tempDirectory: argv.tempDirectory,
+        watermarks: argv.watermarks,
+        resolve: argv.resolve,
+        omitRelative: argv.omitRelative,
+        wrapperLength: argv.wrapperLength,
+        all: argv.all,
+        allowExternal: argv.allowExternal,
+        src: argv.src,
+        skipFull: argv.skipFull,
+        excludeNodeModules: argv.excludeNodeModules,
+        mergeAsync: argv.mergeAsync,
+        monocartArgv: argv.experimentalMonocart || process.env.EXPERIMENTAL_MONOCART ? argv : null,
+    });
+    
+    await report.run();
+    
+    if (argv.checkCoverage)
+        await checkCoverages(argv, report);
+};

package/lib/parse-args.js

@@ -0,0 +1,229 @@
+import {readFileSync} from 'node:fs';
+import {resolve} from 'node:path';
+import process from 'node:process';
+import defaultExclude from '@istanbuljs/schema/default-exclude.js';
+import defaultExtension from '@istanbuljs/schema/default-extension.js';
+import {findUpSync} from 'find-up';
+import Yargs from 'yargs/yargs';
+import {applyExtends} from 'yargs/helpers';
+import parser from 'yargs-parser';
+import * as checkCoverage from './commands/check-coverage.js';
+import * as report from './commands/report.js';
+
+export function buildYargs(withCommands = false) {
+    const yargs = Yargs([])
+        .usage('$0 [opts] [script] [opts]')
+        .options('config', {
+            alias: 'c',
+            config: true,
+            describe: 'path to JSON configuration file',
+            configParser: (path) => {
+                const config = JSON.parse(readFileSync(path));
+                return applyExtends(config, process.cwd(), true);
+            },
+            default: () => findUpSync([
+                '.c8rc',
+                '.c8rc.json',
+                '.nycrc',
+                '.nycrc.json',
+            ]),
+        })
+        .option('reporter', {
+            alias: 'r',
+            group: 'Reporting options',
+            describe: 'coverage reporter(s) to use',
+            default: 'text',
+        })
+        .option('reports-dir', {
+            alias: ['o', 'report-dir'],
+            group: 'Reporting options',
+            describe: 'directory where coverage reports will be output to',
+            default: './coverage',
+        })
+        .options('all', {
+            default: false,
+            type: 'boolean',
+            group: 'Reporting options',
+            describe: 'supplying --all will cause c8 to consider all src files in the current working directory ' + 'when the determining coverage. Respects include/exclude.',
+        })
+        .options('src', {
+            default: undefined,
+            type: 'string',
+            group: 'Reporting options',
+            describe: 'supplying --src will override cwd as the default location where --all looks for src files. --src can be ' + 'supplied multiple times and each directory will be included. This allows for workspaces spanning multiple projects',
+        })
+        .option('exclude-node-modules', {
+            default: true,
+            type: 'boolean',
+            describe: 'whether or not to exclude all node_module folders (i.e. **/node_modules/**) by default',
+        })
+        .option('include', {
+            alias: 'n',
+            default: [],
+            group: 'Reporting options',
+            describe: 'a list of specific files that should be covered (glob patterns are supported)',
+        })
+        .option('exclude', {
+            alias: 'x',
+            default: defaultExclude,
+            group: 'Reporting options',
+            describe: 'a list of specific files and directories that should be excluded from coverage (glob patterns are supported)',
+        })
+        .option('extension', {
+            alias: 'e',
+            default: defaultExtension,
+            group: 'Reporting options',
+            describe: 'a list of specific file extensions that should be covered',
+        })
+        .option('exclude-after-remap', {
+            alias: 'a',
+            type: 'boolean',
+            default: false,
+            group: 'Reporting options',
+            describe: 'apply exclude logic to files after they are remapped by a source-map',
+        })
+        .options('skip-full', {
+            default: false,
+            type: 'boolean',
+            group: 'Reporting options',
+            describe: 'do not show files with 100% statement, branch, and function coverage',
+        })
+        .option('check-coverage', {
+            default: false,
+            type: 'boolean',
+            group: 'Coverage thresholds',
+            description: 'check whether coverage is within thresholds provided',
+        })
+        .option('branches', {
+            default: 0,
+            group: 'Coverage thresholds',
+            description: 'what % of branches must be covered?',
+            type: 'number',
+        })
+        .option('functions', {
+            default: 0,
+            group: 'Coverage thresholds',
+            description: 'what % of functions must be covered?',
+            type: 'number',
+        })
+        .option('lines', {
+            default: 90,
+            group: 'Coverage thresholds',
+            description: 'what % of lines must be covered?',
+            type: 'number',
+        })
+        .option('statements', {
+            default: 0,
+            group: 'Coverage thresholds',
+            description: 'what % of statements must be covered?',
+            type: 'number',
+        })
+        .option('per-file', {
+            default: false,
+            group: 'Coverage thresholds',
+            description: 'check thresholds per file',
+            type: 'boolean',
+        })
+        .option('100', {
+            default: false,
+            group: 'Coverage thresholds',
+            description: 'shortcut for --check-coverage --lines 100 --functions 100 --branches 100 --statements 100',
+            type: 'boolean',
+        })
+        .option('temp-directory', {
+            describe: 'directory V8 coverage data is written to and read from',
+            default: process.env.NODE_V8_COVERAGE,
+        })
+        .option('clean', {
+            default: true,
+            type: 'boolean',
+            describe: 'should temp files be deleted before script execution',
+        })
+        .option('resolve', {
+            default: '',
+            describe: 'resolve paths to alternate base directory',
+        })
+        .option('wrapper-length', {
+            describe: 'how many bytes is the wrapper prefix on executed JavaScript',
+            type: 'number',
+        })
+        .option('omit-relative', {
+            default: true,
+            type: 'boolean',
+            describe: 'omit any paths that are not absolute, e.g., internal/net.js',
+        })
+        .options('allowExternal', {
+            default: false,
+            type: 'boolean',
+            describe: 'supplying --allowExternal will cause c8 to allow files from outside of your cwd. This applies both to ' + 'files discovered in coverage temp files and also src files discovered if using the --all flag.',
+        })
+        .options('merge-async', {
+            default: false,
+            type: 'boolean',
+            describe: 'supplying --merge-async will merge all v8 coverage reports asynchronously and incrementally. ' + 'This is to avoid OOM issues with Node.js runtime.',
+        })
+        .option('experimental-monocart', {
+            default: false,
+            type: 'boolean',
+            describe: 'Use Monocart coverage reports',
+        })
+        .pkgConf('c8')
+        .demandCommand(1)
+        .check((argv) => {
+            if (!argv.tempDirectory)
+                argv.tempDirectory = resolve(argv.reportsDir, 'tmp');
+            
+            return true;
+        })
+        .epilog('visit https://git.io/vHysA for list of available reporters');
+    
+    yargs.middleware((argv) => {
+        if (!argv['100'])
+            return argv;
+        
+        return {
+            ...argv,
+            branches: 100,
+            functions: 100,
+            lines: 100,
+            statements: 100,
+            checkCoverage: 100,
+        };
+    });
+    
+    if (withCommands) {
+        yargs.command(checkCoverage);
+        yargs.command(report);
+    } else {
+        yargs.command(checkCoverage.command, checkCoverage.describe);
+        yargs.command(report.command, report.describe);
+    }
+    
+    return yargs;
+}
+
+export function hideInstrumenterArgs(yargv) {
+    let argv = process.argv.slice(1);
+    
+    argv = argv.slice(argv.indexOf(yargv._[0]));
+    
+    if (argv[0][0] === '-')
+        argv.unshift(process.execPath);
+    
+    return argv;
+}
+
+export function hideInstrumenteeArgs() {
+    let argv = process.argv.slice(2);
+    const yargv = parser(argv);
+    
+    if (!yargv._.length)
+        return argv;
+    
+    // drop all the arguments after the bin being
+    // instrumented by c8.
+    argv = argv.slice(0, argv.indexOf(yargv._[0]));
+    argv.push(yargv._[0]);
+    
+    return argv;
+}