Go Version Detection

Relevant source files

• lint/file.go
• lint/linter.go
• lint/linter_test.go
• lint/package.go
• rule/struct_tag.go
• test/file_filter_test.go
• test/golint_test.go
• test/struct_tag_test.go
• test/utils_test.go
• testdata/go1.24/go.mod
• testdata/go1.24/struct_tag.go
• testdata/struct_tag.go
• testdata/struct_tag_user_options.go
• testdata/struct_tag_user_options_omit.go

Revive automatically detects the Go version for each package being analyzed and uses this information to enable or disable version-specific rule behaviors. This system allows rules to adapt their validation logic based on language features available in different Go versions.

For information about the core linting engine architecture, see Core Linting Engine. For details on how rules use version information, see Rule Architecture and Interfaces.

---

Purpose and Scope

The Go version detection system determines which Go language version each package targets by parsing go.mod files. This version information is then made available to rules so they can:

• Enable checks for features introduced in newer Go versions
• Suppress warnings for deprecated patterns that are valid in older versions
• Provide version-appropriate suggestions and error messages

The system operates transparently during linting, requiring no user configuration unless a specific version override is desired.

---

Version Detection Flow

Sources: lint/linter.go61-123 lint/linter.go159-202

---

Key Components

Linter Version Management

The Linter struct orchestrates version detection during the Lint method execution:

Component	Type	Purpose
perModVersions	map[string]*goversion.Version	Cache mapping module root directories to Go versions
perPkgVersions	[]*goversion.Version	Array storing detected version for each package
defaultGoVersion	*goversion.Version	Fallback version (1.0) when no go.mod is found

The system maintains two levels of caching:

1. Module-level cache: Prevents re-parsing the same go.mod file for multiple packages in the same module
2. Package-level array: Provides O(1) lookup during concurrent package processing

Sources: lint/linter.go54-99

---

Version Detection Algorithm

Step 1: Check Configuration Override

If Config.GoVersion is set, the detection process is bypassed entirely, and this version is used for all packages.

Sources: lint/linter.go70-73

Step 2: Check Module Cache

For each package, the system checks if any previously detected module contains the package:

This optimization avoids repeated filesystem operations when linting multiple packages from the same module.

Sources: lint/linter.go80-90

Step 3: Search and Parse go.mod

The detectGoMod function implements the core detection logic:

The retrieveModFile function walks up the directory tree until it finds a go.mod file or reaches the filesystem root. The search stops at either:

• A directory containing go.mod
• The volume root on Windows (e.g., C:\)
• The root directory on Unix (i.e., /)

Sources: lint/linter.go159-202

Step 4: Cache and Store

After detecting the version, the system:

1. Caches the version in perModVersions with the module directory as key
2. Stores the version in perPkgVersions[n] for the current package
3. Creates the Package struct with the version assigned to Package.goVersion

Sources: lint/linter.go92-99 lint/linter.go125-134

---

Package Integration

Package Structure

The Package struct stores the detected Go version:

The goVersion field is populated during package creation in lintPackage and remains immutable thereafter.

Sources: lint/package.go18-31 lint/linter.go125-134

Version Query API

Rules query the Go version using the IsAtLeastGoVersion method:

Method	Parameters	Returns	Thread-Safe
IsAtLeastGoVersion	v *goversion.Version	bool	Yes (uses RLock)

The method performs a simple comparison: package.goVersion >= v

Sources: lint/package.go218-224

---

Predefined Version Constants

Revive defines constants for commonly checked Go versions:

Constant	Version	Primary Use Case
Go115	1.15	Historical compatibility checks
Go121	1.21	Checking for Go 1.21+ features
Go122	1.22	Range-over-function and other 1.22 features
Go124	1.24	JSON omitzero tag support
Go125	1.25	Future feature checks

These constants are created using goversion.Must(goversion.NewVersion()) to ensure they are always valid and panic at initialization if malformed.

Sources: lint/package.go33-47

---

Rule Integration Example

struct-tag Rule Version Checking

The struct-tag rule demonstrates how rules use version information to validate version-specific struct tag options:

