depguard

README

Depguard

A Go linter that checks package imports are in a list of acceptable packages. This allows you to allow imports from a whole organization or only allow specific packages within a repository.

Install

go install github.com/OpenPeeDeeP/depguard@latest

Config

The Depguard binary looks for a file named ^\.?depguard\.(yaml|yml|json|toml)$ in the current working directory. Examples include (.depguard.yml or depguard.toml).

The following is an example configuration file.

{
  "main": {
    "files": [
      "$all",
      "!$test"
    ],
    "listMode": "Strict",
    "allow": [
      "$gostd",
      "github.com/OpenPeeDeeP"
    ],
    "deny": {
      "reflect": "Who needs reflection",
    }
  },
  "tests": {
    "files": [
      "$test"
    ],
    "listMode": "Lax",
    "deny": {
      "github.com/stretchr/testify": "Please use standard library for tests"
    }
  }
}

• The top level is a map of lists. The key of the map is a name that shows up in the linter's output.
• files - list of file globs that will match this list of settings to compare against
• allow - list of allowed packages
• deny - map of packages that are not allowed where the value is a suggestion = listMode - the mode to use for package matching

Files are matched using Globs. If the files list is empty, then all files will match that list. Prefixing a file with an exclamation mark ! will put that glob in a "don't match" list. A file will match a list if it is allowed and not denied.

Should always prefix a file glob with **/ as files are matched against absolute paths.

Allow is a prefix of packages to allow. A dollar sign $ can be used at the end of a package to specify it must be exact match only.

Deny is a map where the key is a prefix of the package to deny, and the value is a suggestion on what to use instead. A dollar sign $ can be used at the end of a package to specify it must be exact match only.

A Prefix List just means that a package will match a value, if the value is a prefix of the package. Example github.com/OpenPeeDeeP/depguard package will match a value of github.com/OpenPeeDeeP but won't match github.com/OpenPeeDeeP/depguard/v2.

ListMode is used to determine the package matching priority. There are three different modes; Original, Strict, and Lax.

Original is the original way that the package was written to use. It is not recommended to stay with this and is only here for backwards compatibility.

Strict, at its roots, is everything is denied unless in allowed.

Lax, at its roots, is everything is allowed unless it is denied.

There are cases where a package can be matched in both the allow and denied lists. You may allow a subpackage but deny the root or vice versa. The settings_tests.go file has many scenarios listed out under TestListImportAllowed. These tests will stay up to date as features are added.

Variables

There are variable replacements for each type of list (file or package). This is to reduce repetition and tedious behaviors.

File Variables

you can still use an exclamation mark ! in front of a variable to say not to use it. Example !$test will match any file that is not a go test file.

• $all - matches all go files
• $test - matches all go test files

Package Variables

• $gostd - matches all of go's standard library (Pulled from GOROOT)

Example Configs

Below:

• non-test go files will match Main and test go files will match Test.
• both allow all of go standard library except for the reflect package which will tell the user "Please don't use reflect package".
• go test files are also allowed to use https://github.com/stretchr/testify package and any sub-package of it.

Main:
  files:
  - $all
  - "!$test"
  allow:
  - $gostd
  deny:
    reflect: Please don't use reflect package
Test:
  files:
  - $test
  allow:
  - $gostd
  - github.com/stretchr/testify
  deny:
    reflect: Please don't use reflect package

Below:

• All go files will match Main
• Go files in internal will match both Main and Internal

Main:
  files:
  - $all
Internal:
  files:
  - "**/internal/**/*.go"

Below:

• All packages are allowed except for github.com/OpenPeeDeeP/depguard. Though github.com/OpenPeeDeeP/depguard/v2 and github.com/OpenPeeDeeP/depguard/somepackage would be allowed.

Main:
  deny:
  - github.com/OpenPeeDeeP/depguard$

Golangci-lint

This linter was built with Golangci-lint in mind. It is compatible and read their docs to see how to implement all their linters, including this one.

Documentation

Index

• func NewAnalyzer(settings *LinterSettings) (*analysis.Analyzer, error)
• type LinterSettings
• type List
• type UncompiledAnalyzer
  • func NewUncompiledAnalyzer(settings *LinterSettings) *UncompiledAnalyzer
  • func (ua *UncompiledAnalyzer) Compile() error

Functions

func NewAnalyzer

func NewAnalyzer(settings *LinterSettings) (*analysis.Analyzer, error)

NewAnalyzer creates a new analyzer from the settings passed in. This can fail if the passed in LinterSettings does not compile. Use NewUncompiledAnalyzer if you need control when the compile happens.

Types

type LinterSettings

type LinterSettings map[string]*List

type List

type List struct {
	ListMode string            `json:"listMode" yaml:"listMode" toml:"listMode" mapstructure:"listMode"`
	Files    []string          `json:"files" yaml:"files" toml:"files" mapstructure:"files"`
	Allow    []string          `json:"allow" yaml:"allow" toml:"allow" mapstructure:"allow"`
	Deny     map[string]string `json:"deny" yaml:"deny" toml:"deny" mapstructure:"deny"`
}

type UncompiledAnalyzer

type UncompiledAnalyzer struct {
	Analyzer *analysis.Analyzer
	// contains filtered or unexported fields
}

func NewUncompiledAnalyzer

func NewUncompiledAnalyzer(settings *LinterSettings) *UncompiledAnalyzer

NewUncompiledAnalyzer creates a new analyzer from the settings passed in. This can never error unlike NewAnalyzer. It is advised to call the Compile method on the returned Analyzer before running.

func (*UncompiledAnalyzer) Compile

func (ua *UncompiledAnalyzer) Compile() error

Compile the settings ahead of time so each subsuquent run of the analyzer doesn't need to do this work.