0
# LCOV Parse
1

2
LCOV Parse is a simple and effective LCOV file parser that converts code coverage data from the LCOV format into structured JSON output. It supports parsing both LCOV files from disk and LCOV data strings directly, making it versatile for different integration scenarios.
3

4
## Package Information
5

6
- **Package Name**: lcov-parse
7
- **Package Type**: npm
8
- **Language**: JavaScript
9
- **Installation**: `npm install lcov-parse`
10

11
## Core Imports
12

13
```javascript
14
const parse = require('lcov-parse');
15
```
16

17
ES6 import:
18

19
```javascript
20
import parse from 'lcov-parse';
21
```
22

23
## Basic Usage
24

25
```javascript
26
const parse = require('lcov-parse');
27

28
// Parse an LCOV file from disk
29
parse('./path/to/file.info', function(err, data) {
30
    if (err) {
31
        console.error('Parse error:', err);
32
        return;
33
    }
34
    console.log('Coverage data:', data);
35
});
36

37
// Parse LCOV string data directly
38
const lcovString = `TN:Test #1
39
SF:src/example.js
40
FN:1,myFunction
41
FNDA:5,myFunction
42
FNF:1
43
FNH:1
44
DA:1,5
45
DA:2,3
46
LF:2
47
LH:2
48
end_of_record`;
49

50
parse(lcovString, function(err, data) {
51
    if (err) {
52
        console.error('Parse error:', err);
53
        return;
54
    }
55
    console.log('Parsed coverage:', data);
56
});
57
```
58

59
## CLI Usage
60

61
The package includes a command-line interface for parsing LCOV files:
62

63
```bash
64
# Parse a file and output JSON
65
lcov-parse ./lcov.info
66

67
# Use with pipes
68
cat lcov.info | xargs -0 lcov-parse
69
```
70

71
## Capabilities
72

73
### Main Parse Function
74

75
The primary parsing function that handles both file paths and LCOV string data.
76

77
```javascript { .api }
78
/**
79
 * Parse LCOV coverage data from file or string
80
 * @param {string} file - Either a file path to an LCOV file or raw LCOV data string
81
 * @param {function} callback - Error-first callback function (err, data) => void
82
 */
83
function parse(file, callback);
84
```
85

86
**Parameters:**
87
- `file` (string): File path to LCOV file or raw LCOV string data
88
- `callback` (function): Error-first callback with signature `(err, data) => void`
89

90
**Behavior:**
91
- If `file` parameter is a valid file path, reads and parses the file
92
- If `file` parameter is not a valid file path, treats it as raw LCOV string data
93
- Calls callback with parsed JSON data array on success
94
- Calls callback with error string on failure
95

96
### Source String Parser
97

98
Direct string parsing function for raw LCOV data.
99

100
```javascript { .api }
101
/**
102
 * Parse raw LCOV string data directly
103
 * @param {string} str - Raw LCOV data string
104
 * @param {function} callback - Error-first callback function (err, data) => void
105
 */
106
parse.source(str, callback);
107
```
108

109
**Parameters:**
110
- `str` (string): Raw LCOV format string
111
- `callback` (function): Error-first callback with signature `(err, data) => void`
112

113
**Behavior:**
114
- Parses LCOV format string without file system operations
115
- Supports all standard LCOV record types
116
- Returns array of coverage objects for each file
117

118
### CLI Command
119

120
Command-line interface for parsing LCOV files.
121

122
```bash { .api }
123
lcov-parse <file>
124
```
125

126
**Parameters:**
127
- `file` (string): Path to LCOV file
128

129
**Output:**
130
- JSON string printed to stdout
131
- Error messages printed to stderr
132

133
## Data Structure
134

135
The parser returns an array of coverage objects, one for each source file found in the LCOV data. Each coverage object has the following structure:
136

