0
# Reporting & Output
1

2
Multiple reporting formats and customizable output options for different workflows and CI/CD integration. Knip provides built-in reporters and supports custom reporter development.
3

4
## Capabilities
5

6
### Reporter Interface
7

8
Core interface for creating custom reporters.
9

10
```typescript { .api }
11
/**
12
 * Reporter function interface
13
 * @param options - Reporter options containing issues and metadata
14
 */
15
type Reporter = (options: ReporterOptions) => void;
16

17
interface ReporterOptions {
18
  /** Report configuration indicating which issue types to include */
19
  report: Report;
20
  /** All detected issues organized by type */
21
  issues: Issues;
22
  /** Issue counters by type */
23
  counters: Counters;
24
  /** Hints about tagged exports */
25
  tagHints: Set<TagHint>;
26
  /** Configuration improvement suggestions */
27
  configurationHints: Set<ConfigurationHint>;
28
  /** Whether to disable configuration hints */
29
  isDisableConfigHints: boolean;
30
  /** Treat configuration hints as errors */
31
  isTreatConfigHintsAsErrors: boolean;
32
  /** Current working directory */
33
  cwd: string;
34
  /** Production mode flag */
35
  isProduction: boolean;
36
  /** Show progress information */
37
  isShowProgress: boolean;
38
  /** Custom options passed to reporter */
39
  options: string;
40
  /** Options for preprocessors */
41
  preprocessorOptions: string;
42
  /** List of included workspace directories */
43
  includedWorkspaceDirs: string[];
44
  /** Configuration file path */
45
  configFilePath?: string;
46
}
47

48
interface Report {
49
  files: boolean;
50
  dependencies: boolean;
51
  devDependencies: boolean;
52
  optionalPeerDependencies: boolean;
53
  unlisted: boolean;
54
  binaries: boolean;
55
  unresolved: boolean;
56
  exports: boolean;
57
  types: boolean;
58
  nsExports: boolean;
59
  nsTypes: boolean;
60
  duplicates: boolean;
61
  enumMembers: boolean;
62
  classMembers: boolean;
63
}
64
```
65

66
**Usage Examples:**
67

68
### Using Built-in Reporters
69

70
```bash
71
# Default symbols reporter
72
npx knip
73

74
# JSON output
75
npx knip --reporter json
76

77
# Multiple reporters
78
npx knip --reporter symbols --reporter json
79

80
# Compact output
81
npx knip --reporter compact
82

83
# Markdown output for documentation
84
npx knip --reporter markdown
85
```
86

87
### Built-in Reporters
88

89
Knip includes several built-in reporters for different use cases.
90

91
```typescript { .api }
92
/** Available built-in reporters */
93
type BuiltInReporter = 
94
  | 'symbols'      // Default terminal output with symbols
95
  | 'compact'      // Compact terminal output
96
  | 'json'         // JSON format for tools
97
  | 'markdown'     // Markdown format for documentation  
98
  | 'codeowners'   // GitHub CODEOWNERS format
99
  | 'codeclimate'  // Code Climate format for CI
100
  | 'disclosure';  // Issue disclosure summary
101
```
102

103
### Symbols Reporter
104

105
Default reporter with symbol-based output and color coding.
106

107
```typescript { .api }
108
/**
109
 * Default symbols reporter
110
 * @param options - Reporter options
111
 */
112
function symbolsReporter(options: ReporterOptions): void;
113
```
114

115
**Output Example:**
116

117
```
118
✂️  Unused files (2)
119
src/utils/unused-helper.ts
120
test/fixtures/old-test.ts
121

122
✂️  Unused dependencies (3)
123
lodash (devDependencies)
124
moment (dependencies)
125
@types/unused (devDependencies)
126

127
✂️  Unused exports (5)
128
src/api.ts:
129
  • deprecatedFunction
130
  • InternalType
131

132
src/utils.ts:
133
  • helperFunction
134
  • UtilityClass
135
  • CONSTANT_VALUE
136
```
137

138
### JSON Reporter
139

140
Machine-readable JSON output for tool integration.
141

142
```typescript { .api }
143
/**
144
 * JSON reporter for machine-readable output
145
 * @param options - Reporter options
146
 */
147
function jsonReporter(options: ReporterOptions): void;
148

149
interface JsonOutput {
150
  files: string[];
151
  issues: {
152
    [issueType: string]: {
153
      [filePath: string]: Array<{
154
        symbol: string;
155
        symbolType?: string;
156
        parentSymbol?: string;
157
        line?: number;
158
        col?: number;
159
        pos?: number;
160
      }>;
161
    };
162
  };
163
  counters: Record<string, number>;
164
  rules: Record<string, string>;
165
  configurationHints?: ConfigurationHint[];
166
}
167
```
168

169
**Usage Examples:**
170

171
```bash
172
# Output JSON to file
173
npx knip --reporter json > knip-results.json
174

175
# Process with jq
176
npx knip --reporter json | jq '.counters.total'
177
```
178

179
### Compact Reporter
180

181
Minimal output format for CI environments.
182

183
```typescript { .api }
184
/**
185
 * Compact reporter for minimal output
186
 * @param options - Reporter options  
187
 */
188
function compactReporter(options: ReporterOptions): void;
189
```
190

191
**Output Example:**
192

193
```
194
src/unused.ts: unused export "helper"
195
src/api.ts: unused export "oldFunction", "InternalType"  
196
package.json: unused dependency "lodash"
197
Total: 4 issues
198
```
199

200
### Markdown Reporter
201

202
Markdown format suitable for documentation and pull request comments.
203

204
```typescript { .api }
205
/**
206
 * Markdown reporter for documentation
207
 * @param options - Reporter options
208
 */
209
function markdownReporter(options: ReporterOptions): void;
210
```
211

