awslint
v2.139.0-alpha.0
Published
Enforces the AWS Construct Library guidelines
Downloads
1,902
Readme
awslint
The APIs of higher level constructs in this module are in developer preview before they become stable. We will only make breaking changes to address unforeseen API issues. Therefore, these APIs are not subject to Semantic Versioning, and breaking changes will be announced in release notes. This means that while you may use them, you may need to update your source code when upgrading to a newer version of this package.
A linter for the AWS Construct Library's API. It reflects a construct library's
module via it's .jsii
manifest and checks that the module adheres to the AWS
Resource Construct Design Guidelines.
Usage
First, the module must be built through jsii
(the linter reads the .jsii
manifest).
Now, if you simply run awslint
from a module directory, you will
see a list of diagnostic messages.
For example:
$ cd @aws-cdk/aws-sns
$ npm run awslint
warning: [awslint:resource-interface:@aws-cdk/aws-sns.Subscription] every resource must have a resource interface
warning: [awslint:resource-interface:@aws-cdk/aws-sns.TopicPolicy] every resource must have a resource interface
Each diagnostics includes the following elements:
warning: [awslint:resource-interface:@aws-cdk/aws-sns.Subscription] every resource must have a resource interface
[------] [-------------------------] [----------------------------] [-------------------------------------------]
^ ^ ^ ^
| | | |
level rule scope message
Options and Configuration
awslint
accepts options either through the command-line (i.e. --debug
) or
via an awslint
key in the module's package.json
.
{
"awslint": {
"debug": true
}
}
Include/Exclude
The i
/--include
and -x
/--exclude
options can be used to specify which rules will
be evaluated.
For example:
# evaluate only the "resource-props" and "import" rules in all scopes
$ npm run awslint -- -i resource-props -i import
# evaluate only the "import" rule in all scopes besides ones that begin with "@aws-cdk/aws-s3"
$ npm run awslint -- -i import -x "*:@aws-cdk/aws-s3*"
Filters are specified using the following pattern:
rule[*][:scope[*]]
If a "*"
suffix is provided, the component is treated as a prefix. Otherwise,
it is evaluated as a full match.
If scope is not specified, all scopes are implied (*
).
Examples:
*:*
- matches all rules in all scopes*:@aws-cdk/aws-apigateway.IRestApi*
- matches all rules in scopes that begin with@aws-cdk/aws-apigateway.IRestApi
resource-props
- matches theresource-props
rule in all scopesresource-*
- matches all rules that begin withresource-
.resource-*:@aws-cdk/aws-sns*
- matches allresource-
rules with scope that begins with@aws-cdk/aws-sns
.
When a rule is excluded, it will be displayed as skipped:
in the output and
will always considered to pass.
Saving State
The --save
option can be used to capture all failed linting rules and save them as exclude
s
in the module's package.json
file. This is useful to bootstrap the linting process and
progressively fix errors.
$ npm run awslint -- --save
[shows errors]
$ cat package.json
{
...
"awslint": {
"exclude": [
"...", // added by awslint --save
"...", // added by awslint --save
]
}
}
$ npm run awslint
[no errors]
If --save
is specified, awslint
will always exit with status code 0.
Output Options
- Use
--verbose
to print all passing linter rules (disabled by default). - Use
--quiet
to hide all warnings and skips (just prints errors)
Listing Rules
To list all linter rules:
$ npm run awslint list
module-name: module name must be @aws-cdk/aws-<namespace>
construct-ctor: signature of all construct constructors should be "scope, id, props"
resource-class: every resource must have a resource class (L2)
...
The AWS Resource Construct Design Guidelines document includes references for all rules. For example, see #construct-interface for a discussion about the "construct-interface" rule.