0
# Analysis Results
1

2
Structured data format for bundle analysis results, including file size breakdowns, error handling, and formatted output.
3

4
## Capabilities
5

6
### Main Result Interface
7

8
The primary result structure returned by the explore function.
9

10
```typescript { .api }
11
interface ExploreResult {
12
  /** Array of successfully analyzed bundles */
13
  bundles: ExploreBundleResult[];
14
  /** Result as a string - either JSON, TSV or HTML */
15
  output?: string;
16
  /** Array of errors and warnings from analysis */
17
  errors: ExploreErrorResult[];
18
}
19
```
20

21
**Usage Examples:**
22

23
```typescript
24
import { explore } from "source-map-explorer";
25

26
const result = await explore("dist/bundle.js");
27

28
// Access bundle data
29
console.log(result.bundles[0].totalBytes);
30
console.log(result.bundles[0].files);
31

32
// Handle errors
33
if (result.errors.length > 0) {
34
  result.errors.forEach(error => {
35
    console.error(`${error.bundleName}: ${error.message}`);
36
  });
37
}
38

39
// Use formatted output if requested
40
if (result.output) {
41
  console.log(result.output); // JSON, TSV, or HTML string
42
}
43
```
44

45
### Bundle Analysis Results
46

47
Detailed results for each successfully analyzed bundle.
48

49
```typescript { .api }
50
interface ExploreBundleResult {
51
  /** Display name for the bundle */
52
  bundleName: string;
53
  /** Map of source files to their size data */
54
  files: FileDataMap;
55
  /** Total bytes that were successfully mapped to source files */
56
  mappedBytes: number;
57
  /** Bytes that could not be mapped to source files */
58
  unmappedBytes?: number;
59
  /** Bytes consumed by end-of-line characters */
60
  eolBytes: number;
61
  /** Bytes consumed by sourceMappingURL comment */
62
  sourceMapCommentBytes: number;
63
  /** Total size of the bundle file */
64
  totalBytes: number;
65
}
66

67
type FileDataMap = Record<string, FileData>;
68

69
interface FileData {
70
  /** Size in bytes contributed by this file */
71
  size: number;
72
  /** Size in bytes covered by code coverage (if coverage data provided) */
73
  coveredSize?: number;
74
}
75
```
76

77
**Usage Examples:**
78

79
```typescript
80
const result = await explore("dist/bundle.js");
81
const bundle = result.bundles[0];
82

83
// Access size information  
84
console.log(`Total bundle size: ${bundle.totalBytes} bytes`);
85
console.log(`Mapped to sources: ${bundle.mappedBytes} bytes`);
86
console.log(`Unmapped: ${bundle.unmappedBytes || 0} bytes`);
87

88
// Iterate through source files
89
Object.entries(bundle.files).forEach(([filename, data]) => {
90
  console.log(`${filename}: ${data.size} bytes`);
91
  if (data.coveredSize !== undefined) {
92
    console.log(`  Coverage: ${data.coveredSize}/${data.size} bytes`);
93
  }
94
});
95

96
// Find largest contributors
97
const sortedFiles = Object.entries(bundle.files)
98
  .sort(([,a], [,b]) => b.size - a.size)
99
  .slice(0, 10);
100

101
console.log("Top 10 largest files:");
102
sortedFiles.forEach(([filename, data]) => {
103
  console.log(`  ${filename}: ${data.size} bytes`);
104
});
105
```
106

107
### Error Results
108

109
Error information for bundles that could not be analyzed successfully.
110

111
```typescript { .api }
112
interface ExploreErrorResult {
113
  /** Name of the bundle that failed */
114
  bundleName: string;
115
  /** Error code identifier */
116
  code: string;
117
  /** Human-readable error message */
118
  message: string;
119
  /** Original error object if available */
120
  error?: NodeJS.ErrnoException;
121
  /** True if this is a warning rather than a fatal error */
122
  isWarning?: boolean;
123
}
124
```
125

126
**Usage Examples:**
127

128
```typescript
129
const result = await explore(["good-bundle.js", "bad-bundle.js"]);
130

131
// Separate errors from warnings
132
const errors = result.errors.filter(e => !e.isWarning);
133
const warnings = result.errors.filter(e => e.isWarning);
134

135
// Handle fatal errors
136
errors.forEach(error => {
137
  console.error(`ERROR [${error.code}] ${error.bundleName}: ${error.message}`);
138
  if (error.error) {
139
    console.error("  Caused by:", error.error.message);
140
  }
141
});
142

143
// Handle warnings  
144
warnings.forEach(warning => {
145
  console.warn(`WARNING [${warning.code}] ${warning.bundleName}: ${warning.message}`);
146
});
147

148
// Check if any bundles succeeded
149
if (result.bundles.length === 0) {
150
  console.error("No bundles were successfully analyzed");
151
  process.exit(1);
152
}
153
```
154

