@spikedpunch/cbd-cli

The cbd binary for CBD: record a coverage map, ask which tests a change reaches, and explain the answer.

pnpm add -D @spikedpunch/cbd-cli @spikedpunch/cbd
# plus the adapter for your runner, e.g. @spikedpunch/cbd-japa

Commands

cbd --version
cbd build   [--commit <sha>] [--partial] [--root <dir>] [--format json]
cbd select  [--since <ref>] [--no-worktree] [--strict] [--commit <sha>]
cbd explain <file>[:<line>] [--root <dir>] [--format json]
cbd reaches <test-title> <file>[:<line>] [--file <test-file>] [--format json]
cbd stats   [--commit <sha>] [--root <dir>] [--format json]
cbd collect [--no-select] [--no-build] [--shard <path>] -- <test command>
cbd gc      [--keep <n>] [--root <dir>] [--format json]

The root is, within the git top level, the nearest directory upward containing a cbd.config.json, else the git top level itself; outside git, the nearest config, else the working directory. A config above the git top level is not used. --root overrides it. The config is <root>/cbd.config.json unless --config names another; a missing default config means safe defaults, a missing explicit one is an error. cbd --version prints the CLI and core versions, and select --format json carries cbdVersion.

cbd collect

Runs the test command with CBD_SHARD and CBD_COMMIT set, optionally narrows it with CBD_SELECTION, then builds the map in the same process.

pnpm exec cbd collect -- pnpm test
pnpm exec cbd collect --no-select -- pnpm test   # full recording, never narrow

Select and build are on by default once collection is asked for; --no-select and --no-build turn each off. On a repository's first run there is no map, so the honest answer is a full recording, not an error. An interrupted child leaves a shard with no footer, which is refused rather than built.

The adapters are inert unless CBD_SHARD is set, so the same test script works for ordinary runs and for cbd collect.

cbd select

Diffs the map's commit against the working tree (or --since <ref> / --no-worktree for HEAD) and prints the tests to run, with the reasons.

pnpm exec cbd select
pnpm exec cbd select --since origin/main --format json

Exit codes are part of the interface:

| Exit | Meaning | | --- | --- | | 0 | A subset was selected. | | 3 | The answer is "run all"; the reason is printed. | | 1 | Failure (no map, stale shard, git error). | | 2 | Bad arguments. |

A script can therefore branch without parsing output:

pnpm exec cbd select
status=$?
case $status in
  0) run_selected_only ;;
  3) run_everything ;;
  *) exit "$status" ;;
esac

cbd explain and cbd reaches

explain answers "what reaches this file or line?": the functions and the tests whose windows touched them. reaches answers the inverse for one test, which is useful when reading a test or asking a mutation-testing question.

pnpm exec cbd explain src/router.ts:42
pnpm exec cbd reaches 'handles a refund' src/payments.ts --file tests/refund.spec.ts
pnpm exec cbd reaches 'handles a refund' src/payments.ts --format json

A bare title that names more than one test is refused; --file picks one.

cbd stats

Summarises a map: tests, mapped functions, reached and seen files, untested files, bucket sizes, tests per test file, functions per file, tests per function, and the widest files. --format json prints the same object.

cbd build

Merges shards into a map. By default it takes the shards under .cbd/shards whose header names the target commit, so a stale shard from an earlier run does not leak into a new map. --partial accepts a shard with no footer (an interrupted run) when that is deliberate.

cbd gc

Keeps the newest --keep runs of each kind (default 10) under the state directory, always keeps the map select is using, and touches nothing else in .cbd.

Typical workflows

First recording

pnpm exec cbd collect -- pnpm test

Inner loop

pnpm exec cbd select            # what does my working-tree change reach?
pnpm exec cbd select --since origin/main

CI

pnpm exec cbd collect -- pnpm test   # refresh the map for this commit
pnpm exec cbd select --format json   # branch on exit code / parse the subset

Inspect

pnpm exec cbd stats
pnpm exec cbd explain src/router.ts:42

Configuration

The CLI reads the same cbd.config.json as the library:

{
  "$schema": "./node_modules/@spikedpunch/cbd/cbd.config.schema.json",
  "include": ["src/**", "tests/**"],
  "alwaysAll": ["data/**"],
  "maxAgeCommits": 50,
  "strict": false
}

See the root README for every key.

Requirements

Node.js 20.16+ and git on PATH. The CLI depends on @spikedpunch/cbd; the runner adapter is a separate package.