lcov-analysis

Overview

LCOV is "a tool suite for manipulating and displaying code coverage information" with three command-line utilities: geninfo (creates LCOV data files from raw coverage data), lcov (captures, filters, manipulates, processes in parallel), and genhtml (HTML report generation) (lcov-readme).

The toolchain is "language-agnostic (via converter scripts: llvm2lcov, py2lcov, perl2lcov, xml2lcov)" (lcov-readme) - LCOV .info is the lingua franca every coverage UI (Coveralls, Codecov, Codacy, SonarQube, in-house dashboards) ingests.

This skill covers parsing the .info text format directly so the team can gate PRs without running the full HTML generation step. The sibling Cobertura XML format (same PR-gating shape, different parser) is covered in references/cobertura.md - pick whichever format the existing reporter produces.

When to use

• The CI already emits LCOV or Cobertura XML (or can via a converter) and the team wants PR-time per-file coverage gating.
• A coverage SaaS isn't an option (compliance, cost, air-gapped CI).
• A multi-language project needs one analyzer (Python via py2lcov, Java via xml2lcov, Node via nyc/jest's lcov reporter, C++ via gcov → lcov).
• A custom coverage UI / Slack bot needs structured input.

How to use

1. Confirm CI emits LCOV .info (natively or via a converter: py2lcov, xml2lcov, nyc / Jest's lcov reporter, gcov → lcov).
2. Parse the .info into per-file line / function / branch metrics (Parse below); recompute totals from the per-line records rather than trusting the summary fields.
3. Cache main's .info as the baseline; diff each PR's coverage against it.
4. Gate per file on the three rules below (whole-repo drop, per-file drop, new-file minimum) - the diff + gate reference implementation, the full record-format table, and the CI wiring are in references/format-diff-and-ci.md.

Worked example

A single source file's .info record, and how to read it:

TN:
SF:src/checkout/cart.ts
FN:10,addItem
FN:32,removeItem
FNDA:42,addItem
FNDA:0,removeItem
FNF:2
FNH:1
DA:11,42
DA:12,42
DA:13,0
DA:33,0
DA:34,0
LF:5
LH:2
BRDA:13,0,0,42
BRDA:13,0,1,0
BRF:2
BRH:1
end_of_record

Reading: cart.ts has 2 functions, 1 hit (50% function coverage); 5 lines, 2 hit (40% line); 2 branches, 1 hit (50% branch). removeItem was never called (FNDA:0). SF opens the record, DA:<line>,<count> gives per-line hits, LH/LF and BRH/BRF are the roll-ups, and end_of_record closes the file. The full record-keyword table is in references/format-diff-and-ci.md.

Parse

# scripts/parse_lcov.py
from collections import defaultdict

def parse_lcov(path):
    files = []
    cur = None
    with open(path) as f:
        for line in f:
            line = line.strip()
            if line.startswith('SF:'):
                cur = {
                    'path': line[3:],
                    'functions': [],
                    'lines': {},
                    'branches': defaultdict(list),
                    'fnf': 0, 'fnh': 0,
                    'lf': 0, 'lh': 0,
                    'brf': 0, 'brh': 0,
                }
            elif line.startswith('FN:'):
                lineno, name = line[3:].split(',', 1)
                cur['functions'].append({'line': int(lineno), 'name': name, 'hits': 0})
            elif line.startswith('FNDA:'):
                hits, name = line[5:].split(',', 1)
                for fn in cur['functions']:
                    if fn['name'] == name:
                        fn['hits'] = int(hits)
                        break
            elif line.startswith('DA:'):
                lineno, hits = line[3:].split(',', 1)
                cur['lines'][int(lineno)] = int(hits.split(',')[0])  # checksum optional
            elif line.startswith('BRDA:'):
                lineno, block, branch, taken = line[5:].split(',', 3)
                cur['branches'][int(lineno)].append({
                    'block': int(block),
                    'branch': int(branch),
                    'taken': 0 if taken == '-' else int(taken),
                })
            elif line.startswith(('FNF:', 'FNH:', 'LF:', 'LH:', 'BRF:', 'BRH:')):
                key, val = line.split(':', 1)
                cur[key.lower()] = int(val)
            elif line == 'end_of_record':
                files.append(cur)
                cur = None
    return files

Don't trust the FNF/FNH/LF/LH/BRF/BRH summary fields blindly - some buggy emitters produce summaries that don't match the per-line data. For correctness, recompute from lines, functions, branches.

Gate rules

A defensible per-file gate has three rules:

1. Whole-repo line coverage MAY drop by at most N pp (typically N = 0.5 - guards against runaway erosion without blocking refactors).
2. No file MAY drop more than M pp (typically M = 5 - calls out the specific file that lost coverage).
3. New files MUST hit threshold (typically 80% line, 70% branch).

Per-file gates beat whole-repo gates: an aggregate drop hides which file caused it; per-file output gives the reviewer a direct target. The coverage_diff + gate reference implementation and the PR coverage-gate CI job are in references/format-diff-and-ci.md.

Anti-patterns

Limitations

• .info is text, not standardized via a formal spec. The authoritative source is the lcov-readme + the codebase itself; format extensions vary by emitter. Tolerant parsing is required.
• No file-level "this is a test file" marker. Filter by path convention.
• No PR-context awareness. The format doesn't know about git diff - pair with git diff --name-only to scope coverage changes to PR-touched files when needed.
• Branch coverage shape varies. Some emitters report per-condition (multi-arm BRDA); some report per-decision (single arm). Normalize before cross-tool comparisons.

References

• lcov-readme - LCOV toolchain (geninfo / lcov / genhtml), .info format keywords, language-agnostic converters.
• references/format-diff-and-ci.md - full .info record-keyword table, the baseline-diff + gate reference implementation, and the PR coverage-gate CI job.
• references/cobertura.md - the sibling Cobertura XML format (same PR-gating shape, different parser).
• coverage-diff-reporter - build-an-X workflow that consumes parsed coverage and emits a PR comment with file-level deltas.
• test-coverage-targeter - picks which uncovered branches to target first using the parsed output.