Library Interface (revivelib)

Relevant source files

• .github/instructions/go.instructions.md
• .golangci.yml
• DEVELOPING.md
• README.md
• RULES_DESCRIPTIONS.md
• cli/main.go
• cli/main_test.go
• config/config.go
• config/config_test.go
• formatter/formatter_test.go
• formatter/friendly.go
• formatter/sarif.go
• formatter/stylish.go
• logging/logger.go
• logging/logger_test.go
• revivelib/core.go
• revivelib/core_test.go

The revivelib package provides a programmatic API for embedding revive's linting functionality into other Go tools and applications. This enables developers to integrate revive's static analysis capabilities without invoking the command-line interface.

For information about the command-line interface, see Command Line Interface. For details about the internal linting engine, see Core Linting Engine. For guidance on creating custom rules that can be used with this library, see Creating Custom Rules.

---

Package Purpose and Scope

The revivelib package exposes revive's core linting functionality as a Go library. It provides three main capabilities:

1. Configuration and initialization - Creating a configured linting instance
2. Linting execution - Running rules against Go source files
3. Output formatting - Transforming failures into various output formats

The library serves as a bridge between external tools and revive's internal lint package, handling package resolution, concurrency, and failure processing.

Sources: revivelib/core.go1-17

---

Core Types and Structures

Revive Orchestrator

The Revive struct is the primary interface for programmatic linting:

Field	Type	Purpose
config	*lint.Config	Configuration including rules, severity, confidence
lintingRules	[]lint.Rule	Active rule instances to apply
logger	*slog.Logger	Structured logging for debug output
maxOpenFiles	int	Concurrency limit for file reading

Sources: revivelib/core.go19-26

---

Initialization Workflow

Constructor Function

The New() function creates and initializes a Revive instance:

Key parameters:

• conf *lint.Config - Configuration object (typically from config.GetConfig())
• setExitStatus bool - If true, overrides exit codes to 1 for any failures
• maxOpenFiles int - Limits concurrent file reads (0 = unlimited)
• extraRules ...ExtraRule - Custom rules to add beyond built-in rules

Sources: revivelib/core.go28-70

ExtraRule Type

Custom rules are added via the ExtraRule struct:

This allows adding rules not in revive's built-in rule set. The DefaultConfig is used if the rule is not explicitly configured in conf.Rules.

Sources: cli/main.go56-61 revivelib/core_test.go94-100

---

Linting Workflow

Pattern Specification

The LintPattern type specifies which files to lint:

Factory functions:

• revivelib.Include(pattern string) - Creates an include pattern
• revivelib.Exclude(pattern string) - Creates an exclude pattern

Patterns follow Go's package path conventions:

• ./... - All packages recursively from current directory
• path/to/package - Specific package
• vendor/... - Typically excluded by default

Sources: cli/main.go66-75

Lint Method

The Lint() method executes linting and returns a failure channel:

Method signature:

Process:

1. Separate include and exclude patterns
2. Apply default excludes if none specified (vendor/...)
3. Resolve patterns to package file lists via dots.ResolvePackages
4. Create lint.Linter with file reader and concurrency limit
5. Call linter.Lint() to get failure channel
6. Return channel for asynchronous consumption

Sources: revivelib/core.go73-114 revivelib/core.go171-183

---

Formatting Results

Format Method

The Format() method transforms failures into formatted output:

Method signature:

Exit code determination:

1. Starts at 0 (success)
2. Set to config.WarningCode on first failure (default: 0)
3. Set to config.ErrorCode if any failure has SeverityError (default: 0)
4. Can be forced to 1 via setExitStatus parameter in New()

Confidence filtering: Failures with Confidence < config.Confidence are silently dropped before formatting.

Available formatters:

• friendly, stylish, default, unix, plain
• json, ndjson
• checkstyle, sarif

For details on formatters, see Output Formatters.

Sources: revivelib/core.go116-169

---

Integration Patterns

CLI Integration

