Guardrails / Collectors

Code coverage

The coverage the build already measured, read from whichever report format it left behind and normalized into one shape: the line and branch totals across every report, and a summary per file. The covered and missed line numbers are left out unless you set lineDetail, because a large repository's line map is bigger than the facts document is allowed to be. Reports that name the same file are merged line by line, so a per module report and a merged report agree, but a report carrying only totals is added on top.

Facts key	coverage
Version	v1
Script	coverage.py
Timeout	60 seconds

Inputs

Input	Description	Default	Environment
reports	Comma separated globs matched against every file in the working directory and against bare file names, naming the coverage reports to read.	jacoco*.xml,jacocoTestReport.xml,cobertura*.xml,coverage*.xml,lcov.info,coverage-final.json	GUARDRAIL_INPUT_REPORTS
maxFiles	Maximum number of files to carry in byFile, those with the most uncovered lines first. The totals still include files that are dropped.	500	GUARDRAIL_INPUT_MAXFILES
lineDetail	true to carry the covered and missed line numbers of every file in byFile. A guardrail that checks the lines a change touched needs them; for everything else they only add size.	false	GUARDRAIL_INPUT_LINEDETAIL

When a guardrail declares an input with the same name, it passes its value through. That means you set these values in the guardrail's configuration in buildnote.json.

A guardrail asks for these facts by name and reads them back by the same name:

{
  "collect": ["coverage"]
}

coverage = guardrail.facts("coverage")

Facts

These are the fields of the document coverage collects. In a path, [] means each entry of the list before it, and [path] means a key of the object before it.

Fact	Meaning
source	report when a coverage report was read, none when there was none.
reason	Why nothing was read, present only when source is none.
reports	Every report that was read, in path order.
reports[].path	Path of the report, relative to the directory the CLI runs in.
reports[].modified	When the report was last written, in ISO 8601, so you can spot a stale report.
reports[].format	Format it was read as: jacoco, cobertura, istanbul or lcov.
lines.covered	Lines at least one report saw executed, counted once across every report that names the file.
lines.missed	Lines every report saw unexecuted.
lines.percent	Covered lines as a percentage of the lines the reports measured, to two decimal places, 0.0 when they measured none.
branches	The branch totals, or null when no report that was read carries branch coverage.
branches.covered	Branches taken.
branches.missed	Branches never taken.
branches.percent	Taken branches as a percentage of the branches the reports measured, to two decimal places.
files	How many files the reports measured, before maxFiles was applied.
byFile	A summary per file, the ones with the most uncovered lines first, up to maxFiles.
byFile[path].covered	Lines of that file at least one report saw executed.
byFile[path].missed	Lines of that file every report saw unexecuted.
byFile[path].percent	Covered lines of that file as a percentage, to two decimal places.
byFile[path].coveredLines	The covered line numbers, ascending, present only when lineDetail is true.
byFile[path].missedLines	The missed line numbers, ascending, present only when lineDetail is true.
dropped	Files left out of byFile because maxFiles was reached.

If a collector can't finish, it prints what it gathered so far along with an incomplete key that says why. Facts after the point where it stopped are missing, so a check that depends on them should read incomplete first.

Example facts

Here are the facts the coverage collector gathers from an example project:

{
  "source": "report",
  "reports": [
    {
      "path": "jacocoTestReport.xml",
      "modified": "2026-03-04T10:15:00Z",
      "format": "jacoco"
    }
  ],
  "lines": {
    "covered": 4,
    "missed": 3,
    "percent": 57.14
  },
  "branches": {
    "covered": 1,
    "missed": 3,
    "percent": 25.0
  },
  "files": 2,
  "byFile": {
    "com/company/widget/Broker.kt": {
      "covered": 1,
      "missed": 2,
      "percent": 33.33
    },
    "com/company/widget/Queue.kt": {
      "covered": 3,
      "missed": 1,
      "percent": 75.0
    }
  },
  "dropped": 0
}

Collected for

Guardrail	Category	Inputs
tests/coverage-floor	tests	none

All collectors