uncovered-highlight

A package and tool to display source code with uncovered parts highlighted.

Installation

npm install uncovered-highlight

For global installation:

npm install -g uncovered-highlight

Usage

Generating Coverage Data

First, run your TypeScript or JavaScript programs with V8 coverage enabled:

NODE_V8_COVERAGE=coverage node your-program.js

This will create coverage data in the coverage directory.

Command Line Tool

Display source files with uncovered parts highlighted:

uncovered-highlight [options] <file...>

Options

  • -c, --coverage-dir <dir> - Coverage data directory (default: auto-detected from source file path, or coverage)
  • -o, --out-dir <dir> - TypeScript output directory (overrides tsconfig.json)
  • -n, --no-line-numbers - Hide line numbers (line numbers shown by default)
  • -x, --context <n> - Number of context lines around uncovered code (default: 2)
  • -s, --show-omitted - Show “…” for omitted lines
  • -m, --hide-omitted - Hide “…” for omitted lines (default)
  • -h, --highlight <color> - Highlight color: black, red, green, yellow, blue, magenta, cyan, white, bold, underline, reverse, or numeric ANSI code (default: red)
  • --help - Show help message

Examples

Display a TypeScript file with default settings (line numbers shown, red highlights):

uncovered-highlight src/file.ts

Hide line numbers and show omitted line indicators:

uncovered-highlight -n -s src/file.ts

Use bold highlighting with more context lines:

uncovered-highlight -h bold -x 3 src/file.ts

Process multiple files:

uncovered-highlight src/*.ts

Library API

You can also use the library programmatically:

import { 
  V8CoverageReader, 
  SourceMapProcessor, 
  HighlightProcessor 
} from 'uncovered-highlight';

// Read V8 coverage data
const reader = new V8CoverageReader('coverage');

// Get coverage ranges for a JavaScript file
const ranges = reader.getCoverageRanges('path/to/file.js');

// Process with source maps for TypeScript
const processor = new SourceMapProcessor();
const mappedRanges = await processor.mapJsRangesToSource(
  'path/to/file.js', 
  ranges
);

// Generate per-line highlights
const highlighter = new HighlightProcessor();
const lineHighlights = highlighter.processSourceWithCoverage(
  sourceCode, 
  mappedRanges
);

// Clean up
processor.destroy();

Features

  • V8 Coverage Integration: Reads native V8 coverage data generated by Node.js
  • Subdirectory Support: Automatically finds coverage files in subdirectories (e.g., coverage/tmp/)
  • Source Map Support: Maps JavaScript coverage back to TypeScript source files
  • Smart Path Resolution: Correctly handles rootDir and outDir configurations in tsconfig.json
  • Multi-byte Character Support: Correctly handles Unicode characters including emojis
  • Flexible Highlighting: Customizable highlight colors including named colors (red, green, blue, etc.), styles (bold, underline, reverse), or numeric ANSI codes
  • Context Control: Show only relevant lines with configurable context
  • Multiple Files: Process multiple source files in a single run

How It Works

  1. Coverage Collection: Node.js V8 engine records which parts of your JavaScript code were executed
  2. Coverage Reading: The tool reads the V8 coverage data from JSON files
  3. Source Mapping: For TypeScript files, coverage data is mapped back to the original source using source maps
  4. Highlight Generation: Uncovered code regions are identified and per-line highlight ranges are calculated
  5. Terminal Output: Source code is displayed with uncovered parts highlighted using ANSI escape codes with customizable colors and styles
  6. Auto-discovery: Automatically searches for coverage directories and tsconfig.json from the source file location
  7. Subdirectory Scanning: If coverage directory has no files directly, automatically scans subdirectories (supports c8 and similar tools)

Note from a Human

I realized I wanted something like this tool that displays the parts of the source code uncovered by tests. The output to terminal shows lines with surrounding lines for context. If a condition is tested, but following block never covered, I want to know that. Reducing granularity to line-level was not good.

I had no particular interest in making such a tool, and I may have missed one if there is something that does what I needed. Partially as a way to play around with generative AI code generation and agents, this package exists. As long as it works, I have no particular desire to touch the code, provided I can help myself. I wanted the tool, I prompted, I got what you see.

Since all code has been generated by AI, this is not copyrighted even though AI may have added notes about licenses somewhere. The CC0-1.0 license was the suggestion of a Search Assist, which I followed, gullibly or not.

Build Results

Source code repository.

94e09889a5e682159002ca48053b8ad544fdb100 2026-07-23T23:11:34+03:00 Tests run in Cloud Build.

Results: