or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

context.mdfile-writing.mdindex.mdtree-traversal.mdxml-generation.md
tile.json

tessl/npm-istanbul-lib-report

Base reporting library for istanbul providing core utilities for generating coverage reports across different formats

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/istanbul-lib-report@3.0.x

To install, run

npx @tessl/cli install tessl/npm-istanbul-lib-report@3.0.0

index.mddocs/

Istanbul Lib Report

Istanbul Lib Report is the foundational reporting library for the Istanbul code coverage ecosystem. It provides essential infrastructure for generating coverage reports across different formats including JSON, HTML, and text outputs. The library offers a flexible API for creating reporting contexts with customizable options such as output directories, watermark thresholds for coverage metrics, and different summarization strategies.

Package Information

  • Package Name: istanbul-lib-report
  • Package Type: npm
  • Language: JavaScript
  • Installation: npm install istanbul-lib-report

Core Imports

const libReport = require('istanbul-lib-report');

Basic Usage

const libReport = require('istanbul-lib-report');

// Create a context for report generation
const context = libReport.createContext({
  dir: 'coverage',
  watermarks: {
    statements: [50, 80],
    functions: [50, 80],
    branches: [50, 80],
    lines: [50, 80]
  },
  coverageMap, // from istanbul-lib-coverage
  defaultSummarizer: 'nested'
});

// Get default watermarks
const defaultWatermarks = libReport.getDefaultWatermarks();

// Use the context to write reports
const writer = context.getWriter();
const contentWriter = writer.writeFile('report.txt');
contentWriter.println('Coverage Report');
contentWriter.close();

Architecture

Istanbul Lib Report is built around several key components:

  • Context System: Central Context class that provides report generation environment with configurable options
  • File Writing Infrastructure: FileWriter and ContentWriter classes for handling file and console output
  • Tree Traversal System: Visitor pattern implementation for walking coverage trees and generating summaries
  • XML Generation: XMLWriter utility for generating XML-based reports
  • Path Management: Path class for normalized file path operations across platforms
  • Summarization Factory: SummarizerFactory providing different tree organization strategies (flat, nested, pkg)

Capabilities

Context Management

Core reporting context creation and configuration. The Context class serves as the central hub for all reporting operations, managing output directories, watermarks, source code access, and tree summarization strategies.

function createContext(opts) {
  // opts.dir - output directory (default: "coverage")
  // opts.watermarks - coverage thresholds
  // opts.sourceFinder - function to retrieve source code
  // opts.coverageMap - coverage data
  // opts.defaultSummarizer - summarization strategy
}

function getDefaultWatermarks() {
  // Returns default watermark thresholds
}

Context Management

File Writing

File and console output management with support for directory-based organization and content writing abstractions.

class FileWriter {
  constructor(baseDir);
  writeFile(file); // Returns ContentWriter
  writerForDir(subdir); // Returns FileWriter
  copyFile(source, dest, header);
}

class ContentWriter {
  write(str);
  println(str);
  colorize(str, clazz);
  close();
}

File Writing

Tree Traversal

Visitor pattern implementation for traversing coverage trees and generating reports with different organizational strategies.

class Visitor {
  onStart(root, state);
  onSummary(node, state);
  onDetail(node, state);
  onSummaryEnd(node, state);
  onEnd(root, state);
}

class BaseTree {
  visit(visitor, state);
}

Tree Traversal

XML Generation

XML writing utilities for generating structured XML reports with proper indentation and tag management.

class XMLWriter {
  constructor(contentWriter);
  openTag(name, attrs);
  closeTag(name);
  inlineTag(name, attrs, content);
  closeAll();
}

XML Generation

Types

// Context options interface
interface ContextOptions {
  dir?: string;
  watermarks?: WatermarkOptions;
  sourceFinder?: (filePath: string) => string;
  coverageMap: Object;
  defaultSummarizer?: string;
}

// Watermark configuration
interface WatermarkOptions {
  statements?: [number, number];
  functions?: [number, number];
  branches?: [number, number];
  lines?: [number, number];
}

// Base class for all reports
class ReportBase {
  constructor(opts?: { summarizer?: string });
  execute(context: Context): void;
}