`cov`

Code coverage tracking - register source files with total line counts, record which lines are executed, compute per-file and aggregate line-coverage percentages, print formatted reports, gate on minimum coverage thresholds, and merge coverage data from multiple test runs.

Load with: use cov

What this module does

cov is a lightweight line-coverage tracker. A coverage object holds two maps: files (filename → total line count) and hits ("file:line" → hit count). Instrument your code by calling covht at each executable line, then query coverage percentages and generate reports at the end of the test run.

Coverage from multiple independent test runs can be merged into a single object with covmg, which sums hit counts so no execution data is lost.

All functions are also available as cov.new, cov.reg, cov.hit, cov.ln, cov.all, cov.rpt, cov.ok, and cov.mrg.

Quick example

use cov

# Create a coverage tracker
c = covnw()

# Register files with their total line counts
c = covrg(c, "src/math.ilu", 40)
c = covrg(c, "src/util.ilu", 20)

# Record line hits (instrument your code)
c = covht(c, "src/math.ilu", 1)
c = covht(c, "src/math.ilu", 5)
c = covht(c, "src/math.ilu", 5)  # hit again - count increments

# Per-file coverage
prn(covln(c, "src/math.ilu"))  # {total: 40, hit: 2, pct: 5}

# Aggregate
prn(covtt(c))  # {files: 2, total: 60, hit: 2, pct: 3}

# Report
prn(covrp(c))

# Gate: fail if below 80%
if !covok(c, 80):
    err("Coverage too low!")

Functions

Tracker lifecycle

covnw()

Creates a new empty coverage tracker: {files: {}, hits: {}}.

covrg(tracker, file, total_lines)

Registers a source file with its total executable line count. Returns the updated tracker.

Recording hits

covht(tracker, file, line)

Records an execution of line line in file. The key "file:line" is incremented in the hits map. Returns the updated tracker. Call this at every executable line you want to track.

Coverage queries

covln(tracker, file)

Returns per-file coverage: {total, hit, pct}. pct is the integer percentage of lines hit (0–100). Returns {total:0, hit:0, pct:0} for unregistered files.

covtt(tracker)

Returns aggregate coverage across all registered files: {files, total, hit, pct}.

Reporting

covrp(tracker)

Returns a formatted coverage report string listing each file's hit/total/percentage, followed by the overall total. Header line is "=== Coverage Report ===".

covok(tracker, min_pct)

Returns tru if aggregate coverage percentage is at or above min_pct. Use in CI to gate merges on minimum coverage.

Merging

covmg(tracker_a, tracker_b)

Merges two coverage trackers. File registrations from both are combined. Hit counts for the same "file:line" key are summed. Returns a new merged tracker.

Notes

Coverage is line-based only - branch and function coverage are not tracked.
Hit counts go up each time a line is executed, so you can distinguish executed-once from hot paths.
Requires trl and txt.