137
```javascript { .api }
138
/**
139
 * Coverage data structure returned by the parser
140
 */
141
interface CoverageData {
142
  title: string;        // Test name (from TN record)
143
  file: string;         // Source file path (from SF record)
144
  functions: {
145
    found: number;      // Total functions found (from FNF record)
146
    hit: number;        // Functions with coverage (from FNH record)
147
    details: Array<{    // Function details array
148
      name: string;     // Function name (from FN record)
149
      line: number;     // Line number (from FN record)  
150
      hit: number;      // Hit count (from FNDA record)
151
    }>;
152
  };
153
  lines: {
154
    found: number;      // Total lines found (from LF record)
155
    hit: number;        // Lines with coverage (from LH record)
156
    details: Array<{    // Line details array
157
      line: number;     // Line number (from DA record)
158
      hit: number;      // Hit count (from DA record)
159
    }>;
160
  };
161
  branches: {
162
    found: number;      // Total branches found (from BRF record)
163
    hit: number;        // Branches with coverage (from BRH record)
164
    details: Array<{    // Branch details array
165
      line: number;     // Line number (from BRDA record)
166
      block: number;    // Block number (from BRDA record)
167
      branch: number;   // Branch number (from BRDA record)
168
      taken: number;    // Times taken (from BRDA record, 0 if '-')
169
    }>;
170
  };
171
}
172
```
173

174
### Example Output
175

176
```javascript
177
[
178
  {
179
    "title": "Test #1",
180
    "file": "src/example.js",
181
    "functions": {
182
      "hit": 23,
183
      "found": 29,
184
      "details": [
185
        {
186
          "name": "myFunction",
187
          "line": 7,
188
          "hit": 6
189
        },
190
        {
191
          "name": "anotherFunction", 
192
          "line": 25,
193
          "hit": 3
194
        }
195
      ]
196
    },
197
    "lines": {
198
      "found": 181,
199
      "hit": 143,
200
      "details": [
201
        {
202
          "line": 7,
203
          "hit": 6
204
        },
205
        {
206
          "line": 29,
207
          "hit": 6
208
        }
209
      ]
210
    },
211
    "branches": {
212
      "found": 12,
213
      "hit": 10,
214
      "details": [
215
        {
216
          "line": 15,
217
          "block": 0,
218
          "branch": 0,
219
          "taken": 5
220
        }
221
      ]
222
    }
223
  }
224
]
225
```
226

227
## LCOV Format Support
228

229
The parser supports all standard LCOV record types:
230

231
- **TN**: Test name
232
- **SF**: Source file path
233
- **FN**: Function name and line number  
234
- **FNDA**: Function execution count
235
- **FNF**: Functions found
236
- **FNH**: Functions hit
237
- **DA**: Line execution count
238
- **LF**: Lines found
239
- **LH**: Lines hit
240
- **BRDA**: Branch coverage data
241
- **BRF**: Branches found
242
- **BRH**: Branches hit
243
- **end_of_record**: Record separator
244

245
## Error Handling
246

247
The parser handles several error conditions:
248

249
- **File not found**: If the first parameter is not a valid file path, it's treated as string data
250
- **Parse failure**: Returns error string `"Failed to parse string"` via callback if parsing fails
251
- **Invalid data**: May result in incomplete or malformed output objects with default values
252

253
**Example error handling:**
254

255
```javascript
256
parse('./nonexistent.info', function(err, data) {
257
    if (err) {
258
        console.error('Error:', err);
259
        // Handle error - could be parse failure or invalid data
260
        return;
261
    }
262
    // Process successful data
263
    console.log('Coverage reports:', data.length);
264
});
265
```
266

267
## Dependencies
268

269
- **Built-in modules**: `fs`, `path` (Node.js standard library)
270
- **No external runtime dependencies**
271

272
## Use Cases
273

274
- **CI/CD Pipelines**: Parse coverage reports in continuous integration workflows
275
- **Development Tools**: Integrate coverage data into development environments
276
- **Coverage Analysis**: Convert LCOV data for further processing and analysis
277
- **Reporting Systems**: Transform coverage data for custom reporting formats
278
- **Test Automation**: Process coverage results in automated testing workflows