0
# Output Formatters
1

2
NSP provides multiple built-in formatters for displaying vulnerability results in different formats, plus support for custom third-party formatters.
3

4
## Capabilities
5

6
### Built-in Formatters
7

8
All built-in formatters follow the same function signature.
9

10
```javascript { .api }
11
/**
12
 * Format vulnerability scan results for output
13
 * @param {Error|null} err - Error object if scan failed
14
 * @param {VulnerabilityResult[]} data - Array of vulnerability results
15
 * @param {string} pkgPath - Path to the package.json file being scanned
16
 * @returns {string} Formatted output string
17
 */
18
interface FormatterFunction {
19
  (err: Error | null, data: VulnerabilityResult[], pkgPath: string): string;
20
}
21
```
22

23
### Default Formatter
24

25
Provides colorized table output with detailed vulnerability information including CVSS scores.
26

27
```javascript { .api }
28
/**
29
 * Default colorized table formatter with full vulnerability details
30
 * @param {Error|null} err - Error object or null
31
 * @param {VulnerabilityResult[]} data - Vulnerability results
32
 * @param {string} pkgPath - Package path
33
 * @returns {string} Colorized table output
34
 */
35
function default(err, data, pkgPath);
36
```
37

38
**Output Features:**
39
- Color-coded output using chalk (red for vulnerabilities, green for success)
40
- Tabular format with columns for Name, CVSS, Installed, Vulnerable, Patched, Path, More Info
41
- Automatic terminal width detection for responsive layout
42
- Sorts vulnerabilities by CVSS score (highest first)
43
- Shows total vulnerability count
44

45
**Usage Example:**
46

47
```javascript
48
const { formatters } = require('nsp');
49

50
nsp.check(function(err, results) {
51
  const output = formatters.default(err, results, './package.json');
52
  console.log(output);
53
  // Output: Colorized table with vulnerability details
54
});
55
```
56

57
### Summary Formatter
58

59
Simplified table format showing only essential information.
60

61
```javascript { .api }
62
/**
63
 * Summary table formatter with essential vulnerability information
64
 * @param {Error|null} err - Error object or null  
65
 * @param {VulnerabilityResult[]} data - Vulnerability results
66
 * @param {string} pkgPath - Package path
67
 * @returns {string} Summary table output
68
 */
69
function summary(err, data, pkgPath);
70
```
71

72
**Output Features:**
73
- Simplified table with columns: Name, Installed, Patched, Path, More Info
74
- No CVSS scores or detailed descriptions
75
- Clean table formatting without borders
76
- Color-coded vulnerability count
77

78
**Usage Example:**
79

80
```javascript
81
const { formatters } = require('nsp');
82

83
nsp.check(function(err, results) {
84
  const output = formatters.summary(err, results, './package.json');
85
  console.log(output);
86
  // Output: Clean summary table
87
});
88
```
89

90
### JSON Formatter
91

92
Raw JSON output of vulnerability data for programmatic consumption.
93

94
```javascript { .api }
95
/**
96
 * JSON formatter for programmatic consumption
97
 * @param {Error|null} err - Error object or null
98
 * @param {VulnerabilityResult[]} data - Vulnerability results  
99
 * @param {string} pkgPath - Package path
100
 * @returns {string} JSON string output
101
 */
102
function json(err, data, pkgPath);
103
```
104

105
**Output Features:**
106
- Pretty-printed JSON with 2-space indentation
107
- Complete vulnerability data structure
108
- Error information included if scan failed
109
- Machine-readable format for CI/CD integration
110

111
**Usage Example:**
112

113
```javascript
114
const { formatters } = require('nsp');
115

116
nsp.check(function(err, results) {
117
  const output = formatters.json(err, results, './package.json');
118
  
119
  // Save to file
120
  fs.writeFileSync('security-report.json', output);
121
  
122
  // Parse for programmatic use
123
  const data = JSON.parse(output);
124
  console.log(`Found ${data.length} vulnerabilities`);
125
});
126
```
127

128
### Code Climate Formatter
129

130
Code Climate compatible JSON format for integration with Code Climate platform.
131

132
```javascript { .api }
133
/**
134
 * Code Climate compatible formatter
135
 * @param {Error|null} err - Error object or null
136
 * @param {VulnerabilityResult[]} data - Vulnerability results
137
 * @param {string} pkgPath - Package path  
138
 * @returns {string} Code Climate JSON format
139
 */
140
function codeclimate(err, data, pkgPath);
141
```
142

