Creating Custom Formatters

Relevant source files

• .golangci.yml
• cli/main.go
• cli/main_test.go
• formatter/default.go
• formatter/formatter_test.go
• formatter/friendly.go
• formatter/plain.go
• formatter/sarif.go
• formatter/stylish.go
• formatter/unix.go
• revivelib/core.go
• revivelib/core_test.go
• rule/early_return.go
• rule/indent_error_flow.go
• rule/superfluous_else.go

This page explains how to implement custom output formatters for revive. Custom formatters allow you to control how linting failures are displayed, enabling integration with different tools, IDEs, or custom reporting systems. For information about using the built-in formatters, see Built-in Formatters.

Overview

Revive's formatter system is based on a simple interface that transforms a stream of linting failures into formatted output. Custom formatters can produce output in any format: plain text, structured data (JSON, XML), or specialized formats for tooling integration (SARIF, JUnit).

The Formatter Interface

All formatters must implement the lint.Formatter interface, which consists of two methods:

Method	Signature	Purpose
Name()	string	Returns the unique identifier for the formatter
Format()	(<-chan lint.Failure, lint.Config) (string, error)	Processes failures and returns formatted output

The Format method receives:

• A channel of failures (<-chan lint.Failure) - A read-only channel streaming linting violations
• A configuration (lint.Config) - Contains rule configurations, severity settings, and confidence thresholds

Sources: formatter/default.go10-33 formatter/friendly.go17-70 formatter/stylish.go12-97

Formatter Lifecycle

Diagram: Formatter Integration Flow

This diagram shows how formatters are instantiated and invoked within revive's execution pipeline. The formatter receives failures through a channel and processes them asynchronously.

Sources: cli/main.go40-92 revivelib/core.go117-170

Anatomy of a Formatter

Minimal Implementation

A minimal formatter implementation requires:

1. Struct definition with optional metadata field
2. Name method returning the formatter identifier
3. Format method consuming failures and producing output

Here's the structure observed in built-in formatters:

Diagram: Formatter Type Hierarchy

Sources: formatter/default.go10-33 formatter/friendly.go17-70 formatter/stylish.go12-97 formatter/sarif.go13-41

Step-by-Step Implementation Guide

1. Define the Formatter Struct

The Metadata field is optional but recommended for consistency with built-in formatters.

Sources: formatter/default.go10-14 formatter/friendly.go17-21

2. Implement the Name Method

The name should be:

• Lowercase with hyphens (following the naming convention)
• Unique among all formatters
• Descriptive of the output format

Sources: formatter/default.go16-19 formatter/friendly.go23-26 formatter/unix.go18-21

3. Implement the Format Method

The Format method is where the main formatting logic resides. It must:

• Consume all failures from the channel
• Process each failure according to your format specification
• Return the complete output as a string

Key patterns observed in built-in formatters:

Pattern A: Simple Iteration (Default, Unix, Plain)

Sources: formatter/default.go21-33 formatter/unix.go23-33 formatter/plain.go21-31

Pattern B: Collect Then Format (Friendly, Stylish)

Sources: formatter/stylish.go37-97 formatter/friendly.go28-70

Pattern C: Structured Output (SARIF, JSON)

Sources: formatter/sarif.go26-41

Understanding the Failure Object

Each lint.Failure received through the channel contains:

Field	Type	Description
Failure	string	The failure message text
RuleName	string	Name of the rule that generated the failure
Category	string	Category classification of the failure
Position	FailurePosition	Source location information
Confidence	float64	Confidence level of the failure (0.0-1.0)

The Position field contains:

• Start.Filename - File path
• Start.Line - Starting line number
• Start.Column - Starting column number
• End.Line - Ending line number
• End.Column - Ending column number

Sources: formatter/formatter_test.go14-883

Using Configuration Data

The lint.Config parameter provides access to:

Severity Mapping

Use the severity() helper pattern to determine failure severity:

This pattern appears in formatter/friendly.go38-42 and formatter/stylish.go45-48

