delta-coverage

Enforce code coverage thresholds on only the files and lines you actually changed.

Most coverage gates measure your entire codebase and fail when legacy untested code drags the global percentage below a threshold. delta-coverage solves this by running the gate only on what changed in the current branch — making it both fair and practical for large codebases with existing technical debt.

Features

• Two enforcement modes: file-level (total file coverage) and line-level ("true delta" — only the exact lines you changed)
• Framework-agnostic: works with any test runner that produces Istanbul/nyc-compatible JSON reports (Jest, Vitest, Mocha/nyc, etc.)
• Include/exclude glob filtering: scope the gate to specific cartridges, modules, or directory trees
• Fail-safe: exits 0 when no source files were changed, so non-code pushes are never blocked
• Programmatic API: returns a structured DeltaReport for custom dashboards or CI integrations
• Configurable via .deltarc or package.json — no flags required for standard setups
• Debug mode: prints every path comparison so you always know why a file matched or was skipped

Installation

npm install --save-dev delta-coverage

Quick Start

1. Run your tests and generate a coverage report

delta-coverage is a gatekeeper, not a test runner. Run your test suite first and produce a coverage artifact:

# Jest
npx jest --coverage

# Vitest
npx vitest run --coverage

# Mocha + nyc
npx nyc --reporter=json --reporter=json-summary npm test

2. Run the gate

npx delta-coverage --base origin/main --threshold 80

That's it. The tool will diff your current HEAD against origin/main, identify changed source files, load the coverage report, and fail if any touched file falls below 80%.

How It Works

git diff (merge-base HEAD origin/main)..HEAD
        │
        ▼
  Changed files list
        │
        ▼
  Apply include/exclude globs
        │
        ▼
  Load coverage JSON
        │
   ┌────┴────┐
   │         │
 file      line
 mode      mode
   │         │
   │  coverage-summary.json    coverage-final.json
   │  (total % per file)       (statement-level hits)
   │         │
   └────┬────┘
        │
   Compare against threshold
        │
   Pass / Fail

File mode looks at the total coverage percentage for each changed file from coverage-summary.json.

Line mode cross-references the exact lines in the git diff with statement hit-counts from coverage-final.json. A file passes if the ratio of covered-to-modified statements meets the threshold — regardless of how bad the rest of the file is.

CLI Reference

Usage: delta-coverage [options]

Options:
  --base <ref>           Git ref to diff against        (default: "origin/master")
  --threshold <number>   Minimum coverage % required    (default: 80)
  --check-mode <mode>    "file" or "line"                (default: "file")
  --coverage-dir <path>  Directory containing JSON reports (default: "./coverage")
  --debug                Print detailed path comparison output
  -h, --help             Display help

Exit codes

| Code | Meaning | |------|---------| | 0 | All changed files meet the threshold, or no source files were changed | | 1 | One or more changed files failed the coverage threshold, or an unexpected error occurred |

Configuration

delta-coverage uses cosmiconfig to load configuration. Supported locations (in priority order):

• .deltarc (JSON)
• .deltarc.json
• .deltarc.yaml / .deltarc.yml
• .deltarc.js
• delta-coverage key in package.json
• delta-coverage.config.js

All CLI options can be specified in config. CLI flags take precedence.

Example .deltarc

{
  "base": "origin/main",
  "threshold": 90,
  "checkMode": "line",
  "coverageDir": "./coverage",
  "include": ["src/**/*.ts", "lib/**/*.js"],
  "exclude": ["**/*.spec.ts", "**/generated/**", "**/vendor/**"]
}

Configuration options

| Key | Type | Default | Description | |-----|------|---------|-------------| | base | string | "origin/master" | Git ref (branch, SHA, tag) to diff against | | threshold | number | 80 | Minimum coverage percentage (0–100) | | checkMode | "file" \| "line" | "file" | Enforcement mode | | coverageDir | string | "./coverage" | Directory containing coverage JSON files | | include | string[] | — | Glob patterns — only matching files are gated | | exclude | string[] | — | Glob patterns — matching files are always skipped | | onMissingCoverage | "warn" \| "fail" \| "skip" | "warn" (file) / "fail" (line) | Behaviour when a changed file has no coverage data |

Enforcement Modes

--check-mode file (default)

Uses coverage-summary.json. For each changed file, checks its total line-coverage percentage against the threshold.

