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.