covcat

name	covcat
description	covcat - LLM-native coverage-annotated file viewer. Use when the user wants to see code coverage information inline with source code, identify test gaps, analyze uncovered branches, or generate tests for uncovered paths. Renders files in LNCAF (LLM-Native Coverage Annotation Format) with gutter markers showing covered (|), uncovered (.), partial branch (?), and function entry ([FN+]/[FN-]) annotations.
intent	Transform coverage-blind file reading into coverage-aware reading. Instead of reading a source file with zero test coverage signal, covcat overlays per-line coverage data from Istanbul JSON, LCOV, or other coverage formats directly into the source output using the LNCAF annotation format.
triggers	["show coverage","coverage gaps","what's untested","uncovered lines","coverage annotated","covcat","test gaps","branch coverage","which lines are covered","run covcat"]

covcat - Coverage-Annotated File Viewer

What It Does

covcat reads a source file and overlays code coverage data from test runs, producing LNCAF-formatted output where every executable line has a coverage gutter marker. This transforms an LLM from coverage-blind to coverage-aware when reading source files.

Usage

Basic: Show coverage-annotated file

covcat src/utils.ts

Specify annotation tier

covcat --format compact src/utils.ts    # Minimal: | . ? markers only
covcat --format standard src/utils.ts   # Default: + branch annotations + function markers
covcat --format verbose src/utils.ts    # Full: + hit counts + gap summary

Explicit coverage file

covcat --coverage coverage/lcov.info src/utils.ts

Daemon mode (fast cached evaluation)

covcat daemon start       # Start background daemon
covcat src/utils.ts       # Served from cache (<5ms)
covcat daemon status      # Check daemon health
covcat daemon stop        # Shutdown daemon

LNCAF Output Format

Gutter Markers

Marker	Meaning
|	Line covered (executed ≥1 time)
.	Line uncovered (0 executions)
?	Branch statement with untaken paths
	Non-executable line
[FN+]	Function entry, called
[FN-]	Function entry, never called

Standard Tier Example

<system-reminder>
COV: src/orders.ts | | covered  . uncovered  ? partial  [B:x/y]=branches  [FN+/-]=function
Collected: 2026-04-01 | lines: 5/12 (42%) | branches: 1/4 (25%)
</system-reminder>
[FN+]     1→function processOrder(order) {
|         2→  const validated = validateOrder(order);
?         3→  if (!validated) {                          [branch: else never taken]
.         4→    throw new ValidationError('Invalid');
.         5→  }
|         6→  const pricing = calculatePrice(order.items);
?         7→  if (pricing.discount > 0) {                [branch: both paths uncovered]
.         8→    applyDiscount(pricing);
.         9→  } else {
.        10→    pricing.discount = 0;
.        11→  }
|        12→  return fulfillOrder(order, pricing);
         13→}

Configuration

Create covcat.yml in project root:

coverage:
  defaultFormat: standard
  showBranchDetails: true
  discovery:
    coveragePath: coverage/lcov.info  # explicit path
  daemon:
    enabled: true
    watchFiles: true
    cache:
      maxEntries: 500

Supported Coverage Formats

• Istanbul JSON (coverage-final.json) - Jest, Vitest, NYC, c8
• LCOV (lcov.info) - Universal interchange format

When to Use

1. Before writing tests: covcat src/module.ts to see what's untested
2. After test runs: Check which lines your new tests covered
3. Code review: Understand test coverage gaps in changed files
4. Test generation: Feed covcat output to an LLM for targeted test suggestions