Add pkglint rule to require the presence of a README.md file (aws#442)

packages/@aws-cdk/applet-js/README.md

@@ -0,0 +1,2 @@
+## AWS CDK applet host program for Javascript
+This module is part of the [AWS Cloud Development Kit](https://github.com/awslabs/aws-cdk) project.

packages/@aws-cdk/aws-apigateway/README.md

@@ -0,0 +1,2 @@
+## The CDK Construct Library for AWS API Gateway
+This module is part of the [AWS Cloud Development Kit](https://github.com/awslabs/aws-cdk) project.

packages/@aws-cdk/aws-applicationautoscaling/README.md

@@ -0,0 +1,2 @@
+## The CDK Construct Library for AWS Application Auto-Scaling
+This module is part of the [AWS Cloud Development Kit](https://github.com/awslabs/aws-cdk) project.

packages/@aws-cdk/aws-appsync/README.md

@@ -0,0 +1,2 @@
+## The CDK Construct Library for AWS AppSync
+This module is part of the [AWS Cloud Development Kit](https://github.com/awslabs/aws-cdk) project.

packages/@aws-cdk/aws-athena/README.md

@@ -0,0 +1,2 @@
+## The CDK Construct Library for AWS Athena
+This module is part of the [AWS Cloud Development Kit](https://github.com/awslabs/aws-cdk) project.

packages/@aws-cdk/aws-autoscaling/README.md

@@ -0,0 +1,2 @@
+## The CDK Construct Library for AWS Auto-Scaling
+This module is part of the [AWS Cloud Development Kit](https://github.com/awslabs/aws-cdk) project.

packages/@aws-cdk/aws-autoscalingplans/README.md

@@ -0,0 +1,2 @@
+## The CDK Construct Library for AWS Auto-Scaling Plans
+This module is part of the [AWS Cloud Development Kit](https://github.com/awslabs/aws-cdk) project.

packages/@aws-cdk/aws-batch/README.md

@@ -0,0 +1,2 @@
+## The CDK Construct Library for AWS Batch
+This module is part of the [AWS Cloud Development Kit](https://github.com/awslabs/aws-cdk) project.

packages/@aws-cdk/aws-budgets/README.md

@@ -0,0 +1,2 @@
+## The CDK Construct Library for AWS Budgets
+This module is part of the [AWS Cloud Development Kit](https://github.com/awslabs/aws-cdk) project.

packages/@aws-cdk/aws-cloud9/README.md

@@ -0,0 +1,2 @@
+## The CDK Construct Library for AWS Cloud9
+This module is part of the [AWS Cloud Development Kit](https://github.com/awslabs/aws-cdk) project.

packages/@aws-cdk/aws-cloudformation/README.md

@@ -0,0 +1,2 @@
+## CDK Constructs for AWS CloudFormation
+This module is part of the [AWS Cloud Development Kit](https://github.com/awslabs/aws-cdk) project.

packages/@aws-cdk/aws-codedeploy/README.md

@@ -0,0 +1,2 @@
+## The CDK Construct Library for AWS CodeDeploy
+This module is part of the [AWS Cloud Development Kit](https://github.com/awslabs/aws-cdk) project.

packages/@aws-cdk/aws-cognito/README.md

@@ -0,0 +1,2 @@
+## The CDK Construct Library for AWS Cognito
+This module is part of the [AWS Cloud Development Kit](https://github.com/awslabs/aws-cdk) project.

packages/@aws-cdk/aws-config/README.md

@@ -0,0 +1,2 @@
+## The CDK Construct Library for AWS Config
+This module is part of the [AWS Cloud Development Kit](https://github.com/awslabs/aws-cdk) project.

packages/@aws-cdk/aws-datapipeline/README.md

@@ -0,0 +1,2 @@
+## The CDK Construct Library for AWS Data Pipeline
+This module is part of the [AWS Cloud Development Kit](https://github.com/awslabs/aws-cdk) project.

packages/@aws-cdk/aws-dax/README.md

@@ -0,0 +1,2 @@
+## The CDK Construct Library for AWS Data Accelerator (DAX)
+This module is part of the [AWS Cloud Development Kit](https://github.com/awslabs/aws-cdk) project.

packages/@aws-cdk/aws-directoryservice/README.md

@@ -0,0 +1,2 @@
+## The CDK Construct Library for AWS Directory Service
+This module is part of the [AWS Cloud Development Kit](https://github.com/awslabs/aws-cdk) project.

packages/@aws-cdk/aws-dms/README.md

@@ -0,0 +1,2 @@
+## The CDK Construct Library for AWS Database Migration Service (DMS)
+This module is part of the [AWS Cloud Development Kit](https://github.com/awslabs/aws-cdk) project.

packages/@aws-cdk/aws-ecr/README.md

@@ -0,0 +1,2 @@
+## The CDK Construct Library for AWS Elastic Container Registry (ECR)
+This module is part of the [AWS Cloud Development Kit](https://github.com/awslabs/aws-cdk) project.

packages/@aws-cdk/aws-ecs/README.md

@@ -0,0 +1,2 @@
+## The CDK Construct Library for AWS Elastic Container Service (ECS)
+This module is part of the [AWS Cloud Development Kit](https://github.com/awslabs/aws-cdk) project.

packages/@aws-cdk/aws-efs/README.md

@@ -0,0 +1,2 @@
+## The CDK Construct Library for AWS Elastic File System (EFS)
+This module is part of the [AWS Cloud Development Kit](https://github.com/awslabs/aws-cdk) project.

packages/@aws-cdk/aws-eks/README.md

@@ -0,0 +1,2 @@
+## The CDK Construct Library for AWS EKS
+This module is part of the [AWS Cloud Development Kit](https://github.com/awslabs/aws-cdk) project.

packages/@aws-cdk/aws-elasticache/README.md

@@ -0,0 +1,2 @@
+## The CDK Construct Library for AWS ElastiCache
+This module is part of the [AWS Cloud Development Kit](https://github.com/awslabs/aws-cdk) project.

packages/@aws-cdk/aws-elasticbeanstalk/README.md

@@ -0,0 +1,2 @@
+## The CDK Construct Library for AWS Elastic Beanstalk
+This module is part of the [AWS Cloud Development Kit](https://github.com/awslabs/aws-cdk) project.

packages/@aws-cdk/aws-elasticloadbalancing/README.md

@@ -0,0 +1,2 @@
+## CDK Constructs for AWS Elastic Load Balancing (ELB)
+This module is part of the [AWS Cloud Development Kit](https://github.com/awslabs/aws-cdk) project.

packages/@aws-cdk/aws-elasticloadbalancingv2/README.md

@@ -0,0 +1,2 @@
+## The CDK Construct Library for AWS Elastic Load Balancing (V2)
+This module is part of the [AWS Cloud Development Kit](https://github.com/awslabs/aws-cdk) project.

packages/@aws-cdk/aws-elasticsearch/README.md

@@ -0,0 +1,2 @@
+## The CDK Construct Library for AWS Elasticsearch
+This module is part of the [AWS Cloud Development Kit](https://github.com/awslabs/aws-cdk) project.

packages/@aws-cdk/aws-emr/README.md

@@ -0,0 +1,2 @@
+## The CDK Construct Library for AWS Elastic MapReduce (EMR)
+This module is part of the [AWS Cloud Development Kit](https://github.com/awslabs/aws-cdk) project.

packages/@aws-cdk/aws-gamelift/README.md

@@ -0,0 +1,2 @@
+## The CDK Construct Library for AWS GameLift
+This module is part of the [AWS Cloud Development Kit](https://github.com/awslabs/aws-cdk) project.

packages/@aws-cdk/aws-glue/README.md

@@ -0,0 +1,2 @@
+## The CDK Construct Library for AWS Glue
+This module is part of the [AWS Cloud Development Kit](https://github.com/awslabs/aws-cdk) project.

packages/@aws-cdk/aws-guardduty/README.md

@@ -0,0 +1,2 @@
+## The CDK Construct Library for AWS GuardDuty
+This module is part of the [AWS Cloud Development Kit](https://github.com/awslabs/aws-cdk) project.

packages/@aws-cdk/aws-inspector/README.md

@@ -0,0 +1,2 @@
+## The CDK Construct Library for AWS Inspector
+This module is part of the [AWS Cloud Development Kit](https://github.com/awslabs/aws-cdk) project.

packages/@aws-cdk/aws-iot/README.md

@@ -0,0 +1,2 @@
+## The CDK Construct Library for AWS IoT
+This module is part of the [AWS Cloud Development Kit](https://github.com/awslabs/aws-cdk) project.

packages/@aws-cdk/aws-kinesisanalytics/README.md

@@ -0,0 +1,2 @@
+## The CDK Construct Library for AWS Kinesis Analytics
+This module is part of the [AWS Cloud Development Kit](https://github.com/awslabs/aws-cdk) project.

packages/@aws-cdk/aws-kinesisfirehose/README.md

@@ -0,0 +1,2 @@
+## The CDK Construct Library for AWS Kinesis Firehose
+This module is part of the [AWS Cloud Development Kit](https://github.com/awslabs/aws-cdk) project.

packages/@aws-cdk/aws-neptune/README.md

@@ -0,0 +1,2 @@
+## CDK Constructs for AWS Neptune
+This module is part of the [AWS Cloud Development Kit](https://github.com/awslabs/aws-cdk) project.

packages/@aws-cdk/aws-opsworks/README.md

@@ -0,0 +1,2 @@
+## The CDK Construct Library for AWS OpsWorks
+This module is part of the [AWS Cloud Development Kit](https://github.com/awslabs/aws-cdk) project.

packages/@aws-cdk/aws-quickstarts/README.md

@@ -0,0 +1,2 @@
+## AWS Quickstarts for the CDK
+This module is part of the [AWS Cloud Development Kit](https://github.com/awslabs/aws-cdk) project.

packages/@aws-cdk/aws-redshift/README.md

@@ -0,0 +1,2 @@
+## The CDK Construct Library for AWS Redshift
+This module is part of the [AWS Cloud Development Kit](https://github.com/awslabs/aws-cdk) project.

packages/@aws-cdk/aws-sdb/README.md

@@ -0,0 +1,2 @@
+## The CDK Construct Library for AWS Simple Database
+This module is part of the [AWS Cloud Development Kit](https://github.com/awslabs/aws-cdk) project.

packages/@aws-cdk/aws-serverless/README.md

@@ -0,0 +1,2 @@
+## The CDK Construct Library for the AWS Serverless Application Model (SAM)
+This module is part of the [AWS Cloud Development Kit](https://github.com/awslabs/aws-cdk) project.

packages/@aws-cdk/aws-servicecatalog/README.md

@@ -0,0 +1,2 @@
+## The CDK Construct Library for AWS Service Catalog
+This module is part of the [AWS Cloud Development Kit](https://github.com/awslabs/aws-cdk) project.

packages/@aws-cdk/aws-servicediscovery/README.md

@@ -0,0 +1,2 @@
+## The CDK Construct Library for AWS Service Discovery
+This module is part of the [AWS Cloud Development Kit](https://github.com/awslabs/aws-cdk) project.

packages/@aws-cdk/aws-ses/README.md

@@ -0,0 +1,2 @@
+## The CDK Construct Library for AWS Simple Email Service
+This module is part of the [AWS Cloud Development Kit](https://github.com/awslabs/aws-cdk) project.

packages/@aws-cdk/aws-ssm/README.md

@@ -0,0 +1,2 @@
+## The CDK Construct Library for AWS Systems Manager
+This module is part of the [AWS Cloud Development Kit](https://github.com/awslabs/aws-cdk) project.

packages/@aws-cdk/aws-stepfunctions/README.md

@@ -0,0 +1,2 @@
+## The CDK Construct Library for AWS Step Functions
+This module is part of the [AWS Cloud Development Kit](https://github.com/awslabs/aws-cdk) project.

packages/@aws-cdk/aws-waf/README.md

@@ -0,0 +1,2 @@
+## The CDK Construct Library for AWS Web Application Firewall
+This module is part of the [AWS Cloud Development Kit](https://github.com/awslabs/aws-cdk) project.

packages/@aws-cdk/aws-wafregional/README.md

@@ -0,0 +1,2 @@
+## The CDK Construct Library for AWS Web Application Firewall (Regional)
+This module is part of the [AWS Cloud Development Kit](https://github.com/awslabs/aws-cdk) project.

packages/@aws-cdk/aws-workspaces/README.md

@@ -0,0 +1,2 @@
+## AWS CDK Construct Library for AWS WorkSpaces
+This module is part of the [AWS Cloud Development Kit](https://github.com/awslabs/aws-cdk) project.

packages/@aws-cdk/cdk/README.md

@@ -0,0 +1,2 @@
+## AWS Cloud Development Kit for Javascript
+This module is part of the [AWS Cloud Development Kit](https://github.com/awslabs/aws-cdk) project.

packages/@aws-cdk/cloudformation-diff/README.md

@@ -0,0 +1,2 @@
+## Utilities to diff AWS CDK stacks against CloudFormation templates
+This module is part of the [AWS Cloud Development Kit](https://github.com/awslabs/aws-cdk) project.

packages/@aws-cdk/cx-api/README.md

@@ -0,0 +1,2 @@
+## Cloud Executable protocol
+This module is part of the [AWS Cloud Development Kit](https://github.com/awslabs/aws-cdk) project.

packages/@aws-cdk/util/README.md

@@ -0,0 +1,2 @@
+## Utility routines used for implementing AWS CDK libraries
+This module is part of the [AWS Cloud Development Kit](https://github.com/awslabs/aws-cdk) project.

packages/aws-cdk/README.md

@@ -0,0 +1,174 @@
+## AWS CDK Toolkit
+The AWS CDK Toolkit provides the `cdk` command-line interface that can be used to work with AWS CDK applications.
+
+Command                           | Description
+----------------------------------|-------------------------------------------------------------------------------------
+[`cdk docs`](#cdk-docs)           | Access the online documentation
+[`cdk init`](#cdk-init)           | Start a new CDK project (app or library)
+[`cdk list`](#cdk-list)           | List stacks in an application
+[`cdk synth`](#cdk-synthesize)    | Synthesize a CDK app to CloudFormation template(s)
+[`cdk diff`](#cdk-diff)           | Diff stacks against current state
+[`cdk deploy`](#cdk-deploy)       | Deploy a stack into an AWS account
+[`cdk destroy`](#cdk-destroy)     | Deletes a stack from an AWS account
+[`cdk bootstrap`](#cdk-bootstrap) | Deploy a toolkit stack to support deploying large stacks & artifacts
+[`cdk doctor`](#cdk-doctor)       | Inspect the environment and produce information useful for troubleshooting
+
+This module is part of the [AWS Cloud Development Kit](https://github.com/awslabs/aws-cdk) project.
+
+### Commands
+#### `cdk docs`
+Outputs the URL to the documentation for the current toolkit version, and attempts to open a browser to that URL.
+
+```console
+$ # Open the documentation in the default browser (using 'open')
+$ cdk docs
+https://awslabs.github.io/aws-cdk/versions/0.7.4-beta/
+
+$ # Open the documentation in Chrome.
+$ cdk docs --browser='chrome %u'
+https://awslabs.github.io/aws-cdk/versions/0.7.4-beta/
+```
+
+#### `cdk init`
+Creates a new CDK project.
+
+```console
+$ # List the available template types & languages
+$ cdk init --list
+Available templates:
+* app: Template for a CDK Application
+   └─ cdk init app --language=[java|typescript]
+* lib: Template for a CDK Construct Library
+   └─ cdk init lib --language=typescript
+
+$ # Create a new library application in typescript
+$ cdk init lib --language=typescript
+```
+
+#### `cdk list`
+Lists the stacks modeled in the CDK app.
+
+```console
+$ # List all stacks in the CDK app 'node bin/main.js'
+$ cdk list --app='node bin/main.js'
+Foo
+Bar
+Baz
+
+$ # List all stack including all details (add --json to output JSON instead of YAML)
+$ cdk list --app='node bin/main.js' --long
+-
+    name: Foo
+    environment:
+        name: 000000000000/bermuda-triangle-1
+        account: '000000000000'
+        region: bermuda-triangle-1
+-
+    name: Bar
+    environment:
+        name: 111111111111/bermuda-triangle-2
+        account: '111111111111'
+        region: bermuda-triangle-2
+-
+    name: Baz
+    environment:
+        name: 333333333333/bermuda-triangle-3
+        account: '333333333333'
+        region: bermuda-triangle-3
+```
+
+#### `cdk synthesize`
+Synthesize the CDK app and outputs CloudFormation templates. If the application contains multiple stacks and no
+stack name is provided in the command-line arguments, the `--output` option is mandatory and a CloudFormation template
+will be generated in the output folder for each stack.
+
+By default, templates are generated in YAML format. The `--json` option can be used to switch to JSON.
+
+```console
+$ # Generate the template for StackName and output it to STDOUT
+$ cdk synthesize --app='node bin/main.js' MyStackName
+
+$ # Generate the template for MyStackName and save it to template.yml
+$ cdk synth --app='node bin/main.js' MyStackName --output=template.yml
+
+$ # Generate templates for all the stacks and save them into templates/
+$ cdk synth --app='node bin/main.js' --output=templates
+```
+
+#### `cdk diff`
+Computes differences between the infrastructure specified in the current state of the CDK app and the currently
+deployed application (or a user-specified CloudFormation template). This command returns non-zero if any differences are
+found.
+
+```console
+$ # Diff against the currently deployed stack
+$ cdk diff --app='node bin/main.js' MyStackName
+
+$ # Diff against a specific template document
+$ cdk diff --app='node bin/main.js' MyStackName --template=path/to/template.yml
+```
+
+#### `cdk deploy`
+Deploys a stack of your CDK app to it's environment. During the deployment, the toolkit will output progress
+indications, similar to what can be observed in the AWS CloudFormation Console. If the environment was never
+bootstrapped (using `cdk bootstrap`), only stacks that are not using assets and synthesize to a template that is under
+51,200 bytes will successfully deploy.
+
+```console
+$ cdk deploy --app='node bin/main.js' MyStackName
+```
+
+#### `cdk destroy`
+Deletes a stack from it's environment. This will cause the resources in the stack to be destroyed (unless they were
+configured with a `DeletionPolicy` of `Retain`). During the stack destruction, the command will output progress
+information similar to what `cdk deploy` provides.
+
+```console
+$ cdk destroy --app='node bin/main.js' MyStackName
+```
+
+#### `cdk bootstrap`
+Deploys a `CDKToolkit` CloudFormation stack into the specified environment(s), that provides an S3 bucket that
+`cdk deploy` will use to store synthesized templates and the related assets, before triggering a CloudFormation stack
+update. The name of the deployed stack can be configured using the `--toolkit-stack-name` argument.
+
+```console
+$ # Deploys to all environments
+$ cdk bootstrap --app='node bin/main.js'
+
+$ # Deploys only to environments foo and bar
+$ cdk bootstrap --app='node bin/main.js' foo bar
+```
+
+#### `cdk doctor`
+Inspect the current command-line environment and configurations, and collect information that can be useful for
+troubleshooting problems. It is usually a good idea to include the information provided by this command when submitting
+a bug report.
+
+```console
+$ cdk doctor
+ℹ️ CDK Version: 0.7.4-beta (build 0191444)
+ℹ️ AWS environment variables:
+  - AWS_EC2_METADATA_DISABLED = 1
+  - AWS_SDK_LOAD_CONFIG = 1
+```
+
+### Configuration
+On top of passing configuration through command-line arguments, it is possible to use JSON configuration files. The
+configuration's order of precedence is:
+1. Command-line arguments
+2. Project configuration (`./cdk.json`)
+3. User configuration (`~/.cdk.json`)
+
+#### JSON Configuration files
+Some of the interesting keys that can be used in the JSON configuration files:
+```js
+{
+    "app": "node bin/main.js", // Command to start the CDK app     (--app='node bin/main.js')
+    "context": {               // Context entries                  (--context=key:value)
+        "key": "value",
+    },
+    "toolkitStackName": "foo", // Customize 'bootstrap' stack name (--toolkit-stack-name=foo)
+    "versionReporting": false, // Opt-out of version reporting     (--no-version-reporting)
+}
+```

tools/pkglint/lib/rules.ts

@@ -77,6 +77,24 @@ export class AuthorAWS extends ValidationRule {
     }
 }
 
+/**
+ * There must be a README.md file.
+ */
+export class ReadmeFile extends ValidationRule {
+    public validate(pkg: PackageJson): void {
+        const readmeFile = path.join(pkg.packageRoot, 'README.md');
+        if (!fs.existsSync(readmeFile)) {
+            pkg.report({
+                message: 'There must be a README.md file at the root of the package',
+                fix: () => fs.writeFileSync(
+                    readmeFile,
+                    `## ${pkg.json.description}\nThis module is part of the [AWS Cloud Development Kit](https://github.com/awslabs/aws-cdk) project.`
+                )
+            });
+        }
+    }
+}
+
 /**
  * Keywords must contain CDK keywords and be sorted
  */
@@ -107,24 +125,6 @@ export class CDKKeywords extends ValidationRule {
     }
 }
 
-/**
- * Package.json must have 'jsii' section if and only if it's a JSII package
- */
-export class JSIISectionPresent extends ValidationRule {
-    public validate(pkg: PackageJson): void {
-        const hasJSIISection = 'jsii' in pkg.json;
-        if (isJSII(pkg)) {
-            if (!hasJSIISection) {
-                pkg.report({ message: 'JSII package must have "jsii" section in package.json' });
-            }
-        } else {
-            if (hasJSIISection) {
-                pkg.report({ message: 'Non-JSII package must not have "jsii" section in package.json' });
-            }
-        }
-    }
-}
-
 /**
  * JSII Java package is required and must look sane
  */

tools/pkgtools/README.md

@@ -0,0 +1,2 @@
+## Tools for generating cross-package artifacts
+This module is part of the [AWS Cloud Development Kit](https://github.com/awslabs/aws-cdk) project.