tfproviderlint

A linting tool for Terraform Provider code.

Install

Local Install

Release binaries are available in the Releases section.

To instead use Go to install into your $GOBIN directory (e.g. $GOPATH/bin):

$ go get github.com/bflad/tfproviderlint/cmd/tfproviderlint

If you wish to install the command which includes all linting checks, including Extra Lint Checks:

$ go get github.com/bflad/tfproviderlint/cmd/tfproviderlintx

Docker Install

$ docker pull bflad/tfproviderlint

Homebrew Install

$ brew install bflad/tap/tfproviderlint

Usage

The tfproviderlint and tfproviderlintx tools operate similarly except for which checks are available. Additional information about usage and configuration options can be found by passing the help argument:

$ tfproviderlint help

Local Usage

Change into the directory of the Terraform Provider code and run:

$ tfproviderlint ./...

It is also possible to run via go vet:

$ go vet -vettool $(which tfproviderlint) ./...

Docker Usage

Change into the directory of the Terraform Provider code and run:

$ docker run -v $(pwd):/src bflad/tfproviderlint ./...

GitHub Action Usage

A GitHub Action is available: tfproviderlint-github-action

Standard Lint Checks

Standard lint checks are enabled by default in the tfproviderlint tool. Opt-in checks can be found in the Extra Lint Checks section. For additional information about each check, you can run tfproviderlint help NAME.

Standard Acceptance Test Checks

Check	Description	Type
AT001	check for TestCase missing CheckDestroy	AST
AT002	check for acceptance test function names including the word import	AST
AT003	check for acceptance test function names missing an underscore	AST
AT004	check for TestStep Config containing provider configuration	AST
AT005	check for acceptance test function names missing TestAcc prefix	AST
AT006	check for acceptance test functions containing multiple resource.Test() invocations	AST
AT007	check for acceptance test functions containing multiple resource.ParallelTest() invocations	AST

Standard Resource Checks

Check	Description	Type
R001	check for ResourceData.Set() calls using complex key argument	AST
R002	check for ResourceData.Set() calls using * dereferences	AST
R003	check for Resource having Exists functions	AST
R004	check for ResourceData.Set() calls using incompatible value types	AST
R005	check for ResourceData.HasChange() calls that can be combined into one HasChanges() call	AST
R006	check for RetryFunc that omit retryable errors	AST

Standard Schema Checks

Check	Description	Type
S001	check for Schema of TypeList or TypeSet missing Elem	AST
S002	check for Schema with both Required and Optional enabled	AST
S003	check for Schema with both Required and Computed enabled	AST
S004	check for Schema with both Required and Default configured	AST
S005	check for Schema with both Computed and Default configured	AST
S006	check for Schema of TypeMap missing Elem	AST
S007	check for Schema with both Required and ConflictsWith configured	AST
S008	check for Schema of TypeList or TypeSet with Default configured	AST
S009	check for Schema of TypeList or TypeSet with ValidateFunc configured	AST
S010	check for Schema of Computed only with ValidateFunc configured	AST
S011	check for Schema of Computed only with DiffSuppressFunc configured	AST
S012	check for Schema that Type is configured	AST
S013	check for map[string]*Schema that one of Computed, Optional, or Required is configured	AST
S014	check for Schema within Elem that Computed, Optional, and Required are not configured	AST
S015	check for map[string]*Schema that attribute names are valid	AST
S016	check for Schema that Set is only configured for TypeSet	AST
S017	check for Schema that MaxItems and MinItems are only configured for TypeList, TypeMap, or TypeSet	AST
S018	check for Schema that should use TypeList with MaxItems: 1	AST
S019	check for Schema that should omit Computed, Optional, or Required set to false	AST
S020	check for Schema of Computed only with ForceNew enabled	AST
S021	check for Schema that should omit ComputedWhen	AST
S022	check for Schema of TypeMap with invalid Elem of *schema.Resource	AST
S023	check for Schema that should omit Elem with incompatible Type	AST

Standard Validation Checks

Check	Description	Type
V001	check for custom SchemaValidateFunc that implement validation.StringMatch() or validation.StringDoesNotMatch()	AST

Extra Lint Checks

Extra lint checks are not included in the tfproviderlint tool and must be accessed via the tfproviderlintx tool or added to a custom lint tool. Generally these represent advanced Terraform Plugin SDK functionality that is not appropriate for all Terraform Providers.

Extra Resource Checks

Check	Description	Type
XR001	check for usage of ResourceData.GetOkExists() calls	AST
XR002	check for Resource that should implement Importer	AST
XR003	check for Resource that should implement Timeouts	AST
XR004	check for ResourceData.Set() calls that should implement error checking with complex values	AST

Extra Schema Checks

Check	Description	Type
XS001	check for map[string]*Schema that Description is configured	AST

Development and Testing

This project is built on the go/analysis framework and uses Go Modules for dependency management.

Helpful tooling for development:

• astdump: a tool for displaying the AST form of Go file
• ssadump: a tool for displaying and interpreting the SSA form of Go programs

Adding an Analyzer

• Create new analyzer in passes/ (or xpasses/ for extra checks)
• If the Analyzer reports issues, add to AllChecks variable in passes/checks.go (or xpasses/checks.go for extra checks)
• Since the analysistest package does not support Go Modules currently, each analyzer that implements testing must add a symlink to the top level vendor directory in the testdata/src/a directory. e.g. ln -s ../../../../../vendor passes/NAME/testdata/src/a/vendor

Implementing a Custom Lint Tool

The go/analysis framework and this codebase are designed for flexibility. You may wish to permanently disable certain default checks or even implement your own provider-specific checks. An example of how to incorporate all default and extra checks in a CLI command can be found in cmd/tfproviderlintx. To permanently exclude checks, each desired Analyzer must be individually included, similar to how AllChecks() is built in passes/checks.go.

The passes directory also includes the underlying Analyzer which iteratively gather AST-based information about the Terraform Provider code being analyzed. For example, passes/retryfunc returns information from all named and anonymous declarations of helper/resource.RetryFunc().

Primatives for working with Terraform Plugin SDK primatives can be found in helper/terraformtype. Primatives for working with the Go AST can be found in helper/astutils.

Updating Dependencies

$ go get URL
$ go mod tidy
$ go mod vendor

Unit Testing

$ go test ./...

Local Install Testing

$ go install ./cmd/tfproviderlint