0
# Context Management
1

2
Context management in Istanbul Lib Report provides the central coordination system for report generation, managing output directories, coverage thresholds, source code access, and tree summarization strategies.
3

4
## Capabilities
5

6
### Create Context
7

8
Creates a reporting context with configurable options for output directory, watermarks, source finding, and summarization strategy.
9

10
```javascript { .api }
11
/**
12
 * Creates a reporting context for the supplied options
13
 * @param {Object} opts - Configuration options
14
 * @param {string} [opts.dir="coverage"] - The reporting directory
15
 * @param {Object} [opts.watermarks] - Watermarks for statements, lines, branches and functions
16
 * @param {Function} [opts.sourceFinder] - Function that returns source code given a file path
17
 * @param {Object} opts.coverageMap - Coverage map from istanbul-lib-coverage
18
 * @param {string} [opts.defaultSummarizer="pkg"] - Default summarizer type (flat, nested, pkg)
19
 * @returns {Context} Context instance for report generation
20
 */
21
function createContext(opts);
22
```
23

24
**Usage Example:**
25

26
```javascript
27
const libReport = require('istanbul-lib-report');
28

29
const context = libReport.createContext({
30
  dir: 'coverage-reports',
31
  watermarks: {
32
    statements: [60, 90],
33
    functions: [60, 90],
34
    branches: [60, 90],
35
    lines: [60, 90]
36
  },
37
  coverageMap,
38
  defaultSummarizer: 'nested'
39
});
40
```
41

42
### Get Default Watermarks
43

44
Returns the default watermark thresholds used when no custom watermarks are provided.
45

46
```javascript { .api }
47
/**
48
 * Returns the default watermarks that would be used when not overridden
49
 * @returns {Object} Object with statements, functions, branches, and lines keys.
50
 * Each value is a 2-element array with low and high watermark percentages.
51
 */
52
function getDefaultWatermarks();
53
```
54

55
**Usage Example:**
56

57
```javascript
58
const libReport = require('istanbul-lib-report');
59

60
const defaults = libReport.getDefaultWatermarks();
61
// Returns: { statements: [50, 80], functions: [50, 80], branches: [50, 80], lines: [50, 80] }
62
```
63

64
### Context Class
65

66
The Context class provides the reporting environment with methods for file operations, source access, and tree management.
67

68
```javascript { .api }
69
/**
70
 * A reporting context that is passed to report implementations
71
 */
72
class Context {
73
  /**
74
   * Create a new Context instance
75
   * @param {Object} opts - Configuration options
76
   */
77
  constructor(opts);
78

79
  /**
80
   * Returns a FileWriter implementation for reporting use
81
   * @returns {FileWriter} Writer instance for file operations
82
   */
83
  getWriter();
84

85
  /**
86
   * Returns the source code for the specified file path
87
   * @param {string} filePath - The file path as found in a file coverage object
88
   * @returns {string} The source code
89
   * @throws {Error} If the source could not be found
90
   */
91
  getSource(filePath);
92

93
  /**
94
   * Returns the coverage class given a coverage type and percentage value
95
   * @param {string} type - Coverage type: "statements", "functions", "branches", or "lines"
96
   * @param {number} value - The percentage value
97
   * @returns {string} One of "high", "medium", "low", or "unknown"
98
   */
99
  classForPercent(type, value);
100

101
  /**
102
   * Returns an XML writer for the supplied content writer
103
   * @param {ContentWriter} contentWriter - Content writer for XML output
104
   * @returns {XMLWriter} XML writer instance
105
   */
106
  getXMLWriter(contentWriter);
107

108
  /**
109
   * Returns a full visitor given a partial one
110
   * @param {Object} partialVisitor - Partial visitor with methods of interest
111
   * @returns {Visitor} Full visitor instance
112
   */
113
  getVisitor(partialVisitor);
114

115
  /**
116
   * Returns a tree for the specified summarizer type
117
   * @param {string} [name="defaultSummarizer"] - Tree type name
118
   * @returns {Object} Tree instance for traversal
119
   */
120
  getTree(name);
121
}
122
```
123