143
**Output Features:**
144
- Code Climate JSON format with required fields
145
- Maps vulnerability data to Code Climate issue format
146
- Includes severity levels based on CVSS scores
147
- Compatible with Code Climate analysis platform
148

149
**Usage Example:**
150

151
```javascript
152
const { formatters } = require('nsp');
153

154
nsp.check(function(err, results) {
155
  const output = formatters.codeclimate(err, results, './package.json');
156
  
157
  // Output for Code Climate
158
  process.stdout.write(output);
159
});
160
```
161

162
### None Formatter
163

164
Suppresses all output - useful when you only need the exit code.
165

166
```javascript { .api }
167
/**
168
 * No output formatter - suppresses all output
169
 * @param {Error|null} err - Error object or null
170
 * @param {VulnerabilityResult[]} data - Vulnerability results
171
 * @param {string} pkgPath - Package path
172
 * @returns {string} Empty string
173
 */
174
function none(err, data, pkgPath);
175
```
176

177
**Usage Example:**
178

179
```bash
180
# CLI usage - only exit code matters
181
nsp check --output none
182
echo $? # Check exit code: 0 = no vulnerabilities, 1 = vulnerabilities found
183
```
184

185
### Quiet Formatter
186

187
Minimal output formatter for CI/CD environments.
188

189
```javascript { .api }
190
/**
191
 * Quiet formatter with minimal output
192
 * @param {Error|null} err - Error object or null
193
 * @param {VulnerabilityResult[]} data - Vulnerability results  
194
 * @param {string} pkgPath - Package path
195
 * @returns {string} Minimal output string
196
 */
197
function quiet(err, data, pkgPath);
198
```
199

200
**Usage Example:**
201

202
```javascript
203
const { formatters } = require('nsp');
204

205
nsp.check(function(err, results) {
206
  const output = formatters.quiet(err, results, './package.json');
207
  
208
  // Minimal output for logs
209
  if (output) {
210
    console.log(output);
211
  }
212
});
213
```
214

215
### Custom Formatters
216

217
NSP supports third-party formatters following the naming convention `nsp-formatter-<name>`.
218

219
```javascript { .api }
220
// Custom formatter installation and usage
221
// 1. Install custom formatter: npm install nsp-formatter-<name>
222
// 2. Use with CLI: nsp check --output <name>
223
// 3. Use with library: nsp.getFormatter('<name>')
224
```
225

226
**Custom Formatter Examples:**
227

228
```bash
229
# Install custom XML formatter
230
npm install -g nsp-formatter-xml
231

232
# Use with CLI
233
nsp check --output xml
234

235
# Use with library
236
const xmlFormatter = nsp.getFormatter('xml');
237
const output = xmlFormatter(err, results, pkgPath);
238
```
239

240
**Creating Custom Formatters:**
241

242
Custom formatters should export a function matching the FormatterFunction interface:
243

244
```javascript
245
// Example: nsp-formatter-csv
246
module.exports = function(err, data, pkgPath) {
247
  if (err) {
248
    return 'Error,' + err.message;
249
  }
250
  
251
  if (data.length === 0) {
252
    return 'No vulnerabilities found';
253
  }
254
  
255
  let csv = 'Module,Version,Title,CVSS,Advisory\n';
256
  data.forEach(vuln => {
257
    csv += `${vuln.module},${vuln.version},"${vuln.title}",${vuln.cvss_score || 'N/A'},${vuln.advisory}\n`;
258
  });
259
  
260
  return csv;
261
};
262
```
263

264
### Formatter Selection Priority
265

266
When resolving formatter names, NSP follows this priority order:
267

268
1. **Built-in formatters** - default, summary, json, codeclimate, none, quiet
269
2. **Custom formatters** - nsp-formatter-<name> packages
270
3. **Fallback** - default formatter if no match found
271

272
**Usage Example:**
273

274
```javascript
275
const nsp = require('nsp');
276

277
// This will use built-in json formatter even if nsp-formatter-json exists
278
const formatter = nsp.getFormatter('json');
279

280
// This will use custom formatter if nsp-formatter-xml is installed
281
const customFormatter = nsp.getFormatter('xml');
282
```