0
# Logging and Diagnostics
1

2
Verbosity control and diagnostic message reporting system for comprehensive build feedback.
3

4
## Capabilities
5

6
### Verbosity Control
7

8
Configure logging levels to control the amount of build information displayed.
9

10
```typescript { .api }
11
/**
12
 * Verbosity levels for controlling log output
13
 */
14
enum VerbosityLevel {
15
  /** Only show critical errors that stop the build */
16
  Error = 0,
17
  
18
  /** Show errors and warnings (default) */
19
  Warning = 1,
20
  
21
  /** Show errors, warnings, and informational messages */
22
  Info = 2,
23
  
24
  /** Show all messages including debug information */
25
  Debug = 3
26
}
27
```
28

29
**Verbosity Level Examples:**
30

31
```javascript
32
// Production build - minimal output
33
typescript({
34
  verbosity: 0  // VerbosityLevel.Error
35
})
36

37
// Development build - warnings and errors
38
typescript({
39
  verbosity: 1  // VerbosityLevel.Warning (default)
40
})
41

42
// Detailed development - include build info
43
typescript({
44
  verbosity: 2  // VerbosityLevel.Info
45
})
46

47
// Debug build issues - full diagnostic output
48
typescript({
49
  verbosity: 3  // VerbosityLevel.Debug
50
})
51
```
52

53
### Rollup Context Integration
54

55
Logging system that integrates with Rollup's warning and error reporting.
56

57
```typescript { .api }
58
/**
59
 * Rollup context wrapper for consistent logging
60
 */
61
class RollupContext {
62
  /**
63
   * Create logging context
64
   * @param verbosity - Current verbosity level
65
   * @param bail - Whether to throw errors or convert to warnings
66
   * @param context - Rollup plugin context
67
   * @param prefix - Message prefix for identification
68
   */
69
  constructor(
70
    verbosity: VerbosityLevel, 
71
    bail: boolean, 
72
    context: PluginContext, 
73
    prefix?: string
74
  );
75
  
76
  /**
77
   * Log warning message (shown at Warning level and above)
78
   * @param message - Warning message or lazy message function
79
   */
80
  warn(message: string | (() => string)): void;
81
  
82
  /**
83
   * Log error message (shown at Error level and above)
84
   * May throw error if abortOnError is true
85
   * @param message - Error message or lazy message function
86
   */
87
  error(message: string | (() => string)): void | never;
88
  
89
  /**
90
   * Log informational message (shown at Info level and above)
91
   * @param message - Info message or lazy message function
92
   */
93
  info(message: string | (() => string)): void;
94
  
95
  /**
96
   * Log debug message (shown at Debug level only)
97
   * @param message - Debug message or lazy message function
98
   */
99
  debug(message: string | (() => string)): void;
100
}
101
```
102

103
### TypeScript Diagnostic Processing
104

105
Comprehensive handling of TypeScript compiler diagnostics and error messages.
106

107
```typescript { .api }
108
/**
109
 * Convert TypeScript diagnostics to plugin format
110
 * @param type - Diagnostic category identifier
111
 * @param diagnostics - Raw TypeScript diagnostics
112
 * @returns Converted diagnostic objects
113
 */
114
function convertDiagnostic(
115
  type: string, 
116
  diagnostics: readonly tsTypes.Diagnostic[]
117
): PluginDiagnostic[];
118

119
/**
120
 * Plugin diagnostic format
121
 */
122
interface PluginDiagnostic {
123
  /** Source file where diagnostic occurred */
124
  fileName?: string;
125
  
126
  /** Line number (1-based) */
127
  line?: number;
128
  
129
  /** Column number (1-based) */
130
  column?: number;
131
  
132
  /** Diagnostic message text */
133
  messageText: string;
134
  
135
  /** TypeScript diagnostic category */
136
  category: tsTypes.DiagnosticCategory;
137
  
138
  /** TypeScript diagnostic code */
139
  code: number;
140
  
141
  /** Diagnostic type (syntax, semantic, options, etc.) */
142
  type: string;
143
}
144

145
/**
146
 * Print diagnostics with formatting and colors
147
 * @param context - Rollup context for output
148
 * @param diagnostics - Diagnostics to display
149
 * @param pretty - Enable colored/formatted output
150
 */
151
function printDiagnostics(
152
  context: RollupContext, 
153
  diagnostics: PluginDiagnostic[], 
154
  pretty: boolean
155
): void;
156
```
157

