0
# Snazzy
1

2
Snazzy is a CLI tool and Node.js module that transforms compact text output from JavaScript linters (specifically JavaScript Standard Style) into stylish, human-readable format with colored output and formatted tables. It functions as a stream processor that accepts linter output via stdin and outputs beautifully formatted results with syntax highlighting, proper alignment, and clear error reporting.
3

4
## Package Information
5

6
- **Package Name**: snazzy
7
- **Package Type**: npm
8
- **Language**: JavaScript (Node.js)
9
- **Installation**: `npm install -g snazzy` (for CLI usage) or `npm install snazzy` (for programmatic usage)
10

11
## Core Imports
12

13
```javascript
14
const CompactToStylishStream = require("snazzy");
15
```
16

17
For TypeScript usage:
18

19
```typescript
20
import * as CompactToStylishStream from "snazzy";
21
// OR
22
import CompactToStylishStream = require("snazzy");
23
```
24

25
## Basic Usage
26

27
### CLI Usage
28

29
Transform JavaScript Standard Style output to stylish format:
30

31
```bash
32
# Basic pipe usage
33
standard | snazzy
34

35
# Explicit stdin usage
36
snazzy --stdin
37

38
# Using file input
39
cat linter-output.txt | snazzy
40
```
41

42
### Programmatic Usage
43

44
```javascript
45
const CompactToStylishStream = require("snazzy");
46

47
// Create a transform stream
48
const snazzy = new CompactToStylishStream();
49

50
// Pipe compact linter output through snazzy
51
process.stdin.pipe(snazzy).pipe(process.stdout);
52

53
// Check exit code after processing
54
process.on('exit', (code) => {
55
  if (code === 0 && snazzy.exitCode !== 0) {
56
    process.exitCode = snazzy.exitCode;
57
  }
58
});
59
```
60

61
## Architecture
62

63
Snazzy is built around several key components:
64

65
- **Transform Stream**: `CompactToStylishStream` class that extends Node.js `Transform` stream for processing linter output
66
- **CLI Interface**: Binary script in `bin/cmd.js` that handles command-line usage and argument parsing
67
- **Formatting Engine**: Internal functions that convert JSON linter results to stylish formatted output
68
- **Color System**: Uses chalk for terminal color formatting and strip-ansi for string length calculations
69

70
## Capabilities
71

72
### Stream Transformation
73

74
Core functionality for transforming compact linter output to stylish format.
75

76
```javascript { .api }
77
/**
78
 * Transform stream that converts compact linter output to stylish format
79
 * Extends Node.js readable-stream.Transform with buffering and formatting capabilities
80
 * @param {Object} opts - Options object passed to Transform constructor (optional)
81
 *   Accepts all standard Node.js Transform stream options including:
82
 *   - objectMode: boolean - Whether to operate in object mode
83
 *   - highWaterMark: number - Buffer size for the stream
84
 *   - encoding: string - Default encoding for string data
85
 */
86
class CompactToStylishStream extends stream.Transform {
87
  constructor(opts);
88
  
89
  /** Exit code based on presence of errors (0 = no errors, 1 = errors found) */
90
  exitCode: number;
91
}
92
```
93

94
The `CompactToStylishStream` class is the main export and extends Node.js `readable-stream.Transform`. It implements the standard Transform stream interface:
95

96
- **Input Processing**: Buffers incoming compact linter output in `_transform()`
97
- **Output Generation**: Processes buffered data and generates stylish output in `_flush()`  
98
- **Stream Interface**: Supports all standard Node.js stream operations (pipe, write, end, etc.)
99
- **Error Tracking**: Maintains `exitCode` property based on linting results
100

101
The class buffers all input, processes it through the standard-json parser, and outputs formatted results in a single flush operation.
102

103
**Usage Example:**
104

105
```javascript
106
const CompactToStylishStream = require("snazzy");
107
const fs = require("fs");
108

109
// Transform a file containing compact linter output
110
const snazzy = new CompactToStylishStream();
111
fs.createReadStream("compact-output.txt")
112
  .pipe(snazzy)
113
  .pipe(process.stdout);
114

115
// Check for errors after processing
116
snazzy.on('finish', () => {
117
  console.log(`Processing completed with exit code: ${snazzy.exitCode}`);
118
});
119
```
120

