0
# File Coverage
1

2
File coverage objects provide detailed coverage analysis for individual files, including statement, function, and branch coverage with hit counts and location mapping.
3

4
## Capabilities
5

6
### FileCoverage Constructor  
7

8
Creates a coverage object for a single file from a path or existing coverage data.
9

10
```javascript { .api }
11
/**
12
 * Creates a FileCoverage instance
13
 * @param {string|Object|FileCoverage} pathOrObj - File path, coverage data, or existing FileCoverage
14
 * @param {boolean} [reportLogic=false] - Enable branch truthiness tracking
15
 */
16
constructor(pathOrObj, reportLogic)
17
```
18

19
**Usage Examples:**
20

21
```javascript
22
const { createFileCoverage } = require('istanbul-lib-coverage');
23

24
// Create empty coverage for file path
25
const fc = createFileCoverage('/src/utils.js');
26

27
// Create from existing coverage data
28
const fc = createFileCoverage(existingCoverageData);
29

30
// Enable branch truthiness tracking
31
const fc = createFileCoverage('/src/utils.js', true);
32
```
33

34
### Get Line Coverage
35

36
Returns computed line coverage from statement coverage as a map of hit counts keyed by line number.
37

38
```javascript { .api }
39
/**
40
 * Returns computed line coverage from statement coverage
41
 * @returns {Object} Map of hits keyed by line number
42
 */
43
getLineCoverage(): Object
44
```
45

46
**Usage Examples:**
47

48
```javascript
49
const fc = createFileCoverage(coverageData);
50
const lineCoverage = fc.getLineCoverage();
51

52
console.log('Line coverage:');
53
Object.entries(lineCoverage).forEach(([line, hits]) => {
54
  console.log(`Line ${line}: ${hits} hits`);
55
});
56
```
57

58
### Get Uncovered Lines
59

60
Returns an array of line numbers that have zero hits.
61

62
```javascript { .api }
63
/**
64
 * Returns array of uncovered line numbers
65
 * @returns {string[]} Line numbers with zero hits
66
 */
67
getUncoveredLines(): string[]
68
```
69

70
**Usage Examples:**
71

72
```javascript
73
const fc = createFileCoverage(coverageData);
74
const uncoveredLines = fc.getUncoveredLines();
75

76
if (uncoveredLines.length > 0) {
77
  console.log('Uncovered lines:', uncoveredLines.join(', '));
78
} else {
79
  console.log('All lines covered!');
80
}
81
```
82

83
### Get Branch Coverage by Line
84

85
Returns branch coverage organized by source line number with coverage statistics.
86

87
```javascript { .api }
88
/**
89
 * Returns branch coverage organized by source line
90
 * @returns {Object} Keyed by line number with coverage stats
91
 */
92
getBranchCoverageByLine(): Object
93
```
94

95
**Usage Examples:**
96

97
```javascript
98
const fc = createFileCoverage(coverageData);
99
const branchCoverage = fc.getBranchCoverageByLine();
100

101
Object.entries(branchCoverage).forEach(([line, stats]) => {
102
  console.log(`Line ${line}: ${stats.covered}/${stats.total} branches (${stats.coverage}%)`);
103
});
104
```
105

106
### Merge File Coverage
107

108
Merges another file coverage object into this one, combining hit counts for the same file.
109

110
```javascript { .api }
111
/**
112
 * Merges another coverage object into this one
113
 * @param {FileCoverage} other - Coverage object for same file to merge
114
 */
115
merge(other): void
116
```
117

118
**Usage Examples:**
119

120
```javascript
121
const fc1 = createFileCoverage(coverage1);
122
const fc2 = createFileCoverage(coverage2);
123

124
// Merge fc2 into fc1 (both must be for same file)
125
fc1.merge(fc2);
126

127
console.log('Merged coverage:', fc1.toSummary());
128
```
129

130
### Reset Hit Counts
131

132
Resets all hit counts to zero, resulting in zero coverage.
133

134
```javascript { .api }
135
/**
136
 * Resets all hit counts to zero
137
 */
138
resetHits(): void
139
```
140

141
**Usage Examples:**
142

143
```javascript
144
const fc = createFileCoverage(coverageData);
145

146
console.log('Before reset:', fc.toSummary());
147
fc.resetHits();
148
console.log('After reset:', fc.toSummary());
149
```
150

