chore(cx-api): clean up features.ts

CONTRIBUTING.md

@@ -635,8 +635,8 @@ The pattern is simple:
    form `module.Type:feature` (e.g. `@aws-cdk/core:enableStackNameDuplicates`).
 2. Use `node.tryGetContext(cxapi.ENABLE_XXX)` to check if this feature is enabled
    in your code. If it is not defined, revert to the legacy behavior.
-3. Add your feature flag to
-   [cx-api/lib/future.ts](https://github.com/aws/aws-cdk/blob/master/packages/%40aws-cdk/cx-api/lib/future.ts).
+3. Add your feature flag to the `FUTURE_FLAGS` map in
+   [cx-api/lib/features.ts](https://github.com/aws/aws-cdk/blob/master/packages/%40aws-cdk/cx-api/lib/features.ts).
    This map is inserted to generated `cdk.json` files for new projects created
    through `cdk init`.
 4. In your PR title (which goes into CHANGELOG), add a `(under feature flag)` suffix. e.g:

packages/@aws-cdk/cx-api/lib/app.ts

@@ -0,0 +1,29 @@
+// --------------------------------------------------------------------------------
+// This file declares context keys that are used by the CLI to control the
+// behavior of CDK apps. Contrary to feature flags (which are defined under
+// `features.ts`) these options are not bound to be removed in the next major
+// version.
+// --------------------------------------------------------------------------------
+
+/**
+ * Enables the embedding of the "aws:cdk:path" in CloudFormation template metadata.
+ */
+export const PATH_METADATA_ENABLE_CONTEXT = 'aws:cdk:enable-path-metadata';
+
+/**
+ * Disable the collection and reporting of version information.
+ */
+export const DISABLE_VERSION_REPORTING = 'aws:cdk:disable-version-reporting';
+
+/**
+ * If this is set, asset staging is disabled. This means that assets will not be copied to
+ * the output directory and will be referenced with absolute source paths.
+ */
+export const DISABLE_ASSET_STAGING_CONTEXT = 'aws:cdk:disable-asset-staging';
+
+/**
+ * If this context key is set, the CDK will stage assets under the specified
+ * directory. Otherwise, assets will not be staged.
+ * Omits stack traces from construct metadata entries.
+ */
+export const DISABLE_METADATA_STACK_TRACE = 'aws:cdk:disable-stack-trace';

packages/@aws-cdk/cx-api/lib/features.ts

@@ -1,26 +1,12 @@
-
-/**
- * Enables the embedding of the "aws:cdk:path" in CloudFormation template metadata.
- */
-export const PATH_METADATA_ENABLE_CONTEXT = 'aws:cdk:enable-path-metadata';
-
-/**
- * Disable the collection and reporting of version information.
- */
-export const DISABLE_VERSION_REPORTING = 'aws:cdk:disable-version-reporting';
-
-/**
- * If this is set, asset staging is disabled. This means that assets will not be copied to
- * the output directory and will be referenced with absolute source paths.
- */
-export const DISABLE_ASSET_STAGING_CONTEXT = 'aws:cdk:disable-asset-staging';
-
-/**
- * If this context key is set, the CDK will stage assets under the specified
- * directory. Otherwise, assets will not be staged.
- * Omits stack traces from construct metadata entries.
- */
-export const DISABLE_METADATA_STACK_TRACE = 'aws:cdk:disable-stack-trace';
+// --------------------------------------------------------------------------------
+// This file defines context keys that enable certain features that are
+// implemented behind a flag in order to preserve backwards compatibility for
+// existing apps. When a new app is initialized through `cdk init`, the CLI will
+// automatically add enable these features by adding them to the generated
+// `cdk.json` file. In the next major release of the CDK, these feature flags
+// will be removed and will become the default behavior.
+// See https://github.com/aws/aws-cdk-rfcs/blob/master/text/0055-feature-flags.md
+// --------------------------------------------------------------------------------
 
 /**
  * If this is set, multiple stacks can use the same stack name (e.g. deployed to
@@ -39,4 +25,24 @@ export const ENABLE_STACK_NAME_DUPLICATES_CONTEXT = '@aws-cdk/core:enableStackNa
  *
  * Use `cdk diff --fail` to exit with 1 if there's a diff.
  */
-export const ENABLE_DIFF_NO_FAIL = 'aws-cdk:enableDiffNoFail';
+export const ENABLE_DIFF_NO_FAIL_CONTEXT = 'aws-cdk:enableDiffNoFail';
+/** @deprecated use `ENABLE_DIFF_NO_FAIL_CONTEXT` */
+export const ENABLE_DIFF_NO_FAIL = ENABLE_DIFF_NO_FAIL_CONTEXT;
+
+/**
+ * This map includes context keys and values for feature flags that enable
+ * capabilities "from the future", which we could not introduce as the default
+ * behavior due to backwards compatibility for existing projects.
+ *
+ * New projects generated through `cdk init` will include these flags in their
+ * generated `cdk.json` file.
+ *
+ * When we release the next major version of the CDK, we will flip the logic of
+ * these features and clean up the `cdk.json` generated by `cdk init`.
+ *
+ * Tests must cover the default (disabled) case and the future (enabled) case.
+ */
+export const FUTURE_FLAGS = {
+  [ENABLE_STACK_NAME_DUPLICATES_CONTEXT]: 'true',
+  [ENABLE_DIFF_NO_FAIL_CONTEXT]: 'true',
+};

packages/@aws-cdk/cx-api/lib/index.ts

@@ -12,6 +12,6 @@ export * from './assets';
 export * from './environment';
 export * from './metadata';
 export * from './features';
-export * from './future';
+export * from './app';
 
 export { CLOUD_ASSEMBLY_VERSION } from './versioning';