coverctl

Declarative, domain-aware coverage enforcement for any language Supports Go, Python, TypeScript/JavaScript, Java, and Rust. Built with strict Domain-Driven Design layers, TDD-first validation, and automated releases powered by Relicta v2.6.1.

Overview

coverctl enforces domain-aware coverage policies across multiple languages. It auto-detects your project's language and parses coverage profiles from various formats (Go cover profiles, LCOV, Cobertura, JaCoCo), so coverage policy failures surface at the domain level, not just the module level. It autodetects domains, emits human-readable and JSON reports, surfaces warnings when files overlap multiple domains, and keeps builds consistently above target coverage.

Supported Languages

Language	Coverage Format	Auto-Detection
Go	Native go test -cover	go.mod, go.sum
Python	Cobertura, LCOV	pyproject.toml, setup.py, requirements.txt
TypeScript/JavaScript	LCOV	tsconfig.json, package.json
Java	JaCoCo, Cobertura	pom.xml, build.gradle
Rust	LCOV (cargo-llvm-cov)	Cargo.toml

Getting started

# Install
go install github.com/felixgeelhaar/coverctl@latest

# Initialize in any project (Go, Python, TypeScript, Java, or Rust)
cd your-project
coverctl init                               # runs an interactive wizard, auto-detects language
coverctl detect --dry-run                   # preview detected domains without writing config
coverctl check                              # enforce policy, add -o json for automation
coverctl watch                              # continuous coverage feedback during development

CLI reference

Command	What it does	Notes
coverctl init	Autodetect domains and launch the Bubble Tea wizard before writing .coverctl.yaml	Navigate with ↑/↓, adjust thresholds with ←/→ or +/-, and confirm to persist. Pass --no-interactive to skip the UI in scripts.
coverctl detect	Autodetect domains and write config	Writes config by default; use --dry-run to preview without writing. Pass --force to overwrite existing config.
coverctl check	Run coverage, aggregate domains, enforce policy	-o json emits machine-readable results; exit code 1 signals policy violations. Use --show-delta to display coverage changes. Supports --fail-under N, --ratchet, and --from-profile.
coverctl run	Produce coverage artifacts without evaluating policy	Use --profile to customize output path.
coverctl watch	Watch for file changes and re-run coverage	Continuous coverage feedback during development.
coverctl report	Evaluate an already generated profile	Consumes the same config + domains; ideal for CI artifacts or debugging. Supports -o html, --uncovered, --diff <ref>, and --merge <profile>.
coverctl ignore	Show configured exclude patterns and the tracked domains	Use this to document generated folders (e.g., internal/generated/proto/...) that you wish to skip.
coverctl badge	Generate an SVG coverage badge	Use --style flat-square for a different style. Output to coverage.svg by default.
coverctl trend	Show coverage trends over time	Requires history data recorded via coverctl record.
coverctl record	Record current coverage to history	Use with --commit and --branch for CI integration. Use --run or profiles from coverctl run/coverctl check so history matches instrumentation.
coverctl suggest	Suggest optimal coverage thresholds	Strategies: current, aggressive, conservative. Use --write-config to apply.
coverctl debt	Show coverage debt report	Identifies domains/files below target and estimates remediation effort.
coverctl mcp serve	Start MCP server for AI agents	Enables Claude and other AI agents to interact with coverage tools programmatically via STDIO.

Text output (the default) shows domain coverage, required thresholds, and statuses. JSON adds warnings for overlap detection and is suitable for dashboards when you pass -o json. HTML output (-o html) generates a visual report with coverage percentages and status indicators. Use coverctl ignore to review the exclude list, which is how generated folders such as proto artifacts can be omitted before running coverctl check.

Note: coverctl check --from-profile skips running tests but still runs policy evaluation on every configured domain, so reused profiles that already fall below a domain's min will continue to fail until you regenerate them, relax thresholds, scope domains, or adjust domain matches.

Init wizard