212
**Output Example:**
213

214
```markdown
215
# Knip Report
216

217
## Unused Files (2)
218
- `src/utils/unused-helper.ts`
219
- `test/fixtures/old-test.ts`
220

221
## Unused Dependencies (3)
222
- `lodash` (devDependencies)
223
- `moment` (dependencies)  
224
- `@types/unused` (devDependencies)
225

226
## Unused Exports (5)
227
### `src/api.ts`
228
- `deprecatedFunction`
229
- `InternalType`
230

231
### `src/utils.ts`
232
- `helperFunction`
233
- `UtilityClass`
234
- `CONSTANT_VALUE`
235
```
236

237
### Code Climate Reporter
238

239
Code Climate format for CI integration and code quality tracking.
240

241
```typescript { .api }
242
/**
243
 * Code Climate reporter for CI integration
244
 * @param options - Reporter options
245
 */
246
function codeclimateReporter(options: ReporterOptions): void;
247

248
interface CodeClimateIssue {
249
  type: "issue";
250
  check_name: string;
251
  description: string;
252
  categories: string[];
253
  location: {
254
    path: string;
255
    lines?: {
256
      begin: number;
257
      end: number;
258
    };
259
  };
260
  severity: "minor" | "major" | "critical";
261
  fingerprint: string;
262
}
263
```
264

265
### CODEOWNERS Reporter
266

267
Generates GitHub CODEOWNERS format showing issue ownership.
268

269
```typescript { .api }
270
/**
271
 * CODEOWNERS reporter for GitHub integration
272
 * @param options - Reporter options
273
 */
274
function codeownersReporter(options: ReporterOptions): void;
275
```
276

277
### Custom Reporter Development
278

279
Create custom reporters for specific workflows.
280

281
```typescript { .api }
282
/**
283
 * Example custom reporter
284
 */
285
const customReporter: Reporter = (options) => {
286
  const { issues, counters, cwd } = options;
287
  
288
  // Custom reporting logic
289
  console.log(`Custom Report for ${cwd}`);
290
  console.log(`Total issues: ${counters.total}`);
291
  
292
  // Process specific issue types
293
  for (const [filePath, fileIssues] of Object.entries(issues.exports)) {
294
    console.log(`File: ${filePath}`);
295
    for (const [symbol, issue] of Object.entries(fileIssues)) {
296
      console.log(`  - Unused export: ${symbol} (line ${issue.line})`);
297
    }
298
  }
299
  
300
  // Add custom metadata
301
  console.log(`Report generated at ${new Date().toISOString()}`);
302
};
303

304
// Register custom reporter
305
import { runReporters } from "knip";
306

307
await runReporters(['custom'], reporterOptions);
308
```
309

310
### Reporter Options
311

312
Customize reporter behavior with options.
313

314
```typescript { .api }
315
/**
316
 * Run reporters with custom options
317
 * @param reporters - List of reporter names
318
 * @param options - Reporter options
319
 */
320
function runReporters(
321
  reporters: string[],
322
  options: ReporterOptions
323
): Promise<void>;
324

325
/**
326
 * Parse reporter options from JSON string
327
 * @param optionsString - JSON string with options
328
 * @returns Parsed options object
329
 */
330
function parseReporterOptions(optionsString: string): Record<string, any>;
331
```
332

333
**Usage Examples:**
334

335
```bash
336
# Pass options to reporters
337
npx knip --reporter json --reporter-options '{"indent":2,"sort":true}'
338

339
# Compact reporter with custom separator
340
npx knip --reporter compact --reporter-options '{"separator":"|"}'
341
```
342

343
### Preprocessors
344

345
Transform reporter data before output.
346

347
```typescript { .api }
348
/**
349
 * Preprocessor function interface
350
 * @param options - Original reporter options
351
 * @returns Modified reporter options
352
 */
353
type Preprocessor = (options: ReporterOptions) => ReporterOptions;
354

355
/**
356
 * Run preprocessors on reporter data
357
 * @param preprocessors - List of preprocessor names
358
 * @param options - Original reporter options
359
 * @returns Modified reporter options
360
 */
361
function runPreprocessors(
362
  preprocessors: string[],
363
  options: ReporterOptions
364
): Promise<ReporterOptions>;
365
```
366

367
**Usage Examples:**
368

369
```bash
370
# Apply preprocessors before reporting
371
npx knip --preprocessor sort --preprocessor filter --reporter json
372

373
# Pass options to preprocessors
374
npx knip --preprocessor-options '{"filter":{"minSeverity":"error"}}'
375
```
376

377
### Integration Examples
378

379
Common integration patterns for different workflows.
380

381
**GitHub Actions:**
382

383
```yaml
384
- name: Run Knip
385
  run: |
386
    npx knip --reporter json > knip-results.json
387
    npx knip --reporter markdown >> $GITHUB_STEP_SUMMARY
388
```
389

390
**CI/CD with Code Climate:**
391

392
```bash
393
# Export Code Climate format
394
npx knip --reporter codeclimate > codeclimate-knip.json
395
```
396

397
**Pull Request Comments:**
398

399
```bash
400
# Generate markdown for PR comment
401
npx knip --reporter markdown > knip-report.md
402
```
403

404
**Custom Dashboard Integration:**
405

406
```typescript
407
import { main } from "knip";
408

409
const results = await main({ cwd: process.cwd() });
410

411
// Send to custom dashboard
412
await fetch('/api/code-analysis', {
413
  method: 'POST',
414
  headers: { 'Content-Type': 'application/json' },
415
  body: JSON.stringify({
416
    project: 'my-app',
417
    timestamp: Date.now(),
418
    issues: results.issues,
419
    counters: results.counters
420
  })
421
});
422
```