Custom Provider Linter

Relevant source files

The following files were used as context for generating this wiki page:

• providerlint/README.md
• providerlint/main.go
• providerlint/passes/checks.go
• infrastructure/repository/labels-workflow.tf
• README.md
• internal/service/sagemaker/README.md

The providerlint tool is a static analysis tool used for linting the source code of the Terraform AWS Provider. It is specifically tailored to enforce coding standards and best practices within this project, ensuring consistency and preventing common errors. The tool is built upon the general-purpose tfproviderlint and Go's go/analysis framework, with custom checks designed for the unique requirements of the AWS provider.

This linter is a key part of the development workflow, intended for use by provider contributors and maintainers to uphold code quality. Issues and pull requests related to the linter are tracked within the project's repository using a dedicated "linter" label.

Sources: providerlint/README.md, README.md, infrastructure/repository/labels-workflow.tf:65-68

Architecture

The providerlint tool's architecture is layered, extending existing frameworks to provide specialized functionality.

This diagram illustrates the foundational components of the providerlint tool.

• go/analysis Framework: The base layer from the Go standard library for building static analysis tools.
• tfproviderlint: A generic linter for Terraform Providers that providerlint extends. It provides a set of standard checks for acceptance testing (AT), resources (R), and schema (S).
• providerlint: The main tool, which integrates tfproviderlint and adds its own set of custom analyzers.
• Custom AWS Checks: Analyzers written specifically for the Terraform AWS Provider, categorized into groups like AWSAT (AWS Acceptance Test), AWSR (AWS Resource), and AWSV (AWS Validation).

Sources: providerlint/README.md

Lint Checks

providerlint includes several categories of checks. It incorporates all checks from the underlying tfproviderlint tool and adds its own AWS-specific rules.

tfproviderlint Checks

The tool extends and includes all checks from the tfproviderlint tool. For details on these checks, refer to the tfproviderlint documentation. Provider-specific analyzers, like those in providerlint, must use a namespace different from tfproviderlint's AT###, R###, and S### to avoid naming collisions.

Sources: providerlint/README.md

AWS Acceptance Test Checks (AWSAT)

These checks target common issues found in acceptance tests.

Check	Description
AWSAT001	check for resource.TestMatchResourceAttr() calls against ARN attributes
AWSAT002	check for hardcoded AMI IDs
AWSAT003	check for hardcoded regions
AWSAT004	check for TestCheckResourceAttr() calls with hardcoded TypeSet state hashes
AWSAT005	check for hardcoded AWS partitions in ARNs
AWSAT006	check for hardcoded AWS partition DNS suffixes

Sources: providerlint/README.md

AWS Resource Checks (AWSR)

These checks focus on the implementation of Terraform resources.

Check	Description
AWSR001	check for fmt.Sprintf() calls using .amazonaws.com domain suffix
AWSR002	check for d.Set() of tags attribute that should include IgnoreConfig()

Sources: providerlint/README.md

AWS Validation Checks (AWSV)

This category contains checks related to data validation within resources.

Check	Description
AWSV001	check for validation.StringInSlice() calls using []string parameter

Sources: providerlint/README.md

Development

Developing and adding new analyzers to providerlint follows a structured process. The development environment has a critical dependency on a vendor directory due to limitations in the analysistest package, which does not support Go Modules.

Sources: providerlint/README.md

Adding a New Analyzer

The process for adding a new analyzer is outlined below.

This flowchart shows the steps required to contribute a new linter check.

Key Steps:

1. Create a new directory in passes/ matching the analyzer name.
2. Implement the Analyzer in a NAME.go file.
3. Document the analyzer in a README.md within its directory.
4. For full checks, add unit tests using the analysistest framework, which requires creating test source files and symlinking the top-level vendor directory.
5. Update the main providerlint/README.md to include the new analyzer.

Sources: providerlint/README.md

Development Tooling

• analysistest: The testing framework for go/analysis. Its lack of Go Modules support necessitates the use of a vendor directory for testing.
• astdump: A recommended tool for displaying the Abstract Syntax Tree (AST) of a Go file, which is helpful for writing analyzers.

Sources: providerlint/README.md

Project Workflow Integration

The importance of the linter is reflected in the project's repository management. A specific label is defined for tracking linter-related work.

# infrastructure/repository/labels-workflow.tf:65-68
"linter" = {
  color       = "f4ecff", # color:terraform secondary
  description = "Pertains to changes to or issues with the various linters."
},

This "linter" label helps categorize and manage issues and pull requests concerning providerlint and other linters, streamlining maintenance and development efforts.

Sources: infrastructure/repository/labels-workflow.tf:65-68