Snazzy

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.

Package Information

• Package Name: snazzy
• Package Type: npm
• Language: JavaScript (Node.js)
• Installation: npm install -g snazzy (for CLI usage) or npm install snazzy (for programmatic usage)

Core Imports

const CompactToStylishStream = require("snazzy");

For TypeScript usage:

import * as CompactToStylishStream from "snazzy";
// OR
import CompactToStylishStream = require("snazzy");

Basic Usage

CLI Usage

Transform JavaScript Standard Style output to stylish format:

# Basic pipe usage
standard | snazzy

# Explicit stdin usage
snazzy --stdin

# Using file input
cat linter-output.txt | snazzy

Programmatic Usage

const CompactToStylishStream = require("snazzy");

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

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

// Check exit code after processing
process.on('exit', (code) => {
  if (code === 0 && snazzy.exitCode !== 0) {
    process.exitCode = snazzy.exitCode;
  }
});

Architecture

Snazzy is built around several key components:

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

Capabilities

Stream Transformation

Core functionality for transforming compact linter output to stylish format.

/**
 * Transform stream that converts compact linter output to stylish format
 * Extends Node.js readable-stream.Transform with buffering and formatting capabilities
 * @param {Object} opts - Options object passed to Transform constructor (optional)
 *   Accepts all standard Node.js Transform stream options including:
 *   - objectMode: boolean - Whether to operate in object mode
 *   - highWaterMark: number - Buffer size for the stream
 *   - encoding: string - Default encoding for string data
 */
class CompactToStylishStream extends stream.Transform {
  constructor(opts);
  
  /** Exit code based on presence of errors (0 = no errors, 1 = errors found) */
  exitCode: number;
}

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

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

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

Usage Example:

const CompactToStylishStream = require("snazzy");
const fs = require("fs");

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

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

Command Line Interface

CLI functionality for processing linter output from the command line.

# Command line usage patterns
snazzy [options]

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

# Input methods:
standard | snazzy           # Pipe from standard or other linters
snazzy < output.txt         # Redirect file input
echo "output" | snazzy      # Pipe from command
snazzy --stdin              # Explicit stdin flag

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.

Error Handling:

• Returns exit code 0 when no linting errors are found
• Returns exit code 1 when linting errors are present
• Displays usage instructions when run without proper input

Output Formatting

The formatted output includes:

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

Input Format: Compact text format from JavaScript Standard Style linter Output Format: Stylish formatted output with:

• Colored and underlined file paths
• Formatted table with line:column positions
• Color-coded error messages (red for errors)
• Dimmed rule IDs and line numbers
• Bold red summary with total problem count

Types

/**
 * Main transform stream class for converting linter output
 * Extends Node.js readable-stream.Transform with buffering and formatting capabilities
 */
class CompactToStylishStream extends stream.Transform {
  /**
   * @param {Object} opts - Options object passed to Transform constructor (optional)
   *   Accepts all standard Node.js Transform stream options including:
   *   - objectMode: boolean - Whether to operate in object mode
   *   - highWaterMark: number - Buffer size for the stream
   *   - encoding: string - Default encoding for string data
   */
  constructor(opts);
  
  /**
   * Exit code indicating presence of linting errors
   * Set after processing completes in _flush() method
   * @type {number} 0 for success, 1 for errors found
   */
  exitCode: number;
}

Dependencies

Snazzy relies on these external packages:

• chalk: For terminal color formatting
• standard-json: For parsing compact linter output
• readable-stream: For stream functionality
• strip-ansi: For calculating string length without ANSI codes
• text-table: For creating formatted tables
• minimist: For command-line argument parsing
• inherits: For class inheritance utilities

Error Handling

Snazzy handles various scenarios gracefully:

• Invalid input: Processes malformed linter output without crashing
• No input: CLI displays helpful usage instructions
• Empty input: Returns empty output with exit code 0
• Stream errors: Properly propagates stream errors
• Large input: Efficiently processes large amounts of linter output through streaming

Integration Patterns

Build Scripts

{
  "scripts": {
    "lint": "standard --verbose | snazzy",
    "lint-fix": "standard --fix --verbose | snazzy"
  }
}

CI/CD Pipeline

#!/bin/bash
# CI linting with pretty output
npm run lint || {
  echo "Linting failed. See errors above."
  exit 1
}

Custom Formatting Pipeline

const CompactToStylishStream = require("snazzy");
const { spawn } = require("child_process");

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

linter.stdout.pipe(formatter).pipe(process.stdout);
linter.on('close', (code) => {
  process.exitCode = code || formatter.exitCode;
});