Skip to content
llbblPublic

About

find and report on low test coverage JS or TS

Topics

Resources

Stars

1 star

Watchers

0 watching

Forks

Repository files navigation

uncov

CI codecov License: MIT

A zero-dependency CLI tool that reports files with low test coverage from Vitest/Istanbul JSON output.

Features

  • Zero dependencies - Single binary, instant startup
  • Zero config - Just run uncov in any project with coverage output
  • Cross-platform - Binaries for macOS (arm64, x64), Linux (x64), Windows (x64)
  • CI-friendly - JSON output, exit codes for automation
  • Optional setup - Bootstrap coverage scripts with uncov init

Installation

Quick Install (Recommended)

curl -fsSL https://raw.githubusercontent.com/llbbl/uncov/main/install.sh | bash

This automatically detects your platform, downloads the latest binary, verifies the checksum, and installs to your PATH.

Homebrew

brew install llbbl/tap/uncov

To install by short name, run brew tap llbbl/tap and brew trust --formula llbbl/tap/uncov first. Whole-tap trust is also available with brew trust --tap llbbl/tap and covers all current and future formulas, casks, and commands in the shared tap.

If you previously installed from llbbl/uncov, see the migration instructions. The shared tap checks for releases every six hours after a 24-hour hold; Homebrew availability usually follows a release by about 24–30 hours.

npm / pnpm / bun

# npm
npm install -g uncov

# pnpm
pnpm add -g uncov

# bun
bun add -g uncov

Download Binary

Download the latest release for your platform from GitHub Releases.

# macOS (Apple Silicon)
curl -fsSL https://github.com/llbbl/uncov/releases/latest/download/uncov-darwin-arm64 -o uncov
chmod +x uncov
sudo mv uncov /usr/local/bin/

# macOS (Intel)
curl -fsSL https://github.com/llbbl/uncov/releases/latest/download/uncov-darwin-x64 -o uncov
chmod +x uncov
sudo mv uncov /usr/local/bin/

# Linux
curl -fsSL https://github.com/llbbl/uncov/releases/latest/download/uncov-linux-x64 -o uncov
chmod +x uncov
sudo mv uncov /usr/local/bin/

Build from Source

git clone https://github.com/llbbl/uncov.git
cd uncov
bun install
bun run build:local

Quick Start

  1. Run your tests with coverage:

    pnpm test:coverage
    # or
    vitest run --coverage
  2. Report low coverage files:

    uncov

Output:

Files at or below 10% line coverage: 3

   0.00%  LH    0/LF  120   src/renderer.ts
   5.26%  LH    2/LF   38   src/bootstrap.ts
  10.00%  LH   10/LF  100   src/engine.ts

Commands

uncov (default)

Report files below coverage threshold.

uncov                     # Files at or below 10% coverage (default)
uncov --threshold 50      # Files at or below 50% coverage
uncov --threshold 0       # Only 0% coverage files
uncov --fail              # Exit 1 if any files below threshold
uncov --json              # JSON output for scripting
uncov --verbose           # Show debug information
uncov --no-color          # Disable colorized output

uncov init

Bootstrap coverage configuration in your project.

uncov init                # Interactive setup
uncov init --force        # Overwrite existing config
uncov init --dry-run      # Preview changes without modifying files

This command:

  1. Detects your package manager (pnpm, bun, npm, yarn)
  2. Adds scripts to package.json:
    • test:coverage - Run tests with coverage
    • coverage:low - Run uncov
  3. Creates vitest.config.ts with coverage settings
  4. Adds coverage/ to .gitignore

uncov check

Verify coverage setup is correct.

uncov check               # Verify setup
uncov check --verbose     # Show detailed check information

Checks:

  • Vitest config exists
  • Coverage config is present
  • coverage-summary.json exists
  • Required scripts are configured

Configuration

uncov.config.json

{
  "threshold": 10,
  "exclude": ["**/*.test.ts", "**/index.ts"],
  "failOnLow": false,
  "coveragePath": "coverage/coverage-summary.json"
}

package.json

{
  "uncov": {
    "threshold": 20,
    "failOnLow": true
  }
}

Configuration Priority

  1. CLI flags (highest)
  2. uncov.config.json
  3. package.json uncov field
  4. Defaults (lowest)

Exit Codes

Code Meaning
0 Success (or low coverage files found but --fail not set)
1 Low coverage files found and --fail set
2 Missing coverage-summary.json or config error

Development

Setup

git clone https://github.com/llbbl/uncov.git
cd uncov
bun install

Commands

Using Just (recommended):

just              # Show available commands
just install      # Install dependencies
just dev          # Run CLI locally
just dev --help   # Run CLI with args
just test         # Run tests
just lint         # Lint with Biome
just lint-fix     # Fix lint issues
just build        # Build local binary
just build-all    # Build all platform binaries
just check        # Run lint + tests
just clean        # Remove build artifacts

Or using bun directly:

bun run dev           # Run CLI locally
bun test              # Run tests
bun run lint          # Lint with Biome
bun run lint:fix      # Fix lint issues
bun run build:local   # Build local binary
bun run build         # Build all platform binaries

Commit and release rules

Use a Conventional Commit subject for your PR title and the commit that lands on main. Use type: description or type(scope): description, such as fix(cli): handle empty input. Squash PRs using the title as the subject and leave the commit body empty.

Commit type Release
feat Minor
fix, perf, refactor, revert Patch
chore, docs, test, style, ci, build Skip

Auto Release validates every full commit message since the latest release tag on main. A malformed message, ! before the subject colon, or a BREAKING CHANGE: or BREAKING-CHANGE: marker in the body stops the release. If the range contains a feat, it takes precedence over patch changes. A range containing only skip types creates no release. Release and npm publishing accept stable v0.MINOR.PATCH tags, and the npm tag must match package.json.

Project Structure

uncov/
├── src/
│   ├── cli.ts              # Entry point, arg parsing
│   ├── commands/           # Command implementations
│   ├── lib/                # Core logic
│   └── utils/              # Helpers
├── test/                   # Tests
├── scripts/
│   └── build.ts            # Cross-platform build
└── docs/
    └── spec.md             # Full specification

See docs/spec.md for the full specification.

License

MIT

About

find and report on low test coverage JS or TS

Topics

Resources

Stars

1 star

Watchers

0 watching

Forks

Releases

Packages

Used by

Contributors

Languages