Implementation Flow:

1. Version Query (line 145): The rule queries whether the package uses Go 1.24 or higher
2. Context Creation (lines 174-178): A checkContext is created with the isAtLeastGo124 flag set
3. Tag Validation (lines 479-483): When validating JSON tags, the checkJSONTag function checks this flag before accepting the omitzero option

The JSON omitzero option was introduced in Go 1.24, so the rule rejects it for earlier versions with an appropriate error message.

Sources: rule/struct_tag.go66-72 rule/struct_tag.go145 rule/struct_tag.go479-483

---

Testing Version-Specific Behavior

Test Structure

Revive uses a dedicated test directory structure for version-specific tests:

testdata/
├── struct_tag.go                    # Default version tests
└── go1.24/
    ├── go.mod                       # Contains "go 1.24"
    └── struct_tag.go               # Go 1.24-specific tests

The go1.24/go.mod file explicitly declares the Go version:

module github.com/mgechev/revive/testdata
go 1.24

This allows the version detection system to correctly identify the target version during tests.

Sources: testdata/go1.24/go.mod1-3 test/struct_tag_test.go46-48

Test Validation Pattern

The test verifies that:

• Line 26 in testdata/struct_tag.go fails (Go version < 1.24)
• Line 26 in testdata/go1.24/struct_tag.go passes (Go version = 1.24)

This validates that the version detection and rule behavior work correctly together.

Sources: test/struct_tag_test.go46-48 testdata/struct_tag.go28 testdata/go1.24/struct_tag.go26

---

Error Handling

Detection Failure Scenarios

Scenario	Behavior	Fallback
No go.mod found	Silent fallback	Uses defaultGoVersion (1.0)
go.mod without Go directive	Error logged	Uses defaultGoVersion (1.0)
Malformed go.mod	Error logged	Uses defaultGoVersion (1.0)
Invalid version string	Error returned	Linting fails for that package

The system is designed to be permissive: if version detection fails, it assumes Go 1.0 rather than failing the entire linting process. This ensures revive can still analyze code even in unusual project structures.

Sources: lint/linter.go92-96 lint/linter.go159-181

Version Parsing

The system uses github.com/hashicorp/go-version for parsing and comparing versions:

This library provides semantic versioning support and handles various version formats correctly.

Sources: lint/linter.go14 lint/linter.go179

---

Configuration Override

Users can override automatic version detection by setting GoVersion in the configuration:

Configuration Field	Type	Scope	Precedence
Config.GoVersion	*goversion.Version	Global (all packages)	Highest
Detected from go.mod	*goversion.Version	Per-module	Medium
defaultGoVersion	*goversion.Version	Fallback	Lowest

When Config.GoVersion is set, the entire detection process is bypassed, and the specified version is used for all packages regardless of their actual go.mod files.

Sources: lint/linter.go70-73

---

Performance Optimizations

Module-Level Caching

This optimization is particularly effective for monorepos where many packages share the same go.mod file. The system performs directory prefix matching to identify which cached module contains each package.

Sources: lint/linter.go64-90

Concurrent Package Processing

The version detection system is designed for concurrent package linting:

1. Pre-Detection Phase: All versions are detected sequentially before rules are applied
2. Per-Package Array: perPkgVersions array provides thread-safe indexed access
3. Immutable Versions: Once assigned to a Package, the version never changes

This design eliminates the need for synchronization during the linting phase.

Sources: lint/linter.go102-122

---

Summary

The Go version detection system provides automatic, transparent version identification for each package being linted. Key characteristics:

• Automatic: Requires no user configuration in standard Go module projects
• Cached: Avoids repeated filesystem operations for packages in the same module
• Safe: Falls back to Go 1.0 if detection fails rather than failing the linting process
• Thread-Safe: Designed for concurrent package processing
• Extensible: Rules can query version information to implement version-specific checks

This system enables rules like struct-tag to validate code against the appropriate Go language version, ensuring that warnings are relevant to the actual Go version being used.

Sources: lint/linter.go61-123 lint/linter.go159-202 lint/package.go218-224 rule/struct_tag.go145