0
# Reporting System
1

2
Pluggable output formatters for different use cases including default, unix, checkstyle, and XML formats. JSHint's reporting system allows customization of how linting results are displayed and processed.
3

4
## Capabilities
5

6
### Reporter Interface
7

8
Standard interface that all JSHint reporters must implement.
9

10
```javascript { .api }
11
/**
12
 * Reporter function interface for formatting JSHint output
13
 * @param results - Array of linting result objects containing file and error info
14
 * @param data - Array of detailed analysis data objects from JSHINT.data()
15
 * @param opts - Reporter options object (verbose, filename, etc.)
16
 */
17
function reporter(results, data, opts) {
18
  // results: Array of result objects
19
  // data: Array of JSHINT.data() objects  
20
  // opts: Reporter options object
21
}
22

23
// Result Object Structure
24
{
25
  file: string,          // File path
26
  error: {               // Error details
27
    line: number,        // Line number
28
    character: number,   // Character position
29
    reason: string,      // Error message
30
    code: string,        // Error code
31
    evidence: string     // Source code line (optional)
32
  }
33
}
34

35
// Data Object Structure (from JSHINT.data())
36
{
37
  functions: Array,      // Function analysis data
38
  options: Object,       // Options used
39
  errors: Array,         // Error objects
40
  implieds: Array,       // Implied globals
41
  globals: Array,        // Used/defined globals
42
  unused: Array,         // Unused variables
43
  member: Object,        // Member usage data
44
  json: boolean         // JSON mode flag
45
}
46

47
// Options Object Structure
48
{
49
  verbose: boolean,      // Show error codes
50
  filename: string       // Filename for stdin input
51
}
52
```
53

54
**Usage Examples:**
55

56
```javascript
57
// Custom reporter implementation
58
const myReporter = {
59
  reporter: function(results, data, opts) {
60
    // Process results
61
    results.forEach(result => {
62
      if (result.error) {
63
        console.log(`Error in ${result.file}:`);
64
        console.log(`  Line ${result.error.line}: ${result.error.reason}`);
65
        if (opts.verbose) {
66
          console.log(`  Code: ${result.error.code}`);
67
        }
68
      }
69
    });
70
    
71
    // Process additional data if needed
72
    data.forEach(fileData => {
73
      if (fileData.unused && fileData.unused.length > 0) {
74
        console.log('Unused variables:', fileData.unused);
75
      }
76
    });
77
  }
78
};
79

80
// Use with CLI
81
// jshint --reporter ./my-reporter.js file.js
82
```
83

84
### Built-in Reporters
85

86
JSHint includes several built-in reporters for different output formats and use cases.
87

88
```javascript { .api }
89
/**
90
 * Default reporter - Human-readable format with colors
91
 * Located at: src/reporters/default.js
92
 */
93
interface DefaultReporter {
94
  reporter(results, data, opts): void;
95
}
96

97
/**
98
 * Unix reporter - Standard unix tool output format
99
 * Format: filename:line:column: message
100
 * Located at: src/reporters/unix.js
101
 */
102
interface UnixReporter {
103
  reporter(results, data, opts): void;
104
}
105

106
/**
107
 * Checkstyle reporter - XML format for CI tools
108
 * Located at: src/reporters/checkstyle.js
109
 */
110
interface CheckstyleReporter {
111
  reporter(results, data, opts): void;
112
}
113

114
/**
115
 * JSLint XML reporter - JSLint-compatible XML output
116
 * Located at: src/reporters/jslint_xml.js
117
 */
118
interface JSLintXMLReporter {
119
  reporter(results, data, opts): void;
120
}
121

122
/**
123
 * Non-error reporter - Shows additional JSHint data beyond errors
124
 * Located at: src/reporters/non_error.js
125
 */
126
interface NonErrorReporter {
127
  reporter(results, data, opts): void;
128
}
129
```
130

131
**Usage Examples:**
132

133
```bash
134
# Default reporter (human-readable)
135
jshint app.js
136

137
# Unix format (great for grep, editors)
138
jshint --reporter unix app.js
139

140
# XML format for CI systems
141
jshint --reporter checkstyle app.js > checkstyle.xml
142

143
# JSLint-compatible XML
144
jshint --reporter jslint_xml app.js
145

146
# Show additional analysis data
147
jshint --show-non-errors app.js
148
```
149