Confidence Filtering

The configuration contains a confidence threshold. The revivelib.Revive.Format method filters failures by confidence before sending them to formatters:

Sources: revivelib/core.go142-145

Helper Utilities

URL Generation

Built-in formatters use a consistent URL pattern for rule documentation:

Sources: formatter/default.go35-37

Table Formatting

The friendly formatter demonstrates a reusable table formatting utility:

Sources: formatter/friendly.go144-159

Formatter Registration

Diagram: Formatter Registration and Lookup

Currently, formatters are registered within the config package through the GetFormatter function. To make a custom formatter available, it must be added to the formatter registry.

Integration Points

There are two approaches to using custom formatters:

Approach 1: Direct Library Usage

When using revive as a library, you can create formatter instances directly:

Sources: revivelib/core.go117-170

Approach 2: Extending the CLI

To integrate a custom formatter into the CLI tool, you would need to:

1. Modify the config.GetFormatter() function to recognize your formatter name
2. Add your formatter to the formatter registry
3. Rebuild the revive binary

This requires modifying the revive source code.

Sources: cli/main.go82-84 revivelib/core.go126-129

Complete Example Implementations

Example 1: CSV Formatter

A simple CSV formatter that outputs one line per failure:

This follows Pattern A (simple iteration) similar to formatter/default.go21-33 and formatter/unix.go23-33

Example 2: Grouped Formatter with Statistics

A formatter that groups failures by file and provides statistics:

This follows Pattern B (collect then format) similar to formatter/stylish.go37-97 and formatter/friendly.go28-70

Testing Custom Formatters

Unit Test Structure

Built-in formatters use a table-driven test approach:

Sources: formatter/formatter_test.go14-883

Key Testing Considerations

1. Channel closure: Always close the failures channel after sending test data
2. Multiple failures: Test with zero, one, and multiple failures
3. Different severities: Test with both errors and warnings
4. Output validation: Verify complete output string, not just presence of data
5. Error handling: Test error conditions and edge cases

Sources: formatter/formatter_test.go840-882

Best Practices

1. Handle Empty Results Gracefully

Some formatters return empty strings when there are no failures:

Sources: formatter/stylish.go87-94 formatter/formatter_test.go260-264

2. Use Efficient String Building

For formatters processing many failures:

• Use strings.Builder or bytes.Buffer for concatenation
• Pre-allocate capacity if the output size is predictable

Sources: formatter/default.go23-24 formatter/stylish.go65 formatter/friendly.go30

3. Respect Severity Configuration

Use the configuration to determine severity rather than hardcoding:

Sources: formatter/friendly.go38-42 formatter/stylish.go45-48

4. Don't Write to Standard Output

Formatters should return formatted strings, not write directly to stdout. The CLI handles output printing:

Sources: formatter/formatter_test.go840-877

5. Support Color Output

For terminal formatters, consider supporting color while respecting the NO_COLOR environment variable. Built-in formatters use the fatih/color package:

Sources: formatter/friendly.go35-36 formatter/stylish.go26-33

Advanced Patterns

Working with SARIF Format

The SARIF formatter demonstrates integration with external libraries for structured output:

Sources: formatter/sarif.go26-41

Aggregating Statistics

The friendly formatter shows how to collect statistics while processing:

Sources: formatter/friendly.go31-68 formatter/friendly.go120-142

Integration Workflow Summary

Diagram: Custom Formatter Development Workflow

The complete workflow from implementation to integration involves implementing the interface, processing the failure stream, and integrating with either the library API or CLI tool.

Sources: formatter/default.go10-33 formatter/friendly.go17-70 cli/main.go82-84 revivelib/core.go117-170

---

Summary: Custom formatters in revive provide flexibility in how linting results are presented. By implementing the lint.Formatter interface with its two methods (Name and Format), you can create formatters that produce output in any desired format. The key is properly consuming the failure channel, respecting the configuration, and returning well-formatted strings without side effects.