AWS Construct Library: Construct Specs and API Linting

[eladb]

In order to enable rich tooling and IDE integration for AWS Construct Libraries, we propose that libraries publish some form of specification which describes the various capabilities of these constructs. This will also enable "linting" the surface area of the AWS Construct Library.

For example, the spec should include information such as:

• The set of props needed to create the construct (along with documentation and type info).
• The set of attributes the construct exposes
• Which events can be subscribed to (onXxx methods)
• Which metrics are emitted by the construct (metricOfXxx methods)
• Which grants can be given by the construct (grantXxx methods).
• CodePipeline actions (addToPipeline) Move the CodeCommit and CodeBuild Actions from the codepipeline module into their @aws-cdk modules #238
• What information is needed in order to import an external construct to the stack (Xxx.import(,,props))?
• Can this construct be used as a target for a CloudWatch Event Rule?
• Documentation

This mechanism can further be used to annotate constructs with information that tooling can benefit from, such as runtime API (illustratively, table.putItem()), labels which can be used to discover this construct, etc.

We can leverage the jsii schema to reflect on the APIs a library exports and use this information to produce this information quite easily.

Furthermore, by reflecting on the jsii schema of the library, we can "lint" the API and enforce a set of rules to make sure APIs are consistent and enforce capabilities across all of our libraries.

Other things we should include in this toolset:

• Verify that 3rd party dependencies don't introduce licensing issues
• Simplify package.json by providing scripts for the various targets ("build", "test", "integ"), so we don't need to duplicate them.
• A version of pkglint
• Lint package names in all supported languages
• Lint that packages don't take any dependency on non-permissive licenses