chore(cx-api): introducing cloud-assembly-schema (aws#6724)

introduce the `cloud-assembly-schema` package to run `jsii` compatibility checks.

Closes aws#6531
Closes aws#6529

CONTRIBUTING.md

@@ -36,6 +36,7 @@ and let us know if it's not up-to-date (even better, submit a PR with your  corr
   - [Finding dependency cycles between packages](#finding-dependency-cycles-between-packages)
   - [Updating all Dependencies](#updating-all-dependencies)
   - [Running CLI integration tests](#running-cli-integration-tests)
+  - [Changing the Cloud Assembly Schema](#changing-cloud-assembly-schema)
   - [API Compatibility Checks](#api-compatibility-checks)
   - [Examples](#examples)
   - [Feature Flags](#feature-flags)
@@ -54,7 +55,7 @@ For day-to-day development and normal contributions, the following SDKs and tool
  - [.NET Core SDK 3.0](https://www.microsoft.com/net/download)
  - [Python 3.6.5](https://www.python.org/downloads/release/python-365/)
  - [Ruby 2.5.1](https://www.ruby-lang.org/en/news/2018/03/28/ruby-2-5-1-released/)
- 
+
 The basic commands to get the repository cloned and built locally follow:
 
 ```console
@@ -143,7 +144,7 @@ Integration tests perform a few functions in the CDK code base -
 3. (Optionally) Acts as a way to validate that constructs set up the CloudFormation resources as expected. A successful
    CloudFormation deployment does not mean that the resources are set up correctly.
 
-If you are working on a new feature that is using previously unused CloudFormation resource types, or involves 
+If you are working on a new feature that is using previously unused CloudFormation resource types, or involves
 configuring resource types across services, you need to write integration tests that use these resource types or
 features.
 
@@ -556,6 +557,11 @@ run as part of the regular build, since they have some particular requirements.
 See the [CLI CONTRIBUTING.md file](packages/aws-cdk/CONTRIBUTING.md) for
 more information on running those tests.
 
+### Changing Cloud Assembly Schema
+
+If you plan on making changes to the `cloud-assembly-schema` package, make sure you familiarize yourself with
+its own [contribution guide](./packages/@aws-cdk/cloud-assembly-schema/CONTRIBUTING.md)
+
 ### API Compatibility Checks
 
 All stable APIs in the CDK go through a compatibility check during build using

package.json

@@ -53,6 +53,10 @@
       "@aws-cdk/aws-ecr-assets/minimatch/**",
       "@aws-cdk/aws-lambda-nodejs/parcel-bundler",
       "@aws-cdk/aws-lambda-nodejs/parcel-bundler/**",
+      "@aws-cdk/cloud-assembly-schema/jsonschema",
+      "@aws-cdk/cloud-assembly-schema/jsonschema/**",
+      "@aws-cdk/cloud-assembly-schema/semver",
+      "@aws-cdk/cloud-assembly-schema/semver/**",
       "@aws-cdk/cx-api/semver",
       "@aws-cdk/cx-api/semver/**",
       "@aws-cdk/cx-api/semver/**"

packages/@aws-cdk/app-delivery/lib/pipeline-deploy-stack-action.ts

@@ -3,8 +3,8 @@ import * as codepipeline from '@aws-cdk/aws-codepipeline';
 import * as cpactions from '@aws-cdk/aws-codepipeline-actions';
 import * as events from '@aws-cdk/aws-events';
 import * as iam from '@aws-cdk/aws-iam';
+import * as cxschema from '@aws-cdk/cloud-assembly-schema';
 import * as cdk from '@aws-cdk/core';
-import * as cxapi from '@aws-cdk/cx-api';
 
 export interface PipelineDeployStackActionProps {
   /**
@@ -101,7 +101,7 @@ export class PipelineDeployStackAction implements codepipeline.IAction {
 
   constructor(props: PipelineDeployStackActionProps) {
     this.stack = props.stack;
-    const assets = this.stack.node.metadata.filter(md => md.type === cxapi.ASSET_METADATA);
+    const assets = this.stack.node.metadata.filter(md => md.type === cxschema.ArtifactMetadataEntryType.ASSET);
     if (assets.length > 0) {
       // FIXME: Implement the necessary actions to publish assets
       throw new Error(`Cannot deploy the stack ${this.stack.stackName} because it references ${assets.length} asset(s)`);

packages/@aws-cdk/app-delivery/package.json

@@ -48,6 +48,7 @@
     "@aws-cdk/aws-iam": "0.0.0",
     "@aws-cdk/core": "0.0.0",
     "@aws-cdk/cx-api": "0.0.0",
+    "@aws-cdk/cloud-assembly-schema": "0.0.0",
     "constructs": "^2.0.0"
   },
   "devDependencies": {
@@ -85,6 +86,7 @@
     "@aws-cdk/aws-iam": "0.0.0",
     "@aws-cdk/core": "0.0.0",
     "@aws-cdk/cx-api": "0.0.0",
+    "@aws-cdk/cloud-assembly-schema": "0.0.0",
     "constructs": "^2.0.0"
   },
   "engines": {

packages/@aws-cdk/app-delivery/test/test.pipeline-deploy-stack-action.ts

@@ -6,8 +6,8 @@ import * as cpactions from '@aws-cdk/aws-codepipeline-actions';
 import * as events from '@aws-cdk/aws-events';
 import * as iam from '@aws-cdk/aws-iam';
 import * as s3 from '@aws-cdk/aws-s3';
+import * as cxschema from '@aws-cdk/cloud-assembly-schema';
 import * as cdk from '@aws-cdk/core';
-import * as cxapi from '@aws-cdk/cx-api';
 import * as fc from 'fast-check';
 import * as nodeunit from 'nodeunit';
 import { PipelineDeployStackAction } from '../lib/pipeline-deploy-stack-action';
@@ -390,7 +390,7 @@ export = nodeunit.testCase({
 
           const deployedStack = new cdk.Stack(app, 'DeployedStack');
           for (let i = 0 ; i < assetCount ; i++) {
-            deployedStack.node.addMetadata(cxapi.ASSET_METADATA, {});
+            deployedStack.node.addMetadata(cxschema.ArtifactMetadataEntryType.ASSET, {});
           }
 
           test.throws(() => {

packages/@aws-cdk/assert/lib/inspector.ts

@@ -1,3 +1,4 @@
+import * as cxschema from '@aws-cdk/cloud-assembly-schema';
 import * as api from '@aws-cdk/cx-api';
 import { Assertion, not } from './assertion';
 import { MatchStyle, matchTemplate } from './assertions/match-template';
@@ -65,9 +66,9 @@ export class StackPathInspector extends Inspector {
     const metadata = this.stack.manifest.metadata || {};
     const md = metadata[this.path] || metadata[`/${this.stack.id}${this.path}`];
     if (md === undefined) { return undefined; }
-    const resourceMd = md.find(entry => entry.type === api.LOGICAL_ID_METADATA_KEY);
+    const resourceMd = md.find(entry => entry.type === cxschema.ArtifactMetadataEntryType.LOGICAL_ID);
     if (resourceMd === undefined) { return undefined; }
-    const logicalId = resourceMd.data;
+    const logicalId = resourceMd.data as cxschema.LogMessageMetadataEntry;
     return this.stack.template.Resources[logicalId];
   }
 }

packages/@aws-cdk/assert/package.json

@@ -39,6 +39,7 @@
     "@aws-cdk/cloudformation-diff": "0.0.0",
     "@aws-cdk/core": "0.0.0",
     "@aws-cdk/cx-api": "0.0.0",
+    "@aws-cdk/cloud-assembly-schema": "0.0.0",
     "constructs": "^2.0.0"
   },
   "peerDependencies": {

packages/@aws-cdk/assert/test/have-output.test.ts

@@ -1,3 +1,4 @@
+import * as cxschema from '@aws-cdk/cloud-assembly-schema';
 import * as cxapi from '@aws-cdk/cx-api';
 import { unlink, writeFileSync } from 'fs';
 import { join } from 'path';
@@ -187,7 +188,7 @@ function mkStack(template: any): cxapi.CloudFormationStackArtifact {
   const assembly = new cxapi.CloudAssemblyBuilder();
 
   assembly.addArtifact(stackName, {
-    type: cxapi.ArtifactType.AWS_CLOUDFORMATION_STACK,
+    type: cxschema.ArtifactType.AWS_CLOUDFORMATION_STACK,
     environment: cxapi.EnvironmentUtils.format('123456789012', 'bermuda-triangle-1'),
     properties: {
       templateFile: templateFileName

packages/@aws-cdk/assert/test/have-resource.test.ts

@@ -1,3 +1,4 @@
+import * as cxschema from '@aws-cdk/cloud-assembly-schema';
 import * as cxapi from '@aws-cdk/cx-api';
 import { writeFileSync } from 'fs';
 import { join } from 'path';
@@ -142,7 +143,7 @@ describe('property absence', () => {
 function mkStack(template: any): cxapi.CloudFormationStackArtifact {
   const assembly = new cxapi.CloudAssemblyBuilder();
   assembly.addArtifact('test', {
-    type: cxapi.ArtifactType.AWS_CLOUDFORMATION_STACK,
+    type: cxschema.ArtifactType.AWS_CLOUDFORMATION_STACK,
     environment: cxapi.EnvironmentUtils.format('123456789', 'us-west-2'),
     properties: {
       templateFile: 'template.json'

packages/@aws-cdk/aws-autoscaling/package.json

@@ -69,7 +69,8 @@
     "cdk-integ-tools": "0.0.0",
     "cfn2ts": "0.0.0",
     "nodeunit": "^0.11.3",
-    "pkglint": "0.0.0"
+    "pkglint": "0.0.0",
+    "@aws-cdk/cloud-assembly-schema": "0.0.0"
   },
   "dependencies": {
     "@aws-cdk/aws-autoscaling-common": "0.0.0",

packages/@aws-cdk/aws-autoscaling/test/test.auto-scaling-group.ts

@@ -2,8 +2,8 @@ import { ABSENT, expect, haveResource, haveResourceLike, InspectionFailure, Reso
 import * as cloudwatch from '@aws-cdk/aws-cloudwatch';
 import * as ec2 from '@aws-cdk/aws-ec2';
 import * as iam from '@aws-cdk/aws-iam';
+import * as cxschema from '@aws-cdk/cloud-assembly-schema';
 import * as cdk from '@aws-cdk/core';
-import * as cxapi from '@aws-cdk/cx-api';
 import { Test } from 'nodeunit';
 import * as autoscaling from '../lib';
 
@@ -827,7 +827,7 @@ export = {
     });
 
     // THEN
-    test.deepEqual(asg.node.metadata[0].type, cxapi.WARNING_METADATA_KEY);
+    test.deepEqual(asg.node.metadata[0].type, cxschema.ArtifactMetadataEntryType.WARN);
     test.deepEqual(asg.node.metadata[0].data, 'iops will be ignored without volumeType: EbsDeviceVolumeType.IO1');
 
     test.done();
@@ -854,7 +854,7 @@ export = {
     });
 
     // THEN
-    test.deepEqual(asg.node.metadata[0].type, cxapi.WARNING_METADATA_KEY);
+    test.deepEqual(asg.node.metadata[0].type, cxschema.ArtifactMetadataEntryType.WARN);
     test.deepEqual(asg.node.metadata[0].data, 'iops will be ignored without volumeType: EbsDeviceVolumeType.IO1');
 
     test.done();

packages/@aws-cdk/aws-ec2/package.json

@@ -68,7 +68,8 @@
     "cdk-integ-tools": "0.0.0",
     "cfn2ts": "0.0.0",
     "nodeunit": "^0.11.3",
-    "pkglint": "0.0.0"
+    "pkglint": "0.0.0",
+    "@aws-cdk/cloud-assembly-schema": "0.0.0"
   },
   "dependencies": {
     "@aws-cdk/aws-cloudwatch": "0.0.0",

packages/@aws-cdk/aws-ec2/test/test.instance.ts

@@ -1,7 +1,7 @@
 import { expect, haveResource } from '@aws-cdk/assert';
 import { StringParameter } from '@aws-cdk/aws-ssm';
+import * as cxschema from '@aws-cdk/cloud-assembly-schema';
 import { Stack } from '@aws-cdk/core';
-import * as cxapi from '@aws-cdk/cx-api';
 import { Test } from 'nodeunit';
 import { AmazonLinuxImage, BlockDeviceVolume, EbsDeviceVolumeType, Instance, InstanceClass, InstanceSize, InstanceType, Vpc } from '../lib';
 
@@ -237,7 +237,7 @@ export = {
       });
 
       // THEN
-      test.deepEqual(instance.node.metadata[0].type, cxapi.WARNING_METADATA_KEY);
+      test.deepEqual(instance.node.metadata[0].type, cxschema.ArtifactMetadataEntryType.WARN);
       test.deepEqual(instance.node.metadata[0].data, 'iops will be ignored without volumeType: EbsDeviceVolumeType.IO1');
 
       test.done();
@@ -264,7 +264,7 @@ export = {
       });
 
       // THEN
-      test.deepEqual(instance.node.metadata[0].type, cxapi.WARNING_METADATA_KEY);
+      test.deepEqual(instance.node.metadata[0].type, cxschema.ArtifactMetadataEntryType.WARN);
       test.deepEqual(instance.node.metadata[0].data, 'iops will be ignored without volumeType: EbsDeviceVolumeType.IO1');
 
       test.done();

packages/@aws-cdk/aws-ecr-assets/package.json

@@ -67,7 +67,8 @@
     "cdk-integ-tools": "0.0.0",
     "nodeunit": "^0.11.3",
     "pkglint": "0.0.0",
-    "proxyquire": "^2.1.3"
+    "proxyquire": "^2.1.3",
+    "@aws-cdk/cloud-assembly-schema": "0.0.0"
   },
   "dependencies": {
     "@aws-cdk/assets": "0.0.0",

packages/@aws-cdk/aws-ecr-assets/test/test.image-asset.ts

@@ -1,7 +1,7 @@
 import { expect, haveResource } from '@aws-cdk/assert';
 import * as iam from '@aws-cdk/aws-iam';
+import * as cxschema from '@aws-cdk/cloud-assembly-schema';
 import { App, Lazy, Stack } from '@aws-cdk/core';
-import { ASSET_METADATA } from '@aws-cdk/cx-api';
 import * as fs from 'fs';
 import { Test } from 'nodeunit';
 import * as path from 'path';
@@ -50,8 +50,8 @@ export = {
     });
 
     // THEN
-    const assetMetadata = stack.node.metadata.find(({ type }) => type === ASSET_METADATA);
-    test.deepEqual(assetMetadata && assetMetadata.data.buildArgs, { a: 'b' });
+    const assetMetadata = stack.node.metadata.find(({ type }) => type === cxschema.ArtifactMetadataEntryType.ASSET);
+    test.deepEqual(assetMetadata && (assetMetadata.data as cxschema.ContainerImageAssetMetadataEntry).buildArgs, { a: 'b' });
     test.done();
   },
 
@@ -69,8 +69,8 @@ export = {
     });
 
     // THEN
-    const assetMetadata = stack.node.metadata.find(({ type }) => type === ASSET_METADATA);
-    test.deepEqual(assetMetadata && assetMetadata.data.target, 'a-target');
+    const assetMetadata = stack.node.metadata.find(({ type }) => type === cxschema.ArtifactMetadataEntryType.ASSET);
+    test.deepEqual(assetMetadata && (assetMetadata.data as cxschema.ContainerImageAssetMetadataEntry).target, 'a-target');
     test.done();
   },
 
@@ -86,8 +86,8 @@ export = {
     });
 
     // THEN
-    const assetMetadata = stack.node.metadata.find(({ type }) => type === ASSET_METADATA);
-    test.deepEqual(assetMetadata && assetMetadata.data.file, 'Dockerfile.Custom');
+    const assetMetadata = stack.node.metadata.find(({ type }) => type === cxschema.ArtifactMetadataEntryType.ASSET);
+    test.deepEqual(assetMetadata && (assetMetadata.data as cxschema.ContainerImageAssetMetadataEntry).file, 'Dockerfile.Custom');
     test.done();
   },
 

packages/@aws-cdk/aws-efs/package.json

@@ -89,6 +89,7 @@
     "@aws-cdk/aws-ec2": "0.0.0",
     "@aws-cdk/aws-kms": "0.0.0",
     "@aws-cdk/cx-api": "0.0.0",
+    "@aws-cdk/cloud-assembly-schema": "0.0.0",
     "constructs": "^2.0.0"
   },
   "homepage": "https://github.com/aws/aws-cdk",
@@ -97,6 +98,7 @@
     "@aws-cdk/aws-ec2": "0.0.0",
     "@aws-cdk/aws-kms": "0.0.0",
     "@aws-cdk/cx-api": "0.0.0",
+    "@aws-cdk/cloud-assembly-schema": "0.0.0",
     "constructs": "^2.0.0"
   },
   "engines": {

packages/@aws-cdk/aws-efs/test/efs-file-system.test.ts

@@ -1,8 +1,8 @@
 import {expect as expectCDK, haveResource} from '@aws-cdk/assert';
 import * as ec2 from '@aws-cdk/aws-ec2';
 import * as kms from '@aws-cdk/aws-kms';
+import * as cxschema from '@aws-cdk/cloud-assembly-schema';
 import {Stack} from '@aws-cdk/core';
-import {WARNING_METADATA_KEY} from '@aws-cdk/cx-api';
 import {EfsFileSystem, EfsLifecyclePolicyProperty, EfsPerformanceMode, EfsThroughputMode} from '../lib/efs-file-system';
 
 let stack = new Stack();
@@ -127,7 +127,7 @@ test('Warning when provisioned throughput is less than the valid range', () => {
     provisionedThroughputInMibps: 0
   });
 
-  expect(fileSystem.node.metadata[0].type).toMatch(WARNING_METADATA_KEY);
+  expect(fileSystem.node.metadata[0].type).toMatch(cxschema.ArtifactMetadataEntryType.WARN);
   expect(fileSystem.node.metadata[0].data).toContain('Valid values for throughput are 1-1024 MiB/s');
   expect(fileSystem.node.metadata[0].data).toContain('You can get this limit increased by contacting AWS Support');
 
@@ -141,7 +141,7 @@ test('Warning when provisioned throughput is above than the valid range', () =>
     provisionedThroughputInMibps: 1025
   });
 
-  expect(fileSystem.node.metadata[0].type).toMatch(WARNING_METADATA_KEY);
+  expect(fileSystem.node.metadata[0].type).toMatch(cxschema.ArtifactMetadataEntryType.WARN);
   expect(fileSystem.node.metadata[0].data).toContain('Valid values for throughput are 1-1024 MiB/s');
   expect(fileSystem.node.metadata[0].data).toContain('You can get this limit increased by contacting AWS Support');
 

packages/@aws-cdk/aws-s3-assets/package.json

@@ -68,6 +68,7 @@
     "nodeunit": "^0.11.3",
     "pkglint": "0.0.0",
     "sinon": "^9.0.2",
+    "@aws-cdk/cloud-assembly-schema": "0.0.0",
     "ts-mock-imports": "^1.3.0"
   },
   "dependencies": {

packages/@aws-cdk/aws-s3-assets/test/test.asset.ts

@@ -1,5 +1,6 @@
 import { expect, haveResource, ResourcePart, SynthUtils } from '@aws-cdk/assert';
 import * as iam from '@aws-cdk/aws-iam';
+import * as cxschema from '@aws-cdk/cloud-assembly-schema';
 import * as cdk from '@aws-cdk/core';
 import * as cxapi from '@aws-cdk/cx-api';
 import * as fs from 'fs';
@@ -341,7 +342,7 @@ export = {
       const session = app.synth();
       const artifact = session.getStackByName(stack.stackName);
       const metadata = artifact.manifest.metadata || {};
-      const md = Object.values(metadata)[0]![0]!.data;
+      const md = Object.values(metadata)[0]![0]!.data as cxschema.AssetMetadataEntry;
       test.deepEqual(md.path, 'asset.6b84b87243a4a01c592d78e1fd3855c4bfef39328cd0a450cc97e81717fea2a2');
       test.done();
     }

packages/@aws-cdk/cloud-assembly-schema/.gitignore

@@ -0,0 +1,17 @@
+lib/*.js
+test/*.js
+scripts/*.js
+*.js.map
+*.d.ts
+node_modules
+dist
+tsconfig.json
+tslint.json
+.jsii
+
+.LAST_BUILD
+.LAST_PACKAGE
+*.snk
+.nyc_output
+coverage
+nyc.config.js

packages/@aws-cdk/cloud-assembly-schema/.npmignore

@@ -0,0 +1,20 @@
+# Don't include original .ts files when doing `npm pack`
+*.ts
+!*.d.ts
+coverage
+.nyc_output
+*.tgz
+
+dist
+.LAST_PACKAGE
+.LAST_BUILD
+!*.js
+
+# Include .jsii
+!.jsii
+
+*.snk
+
+*.tsbuildinfo
+
+tsconfig.json