121
### Command Line Interface
122

123
CLI functionality for processing linter output from the command line.
124

125
```bash { .api }
126
# Command line usage patterns
127
snazzy [options]
128

129
# Options:
130
--stdin    # Explicitly read from stdin (optional, auto-detected)
131

132
# Input methods:
133
standard | snazzy           # Pipe from standard or other linters
134
snazzy < output.txt         # Redirect file input
135
echo "output" | snazzy      # Pipe from command
136
snazzy --stdin              # Explicit stdin flag
137
```
138

139
The CLI automatically detects whether input is coming from stdin (pipe/redirect) or if it's being run interactively. When run without piped input, it displays a helpful error message directing users to install and use the `standard` linter.
140

141
**Error Handling:**
142

143
- Returns exit code 0 when no linting errors are found
144
- Returns exit code 1 when linting errors are present
145
- Displays usage instructions when run without proper input
146

147
### Output Formatting
148

149
The formatted output includes:
150

151
- **File Headers**: Underlined file paths where errors occur
152
- **Error Tables**: Aligned columns showing line numbers, column numbers, error types, and messages
153
- **Syntax Highlighting**: Color-coded error messages and metadata
154
- **Summary**: Total error count with pluralized messaging
155

156
**Input Format**: Compact text format from JavaScript Standard Style linter
157
**Output Format**: Stylish formatted output with:
158
- Colored and underlined file paths
159
- Formatted table with line:column positions
160
- Color-coded error messages (red for errors)
161
- Dimmed rule IDs and line numbers
162
- Bold red summary with total problem count
163

164
## Types
165

166
```javascript { .api }
167
/**
168
 * Main transform stream class for converting linter output
169
 * Extends Node.js readable-stream.Transform with buffering and formatting capabilities
170
 */
171
class CompactToStylishStream extends stream.Transform {
172
  /**
173
   * @param {Object} opts - Options object passed to Transform constructor (optional)
174
   *   Accepts all standard Node.js Transform stream options including:
175
   *   - objectMode: boolean - Whether to operate in object mode
176
   *   - highWaterMark: number - Buffer size for the stream
177
   *   - encoding: string - Default encoding for string data
178
   */
179
  constructor(opts);
180
  
181
  /**
182
   * Exit code indicating presence of linting errors
183
   * Set after processing completes in _flush() method
184
   * @type {number} 0 for success, 1 for errors found
185
   */
186
  exitCode: number;
187
}
188
```
189

190
## Dependencies
191

192
Snazzy relies on these external packages:
193

194
- **chalk**: For terminal color formatting
195
- **standard-json**: For parsing compact linter output
196
- **readable-stream**: For stream functionality
197
- **strip-ansi**: For calculating string length without ANSI codes
198
- **text-table**: For creating formatted tables
199
- **minimist**: For command-line argument parsing
200
- **inherits**: For class inheritance utilities
201

202
## Error Handling
203

204
Snazzy handles various scenarios gracefully:
205

206
- **Invalid input**: Processes malformed linter output without crashing
207
- **No input**: CLI displays helpful usage instructions
208
- **Empty input**: Returns empty output with exit code 0
209
- **Stream errors**: Properly propagates stream errors
210
- **Large input**: Efficiently processes large amounts of linter output through streaming
211

212
## Integration Patterns
213

214
### Build Scripts
215

216
```json
217
{
218
  "scripts": {
219
    "lint": "standard --verbose | snazzy",
220
    "lint-fix": "standard --fix --verbose | snazzy"
221
  }
222
}
223
```
224

225
### CI/CD Pipeline
226

227
```bash
228
#!/bin/bash
229
# CI linting with pretty output
230
npm run lint || {
231
  echo "Linting failed. See errors above."
232
  exit 1
233
}
234
```
235

236
### Custom Formatting Pipeline
237

238
```javascript
239
const CompactToStylishStream = require("snazzy");
240
const { spawn } = require("child_process");
241

242
// Custom linter integration
243
const linter = spawn("your-linter", ["--format=compact"]);
244
const formatter = new CompactToStylishStream();
245

246
linter.stdout.pipe(formatter).pipe(process.stdout);
247
linter.on('close', (code) => {
248
  process.exitCode = code || formatter.exitCode;
249
});
250
```