coverctl init now launches a short Bubble Tea wizard that reviews the detected domains, lets you adjust coverage minima with arrow keys or +/- shortcuts, and confirms the policy before persisting .coverctl.yaml. Use --no-interactive when you need to run the command in CI or scripted workflows and you just want to write the autodetected configuration.

Build/test flags

The check, run, and watch commands support common test flags for customizing test execution. For Go projects:

Flag	Description	Example
--tags	Build tags	--tags integration,e2e
--race	Enable race detector	--race
--short	Skip long-running tests	--short
-v	Verbose test output	-v
--run	Run only tests matching pattern	--run TestFoo
--timeout	Test timeout	--timeout 30m
--test-arg	Additional go test argument (repeatable)	--test-arg=-count=1

Examples:

# Run integration tests with build tag
coverctl check --tags integration

# Run with race detector and extended timeout
coverctl check --race --timeout 30m

# Run specific tests with verbose output
coverctl run --run TestMyFunction -v

# Pass multiple extra arguments to go test
coverctl check --test-arg=-count=1 --test-arg=-parallel=4

Coverage policy

coverctl check parses coverage profiles (Go, LCOV, Cobertura, JaCoCo) and assigns statements to the domains defined in .coverctl.yaml. Because raw coverage output often aggregates everything—including helpers, generated files, and adapters you may already exclude—the percentage it reports is not used directly. The policy enforces coverage thresholds only within the scoped domains, so staying focused there while keeping generated folders listed in exclude prevents quality from falling through the cracks.

Configuration

The schema lives in schemas/coverctl.schema.json. Configs are versioned; set version: 1 today and keep it in place so future schema upgrades can be detected safely. A policy looks like:

version: 1
policy:
  default:
    min: 75
  domains:
    - name: core
      match: ["./internal/core/..."]
      min: 85
    - name: api
      match: ["./internal/api/..."]