158
### Diagnostic Categories
159

160
TypeScript provides several categories of diagnostic messages:
161

162
```typescript { .api }
163
/**
164
 * TypeScript diagnostic categories
165
 */
166
enum DiagnosticCategory {
167
  /** Warning messages that don't prevent compilation */
168
  Warning = 0,
169
  
170
  /** Error messages that may prevent compilation */
171
  Error = 1,
172
  
173
  /** Suggestion messages for code improvements */
174
  Suggestion = 2,
175
  
176
  /** Informational messages */
177
  Message = 3
178
}
179

180
/**
181
 * Common diagnostic types processed by the plugin
182
 */
183
interface DiagnosticTypes {
184
  /** Syntax errors in TypeScript code */
185
  syntax: 'syntax';
186
  
187
  /** Type checking and semantic errors */
188
  semantic: 'semantic';
189
  
190
  /** Compiler configuration errors */
191
  options: 'options';
192
  
193
  /** Global errors not tied to specific files */
194
  global: 'global';
195
}
196
```
197

198
### Build Information Logging
199

200
Detailed logging of build process information and configuration.
201

202
```typescript { .api }
203
/**
204
 * Build information logged at various verbosity levels
205
 */
206
interface BuildInformation {
207
  /** TypeScript version being used */
208
  typescriptVersion: string;
209
  
210
  /** Rollup version being used */
211
  rollupVersion: string;
212
  
213
  /** Plugin version */
214
  pluginVersion: string;
215
  
216
  /** TSLib version for helper functions */
217
  tslibVersion: string;
218
  
219
  /** Current plugin configuration */
220
  pluginOptions: IOptions;
221
  
222
  /** Rollup configuration object */
223
  rollupConfig: InputOptions;
224
  
225
  /** Path to tsconfig file being used */
226
  tsconfigPath?: string;
227
  
228
  /** Parsed TypeScript configuration */
229
  parsedTsconfig: tsTypes.ParsedCommandLine;
230
}
231
```
232

233
**Example Build Information Output:**
234

235
```
236
rpt2: typescript version: 5.1.3
237
rpt2: tslib version: 2.6.2
238
rpt2: rollup version: 2.70.2
239
rpt2: rollup-plugin-typescript2 version: 0.36.0
240
rpt2: running in watch mode
241
```
242

243
### Error Handling Strategies
244

245
Configure how errors are handled during the build process.
246

247
```typescript { .api }
248
/**
249
 * Error handling configuration
250
 */
251
interface ErrorHandling {
252
  /** Stop build on first error vs collect all errors */
253
  abortOnError: boolean;
254
  
255
  /** Enable comprehensive type checking */
256
  check: boolean;
257
  
258
  /** Control diagnostic output verbosity */
259
  verbosity: VerbosityLevel;
260
}
261

262
/**
263
 * Error processing flow
264
 */
265
interface ErrorProcessingFlow {
266
  /** Collect syntax diagnostics from TypeScript */
267
  syntaxDiagnostics: tsTypes.Diagnostic[];
268
  
269
  /** Collect semantic diagnostics from TypeScript */
270
  semanticDiagnostics: tsTypes.Diagnostic[];
271
  
272
  /** Collect compiler option diagnostics */
273
  optionsDiagnostics: tsTypes.Diagnostic[];
274
  
275
  /** Convert to plugin format */
276
  pluginDiagnostics: PluginDiagnostic[];
277
  
278
  /** Format and display to user */
279
  formattedOutput: string;
280
}
281
```
282

283
### Diagnostic Display Formats
284

285
Control how diagnostic messages are formatted and displayed.
286

