README.md

codecov-rs

Library for processing code coverage reports.

Supported formats include:

• codecov-rs's SQLite format described in src/report/models.rs
• Codecov's Python report implementation ("pyreport")

See src/parsers or the list of features in Cargo.toml for a complete list. All formats are converted to codecov-rs's SQLite format (inspired by coverage.py) and converting back is generally not a goal (pyreport being the exception).

All details (e.g. SQLite schema, code interfaces) subject to breaking changes until further notice. In the future, we will at least use SQLite's schema_version pragma to attempt backwards compatibility.

Developing

At time of writing, codecov-rs requires the nightly compiler for niceties such as #[feature(trait_alias)] in the library itself and some convenient mockall behavior in tests.

codecov-rs aims to serve as effective documentation for every flavor of every format it supports. To that end, the following are greatly appreciated in submissions:

• Thorough doc comments (/// / /**). For parsers, include snippets that show what inputs look like
• Granular, in-module unit tests (mockall may help)
• Integration tests with real-world samples (that are safe to distribute; don't send us data from your private repo)

The examples/ directory contains runnable commands for developers including:

• parse_pyreport: converts a given pyreport into a SQLite report
• sql_to_pyreport: converts a given SQLite report into a pyreport (report JSON + chunks file)

Considering following suit for your own new feature.

Writing new parsers

TBD: Design not settled

New parsers should be optional via Cargo features. Adding them to the default featureset is fine.

Where possible, parsers should not load their entire input or output into RAM. On the input side, you can avoid that with a streaming parser or by using memmap2 to map the input file into virtual memory. SQLite makes it straightforward enough to stream outputs to the database.

Coverage formats really run the gamut so there's no one-size-fits-all framework we can use. Some options:

• quick_xml, a streaming XML parser
• winnow, a parser combinator framework (fork of nom)
  • winnow's docs illustrate how one can write a streaming parser
• serde, a popular serialization/deserialization framework
  • serde's docs illustrate how one can write a streaming parser

Non-XML formats lack clean OOTB support for streaming so codecov-rs currently relies more on the mmap approach.

Testing

Run tests with:

$ cargo test