150
### Default Reporter
151

152
Human-readable output format with optional colors and detailed error information.
153

154
**Example Output:**
155
```
156
app.js: line 12, col 25, Missing semicolon. (W033)
157
app.js: line 15, col 10, 'unusedVar' is defined but never used. (W098)
158

159
2 errors
160
```
161

162
**With verbose mode:**
163
```bash
164
jshint --verbose app.js
165
```
166
```
167
app.js: line 12, col 25, Missing semicolon. (W033)
168
app.js: line 15, col 10, 'unusedVar' is defined but never used. (W098)
169

170
2 errors
171
```
172

173
### Unix Reporter
174

175
Standard Unix tool output format ideal for integration with editors, grep, and other command-line tools.
176

177
**Format:** `filename:line:column: message`
178

179
**Example Output:**
180
```
181
app.js:12:25: Missing semicolon.
182
app.js:15:10: 'unusedVar' is defined but never used.
183
```
184

185
**Usage with editors:**
186
```bash
187
# Vim quickfix
188
jshint --reporter unix *.js | vim -q -
189

190
# Emacs compilation mode
191
jshint --reporter unix src/
192
```
193

194
### Checkstyle Reporter
195

196
XML format compatible with checkstyle and many CI/CD systems.
197

198
**Example Output:**
199
```xml
200
<?xml version="1.0" encoding="utf-8"?>
201
<checkstyle version="4.3">
202
  <file name="app.js">
203
    <error line="12" column="25" severity="error" message="Missing semicolon." source="jshint.W033" />
204
    <error line="15" column="10" severity="error" message="'unusedVar' is defined but never used." source="jshint.W098" />
205
  </file>
206
</checkstyle>
207
```
208

209
**CI Integration Examples:**
210

211
```bash
212
# Jenkins with Checkstyle plugin
213
jshint --reporter checkstyle src/ > checkstyle-jshint.xml
214

215
# SonarQube integration
216
jshint --reporter checkstyle --config .jshintrc src/ > jshint-report.xml
217
```
218

219
### JSLint XML Reporter
220

221
JSLint-compatible XML format for tools that expect JSLint output.
222

223
**Example Output:**
224
```xml
225
<?xml version="1.0" encoding="UTF-8" ?>
226
<jslint>
227
  <file name="app.js">
228
    <issue line="12" char="25" reason="Missing semicolon." evidence="    var x = 1" />
229
    <issue line="15" char="10" reason="'unusedVar' is defined but never used." evidence="    var unusedVar = 42;" />
230
  </file>
231
</jslint>
232
```
233

234
### Non-Error Reporter
235

236
Shows additional JSHint analysis data beyond just errors, including function information, globals, and unused variables.
237

238
**Example Output:**
239
```
240
app.js:
241
  Functions: 3
242
  Globals: console, require, module
243
  Unused variables: unusedVar (Line 15)
244
  Implied globals: (none)
245
```
246

247
**Usage:**
248
```bash
249
jshint --show-non-errors app.js
250
```
251

252
### Custom Reporters
253

254
Creating custom reporters for specific needs and integrations.
255

256
```javascript { .api }
257
/**
258
 * Custom reporter template
259
 * Export an object with a reporter function
260
 */
261
interface CustomReporter {
262
  reporter(results, data, opts): void;
263
}
264
```
265

266
**JSON Reporter Example:**
267

268
```javascript
269
// json-reporter.js
270
module.exports = {
271
  reporter: function(results, data, opts) {
272
    const output = {
273
      timestamp: new Date().toISOString(),
274
      files: results.reduce((acc, result) => {
275
        if (!acc[result.file]) {
276
          acc[result.file] = {
277
            errors: [],
278
            warnings: []
279
          };
280
        }
281
        
282
        if (result.error) {
283
          const error = {
284
            line: result.error.line,
285
            column: result.error.character,
286
            message: result.error.reason,
287
            code: result.error.code,
288
            severity: result.error.code.startsWith('E') ? 'error' : 'warning'
289
          };
290
          
291
          if (error.severity === 'error') {
292
            acc[result.file].errors.push(error);
293
          } else {
294
            acc[result.file].warnings.push(error);
295
          }
296
        }
297
        
298
        return acc;
299
      }, {}),
300
      summary: {
301
        totalFiles: Object.keys(results.reduce((acc, r) => {
302
          acc[r.file] = true;
303
          return acc;
304
        }, {})).length,
305
        totalErrors: results.filter(r => r.error && r.error.code.startsWith('E')).length,
306
        totalWarnings: results.filter(r => r.error && r.error.code.startsWith('W')).length
307
      }
308
    };
309
    
310
    console.log(JSON.stringify(output, null, 2));
311
  }
312
};
313
```
314

