Find Coverage Gaps

---
name: find-coverage-gaps
description: Identify files and modules with missing or insufficient test coverage, ranked by churn and complexity, and suggest what to test first.
allowed-tools: Bash, Read, Glob, Grep
argument-hint: "[path]"
---

TODAY=!`date +%Y-%m-%d`

# Coverage Gaps

Finds the parts of the codebase with the least test coverage, then ranks them by churn and complexity so the most important gaps appear first. Low coverage in a stable file is a minor concern. Low coverage in a file that changes constantly and is hard to understand is a production risk.

## Prerequisites

- Working directory is the root of the repository
- Optional: `$1` — path to limit the scan (defaults to `.`)
- Tests must be runnable; coverage data is generated by running the test suite
- Language-specific tools:
  - Python: `pytest-cov` (`uv add --dev pytest-cov`)
  - JavaScript/TypeScript: `jest --coverage` or `vitest --coverage`
  - Go: `go test -cover ./...`
  - Rust: `cargo tarpaulin` (`cargo install cargo-tarpaulin`)

## Coverage Thresholds

| Coverage | Status |
|----------|--------|
| ≥ 80% | Acceptable |
| 50–79% | 🟡 Gap — schedule tests |
| < 50% | 🔴 Critical gap — prioritize |
| 0% | 🔴 No tests at all |

Files below threshold are ranked by a **risk score**: `(1 - coverage) × churn_commits × complexity_score`.

## Steps

### 1. Run the Test Suite with Coverage

**Python:**
```
python -m pytest ${1:-.} --cov=${1:-.} --cov-report=term-missing --cov-report=json:coverage.json -q 2>&1 | tail -40
```

**JavaScript/TypeScript — Jest:**
```
npx jest --coverage --coverageReporters=json-summary --coverageDirectory=.coverage 2>/dev/null
cat .coverage/coverage-summary.json | jq '.[] | select(.lines.pct < 80) | {file: ., pct: .lines.pct}' 2>/dev/null | head -40
```

**JavaScript/TypeScript — Vitest:**
```
npx vitest run --coverage 2>/dev/null
```

**Go:**
```
go test -coverprofile=coverage.out ./... 2>/dev/null && go tool cover -func=coverage.out | rg -v "100.0%" | sort -k3 -n | head -30
```

**Rust:**
```
cargo tarpaulin --out Json --output-dir .coverage 2>/dev/null
```

### 2. Parse Coverage Results

Extract per-file coverage percentages from the generated report:

**Python — from coverage.json:**
```
python3 -c "
import json, sys
data = json.load(open('coverage.json'))
files = [(v['summary']['percent_covered'], k) for k, v in data['files'].items()]
for pct, f in sorted(files):
    if pct < 80:
        print(f'{pct:5.1f}%  {f}')
" 2>/dev/null
```

**Go — from coverage.out:**
```
go tool cover -func=coverage.out | awk '$3 != "100.0%" {print $3, $1}' | sort -n | head -30
```

### 3. Identify Files with Zero Coverage

```
# Python: files with no corresponding test file
find ${1:-.} -name "*.py" ! -name "test_*" ! -name "*_test.py" ! -path "*/tests/*" | \
  while read f; do
    base=$(basename "$f" .py)
    tests=$(find . -name "test_${base}.py" -o -name "${base}_test.py" 2>/dev/null | wc -l)
    [ "$tests" -eq 0 ] && echo "$f"
  done | head -30
```

### 4. Rank by Risk Score

For each file below threshold, compute a risk score combining three factors:

**Factor 1 — Coverage deficit** (how far below threshold):
```
coverage_deficit = max(0, 80 - coverage_pct)
```

**Factor 2 — Recent churn** (commits in the past month):
```
git log --since="1 month ago" --name-only --pretty=format: | sort | uniq -c | sort -rn | head -40
```

**Factor 3 — Complexity signal** (line count as a proxy if radon/gocyclo not available):
```
wc -l <file>
```

**Risk score** = `coverage_deficit × (1 + churn_commits) × log(line_count + 1)`

Sort files descending by risk score.

### 5. Inspect Top-10 Files

For each high-risk file:
1. Read the file.
2. Identify which functions/methods have no coverage (from `--cov-report=term-missing` output or equivalent).
3. Assess why coverage is low: no tests at all, tests exist but don't reach these branches, or the code is hard to test (tight coupling, side effects, no dependency injection).

### 6. Generate Testing Suggestions

For each file, suggest the specific tests to write:

**Test types to recommend:**
- **Unit tests** — pure functions, data transformations, business logic
- **Integration tests** — database access, API calls, file I/O
- **Characterization tests** — existing behavior locked in before a planned refactor (especially for complex, untested legacy code)
- **Property-based tests** — functions with many input combinations (`hypothesis` for Python, `fast-check` for JS)
- **Mocking/patching** — when the barrier to testing is external dependencies

For each recommendation, name the specific functions to cover and the edge cases to include (null inputs, empty collections, error paths, boundary values).

### 7. Print the Report

```
# Coverage Gaps — {TODAY}

## Summary

- Files analyzed: N
- Overall coverage: X%
- 🔴 Critical gaps (< 50%): N files
- 🟡 Gaps (50–79%): N files
- ✅ Acceptable (≥ 80%): N files

## Risk-Ranked Gaps

| Rank | File | Coverage | Churn (1mo) | Risk Score |
|------|------|----------|-------------|-----------|
| 1    | `src/payments/processor.py` | 12% | 8 commits | 94.2 |

## File-by-File Recommendations

### 1. `<path>` — X% coverage

<What the file does and why coverage matters here>

**Uncovered functions:** `foo()`, `bar()`, `baz()`

**Suggested tests:**
- Unit test `foo()` with empty input, normal input, and boundary value N
- Integration test `bar()` with a real DB fixture
- Characterization test for `baz()` before refactoring

### 2. `<path>` — X% coverage

…

## Files With No Tests At All

<list>

## Quick Wins

3–5 test additions that would raise coverage most for the least effort (e.g., a single parametrized test covering 5 branches).
```

## Example Usage

**Scenario 1: Baseline audit**
```
/find-coverage-gaps
```
Overall coverage is 61%. Finds `src/billing/invoice.py` (8%, 12 churn commits) as the top risk. Recommends unit tests for the three calculation functions and an integration test for the PDF export path.

**Scenario 2: Pre-refactor safety check**
```
/find-coverage-gaps src/legacy
```
The legacy module has 3% coverage. Recommends writing characterization tests for all public functions before any refactoring begins, to lock in current behavior.

## Useful Commands Reference

| Command | Description |
|---------|-------------|
| `pytest --cov=. --cov-report=term-missing` | Python coverage with uncovered lines |
| `pytest --cov=. --cov-report=json:coverage.json` | Python coverage as JSON |
| `go test -coverprofile=coverage.out ./...` | Go coverage profile |
| `go tool cover -func=coverage.out` | Go per-function coverage |
| `npx jest --coverage` | Jest coverage report |
| `git log --since="1 month ago" --name-only --pretty=format: \| sort \| uniq -c \| sort -rn` | Churn for risk scoring |