0
# Tree Summarization
1

2
Tree summarization generates hierarchical coverage summaries organized by directory structure. This capability is primarily used by the HTML report generator to create navigable coverage trees and is useful for analyzing coverage patterns across large codebases.
3

4
## Capabilities
5

6
### TreeSummarizer Class
7

8
Creates tree-structured coverage summaries from file coverage data.
9

10
```javascript { .api }
11
/**
12
 * Creates a tree summarizer for organizing coverage data by directory structure
13
 */
14
class TreeSummarizer {
15
    constructor();
16
    
17
    /**
18
     * Adds coverage metrics for a specific file path
19
     * @param {string} filePath - The full path to the file
20
     * @param {Object} metrics - Coverage metrics summary for the file
21
     */
22
    addFileCoverageSummary(filePath: string, metrics: Object): void;
23
    
24
    /**
25
     * Generates a hierarchical tree summary from all added file coverage data
26
     * @returns {TreeSummary} Tree structure with coverage metrics
27
     */
28
    getTreeSummary(): TreeSummary;
29
}
30
```
31

32
**Usage Example:**
33

34
```javascript
35
const istanbul = require('istanbul');
36
const TreeSummarizer = istanbul.TreeSummarizer;
37

38
// Create summarizer and add file coverage
39
const summarizer = new TreeSummarizer();
40
summarizer.addFileCoverageSummary('/src/utils/math.js', {
41
    statements: { total: 10, covered: 8, pct: 80 },
42
    branches: { total: 4, covered: 3, pct: 75 },
43
    functions: { total: 2, covered: 2, pct: 100 },
44
    lines: { total: 8, covered: 7, pct: 87.5 }
45
});
46

47
summarizer.addFileCoverageSummary('/src/lib/core.js', {
48
    statements: { total: 25, covered: 20, pct: 80 },
49
    branches: { total: 8, covered: 6, pct: 75 },
50
    functions: { total: 5, covered: 4, pct: 80 },
51
    lines: { total: 20, covered: 16, pct: 80 }
52
});
53

54
// Generate tree summary
55
const treeSummary = summarizer.getTreeSummary();
56
console.log(treeSummary.toJSON());
57
```
58

59
### TreeSummary Interface
60

61
Represents the hierarchical coverage tree with navigation capabilities.
62

63
```javascript { .api }
64
interface TreeSummary {
65
    /**
66
     * Common path prefix for all files in the tree
67
     */
68
    prefix: string[];
69
    
70
    /**
71
     * Root node of the coverage tree
72
     */
73
    root: Node;
74
    
75
    /**
76
     * Retrieves a node by its short name
77
     * @param {string} shortName - The relative name of the node
78
     * @returns {Node} The node if found
79
     */
80
    getNode(shortName: string): Node;
81
    
82
    /**
83
     * Converts the tree summary to JSON format
84
     * @returns {Object} JSON representation of the tree
85
     */
86
    toJSON(): Object;
87
}
88
```
89

90
### Node Interface
91

92
Represents individual files and directories in the coverage tree.
93

94
```javascript { .api }
95
interface Node {
96
    /**
97
     * Short name of the node (filename or directory name)
98
     */
99
    name: string;
100
    
101
    /**
102
     * Name relative to parent directory
103
     */
104
    relativeName: string;
105
    
106
    /**
107
     * Full path name of the node
108
     */
109
    fullName: string;
110
    
111
    /**
112
     * Type of node: 'file' for files, 'dir' for directories
113
     */
114
    kind: 'file' | 'dir';
115
    
116
    /**
117
     * Coverage metrics for this node (null for directories without files)
118
     * Aggregated from all child nodes for directories
119
     */
120
    metrics: Object | null;
121
    
122
    /**
123
     * Package-style metrics including only direct file children
124
     * (excludes subdirectory contributions)
125
     */
126
    packageMetrics: Object | null;
127
    
128
    /**
129
     * Parent node (null for root)
130
     */
131
    parent: Node | null;
132
    
133
    /**
134
     * Array of child nodes
135
     */
136
    children: Node[];
137
    
138
    /**
139
     * Returns the display name for the node
140
     * @returns {string} The relative name for display
141
     */
142
    displayShortName(): string;
143
    
144
    /**
145
     * Adds a child node and sets parent relationship
146
     * @param {Node} child - The child node to add
147
     */
148
    addChild(child: Node): void;
149
    
150
    /**
151
     * Converts the node and its children to JSON format
152
     * @returns {Object} JSON representation including all descendants
153
     */
154
    toJSON(): Object;
155
}
156
```
157

158
## Coverage Metrics Structure
159

160
The metrics objects used throughout the tree summarizer follow this structure:
161

162
```javascript { .api }
163
interface CoverageMetrics {
164
    statements: {
165
        total: number;    // Total number of statements
166
        covered: number;  // Number of covered statements  
167
        skipped: number;  // Number of skipped statements
168
        pct: number;      // Coverage percentage
169
    };
170
    branches: {
171
        total: number;    // Total number of branches
172
        covered: number;  // Number of covered branches
173
        skipped: number;  // Number of skipped branches
174
        pct: number;      // Coverage percentage
175
    };
176
    functions: {
177
        total: number;    // Total number of functions
178
        covered: number;  // Number of covered functions
179
        skipped: number;  // Number of skipped functions
180
        pct: number;      // Coverage percentage
181
    };
182
    lines: {
183
        total: number;    // Total number of lines
184
        covered: number;  // Number of covered lines
185
        skipped: number;  // Number of skipped lines
186
        pct: number;      // Coverage percentage
187
    };
188
}
189
```
190

191
## Integration with Report Generation
192

193
The TreeSummarizer is primarily used by the HTML report generator to create navigable directory trees:
194

195
```javascript
196
const istanbul = require('istanbul');
197
const collector = new istanbul.Collector();
198
// ... add coverage data to collector
199

200
// Generate tree for HTML reports
201
const summarizer = new istanbul.TreeSummarizer();
202
collector.files().forEach(file => {
203
    const fileCoverage = collector.fileCoverageFor(file);
204
    const summary = istanbul.utils.summarizeFileCoverage(fileCoverage);
205
    summarizer.addFileCoverageSummary(file, summary);
206
});
207

208
const tree = summarizer.getTreeSummary();
209
// Tree is used by HTML report templates for navigation
210
```