155
## Special File Keys
156

157
Analysis results include special keys for different types of content:
158

159
```typescript { .api }
160
// Special filename constants used in results
161
const UNMAPPED_KEY = "[unmapped]";           // Bytes not mapped to source files
162
const SOURCE_MAP_COMMENT_KEY = "[sourceMappingURL]"; // Source map comment bytes  
163
const NO_SOURCE_KEY = "[no source]";         // Mapped bytes without source info
164
const EOL_KEY = "[EOLs]";                   // End-of-line character bytes
165
```
166

167
**Usage Examples:**
168

169
```typescript
170
import { explore, UNMAPPED_KEY, SOURCE_MAP_COMMENT_KEY } from "source-map-explorer";
171

172
const result = await explore("bundle.js");
173
const files = result.bundles[0].files;
174

175
// Check for unmapped bytes
176
if (files[UNMAPPED_KEY]) {
177
  console.log(`Unmapped bytes: ${files[UNMAPPED_KEY].size}`);
178
}
179

180
// Check source map comment size
181
if (files[SOURCE_MAP_COMMENT_KEY]) {
182
  console.log(`Source map comment: ${files[SOURCE_MAP_COMMENT_KEY].size} bytes`);
183
}
184

185
// Filter out special keys to get only source files
186
const sourceFiles = Object.entries(files).filter(([filename]) => 
187
  !filename.startsWith("[") || !filename.endsWith("]")
188
);
189

190
console.log(`Found ${sourceFiles.length} source files`);
191
```
192

193
## Output Formats
194

195
### JSON Output
196

197
Structured data format for programmatic processing.
198

199
```typescript
200
const result = await explore("bundle.js", { 
201
  output: { format: "json" } 
202
});
203

204
// result.output contains JSON string
205
const data = JSON.parse(result.output);
206
console.log(data.results[0].files);
207
```
208

209
**JSON Structure:**
210
```json
211
{
212
  "results": [
213
    {
214
      "bundleName": "bundle.js",
215
      "totalBytes": 12345,
216
      "mappedBytes": 11000,
217
      "unmappedBytes": 1000,
218
      "eolBytes": 200,
219
      "sourceMapCommentBytes": 145,
220
      "files": {
221
        "src/main.js": { "size": 2500 },
222
        "src/utils.js": { "size": 1200 },
223
        "node_modules/lodash/index.js": { "size": 7300 },
224
        "[unmapped]": { "size": 1000 }
225
      }
226
    }
227
  ]
228
}
229
```
230

231
### TSV Output
232

233
Tab-separated values format for spreadsheet import and analysis.
234

235
```typescript
236
const result = await explore("bundle.js", { 
237
  output: { format: "tsv" } 
238
});
239

240
// result.output contains TSV string
241
console.log(result.output);
242
```
243

244
**TSV Format:**
245
```
246
Source	Size
247
src/main.js	2500
248
node_modules/lodash/index.js	7300
249
src/utils.js	1200
250
[unmapped]	1000
251
[sourceMappingURL]	145
252
```
253

254
### HTML Output
255

256
Interactive treemap visualization for visual analysis.
257

258
```typescript
259
const result = await explore("bundle.js", { 
260
  output: { format: "html" } 
261
});
262

263
// result.output contains complete HTML document
264
fs.writeFileSync("analysis.html", result.output);
265
```
266

267
The HTML output includes:
268
- Interactive treemap visualization using d3.js
269
- Hover tooltips showing file sizes and percentages
270
- Clickable navigation for drilling into directories
271
- Color coding for coverage data (if provided)
272
- Responsive design for different screen sizes
273

274
## Coverage Data Integration
275

276
When Chrome DevTools coverage data is provided, results include coverage information:
277

278
```typescript
279
const result = await explore("bundle.js", {
280
  coverage: "coverage.json"
281
});
282

283
// FileData includes coveredSize when coverage is available
284
const files = result.bundles[0].files;
285
Object.entries(files).forEach(([filename, data]) => {
286
  if (data.coveredSize !== undefined) {
287
    const coverage = (data.coveredSize / data.size * 100).toFixed(1);
288
    console.log(`${filename}: ${coverage}% covered`);
289
  }
290
});
291
```
292

293
Coverage data affects:
294
- HTML visualization colors (red = low coverage, green = high coverage)
295
- FileData objects include `coveredSize` property
296
- Analysis warnings for files with zero coverage