Skip to content

Latest commit

 

History

History
286 lines (211 loc) · 15.7 KB

README.md

File metadata and controls

286 lines (211 loc) · 15.7 KB

tfproviderlint

Static analysis libraries and tooling for Terraform Provider code.

PkgGoDev

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 install github.com/bflad/tfproviderlint/cmd/tfproviderlint@latest

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

go install github.com/bflad/tfproviderlint/cmd/tfproviderlintx@latest

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

To enable only specific checks, they can be passed in as flags:

tfproviderlint -AT001

To enable all checks, but disable specific checks, they can be passed in as flags set to false:

tfproviderlint -AT001=false

Local Usage

To report issues, change into the directory of the Terraform Provider code and run:

tfproviderlint ./...

To apply automated fixes for checks that support them, change into the directory of the Terraform Provider code and run:

tfproviderlint -fix ./...

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
AT008 check for acceptance test function declaration *testing.T parameter naming AST
AT009 check for acctest.RandStringFromCharSet() calls that can be simplified to acctest.RandString() AST
AT010 check for TestCase including IDRefreshName implementation AST
AT011 check for TestCase including IDRefreshIgnore implementation without IDRefreshName AST
AT012 check for files containing multiple acceptance test function name prefixes 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
R007 check for deprecated (schema.ResourceData).Partial usage AST
R008 REMOVED in v0.30.0 check for deprecated (schema.ResourceData).SetPartial usage AST
R009 check for Go panic usage AST
R010 check for (schema.ResourceData).GetChange assignment which should use (schema.ResourceData).Get AST
R011 check for Resource that configure MigrateState AST
R012 check for data source Resource that configure CustomizeDiff AST
R013 check for map[string]*Resource that resource names contain at least one underscore AST
R014 check for CreateFunc, CreateContextFunc, DeleteFunc, DeleteContextFunc, ReadFunc, ReadContextFunc, UpdateFunc, and UpdateContextFunc parameter naming AST
R015 check for (*schema.ResourceData).SetId() receiver method usage with unstable resource.UniqueId() value AST
R016 check for (*schema.ResourceData).SetId() receiver method usage with unstable resource.PrefixedUniqueId() value AST
R017 check for (*schema.ResourceData).SetId() receiver method usage with unstable time.Now() value AST
R018 check for time.Sleep() function usage AST
R019 check for (*schema.ResourceData).HasChanges() receiver method usage with many arguments 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
S024 check for Schema that should omit ForceNew in data source schema attributes AST
S025 check for Schema of Computed only with AtLeastOneOf configured AST
S026 check for Schema of Computed only with ConflictsWith configured AST
S027 check for Schema of Computed only with Default configured AST
S028 check for Schema of Computed only with DefaultFunc configured AST
S029 check for Schema of Computed only with ExactlyOneOf configured AST
S030 check for Schema of Computed only with InputDefault configured AST
S031 check for Schema of Computed only with MaxItems configured AST
S032 check for Schema of Computed only with MinItems configured AST
S033 check for Schema of Computed only with StateFunc configured AST
S034 REMOVED in v0.30.0 check for Schema that configure PromoteSingle AST
S035 check for Schema with invalid AtLeastOneOf attribute references AST
S036 check for Schema with invalid ConflictsWith attribute references AST
S037 check for Schema with invalid ExactlyOneOf attribute references AST

Standard Validation Checks

Check Description Type
V001 check for custom SchemaValidateFunc that implement validation.StringMatch() or validation.StringDoesNotMatch() AST
V002 REMOVED in v0.30.0 check for deprecated CIDRNetwork validation function usage AST
V003 REMOVED in v0.30.0 check for deprecated IPRange validation function usage AST
V004 REMOVED in v0.30.0 check for deprecated SingleIP validation function usage AST
V005 REMOVED in v0.30.0 check for deprecated ValidateJsonString validation function usage AST
V006 REMOVED in v0.30.0 check for deprecated ValidateListUniqueStrings validation function usage AST
V007 REMOVED in v0.30.0 check for deprecated ValidateRegexp validation function usage AST
V008 REMOVED in v0.30.0 check for deprecated ValidateRFC3339TimeString validation function usage AST
V009 check for validation.StringMatch() call with empty message argument AST
V010 check for validation.StringDoesNotMatch() call with empty message argument AST
V011 check for custom SchemaValidateFunc that implement validation.StringLenBetween() AST
V012 check for custom SchemaValidateFunc that implement validation.IntAtLeast(), validation.IntAtMost(), or validation.IntBetween() AST
V013 check for custom SchemaValidateFunc that implement validation.StringInSlice() or validation.StringNotInSlice() AST
V014 check for custom SchemaValidateFunc that implement validation.IntInSlice() or validation.IntNotInSlice() 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 Acceptance Test Checks

Check Description Type
XAT001 check for TestCase missing ErrorCheck AST

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
XR005 check for Resource that Description is configured AST
XR006 check for Resource that implements Timeouts for missing Create, Delete, Read, or Update implementation AST
XR007 check for os/exec.Command usage AST
XR008 check for os/exec.CommandContext usage AST

Extra Schema Checks

Check Description Type
XS001 check for map[string]*Schema that Description is configured AST
XS002 check for map[string]*Schema that keys are in alphabetical order 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

Go Compatibility

This project follows the Go support policy for versions. The two latest major releases of Go are supported by the project.

Currently, that means Go 1.21 or later must be used when including this project as a dependency.

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)

Implementing SuggestedFixes Testing

The upstream analysistest package now contains functionality to verify SuggestedFixes via RunWithSuggestedFixes.

import (
  "testing"

  "golang.org/x/tools/go/analysis/analysistest"
)

func TestAnalyzerFixes(t *testing.T) {
  testdata := analysistest.TestData()
  analysistest.RunWithSuggestedFixes(t, testdata, Analyzer, "testdata/src/a")
}

To setup the expected file content verification, the testing expects a file suffixed with .golden (e.g. testdata/src/a/main.go.golden).

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/helper/resource/retryfuncinfo 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

Dependency updates are managed by Dependabot.

Unit Testing

go test ./...

Local Install Testing

go install ./cmd/tfproviderlint