Core Linting Engine

Relevant source files

• lint/file.go
• lint/linter.go
• lint/linter_test.go
• lint/package.go
• test/file_filter_test.go
• test/golint_test.go
• test/utils_test.go

Purpose and Scope

This document explains the core linting engine that powers revive's code analysis. The engine consists of three primary types—Linter, Package, and File—that work together to parse Go source code, perform type checking, and apply linting rules. This page focuses on the internal mechanics of AST processing and rule application. For information about configuring rules and writing custom rules, see Rule System. For the programmatic library interface that wraps this engine, see Library Interface (revivelib).

---

Architecture Overview

The core linting engine implements a three-tier hierarchy that processes Go code from high-level package groups down to individual files:

Sources: lint/linter.go22-26 lint/package.go18-31 lint/file.go16-22

Each tier has distinct responsibilities:

Tier	Type	Responsibilities
Top	Linter	File I/O, concurrency control, Go version detection, package-level parallelism
Middle	Package	Type checking, type information management, file-level parallelism
Bottom	File	AST parsing, directive processing, rule application, failure filtering

---

The Linter Type

Structure and Initialization

The Linter type serves as the entry point for all linting operations:

Sources: lint/linter.go19-38

The Linter is created using lint.New():

• reader: An abstraction for reading files, typically os.ReadFile but can be customized for testing
• maxOpenFiles: Controls concurrent file reading; if > 0, limits simultaneous open files using a buffered channel as a semaphore

Sources: lint/linter.go28-38

File Reading Abstraction

The ReadFile type provides an abstraction layer that enables:

• Testing with in-memory file contents
• Rate limiting of file system operations
• Custom file loading logic

The semaphore implementation uses a channel-based token system at lint/linter.go40-52 When maxOpenFiles > 0, the linter creates a buffered channel where each read operation must acquire a token before proceeding, preventing excessive file descriptor usage.

Sources: lint/linter.go19-20 lint/linter.go40-52

Go Version Detection

Before linting each package, the Linter detects the Go version by searching for go.mod files:

Sources: lint/linter.go61-100 lint/linter.go159-181 lint/linter.go183-202

The version detection logic:

1. Checks if config.GoVersion is explicitly set
2. If not, walks up the directory tree from the first file in each package
3. Parses the go.mod file using golang.org/x/mod/modfile
4. Caches results by module root directory to avoid redundant parsing
5. Falls back to Go 1.0 if no go.mod is found

The cached versions are stored in perModVersions (by module directory) and perPkgVersions (by package index) at lint/linter.go64-99

Sources: lint/linter.go64-99 lint/linter.go159-181

Generated File Detection

The Linter can skip generated files based on the standard Go convention:

The detection logic at lint/linter.go207-216 checks for:

• Line prefix: // Code generated (note the trailing space)
• Line suffix: DO NOT EDIT.
• Both must appear on the same line

This behavior is controlled by config.IgnoreGeneratedHeader. When false (default), generated files are skipped.

Sources: lint/linter.go54-58 lint/linter.go140-142 lint/linter.go207-216

Package-Level Parallelism

The Lint() method processes packages concurrently using golang.org/x/sync/errgroup:

Sources: lint/linter.go61-123 lint/linter.go102-122

The parallelism strategy:

1. Creates a failure channel that all packages write to
2. Launches one goroutine per package using errgroup
3. Returns the failure channel immediately (non-blocking)
4. A background goroutine waits for all packages to complete
5. Closes the failure channel when done

This streaming approach enables processing large codebases without loading all results into memory.

Sources: lint/linter.go102-122

---

The Package Type

Structure and Type Information

The Package type represents a single Go package and manages type checking:

Sources: lint/package.go18-31

The Package fields serve specific purposes:

