0
# Istanbul Lib Report
1

2
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.
3

4
## Package Information
5

6
- **Package Name**: istanbul-lib-report
7
- **Package Type**: npm
8
- **Language**: JavaScript
9
- **Installation**: `npm install istanbul-lib-report`
10

11
## Core Imports
12

13
```javascript
14
const libReport = require('istanbul-lib-report');
15
```
16

17
## Basic Usage
18

19
```javascript
20
const libReport = require('istanbul-lib-report');
21

22
// Create a context for report generation
23
const context = libReport.createContext({
24
  dir: 'coverage',
25
  watermarks: {
26
    statements: [50, 80],
27
    functions: [50, 80],
28
    branches: [50, 80],
29
    lines: [50, 80]
30
  },
31
  coverageMap, // from istanbul-lib-coverage
32
  defaultSummarizer: 'nested'
33
});
34

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

38
// Use the context to write reports
39
const writer = context.getWriter();
40
const contentWriter = writer.writeFile('report.txt');
41
contentWriter.println('Coverage Report');
42
contentWriter.close();
43
```
44

45
## Architecture
46

47
Istanbul Lib Report is built around several key components:
48

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

56
## Capabilities
57

58
### Context Management
59

60
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.
61

62
```javascript { .api }
63
function createContext(opts) {
64
  // opts.dir - output directory (default: "coverage")
65
  // opts.watermarks - coverage thresholds
66
  // opts.sourceFinder - function to retrieve source code
67
  // opts.coverageMap - coverage data
68
  // opts.defaultSummarizer - summarization strategy
69
}
70

71
function getDefaultWatermarks() {
72
  // Returns default watermark thresholds
73
}
74
```
75

76
[Context Management](./context.md)
77

78
### File Writing
79

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

82
```javascript { .api }
83
class FileWriter {
84
  constructor(baseDir);
85
  writeFile(file); // Returns ContentWriter
86
  writerForDir(subdir); // Returns FileWriter
87
  copyFile(source, dest, header);
88
}
89

90
class ContentWriter {
91
  write(str);
92
  println(str);
93
  colorize(str, clazz);
94
  close();
95
}
96
```
97

98
[File Writing](./file-writing.md)
99

100
### Tree Traversal
101

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

104
```javascript { .api }
105
class Visitor {
106
  onStart(root, state);
107
  onSummary(node, state);
108
  onDetail(node, state);
109
  onSummaryEnd(node, state);
110
  onEnd(root, state);
111
}
112

113
class BaseTree {
114
  visit(visitor, state);
115
}
116
```
117

118
[Tree Traversal](./tree-traversal.md)
119

120
### XML Generation
121

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

124
```javascript { .api }
125
class XMLWriter {
126
  constructor(contentWriter);
127
  openTag(name, attrs);
128
  closeTag(name);
129
  inlineTag(name, attrs, content);
130
  closeAll();
131
}
132
```
133

134
[XML Generation](./xml-generation.md)
135

136
## Types
137

138
```javascript { .api }
139
// Context options interface
140
interface ContextOptions {
141
  dir?: string;
142
  watermarks?: WatermarkOptions;
143
  sourceFinder?: (filePath: string) => string;
144
  coverageMap: Object;
145
  defaultSummarizer?: string;
146
}
147

148
// Watermark configuration
149
interface WatermarkOptions {
150
  statements?: [number, number];
151
  functions?: [number, number];
152
  branches?: [number, number];
153
  lines?: [number, number];
154
}
155

156
// Base class for all reports
157
class ReportBase {
158
  constructor(opts?: { summarizer?: string });
159
  execute(context: Context): void;
160
}
161
```