coverctl

Declarative, domain-aware coverage enforcement for any language Supports 15 languages including Go, Python, TypeScript/JavaScript, Java, Rust, C#, C/C++, PHP, Ruby, Swift, Dart, Scala, Elixir, and Shell. 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

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

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:

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

Available Resources

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 nox in GitHub Actions and upload SARIF results:

jobs:
  security:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      security-events: write
    steps:
      - uses: actions/checkout@v6
      - name: Install nox
        run: |
          curl -sL https://github.com/nox-hq/nox/releases/download/v0.7.0/nox_0.7.0_linux_amd64.tar.gz | tar xz -C /usr/local/bin nox
      - name: Run nox (SARIF)
        run: nox -format sarif -output . scan . || true
      - name: Upload SARIF
        uses: github/codeql-action/upload-sarif@v4
        with:
          sarif_file: results.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

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.