Field	Type	Purpose
fset	*token.FileSet	Maps token positions to file locations
files	map[string]*File	All parsed files in the package
goVersion	*goversion.Version	Go version from go.mod or config
typesPkg	*types.Package	Type-checked package information
typesInfo	*types.Info	Mapping from expressions to types
sortable	map[string]bool	Types implementing sort.Interface
main	int	Cached result: is this package main?

All fields except fset are protected by the mu read-write mutex for thread-safe access.

Sources: lint/package.go18-31

Type Checking Process

Type checking is performed lazily on first access via TypeCheck():

Sources: lint/package.go103-157

Key aspects of the type checking implementation:

1. Idempotency: Checks if typesInfo or typesPkg are non-nil to avoid redundant work at lint/package.go107-110

2. Error Handling: Uses a no-op error handler at lint/package.go114 to make the type checker do as much work as possible, even with errors

3. Info Structure: Populates four maps at lint/package.go117-122:

   • Types: Expression → type and value
   • Defs: Identifier → definition object
   • Uses: Identifier → use object
   • Scopes: Node → scope

4. Panic Recovery: Wraps types.Config.Check() in a panic handler at lint/package.go145-157 to handle rare panics (issue #59)

5. Partial Results: Stores results even on failure to provide partial information for rules

Sources: lint/package.go103-157

Sortable Type Detection

The Package scans for types implementing sort.Interface to support the range rule:

Sources: lint/package.go180-204 lint/package.go226-237

The detection process at lint/package.go180-204:

1. Iterates through all function declarations in all files
2. Identifies methods (functions with receivers)
3. Checks if the method signature matches sort.Interface:
   • Len() int
   • Less(i, j int) bool
   • Swap(i, j int)
4. Tracks which methods each receiver type implements using bitwise flags at lint/package.go171-178
5. Marks types that implement all three methods as sortable

The helper function getSortableMethodFlagForFunction() at lint/package.go226-237 uses astutils.FuncSignatureIs() to match method signatures.

Sources: lint/package.go180-204 lint/package.go171-178 lint/package.go226-237

Version Checking

The Package provides IsAtLeastGoVersion() for rules that need version-specific behavior:

This enables rules to adapt their behavior based on the Go version. Pre-defined version constants are available at lint/package.go37-46:

• Go115: Go 1.15
• Go121: Go 1.21
• Go122: Go 1.22
• Go124: Go 1.24
• Go125: Go 1.25

Sources: lint/package.go218-224 lint/package.go37-46

File-Level Parallelism

The Package.lint() method processes files concurrently:

Unlike package-level parallelism, this waits for all files to complete before returning.

Sources: lint/package.go206-216

---

The File Type

Structure and AST Representation

The File type represents a single Go source file:

Sources: lint/file.go16-22

Key methods for rule authors:

Method	Purpose
IsTest()	Returns true for *_test.go files
IsImportable()	Returns false for test files and main package
ToPosition()	Converts token.Pos to human-readable position
Render()	Converts AST node to source code string
CommentMap()	Builds map of comments associated with nodes

Sources: lint/file.go24-80

File Creation and Parsing

Files are created via NewFile() during package linting:

Sources: lint/linter.go125-157 lint/file.go49-61

The parser is invoked with parser.ParseComments at lint/file.go51 to preserve comments, which are essential for:

• In-code directive processing (e.g., //revive:disable)
• Comment-based rules (e.g., exported)

If parsing fails, an "invalid file" failure is generated with position information extracted from the error message at lint/linter.go218-258

Sources: lint/file.go49-61 lint/linter.go218-258

In-Code Directive Processing

Files process inline directives to enable/disable rules selectively:

Sources: lint/file.go117-148 lint/file.go166-274

Directive Syntax

The directive regex at lint/file.go164 matches:

//revive:(enable|disable)(?:-(line|next-line))?(?::([^\s]+))?\s*(?: (.+))?

Breaking this down:

Component	Regex	Meaning
Prefix	//[\s]*revive:	Comment with optional whitespace
Action	(enable|disable)	Enable or disable rules
Modifier	(?:-(line|next-line))?	Optional scope modifier
Rules	(?::([^\s]+))?	Optional comma-separated rule names
Reason	(?: (.+))?	Optional reason (for disable)

Examples:

Sources: lint/file.go157-164

Interval Construction

Directives are converted to DisabledInterval structs:

The interval logic at lint/file.go169-196:

1. Maintains a map of rule name → array of enable/disable configs
2. Each config records whether it's an enable (true) or disable (false) and the line number
3. Converts the array to intervals by pairing consecutive disable/enable entries
4. If no matching enable is found, the interval extends to math.MaxInt32

For -line and -next-line modifiers at lint/file.go217-227:

• -line: Immediately records both disable and enable on the same line
• -next-line: Records disable on line+1, then enable on line+1

Sources: lint/file.go150-155 lint/file.go166-274

Failure Filtering

After rules are applied, failures are filtered at lint/file.go276-302:

Sources: lint/file.go276-302

The overlap check considers a failure excluded if either:

• Its start line is within an interval
• Its end line is within an interval

Sources: lint/file.go291-292

Rule Application

The File.lint() method orchestrates rule application:

Sources: lint/file.go117-148

Key steps:

1. Extract disabled intervals from directives at lint/file.go120
2. For each rule:
   • Check if the file is excluded via RuleConfig.Exclude at lint/file.go123-125
   • Apply the rule to get failures at lint/file.go126
   • Enrich failures with rule name and position at lint/file.go128-139
   • Filter by disabled intervals at lint/file.go140
   • Filter by confidence threshold at lint/file.go142-144
   • Send passing failures to the channel at lint/file.go143

Sources: lint/file.go117-148

---

Complete Execution Flow

The following diagram shows the end-to-end linting process:

Sources: lint/linter.go61-123 lint/package.go206-216 lint/file.go117-148

---

Concurrency Model

The engine uses a two-level parallelism strategy:

Level 1: Package Parallelism

Characteristics:

• Each package runs in its own goroutine
• Non-blocking: returns channel immediately
• Background goroutine waits for completion
• Failures streamed as they're found

Sources: lint/linter.go102-122

Level 2: File Parallelism

Characteristics:

• Each file within a package runs in parallel
• Blocking: waits for all files before returning
• All write to the same failure channel
• Rules applied sequentially within each file

Sources: lint/package.go206-216

File Read Throttling

When maxOpenFiles > 0, file reading is rate-limited:

Sources: lint/linter.go29-37 lint/linter.go40-52

---

Integration Points

The core linting engine integrates with other revive systems:

Configuration System

The engine consumes:

• config.GoVersion: Override detected Go version
• config.IgnoreGeneratedHeader: Skip generated file check
• config.Rules: Per-rule configuration
• config.Confidence: Minimum failure confidence threshold
• config.Directives: Directive enforcement (e.g., specify-disable-reason)

Sources: lint/linter.go61 lint/file.go117-148

Rule System

Rules interact with files through the Rule.Apply() interface:

The File type provides utility methods for rules:

• ToPosition(): Convert token positions
• Render(): Convert AST to source code
• CommentMap(): Access comments
• IsUntypedConst(): Type checking helper

Rules access package-level information through file.Pkg:

• TypesPkg(): Package type information
• TypesInfo(): Expression type mapping
• Sortable(): Types implementing sort.Interface
• IsAtLeastGoVersion(): Version checking

Sources: lint/file.go16-22 lint/file.go64-109 lint/package.go49-100

Formatter System

The engine outputs Failure structs through a channel. Formatters consume this channel to produce output. See Output Formatters for details.

Sources: lint/linter.go62

Testing Infrastructure

The test framework at test/utils_test.go demonstrates engine usage:

Tests parse inline MATCH comments to verify expected failures. See Testing Framework for details.

Sources: test/utils_test.go63-83 test/utils_test.go85-198

---

Sources: lint/linter.go lint/package.go lint/file.go test/utils_test.go