c8 7.7.3 → 7.8.0

package/CHANGELOG.md

@@ -2,6 +2,13 @@
 
 All notable changes to this project will be documented in this file. See [standard-version](https://github.com/conventional-changelog/standard-version) for commit guidelines.
 
+## [7.8.0](https://www.github.com/bcoe/c8/compare/v7.7.3...v7.8.0) (2021-07-10)
+
+
+### Features
+
+* add --config option and documentation on options and configs ([#308](https://www.github.com/bcoe/c8/issues/308)) ([99436ef](https://www.github.com/bcoe/c8/commit/99436ef131c2ab966174b5012fe22e499fb44ccd))
+
 ### [7.7.3](https://www.github.com/bcoe/c8/compare/v7.7.2...v7.7.3) (2021-06-03)
 
 

package/README.md

@@ -16,6 +16,31 @@ 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) |
+| `--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` |
+| `--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` |
+
 ## 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
@@ -23,8 +48,9 @@ project that are flexed in production but not in your tests, your coverage numbe
 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 `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.
+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.
 
 ## c8 report
 

package/lib/parse-args.js

@@ -5,65 +5,100 @@ const Yargs = require('yargs/yargs')
 const parser = require('yargs-parser')
 const { resolve } = require('path')
 
-const configPath = findUp.sync(['.c8rc', '.c8rc.json', '.nycrc', '.nycrc.json'])
-const config = configPath ? JSON.parse(readFileSync(configPath)) : {}
-
 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) => JSON.parse(readFileSync(path)),
+      default: () => findUp.sync(['.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('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('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'
     })
-    .option('include', {
-      alias: 'n',
-      default: [],
-      describe: 'a list of specific files that should be covered (glob patterns are supported)'
+    .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'
     })
@@ -71,6 +106,11 @@ function buildYargs (withCommands = false) {
       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'
@@ -84,36 +124,13 @@ function buildYargs (withCommands = false) {
       type: 'boolean',
       describe: 'omit any paths that are not absolute, e.g., internal/net.js'
     })
-    .option('clean', {
-      default: true,
-      type: 'boolean',
-      describe: 'should temp files be deleted before script execution'
-    })
-    .options('all', {
-      default: false,
-      type: 'boolean',
-      describe: 'supplying --all will cause c8 to consider all src files in the current working directory ' +
-        'when the determining coverage. Respects include/exclude.'
-    })
     .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('src', {
-      default: undefined,
-      type: 'string',
-      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'
-    })
-    .options('skip-full', {
-      default: false,
-      type: 'boolean',
-      describe: 'do not show files with 100% statement, branch, and function coverage'
-    })
     .pkgConf('c8')
-    .config(config)
     .demandCommand(1)
     .check((argv) => {
       if (!argv.tempDirectory) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "c8",
-  "version": "7.7.3",
+  "version": "7.8.0",
   "description": "output coverage reports using Node.js' built in coverage",
   "main": "./index.js",
   "types": "./index.d.ts",
@@ -49,7 +49,7 @@
   "devDependencies": {
     "chai": "^4.2.0",
     "chai-jest-snapshot": "^2.0.0",
-    "mocha": "^8.1.3",
+    "mocha": "^9.0.0",
     "standard": "^16.0.3",
     "ts-node": "^9.0.0",
     "typescript": "^4.0.0"