gomoddirectives

README

gomoddirectives

A linter that handle directives into go.mod.

Usage

Inside golangci-lint

Recommended.

linters:
  enable:
    - gomoddirectives

linters-settings:
  gomoddirectives:
    # Allow local `replace` directives.
    # Default: false
    replace-local: true
    
    # List of allowed `replace` directives.
    # Default: []
    replace-allow-list:
      - launchpad.net/gocheck
    # Allow to not explain why the version has been retracted in the `retract` directives.
    # Default: false
    retract-allow-no-explanation: true
    
    # Forbid the use of the `exclude` directives.
    # Default: false
    exclude-forbidden: true

    # Forbid the use of the `toolchain` directive.
    # Default: false
    toolchain-forbidden: true

    # Defines a pattern to validate `toolchain` directive.
    # Default: '' (no match)
    toolchain-pattern: 'go1\.22\.\d+$'

    # Forbid the use of the `tool` directives.
    # Default: false
    tool-forbidden: true

    # Forbid the use of the `godebug` directive.
    # Default: false
    go-debug-forbidden: true

    # Defines a pattern to validate `go` minimum version directive.
    # Default: '' (no match)
    go-version-pattern: '1\.\d+(\.0)?$'

As a CLI

gomoddirectives [flags]

Flags:
  -exclude
        Forbid the use of exclude directives
  -godebug
        Forbid the use of godebug directives
  -goversion string
        Pattern to validate go min version directive
  -h    Show this help.
  -list value
        List of allowed replace directives
  -local
        Allow local replace directives
  -retract-no-explanation
        Allow to use retract directives without explanation
  -tool
        Forbid the use of tool directives
  -toolchain
        Forbid the use of toolchain directive
  -toolchain-pattern string
        Pattern to validate toolchain directive

Details

retract directives

• Force explanation for retract directives.

module example.com/foo

go 1.22

require (
	github.com/ldez/grignotin v0.4.1
)

retract (
    v1.0.0 // Explanation
)

replace directives

• Ban all replace directives.
• Allow only local replace directives.
• Allow only some replace directives.
• Detect duplicated replace directives.
• Detect identical replace directives.

module example.com/foo

go 1.22

require (
	github.com/ldez/grignotin v0.4.1
)

replace github.com/ldez/grignotin => ../grignotin/

exclude directives

• Ban all exclude directives.

module example.com/foo

go 1.22

require (
	github.com/ldez/grignotin v0.4.1
)

exclude (
    golang.org/x/crypto v1.4.5
    golang.org/x/text v1.6.7
)

tool directives

• Ban all tool directives.

module example.com/foo

go 1.24

tool (
    example.com/module/cmd/a
    example.com/module/cmd/b
)

toolchain directive

• Ban toolchain directive.
• Use a regular expression to constraint the Go minimum version.

module example.com/foo

go 1.22

toolchain go1.23.3

godebug directives

• Ban godebug directive.

module example.com/foo

go 1.22

godebug default=go1.21
godebug (
    panicnil=1
    asynctimerchan=0
)

go directive

• Use a regular expression to constraint the Go minimum version.

module example.com/foo

go 1.22.0

Documentation

Overview

Package gomoddirectives a linter that handle directives into `go.mod`.

Index

• func GetModuleFile() (*modfile.File, error)
• type Options
• type Result
  • func Analyze(opts Options) ([]Result, error)
  • func AnalyzeFile(file *modfile.File, opts Options) []Result
  • func AnalyzePass(pass *analysis.Pass, opts Options) ([]Result, error)
  • func NewResult(file *modfile.File, line *modfile.Line, reason string) Result
  • func (r Result) String() string

Functions

func GetModuleFile

func GetModuleFile() (*modfile.File, error)

GetModuleFile gets module file.

Types

type Options

type Options struct {
	ReplaceAllowList          []string
	ReplaceAllowLocal         bool
	ExcludeForbidden          bool
	RetractAllowNoExplanation bool
	ToolchainForbidden        bool
	ToolchainPattern          *regexp.Regexp
	ToolForbidden             bool
	GoDebugForbidden          bool
	GoVersionPattern          *regexp.Regexp
}

Options the analyzer options.

type Result

type Result struct {
	Reason string
	Start  token.Position
	End    token.Position
}

Result the analysis result.

func Analyze

func Analyze(opts Options) ([]Result, error)

Analyze analyzes a project.

func AnalyzeFile

func AnalyzeFile(file *modfile.File, opts Options) []Result

AnalyzeFile analyzes a mod file.

func AnalyzePass

func AnalyzePass(pass *analysis.Pass, opts Options) ([]Result, error)

AnalyzePass analyzes a pass.

func NewResult

func NewResult(file *modfile.File, line *modfile.Line, reason string) Result

NewResult creates a new Result.

func (Result) String

func (r Result) String() string