287
```typescript { .api }
288
/**
289
 * Diagnostic formatting options
290
 */
291
interface DiagnosticFormatting {
292
  /** Enable colored output with ANSI codes */
293
  pretty: boolean;
294
  
295
  /** Include file paths in output */
296
  showFilePaths: boolean;
297
  
298
  /** Include line and column numbers */
299
  showPositions: boolean;
300
  
301
  /** Include TypeScript error codes */
302
  showErrorCodes: boolean;
303
  
304
  /** Group diagnostics by file */
305
  groupByFile: boolean;
306
}
307
```
308

309
**Pretty Formatted Output Example:**
310

311
```
312
src/main.ts(15,7): error TS2322: Type 'string' is not assignable to type 'number'.
313
  
314
  15     const count: number = "hello";
315
                ~~~~~ 
316
  
317
src/utils.ts(8,12): warning TS6133: 'unused' is declared but its value is never read.
318
  
319
   8     const unused = 42;
320
               ~~~~~~
321
```
322

323
### Performance Diagnostics
324

325
Monitor build performance and identify bottlenecks.
326

327
```typescript { .api }
328
/**
329
 * Performance monitoring capabilities
330
 */
331
interface PerformanceMonitoring {
332
  /** Track compilation time per file */
333
  fileCompilationTimes: Map<string, number>;
334
  
335
  /** Track cache hit/miss ratios */
336
  cacheStatistics: {
337
    hits: number;
338
    misses: number;
339
    hitRatio: number;
340
  };
341
  
342
  /** Track type checking time */
343
  typeCheckingTime: number;
344
  
345
  /** Track total build time */
346
  totalBuildTime: number;
347
}
348
```
349

350
### Custom Diagnostic Handlers
351

352
Advanced logging customization for specialized use cases.
353

354
```typescript { .api }
355
/**
356
 * Custom diagnostic processing
357
 */
358
interface CustomDiagnosticHandler {
359
  /** Filter diagnostics before display */
360
  filterDiagnostics?: (diagnostics: PluginDiagnostic[]) => PluginDiagnostic[];
361
  
362
  /** Custom formatting function */
363
  formatDiagnostic?: (diagnostic: PluginDiagnostic) => string;
364
  
365
  /** Custom output handler */
366
  outputHandler?: (formattedMessage: string) => void;
367
}
368
```
369

370
**Usage Examples:**
371

372
```javascript
373
// Minimal logging for CI builds
374
typescript({
375
  verbosity: 0,           // Errors only
376
  abortOnError: true,     // Fail fast
377
  check: true            // Still check types
378
})
379

380
// Development with detailed feedback
381
typescript({
382
  verbosity: 2,          // Info level
383
  abortOnError: false,   // Continue on errors
384
  check: true           // Full type checking
385
})
386

387
// Debug build issues
388
typescript({
389
  verbosity: 3,          // Debug level
390
  clean: true,          // Fresh cache
391
  abortOnError: false   // See all issues
392
})
393

394
// Production build - fast and quiet
395
typescript({
396
  verbosity: 1,          // Warnings and errors
397
  check: false,         // Transpile only (fastest)
398
  clean: false          // Use cache
399
})
400
```
401

402
### Lazy Message Evaluation
403

404
Optimize performance by only evaluating expensive debug messages when needed.
405

406
```typescript { .api }
407
/**
408
 * Lazy message evaluation for performance
409
 */
410
type LazyMessage = string | (() => string);
411

412
/**
413
 * Example usage of lazy messages
414
 */
415
const examples = {
416
  // Expensive string operations only run if debug level is active
417
  debug: () => `Detailed analysis: ${JSON.stringify(complexObject, null, 2)}`,
418
  
419
  // Simple string - always evaluated
420
  info: "Build completed successfully",
421
  
422
  // Conditional message based on state
423
  warning: () => errors.length > 0 ? `Found ${errors.length} errors` : "No errors found"
424
};
425
```
426

427
This lazy evaluation pattern ensures that expensive string operations (like JSON serialization) only occur when the message will actually be displayed, improving performance at lower verbosity levels.