315
**Usage:**
316
```bash
317
jshint --reporter ./json-reporter.js src/ > report.json
318
```
319

320
**Slack Reporter Example:**
321

322
```javascript
323
// slack-reporter.js
324
const https = require('https');
325

326
module.exports = {
327
  reporter: function(results, data, opts) {
328
    const errors = results.filter(r => r.error);
329
    
330
    if (errors.length === 0) {
331
      return; // No errors to report
332
    }
333
    
334
    const message = {
335
      text: `JSHint found ${errors.length} issues`,
336
      attachments: errors.slice(0, 10).map(result => ({
337
        color: result.error.code.startsWith('E') ? 'danger' : 'warning',
338
        fields: [
339
          {
340
            title: 'File',
341
            value: result.file,
342
            short: true
343
          },
344
          {
345
            title: 'Line',
346
            value: result.error.line,
347
            short: true
348
          },
349
          {
350
            title: 'Message',
351
            value: result.error.reason,
352
            short: false
353
          }
354
        ]
355
      }))
356
    };
357
    
358
    // Send to Slack webhook (URL from environment)
359
    const webhookUrl = process.env.SLACK_WEBHOOK_URL;
360
    if (webhookUrl) {
361
      // Implementation for posting to Slack webhook
362
      console.log('Posting to Slack:', JSON.stringify(message, null, 2));
363
    } else {
364
      console.log('SLACK_WEBHOOK_URL not set');
365
    }
366
  }
367
};
368
```
369

370
### Reporter Options
371

372
Options passed to reporters for customization.
373

374
```javascript { .api }
375
interface ReporterOptions {
376
  /**
377
   * Show error codes in output
378
   */
379
  verbose: boolean;
380
  
381
  /**
382
   * Filename to use for stdin input
383
   */
384
  filename?: string;
385
  
386
  /**
387
   * Show additional JSHint data beyond errors
388
   */
389
  'show-non-errors': boolean;
390
  
391
  /**
392
   * Custom options specific to reporter implementation
393
   */
394
  [key: string]: any;
395
}
396
```
397

398
### Integration Examples
399

400
**GitHub Actions:**
401
```yaml
402
- name: Run JSHint
403
  run: |
404
    jshint --reporter checkstyle src/ > jshint-report.xml
405
    
406
- name: Publish JSHint Results
407
  uses: dorny/test-reporter@v1
408
  if: always()
409
  with:
410
    name: JSHint Results
411
    path: jshint-report.xml
412
    reporter: java-junit
413
```
414

415
**Webpack Integration:**
416
```javascript
417
// webpack.config.js
418
const jshint = require('jshint').JSHINT;
419

420
class JSHintPlugin {
421
  apply(compiler) {
422
    compiler.hooks.emit.tap('JSHintPlugin', (compilation) => {
423
      // Custom reporter for webpack builds
424
      const reporter = {
425
        reporter: function(results) {
426
          results.forEach(result => {
427
            if (result.error) {
428
              const message = `${result.file}:${result.error.line}:${result.error.character} ${result.error.reason}`;
429
              compilation.warnings.push(new Error(message));
430
            }
431
          });
432
        }
433
      };
434
      
435
      // Use reporter with JSHint
436
    });
437
  }
438
}
439
```
440

441
**Gulp Integration:**
442
```javascript
443
const gulp = require('gulp');
444
const jshint = require('gulp-jshint');
445

446
gulp.task('lint', function() {
447
  return gulp.src('src/**/*.js')
448
    .pipe(jshint())
449
    .pipe(jshint.reporter('unix'))
450
    .pipe(jshint.reporter('fail')); // Fail build on errors
451
});
452
```