lcov-trace-doctor-kit

Inspect LCOV tracefiles with structured diagnostics and coverage summaries.

lcov-trace-doctor-kit is a clean-room TypeScript package for checking lcov.info content before CI upload, coverage merge, or a browser workbench. It is browser-friendly, ESM-only, dependency-free, and does not read files by itself.

Links: Demo · GitHub

Install

npm install lcov-trace-doctor-kit

Quick Start

import { inspectLcovTrace, formatLcovDiagnostics } from "lcov-trace-doctor-kit";

const report = inspectLcovTrace(`
TN:unit
SF:src/math.ts
FN:1,add
FNDA:3,add
DA:1,3
DA:2,0
FNF:1
FNH:1
LF:2
LH:1
end_of_record
`);

console.log(report.summary.lineCoverage); // 50
console.log(formatLcovDiagnostics(report.diagnostics));

Why This Package

Use this package when you need a small LCOV doctor, not a full coverage platform:

• parse tracefiles into records with line, function and branch details;
• check declared counters such as LF, LH, FNF, FNH, BRF and BRH;
• report malformed records, missing SF, unterminated records, duplicate details and unknown fields;
• optionally normalize source paths for browser and CI display;
• keep diagnostics stable for tests, logs, PR comments and UI annotations.

API

inspectLcovTrace(input, options?)

Returns { ok, records, summary, diagnostics }. Fatal parse problems use severity: "error" and make ok false. Usable-but-suspicious traces use warnings.

const result = inspectLcovTrace(lcovText, {
  normalizePaths: true,
  maxInputLength: 2_000_000
});

summarizeLcovTrace(input, options?)

Returns only the global summary.

const summary = summarizeLcovTrace(lcovText);

formatLcovDiagnostics(diagnostics)

Formats diagnostics as plain text for CLIs, logs or simple UI panels.

createLcovTraceDoctor(defaultOptions?)

Creates a reusable inspector with shared defaults.

Options

| Option | Default | Description | | --- | ---: | --- | | normalizePaths | false | Convert backslashes to slashes, collapse repeated slashes and remove leading ./. | | maxInputLength | 1000000 | Reject unexpectedly large strings before parsing. |

Diagnostics

Diagnostic codes are stable strings:

• invalid-input
• invalid-options
• empty-input
• input-too-large
• missing-source-file
• unterminated-record
• duplicate-source-file
• unknown-record
• malformed-record
• negative-number
• line-count-mismatch
• function-count-mismatch
• branch-count-mismatch
• function-hit-without-definition
• duplicate-line-hit
• duplicate-function-definition
• summary-before-detail
• path-normalized

Scope Limits

This package intentionally does not execute lcov, inspect source files, merge tracefiles, resolve paths on disk, upload coverage, or implement every genhtml behavior. It works on a string that your app, CLI, worker or build tool already has.

Package quality

• TypeScript types are generated from the source.
• ESM-only package with no runtime dependencies.
• Marked as side-effect free for bundlers.
• Browser-friendly implementation with no Node-only APIs.
• CI runs npm ci, typecheck, build, and test.
• Tested on Node.js 20 and 22 with GitHub Actions.

License

MPL-2.0