covsift
Exact, local analysis of code coverage reports, as four Hermes tools.
After writing code and tests, the question a coding agent gets is "did my change
get tested?" The answer is in the coverage report, but a real report is
megabytes of XML or LCOV covering every file in the project, and the part that
matters is the handful of lines the change added. covsift reads the report on
disk and returns exact answers: overall coverage, the least covered files and
their uncovered lines, and, given a diff, the added lines no test ran.
Why a tool and not a prompt or skill
-
Diff coverage. Pass the output of
git diff origin/main...HEAD(or a file
holding it) and get, per changed file, the added lines tests never executed.
You also get added lines with partly covered branches, a total, and an optional
fail_undergate. Real output on a change that added an unused helper and an
untested branch:{"lines_added": 74, "lines_measured": 58, "lines_missing": 5, "diff_percent": 91.38, "passed": false, "changed_files": [{"file": "covsift.py", "measured": 58, "covered": 53, "missing_lines": ["195-198", "203"], "partial_branches": [{"line": 202, "covered": 1, "total": 2}, ...]}]}Changed files that the report does not cover at all are listed separately
(not_in_report): a new module that no test imports shows up there, not as
"100%". -
Every common format, one answer. LCOV, Cobertura, JaCoCo, Clover,
SonarQube generic XML, coverage.py JSON, gcovr JSON, Coveralls JSON and Go
cover profiles are read into the same model. A directory of reports (one per
package or test suite) is merged. -
Paths that don't line up. Reports name files differently from git:
- absolute CI paths (
/home/runner/work/app/app/src/x.py) - paths under a Cobertura
<source>root - Go import paths (
github.com/org/repo/pkg/x.go) - JaCoCo packages (
org/acme/A.java) - Windows drive paths
A repository path matches a report file in this order:
- the same path;
- a longer report path ending in it (an absolute CI path, a Go import path,
a<source>root), even for a root-level file; - a shorter report path it ends in, as long as that path includes a directory;
- a shared tail of at least two components (
app/x.pyunder/code/and under
backend/, or a Go module path against its directory). This only applies when
the differing leading parts have nothing in common: different checkout roots,
not different directories of one tree.
Case is ignored only when nothing matches exactly. Two equally good candidates
are reported asambiguous, never guessed. So is a match on the file name
alone: a report'sutils.pyis not taken as the diff's newpkg/utils.py,
which would show an untested file as covered. - absolute CI paths (
Tools
All four always return a JSON string. A bad path or a file that is not a
coverage report returns { "ok": false, "error": "..." } rather than raising.
path (and base/head) is a report file or a directory searched recursively
for reports. Files that are not reports (pom.xml, package.json) are skipped
and listed in skipped.
coverage_summary
| arg | type | required | default | meaning |
|---|---|---|---|---|
path | string | yes | - | report file or directory |
top | integer | no | 15 | files and directories to rank (cap 200) |
directory_depth | integer | no | 2 | path components that make a directory in the rollup |
Returns:
totals: lines, branches, and Go statements, each with a percent.least_covered: files with at least 5 lines, each with its uncovered line ranges.directories: coverage per directory.uncovered_files: files with no covered line.formatsandreports_read.
coverage_file
| arg | type | required | default | meaning |
|---|---|---|---|---|
path | string | yes | - | report file or directory |
file | string | yes | - | source file, e.g. src/app/models.py |
Returns the file's counts, missing_lines (ranges such as "10-14") and
partial_branches ({line, covered, total}).
coverage_diff
| arg | type | required | default | meaning |
|---|---|---|---|---|
path | string | yes | - | report file or directory |
diff | string | one of | - | unified diff text (git diff, diff -u, git format-patch) |
diff_path | string | one of | - | a file holding the diff |
fail_under | number | no | - | passed: false when diff coverage is below this percentage |
max_files | integer | no | 50 | changed files to list (cap 1,000) |
Returns:
lines_added,lines_measured(added lines the report knows are executable),
lines_covered,lines_missinganddiff_percent.changed_files, each with its missing lines and partial branches, least covered first.not_in_report, plusambiguouswhen a path matches more than one report file.
A diff with no measurable added line has diff_percent: null and passes the
gate, because nothing executable changed. The diff parser:
- handles renames, deletions, new files, CRLF line endings and git's quoted
unicode paths; - follows each hunk's line counts, as
git applydoes; - reads on to the next header when a hand-edited hunk is longer than its header
says, and setsdiff_notewhen it does.
coverage_compare
| arg | type | required | default | meaning |
|---|---|---|---|---|
base | string | yes | - | baseline report file or directory |
head | string | yes | - | new report file or directory |
max_files | integer | no | 50 | files per list (cap 1,000) |
Returns:
- Both runs' totals, and
changein line, branch and statement percent. dropped: files that lost coverage, with the lines that were covered before
and are not any more.improved,added_filesandremoved_files.
How formats are read
- Lines. A line is covered when any record for it ran: repeated records,
template instantiations and several reports all count once. - Branches. These are per line (
covered/total).- When a format names its branches (LCOV block/branch, coverage.py arcs, gcovr
and Coveralls branch numbers), records and reports merge branch by branch, as
lcov -adoes: a branch one test took and another missed counts as taken. - A Go line holding a block that ran and one that did not
(if err != nil { return err }on one line) counts as a partly covered branch.
- When a format names its branches (LCOV block/branch, coverage.py arcs, gcovr
- Go statements are counted the way
go test -covercounts them. A block
that appears in several profiles is counted once. - LCOV follows
DA:lines. Function declaration lines (FN:) are not
counted as executable lines. When a record's ownLF/LHdisagree with its
DA:lines (gcovr--exclude-function-linesstill writesDA:for excluded
lines),report_notessays so. - gcovr's JaCoCo output has no line counts, only branch counts. Line
coverage for those files is reported as unknown, never as 0% or 100%. - Declared totals that differ. When a Cobertura report's own totals differ
from its per-line data, the result says so inreport_notes(istanbul counts
branches it attaches to no line). - Not read. Istanbul's
coverage-final.jsonandcoverage-summary.json:
use thelcovorcoberturareporter (c8, nyc, Jest and Vitest all have them).
Merging a directory of reports
Reports in a directory are merged by file path. That is right for several runs of
one project (unit and integration tests), but two cases need care:
- Per-package reports whose paths are relative to each package (two
lib/main.dart) would merge into one file. Pass each package's report on its
own. - The same run exported twice (
coverage.xmlandcoverage.json) can name files
differently and count them twice. Keep one format per run in the directory.
Safety
- Read-only. It reads only the paths you pass: regular files, up to 512 MiB per
report, 2,000 reports per directory, and a 64 MiB diff. - No network, no credentials, no subprocess (it never runs git or tests; the
diff is passed in), no background work, no self-update. Standard library
only. - XML is parsed by a streaming expat parser. Entity declarations are refused,
so entity expansion and external entities cannot be used. ADOCTYPEsuch
as JaCoCo's is allowed but its DTD is never fetched. - Honours Hermes' core read denylist (credential stores, project
.envfiles,
NT/device namespace paths). Each path is checked as given and as an absolute
path before anything is opened, including every file found in a directory.
Device, fd and/procpaths are refused, also through symlinks, and
symlinked directories are not followed.
Install
hermes plugins install rodricksz4h5/covsift --enable
License
MIT
README from the reviewed commit 5d2ea15; it updates when the author re-pins.

rodricksz4h5