124
**Usage Examples:**
125

126
```javascript
127
const context = libReport.createContext({ dir: 'reports', coverageMap });
128

129
// Get file writer
130
const writer = context.getWriter();
131

132
// Get source code
133
const sourceCode = context.getSource('/path/to/file.js');
134

135
// Classify coverage percentage
136
const cssClass = context.classForPercent('statements', 75); // "medium"
137

138
// Get XML writer
139
const contentWriter = writer.writeFile('report.xml');
140
const xmlWriter = context.getXMLWriter(contentWriter);
141

142
// Create visitor
143
const visitor = context.getVisitor({
144
  onSummary(node, state) {
145
    console.log('Processing summary node:', node.getQualifiedName());
146
  }
147
});
148

149
// Get tree
150
const tree = context.getTree('nested');
151
```
152

153
## Properties
154

155
```javascript { .api }
156
/**
157
 * FileWriter property - getter that creates FileWriter if needed
158
 */
159
Context.prototype.writer; // Returns FileWriter instance
160
```
161

162
### SummarizerFactory
163

164
The internal SummarizerFactory provides different tree organization strategies for coverage reporting, accessed through Context.getTree().
165

166
```javascript { .api }
167
/**
168
 * Factory for creating different tree summarization strategies
169
 */
170
class SummarizerFactory {
171
  /**
172
   * Create a summarizer factory
173
   * @param {Object} coverageMap - Coverage map from istanbul-lib-coverage
174
   * @param {string} [defaultSummarizer="pkg"] - Default summarizer type
175
   */
176
  constructor(coverageMap, defaultSummarizer);
177

178
  /**
179
   * Get the default summarizer tree
180
   * @returns {ReportTree} Default summarizer tree instance
181
   */
182
  get defaultSummarizer();
183

184
  /**
185
   * Get flat tree organization (all files at root level)
186
   * @returns {ReportTree} Flat tree instance
187
   */
188
  get flat();
189

190
  /**
191
   * Get package-based tree organization
192
   * @returns {ReportTree} Package tree instance
193
   */
194
  get pkg();
195

196
  /**
197
   * Get nested directory tree organization
198
   * @returns {ReportTree} Nested tree instance
199
   */
200
  get nested();
201
}
202
```
203

204
**Tree Organization Strategies:**
205

206
- **flat**: All files at the root level, no directory structure
207
- **pkg**: Organizes files by package/directory structure with common parent prefix handling
208
- **nested**: Full nested directory tree with intermediate directories as summary nodes
209

210
**Usage Example:**
211

212
```javascript
213
const context = libReport.createContext({
214
  coverageMap,
215
  defaultSummarizer: 'nested' // Can be 'flat', 'pkg', or 'nested'
216
});
217

218
// Get different tree organizations
219
const flatTree = context.getTree('flat');
220
const nestedTree = context.getTree('nested');
221
const pkgTree = context.getTree('pkg');
222
const defaultTree = context.getTree(); // Uses defaultSummarizer
223
```
224

225
## Types
226

227
```javascript { .api }
228
interface ContextOptions {
229
  dir?: string;                              // Output directory (default: "coverage")
230
  watermarks?: WatermarkThresholds;          // Coverage thresholds
231
  sourceFinder?: (filePath: string) => string; // Source code finder function
232
  coverageMap: Object;                       // Coverage map from istanbul-lib-coverage
233
  defaultSummarizer?: 'flat' | 'nested' | 'pkg';  // Summarizer strategy
234
}
235

236
interface WatermarkThresholds {
237
  statements?: [number, number];  // [low, high] thresholds
238
  functions?: [number, number];   // [low, high] thresholds
239
  branches?: [number, number];    // [low, high] thresholds
240
  lines?: [number, number];       // [low, high] thresholds
241
}
242
```