# Coverage baselines

Frozen coverage snapshots, scoped per published package. Updated **in place** as the codebase progresses; history of "what changed when" lives in git log, not in the filename.

```
coverage/
├── README.md              # this file
├── worca-cc/
│   └── baseline.json      # Python (src/worca/) — produced by scripts/coverage.py
└── worca-ui/
    └── baseline.json      # JS (worca-ui/) — produced by vitest --coverage
```

Both files are committed; CI does not regenerate them. They serve as the reference point for:

- humans eyeballing whether a branch's coverage moved up or down
- the `scripts/coverage.py compare` workflow (Python only)
- a future codecov "no-regression" gate (see the rollout plan in #131 / #123 follow-ups)

## When to refresh

- **After major coverage-impacting work merges to master** — e.g. a bundle of new tests, a refactor that changes module boundaries, a CI workflow change that affects what gets measured.
- **NOT on every PR.** A PR's coverage delta should be evaluated against this baseline, not folded into it. Updating the baseline as part of unrelated work hides regressions.
- Each refresh should be its own PR/commit with a one-line summary of why and a before/after delta in the body.

## Refresh workflow

### worca-cc (Python)

```bash
# From repo root, on a clean master:
python scripts/coverage.py ci
cp coverage-out/coverage.json coverage/worca-cc/baseline.json
```

`scripts/coverage.py ci` writes `coverage-out/coverage.json` (augmented schema with `summary`, `modules`, `omitted`, `raw`). Module keys are already relative (`src/worca/...`), so no normalization step is needed.

To diff a working tree against this baseline:

```bash
python scripts/coverage.py ci
python scripts/coverage.py compare \
    --baseline=coverage/worca-cc/baseline.json \
    --current=coverage-out/coverage.json
```

### worca-ui (JS)

```bash
# From repo root:
cd worca-ui && npm run test:coverage && cd -

# Normalize absolute paths → repo-relative, sort for deterministic diffs:
python3 - <<'PY'
import json
from pathlib import Path
ROOT = Path.cwd().resolve()
src = ROOT / 'worca-ui' / 'coverage-out' / 'coverage-summary.json'
dst = ROOT / 'coverage' / 'worca-ui' / 'baseline.json'
data = json.load(src.open())
prefix = str(ROOT) + '/'
norm = {k if k == 'total' else k[len(prefix):] if k.startswith(prefix) else k: v
        for k, v in data.items()}
sorted_data = {'total': norm['total'], **{k: norm[k] for k in sorted(k for k in norm if k != 'total')}}
json.dump(sorted_data, dst.open('w'), indent=2)
dst.open('a').write('\n')
PY
```

Vitest writes per-file keys as absolute paths. The normalization step strips the repo-root prefix so the committed baseline is portable across machines.

## What's intentionally excluded from coverage

### worca-cc

- `tests/**` — measuring test coverage of test code is meaningless.
- `src/worca/cli/init.py` — runs as a non-coverage-wrapped subprocess in the integration fixture by design (W-050 plan §18). Wrapping it would multiply test runtime by N. The 0% line in the baseline is a measurement artifact, not a real gap.
- `scripts/coverage.py` itself — the runner, not the system under test.

### worca-ui

Configured in `worca-ui/vitest.config.js` under `test.coverage.exclude`:
- `**/*.test.js` and `**/test/**` — test code.
- `app/main.bundle.js[.map]` — generated by esbuild, not source.
- `app/vendor/**` — third-party code shipped as-is.
- `scripts/**` — build orchestration.

## Reading the numbers

Both baselines contain a top-level `total` (or `summary` for the Python schema) plus per-module/per-file detail.

Quick eyeball commands:

```bash
# Python totals
python3 -c "import json; d=json.load(open('coverage/worca-cc/baseline.json')); print(d['summary'])"

# JS totals
python3 -c "import json; d=json.load(open('coverage/worca-ui/baseline.json')); print(d['total'])"
```

For the Python side, **branch coverage matters more than line coverage** — many of the bugs hide in retry-loop branches that line coverage paints green. The augmented JSON's per-module `branch_pct` is the more meaningful signal.