151
### Get Coverage Summary
152

153
Returns a coverage summary object for this file with aggregated statistics.
154

155
```javascript { .api }
156
/**
157
 * Returns coverage summary for this file
158
 * @returns {CoverageSummary} Coverage summary with statistics
159
 */
160
toSummary(): CoverageSummary
161
```
162

163
**Usage Examples:**
164

165
```javascript
166
const fc = createFileCoverage(coverageData);
167
const summary = fc.toSummary();
168

169
console.log('File coverage summary:');
170
console.log(`Lines: ${summary.lines.covered}/${summary.lines.total} (${summary.lines.pct}%)`);
171
console.log(`Statements: ${summary.statements.covered}/${summary.statements.total} (${summary.statements.pct}%)`);
172
console.log(`Functions: ${summary.functions.covered}/${summary.functions.total} (${summary.functions.pct}%)`);
173
console.log(`Branches: ${summary.branches.covered}/${summary.branches.total} (${summary.branches.pct}%)`);
174
```
175

176
### JSON Serialization
177

178
Returns a JSON-serializable representation of the file coverage data.
179

180
```javascript { .api }
181
/**
182
 * Returns JSON-serializable POJO
183
 * @returns {Object} Raw coverage data
184
 */
185
toJSON(): Object
186
```
187

188
**Usage Examples:**
189

190
```javascript
191
const fc = createFileCoverage(coverageData);
192
const jsonData = fc.toJSON();
193

194
// Access raw coverage data
195
console.log('File path:', jsonData.path);
196
console.log('Statement map:', jsonData.statementMap);
197
console.log('Statement hits:', jsonData.s);
198
console.log('Function hits:', jsonData.f);
199
console.log('Branch hits:', jsonData.b);
200
```
201

202
## Data Properties
203

204
File coverage objects expose coverage data through getter properties:
205

206
```javascript { .api }
207
// File and mapping properties
208
path: string                     // File path
209
statementMap: Object             // Statement location mapping
210
fnMap: Object                    // Function metadata mapping
211
branchMap: Object                // Branch metadata mapping
212

213
// Hit count properties  
214
s: Object                        // Statement hit counts
215
f: Object                        // Function hit counts
216
b: Object                        // Branch hit counts
217
bT: Object                       // Branch truthiness (optional)
218

219
// Special properties
220
all: boolean                     // Indicates if represents all files
221
```
222

223
**Usage Examples:**
224

225
```javascript
226
const fc = createFileCoverage(coverageData);
227

228
console.log('File path:', fc.path);
229
console.log('Statements:', Object.keys(fc.s).length);
230
console.log('Functions:', Object.keys(fc.f).length);
231
console.log('Branches:', Object.keys(fc.b).length);
232

233
// Check if branch truthiness is enabled
234
if (fc.bT) {
235
  console.log('Branch truthiness tracking enabled');
236
}
237
```
238

239
## Coverage Data Structure
240

241
The file coverage data follows this structure:
242

243
```javascript { .api }
244
interface FileCoverageData {
245
  path: string;                  // File path
246
  statementMap: {                // Statement locations by index
247
    [index: string]: {
248
      start: { line: number, column: number };
249
      end: { line: number, column: number };
250
    };
251
  };
252
  fnMap: {                       // Function metadata by index
253
    [index: string]: {
254
      name: string;
255
      decl: { start: LineCol, end: LineCol };
256
      loc: { start: LineCol, end: LineCol };
257
      line: number;
258
    };
259
  };
260
  branchMap: {                   // Branch metadata by index
261
    [index: string]: {
262
      loc: { start: LineCol, end: LineCol };
263
      type: string;
264
      locations: Array<{ start: LineCol, end: LineCol }>;
265
      line: number;
266
    };
267
  };
268
  s: { [index: string]: number }; // Statement hit counts
269
  f: { [index: string]: number }; // Function hit counts  
270
  b: { [index: string]: number[] }; // Branch hit counts (array per branch)
271
  bT?: { [index: string]: number[] }; // Branch truthiness (optional)
272
}
273

274
interface LineCol {
275
  line: number;
276
  column: number;
277
}
278
```