The revive CLI demonstrates basic library usage:

Sources: cli/main.go41-92

Test Integration Example

From the test suite, showing programmatic usage:

Sources: revivelib/core_test.go86-106

---

Complete Usage Example

Basic Workflow

Typical Integration Steps

1. Configuration Loading

   • Load from TOML file via config.GetConfig()
   • Or construct lint.Config programmatically
   • Configure rules, severity, confidence thresholds

2. Instance Creation

   • Call revivelib.New() with configuration
   • Optionally add custom rules via ExtraRule
   • Set exit status behavior and concurrency limits

3. Pattern Building

   • Use revivelib.Include() for files/packages to lint
   • Use revivelib.Exclude() for exclusions
   • Patterns support Go package syntax (./..., path/to/pkg)

4. Linting Execution

   • Call revive.Lint() with patterns
   • Receive channel for asynchronous failure processing
   • Channel closes when linting completes

5. Output Formatting

   • Call revive.Format() with formatter name and channel
   • Consumes failure channel and produces formatted string
   • Returns output, exit code, and any formatting errors

6. Result Handling

   • Display or log the formatted output
   • Use exit code for process termination or further logic

Sources: cli/main.go41-92 revivelib/core_test.go15-74

---

Concurrency and File Reading

File Reader Abstraction

The library creates a file reader function passed to lint.Linter:

This abstraction allows for:

• Custom file systems (e.g., in-memory for testing)
• Instrumentation and logging
• Alternative content sources

Concurrency Control

The maxOpenFiles parameter limits concurrent file reads:

• 0 (default): Unlimited concurrency
• > 0: Maximum simultaneous open files

This is implemented via a buffered channel acting as a semaphore in the lint.Linter.

Sources: revivelib/core.go99-106 lint/linter.go28-52

---

Error Handling

Error Types

The library returns errors at three stages:

Stage	Error Source	Example
Initialization	revivelib.New()	Logger initialization, invalid rules
Linting	revive.Lint()	Package resolution, file reading
Formatting	revive.Format()	Formatter lookup, template rendering

Failure Channel

The failure channel from Lint() is closed when complete. Internal errors are sent as special failure objects:

Check failure.IsInternal() to detect linting engine errors vs. rule violations.

Sources: revivelib/core.go73-114 revivelib/core.go116-169

---

Advanced Configuration

Rule Configuration Table

Rules are configured in conf.Rules map:

Field	Type	Purpose
Severity	lint.Severity	"warning" or "error"
Arguments	[]interface{}	Rule-specific parameters
Exclude	[]string	File patterns to skip for this rule
Disabled	bool	If true, rule is not executed

Confidence Threshold

The conf.Confidence field (0.0 to 1.0) filters failures:

• Only failures with Confidence >= conf.Confidence are reported
• Lower threshold = more warnings (including uncertain ones)
• Higher threshold = fewer, more confident warnings

Exit Code Mapping

Configuration	Exit Code Behavior
setExitStatus=true	Overrides ErrorCode=1, WarningCode=1
conf.ErrorCode	Returned when any error-severity failure
conf.WarningCode	Returned when only warning-severity failures
No failures	Returns 0

Sources: revivelib/core.go28-70 revivelib/core.go141-157

---

Type Reference

Key Types

Sources: revivelib/core.go19-211

---

Summary

The revivelib package provides a clean, programmatic interface for embedding revive into Go applications:

• New() - Initialize with configuration and custom rules
• Lint() - Execute linting on specified patterns, returns failure channel
• Format() - Transform failures into formatted output with exit code

This design enables:

• Integration into editors and IDEs
• Use in CI/CD pipelines as a library
• Embedding in meta-linters (e.g., golangci-lint)
• Custom tooling with extended rule sets

The asynchronous channel-based architecture allows for streaming results and efficient memory usage when processing large codebases.

Sources: revivelib/core.go1-212 cli/main.go41-92 revivelib/core_test.go1-107