Module Windtrap_coverageSource

Coverage data collection and reporting.

Instrumented code calls register_file at module load time; visit functions increment counters during execution; an at_exit handler writes .coverage files to disk. The test runner reads data directly for inline reporting.

Types

Sourcetype instrumented_file = {
  1. filename : string;
  2. points : int array;
  3. counts : int array;
}
Sourcetype coverage = (string, instrumented_file) Hashtbl.t

Output Configuration

Sourceval set_output_prefix : string -> unit

set_output_prefix path sets the directory and filename prefix for .coverage files written at exit. For example, set_output_prefix "/project/_build/_coverage/windtrap" writes files like /project/_build/_coverage/windtrap123456789.coverage. The directory is created automatically when coverage data is written. Can be overridden by the WINDTRAP_COVERAGE_FILE environment variable.

Registration

Sourceval register_file : filename:string -> points:int array -> [ `Visit of int -> unit ]

Register an instrumented source file. Called by PPX-generated code at module load time. Returns a visit function that increments the counter for a given point index. Registers an at_exit handler on first call.

Data Access

Sourceval data : unit -> coverage

Return the accumulated in-memory coverage data. Empty if no instrumented files have been registered.

Sourceval reset_counters : unit -> unit

Reset all counters to zero without removing registered files.

Serialization

Sourceval file_identifier : string

Magic header for .coverage files.

Sourceval serialize : coverage -> string

Serialize coverage data to the binary format used by .coverage files.

Deserialization

Sourceval read_file : string -> instrumented_file list

Read a single .coverage file. Returns an empty list if the file has an invalid header, is unreadable, or is truncated.

Merging

Sourceval merge : coverage -> instrumented_file list -> unit

merge tbl files folds files into tbl, using saturating addition when the same source file appears more than once.

Reporting

Sourcetype summary = {
  1. visited : int;
  2. total : int;
}
Sourcetype file_report = {
  1. filename : string;
  2. summary : summary;
  3. uncovered_offsets : int list;
  4. uncovered_lines : int list;
  5. source_available : bool;
}
Sourceval summarize : coverage -> summary

Compute aggregate (visited, total) counts across all files.

Sourceval summarize_per_file : coverage -> (string * summary) list

Per-file summaries sorted by filename.

Sourceval percentage : summary -> float

percentage s is 100.0 when s.total = 0.

Sourceval coverage_style : summary -> [ `Green | `Yellow | `Red ]

Return a color style based on coverage percentage: green >= 80%, yellow >= 60%, red < 60%. Useful with Pp.styled for inline output.

Sourceval collapse_ranges : int list -> (int * int) list

collapse_ranges lines collapses a sorted list of line numbers into contiguous ranges. E.g., [1; 2; 3; 7; 8] becomes [(1, 3); (7, 8)].

Sourceval format_ranges : (int * int) list -> string

format_ranges ranges formats ranges as "1-3, 7-8". Single lines appear without a dash.

Sourceval reports : ?source_paths:string list -> coverage -> file_report list

Build deterministic per-file coverage reports with uncovered points and uncovered line numbers.

source_paths is used to resolve source files for line mapping. When a source file can't be found or read, uncovered_lines is empty and source_available is false.

Sourceval print_summary : per_file:bool -> skip_covered:bool -> ?source_paths:string list -> coverage -> unit

Print a human-readable coverage report to stdout with color-coded percentages. When per_file is true and source_paths is provided, uncovered line ranges are shown below each file. When skip_covered is true, files with 100% coverage are omitted from the per-file report.

Sourceval print_uncovered : ?context:int -> ?source_paths:string list -> coverage -> unit

Print uncovered source code snippets with surrounding context lines. Each uncovered line is prefixed with > and highlighted. Context lines are dimmed. Only files with uncovered lines and available source are shown. context defaults to 1.