exclude:
  - internal/generated/*

The autodetect command covers cmd/, pkg/, and directories inside internal/, skipping generated/mocks.

Advanced options you can enable as needed:

version: 1
files:
  - match: ["internal/core/*.go"]
    min: 90
diff:
  enabled: true
  base: origin/main
integration:
  enabled: true
  packages: ["./internal/integration/..."]
  run_args: ["-test.run", "TestIntegration"]
  cover_dir: ".cover/integration"
  profile: ".cover/integration.out"
merge:
  profiles: [".cover/unit.out", ".cover/integration.out"]
annotations:
  enabled: true

• files enforces per-file minima for any matching paths.
• diff enforces coverage only on files changed since the base ref.
• integration builds go test -c binaries and runs them with GOCOVERDIR (Go 1.20+).
• merge combines multiple coverprofiles into a single policy evaluation.
• annotations enables // coverctl:ignore and // coverctl:domain=NAME pragmas.

Need a starting point? Copy templates/coverctl.yaml and adjust domains and thresholds to fit your repo.

MCP Server (AI Agent Integration)

coverctl includes a Model Context Protocol (MCP) server that enables AI agents like Claude to interact with coverage tools programmatically. Start it with:

coverctl mcp serve

Available Tools

Tool	Description
check	Run coverage tests and enforce policy thresholds
report	Analyze an existing coverage profile
record	Record current coverage to history

Available Resources

URI	Description
coverctl://debt	Coverage debt metrics
coverctl://trend	Coverage trends over time
coverctl://suggest	Threshold recommendations
coverctl://config	Current configuration

Claude Desktop Configuration

Add to ~/.config/claude/claude_desktop_config.json (macOS/Linux) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "coverctl": {
      "command": "coverctl",
      "args": ["mcp", "serve"],
      "cwd": "/path/to/your/go/project"
    }
  }
}

Once configured, Claude can run coverage checks, analyze reports, and provide recommendations based on your project's coverage data.

Architecture

• internal/domain: coverage stats, policy evaluation, warning aggregation.
• internal/application: services (check, run, report, detect) orchestrate config loading, domain resolution, coverage runs, and reporting.
• internal/infrastructure: adapters for config files, Go tooling (go test), profile parsing, reporters, and autodetection.
• internal/cli: CLI parsing, output, and wiring for the root command entrypoint.
• main.go: root entrypoint so go install github.com/felixgeelhaar/coverctl@latest works. (The cmd/coverctl wrapper remains for compatibility.)

Testing & contribution guidelines

• Practice TDD: add or update tests before implementing behavior changes.
• Keep test coverage ≥80% using go test ./... -cover.
• Follow Conventional Commits (feat:, fix:, etc.) for Relicta’s version bump logic.
• main is protected: merge via PRs after CI passes (see .github/workflows/go.yml). This keeps the release workflow deterministic and reviewable.
• Pull requests that touch reporting should document CLI output or sample JSON to keep churn visible.

Releases

• Relicta v2.6.1 (relicta.config.yaml) drives releases: it creates semver tags, updates CHANGELOG.md, and publishes GitHub releases.
• .github/workflows/release.yml triggers relicta release --yes on protected main (after each merge). The Relicta pre_release_hook runs scripts/build-artifacts.sh to compile Linux/macOS/Windows CLI tarballs/zips that the GitHub plugin attaches as release assets.
• Configure a secret named RELICTA_TOKEN (or rely on ${{ secrets.GITHUB_TOKEN }}) with contents/workflows/packages permissions so Relicta can push tags, update the changelog, and attach artifacts.
• Do not manually push v* tags; let Relicta own the tag lifecycle to avoid conflicts.

GitHub Action

Use the built-in composite action to run coverctl in CI:

jobs:
  coverage:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6
      - uses: actions/setup-go@v6
        with:
          go-version: "1.25"
      - uses: ./.github/actions/coverctl
        with:
          command: check
          config: .coverctl.yaml
          output: text

Security Scan (SARIF)

Run VerdictSec in GitHub Actions and upload SARIF results:

jobs:
  security:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      security-events: write
    steps:
      - uses: actions/checkout@v6
      - uses: actions/setup-go@v6
        with:
          go-version: "1.25"
      - name: Install verdict
        run: go install github.com/felixgeelhaar/verdictsec/cmd/verdict@v0.8.0
      - name: Install verdict engines
        run: |
          go install github.com/securego/gosec/v2/cmd/gosec@latest
          go install golang.org/x/vuln/cmd/govulncheck@latest
          go install github.com/gitleaks/gitleaks/v8@latest
          go install github.com/CycloneDX/cyclonedx-gomod/cmd/cyclonedx-gomod@latest
          go install github.com/anchore/syft/cmd/syft@latest
          go install honnef.co/go/tools/cmd/staticcheck@latest
      - name: Run verdict (SARIF)
        run: verdict scan --sarif -o verdict.sarif || true
      - name: Upload SARIF
        uses: github/codeql-action/upload-sarif@v4
        with:
          sarif_file: verdict.sarif

Multi-Language Support

coverctl is a universal coverage enforcement platform supporting multiple languages out of the box. For design details, see:

• Product Requirements (PRD) - Goals, personas, and feature requirements
• Technical Design (TDD) - Architecture, implementation details, and code examples

Language Support Status

Language	Format	Status
Go	Native coverage profile	✅ Supported
Python	LCOV, Cobertura	✅ Supported
TypeScript/JavaScript	LCOV	✅ Supported
Java	Cobertura, JaCoCo	✅ Supported
Rust	LCOV (cargo-llvm-cov)	✅ Supported

Usage with Different Languages

coverctl auto-detects your project language, or you can specify it explicitly:

# Auto-detect (recommended)
coverctl check

# Explicit language
coverctl check --language python --profile coverage.xml

# Explicit format
coverctl report --format lcov --profile coverage/lcov.info

Claude Code Plugin

coverctl is available as a Claude Code plugin for AI-assisted coverage enforcement:

/plugin install coverctl
/coverctl:check
/coverctl:suggest

Docs & governance

• Product/architecture docs live under docs/design/ (TDD/PRD). AGENTS.md covers contributor expectations.
• The scripts/build-artifacts.sh helper compiles cross-platform binaries for release artifacts.
• Keep CHANGELOG.md tracked so Relicta can automatically append release notes during relicta release.