Best for: teams moving from zero gates toward measurable quality. Straightforward to understand and explain.

Trade-off: a 1-line change to a large legacy file can block a push if the file's overall coverage is low.

--check-mode line

Uses coverage-final.json. Parses the git diff to identify specific changed line ranges, then checks whether those exact statement positions were executed by tests.

Best for: large enterprise codebases with existing technical debt. Developers are held accountable only for what they wrote.

Pass criteria:

(covered modified statements / total modified statements) × 100 ≥ threshold

Non-executable lines (comments, blank lines, closing braces) are automatically excluded from the count.

Filtering

Use include and exclude to precisely scope the gate:

{
  "include": ["cartridges/app_custom_**/cartridge/scripts/**/*.js"],
  "exclude": [
    "**/static/**",
    "**/*.spec.js",
    "**/test/**",
    "**/node_modules/**"
  ]
}

If no include is specified, all files from the git diff with supported extensions (.js, .ts, .mjs, .cjs) are checked. Files that have no coverage data are treated according to onMissingCoverage.

Integration Examples

package.json script (recommended)

{
  "scripts": {
    "test:gate": "vitest run --coverage && delta-coverage --base origin/main --threshold 85"
  }
}

Husky pre-push hook

# .husky/pre-push
npm run test:coverage && npx delta-coverage --base origin/main --threshold 80

GitHub Actions

- name: Run tests with coverage
  run: npm run test:coverage

- name: Enforce delta coverage
  run: npx delta-coverage --base origin/main --threshold 80 --check-mode line

GitLab CI

test:
  script:
    - npm run test:coverage
    - npx delta-coverage --base origin/main --threshold 80

Programmatic API

Use delta-coverage as a library in your own tooling, CI scripts, or dashboards:

import { runDeltaCheck } from 'delta-coverage';
import type { DeltaReport } from 'delta-coverage';

const report: DeltaReport = await runDeltaCheck({
  base: 'origin/main',
  threshold: 85,
  checkMode: 'line',
  coverageDir: './coverage',
  include: ['src/**/*.ts'],
  exclude: ['**/*.spec.ts'],
});

if (!report.passed) {
  const failed = report.files.filter(f => f.status === 'failed');
  console.error(`${failed.length} file(s) below threshold:`);
  failed.forEach(f => console.error(`  ${f.file}: ${f.pct}% (need ${f.threshold}%)`));
  process.exit(1);
}

DeltaOptions

interface DeltaOptions {
  base: string;           // Git ref to diff against
  threshold: number;      // Coverage threshold (0–100)
  checkMode: 'file' | 'line';
  coverageDir: string;    // Path to directory with coverage JSON
  include?: string[];     // Glob allowlist
  exclude?: string[];     // Glob denylist
  onMissingCoverage?: 'warn' | 'fail' | 'skip';
  debug?: boolean;        // Enable verbose logging
  log?: LogFn;            // Custom logger (level, message) => void
  cwd?: string;           // Working directory (defaults to process.cwd())
}

DeltaReport

interface DeltaReport {
  passed: boolean;
  files: FileResult[];
  summary: {
    total: number;
    passed: number;
    failed: number;
    skipped: number;
    missing: number;
  };
}

interface FileResult {
  file: string;
  status: 'passed' | 'failed' | 'skipped' | 'missing';
  pct?: number;       // Calculated coverage percentage
  threshold?: number; // Threshold that was applied
  message?: string;   // Reason for skipped/missing status
}

Debugging

Run with --debug to see every path that was considered and why it matched or was skipped:

$ delta-coverage --base origin/main --threshold 80 --debug

[debug] Base: origin/main, mode: file, threshold: 80%
[debug] Merge base: a3f1c2d...
[debug] Changed files (raw): src/orders/service.ts, src/orders/mapper.ts
[debug] Filtered files: src/orders/service.ts, src/orders/mapper.ts
✓ src/orders/service.ts: 92% (threshold: 80%)
✗ src/orders/mapper.ts: 71% (threshold: 80%)
Results: 1 passed, 1 failed, 0 skipped, 0 missing
✗ Coverage check failed. Fix coverage on changed files before pushing.

Requirements

• Node.js >= 16
• Git must be available in PATH
• A compatible coverage report must be generated before running delta-coverage:
  • File mode: requires coverage-summary.json (Istanbul/nyc format)
  • Line mode: requires coverage-final.json (Istanbul/nyc format)

License

MIT