# coveragegate

Standalone coverage-threshold enforcement tool for this repository.

This tool is a quality gate. It is not part of Cue runtime orchestration.

## What it does

- Reads a Go coverage profile (for example `_build/coverage.out`).
- Loads package coverage policy from JSON.
- Discovers packages under a source root using `go list ./...`.
- Evaluates per-package statement coverage against policy thresholds.
- Prints a package table and returns a non-zero exit code when any package fails.

## Repository integration

Primary repository flow:

1. `just test-coverage` runs tests in `src/` and writes `_build/coverage.out`.
2. `scripts/check-core-coverage.sh` runs this tool from `tools/coveragegate/`.
3. The script currently passes:
   - `--profile $ROOT_DIR/_build/coverage.out`
   - `--policy $ROOT_DIR/docs/coverage-thresholds.json`
   - `--src-root $ROOT_DIR/src`

## Usage

From repository root:

```bash
cd tools/coveragegate
go run . \
  --profile ../../_build/coverage.out \
  --policy ../../docs/coverage-thresholds.json \
  --src-root ../../src
```

Or use the repository wrapper:

```bash
bash scripts/check-core-coverage.sh
```

## Flags

- `--profile`: Path to Go coverage profile.
- `--policy`: Path to JSON policy file.
- `--src-root`: Directory where packages are discovered with `go list ./...`.

## Exit codes

- `0`: All in-scope packages meet threshold.
- `1`: Policy/profile/load failure or one or more packages below threshold.
- `2`: Invalid CLI arguments.

## Policy model (current)

The tool expects a JSON object with at least:

- `minimum_statement_coverage` (number)
- `critical_packages` (array)

Each critical package may include:

- `package` (string)
- `minimum_statement_coverage` (number)
- `include` (boolean)
- `exclusions` (array of strings)

Behavior notes:

- If a package has no policy override, the global minimum is used.
- Generated/composition files are excluded by built-in rules.
- Packages with no statements are treated as passing.

## Development

Run tests:

```bash
cd tools/coveragegate
go test ./...
```

Keep code `gofmt` and `go vet` clean.