feat: "stack relative exports" flag (#9604)

Previously, CloudFormation `Exports` generated by cross-stack references
were named after a static part of the construct tree (everything after
the 2nd component). This must have been left over from the days
when the construct tree structure was strictly

```
App -> Stack -> Other constructs...
```

And so it would skip the `App` and `Stack` levels, leaving a construct
path that was relative to the containing stack.

For a while, `Stacks` have been able to occur at multiple levels, but
this code was never updated. The result is that this now produces
considerable breakage if stacks are moved around (motivating example:
moving `Stack`s into `Stages` for the benefit of deploying them
using CDK Pipelines).

This behavior cannot be fixed without breaking most CDK applications
that currently exist, so it is being introduced as a feature flag,
which should be enabled on new applications and made default in V2,
but for now is opt-in and to be enabled by people migrating their
existing apps onto CDK Pipelines.

The new behavior is to explicitly build the export name relative to the
containing Stack, as opposed to relative to construct tree level 2.

> Note that giving the new containing Stage the construct ID `"Default"` 
> is not good enough, as the new construct tree leveling looks like:
>
> ```
> App -> Stage     -> Stack    -> [Construct IDs]
>        "Default" /  "Stack"  /  "IDs/I/care/about"
>                     ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ current algo will use these
>                                 ^^^^^^^^^^^^^^^^^ I actually want these
> ```
> i.e., `"Default"` does not occur at a level where it will be properly ignored.


----

*By submitting this pull request, I confirm that my contribution is made under the terms of the Apache-2.0 license*

Author: rix0rrr

packages/@aws-cdk/core/lib/private/refs.ts

@@ -1,6 +1,8 @@
 // ----------------------------------------------------
 // CROSS REFERENCES
 // ----------------------------------------------------
+import * as cxapi from '@aws-cdk/cx-api';
+
 import { CfnElement } from '../cfn-element';
 import { CfnOutput } from '../cfn-output';
 import { CfnParameter } from '../cfn-parameter';
@@ -199,8 +201,15 @@ function getCreateExportsScope(stack: Stack) {
 }
 
 function generateExportName(stackExports: Construct, id: string) {
+  const stackRelativeExports = stackExports.construct.tryGetContext(cxapi.STACK_RELATIVE_EXPORTS_CONTEXT);
   const stack = Stack.of(stackExports);
-  const components = [...stackExports.construct.scopes.slice(2).map(c => c.construct.id), id];
+
+  const components = [
+    ...stackExports.construct.scopes
+      .slice(stackRelativeExports ? stack.construct.scopes.length : 2)
+      .map(c => c.construct.id),
+    id,
+  ];
   const prefix = stack.stackName ? stack.stackName + ':' : '';
   const exportName = prefix + makeUniqueId(components);
   return exportName;

packages/@aws-cdk/core/test/test.stack.ts

@@ -249,6 +249,43 @@ export = {
     test.done();
   },
 
+  'Cross-stack reference export names are relative to the stack (when the flag is set)'(test: Test) {
+    // GIVEN
+    const app = new App({
+      context: {
+        '@aws-cdk/core:stackRelativeExports': 'true',
+      },
+    });
+    const indifferentScope = new Construct(app, 'ExtraScope');
+
+    const stack1 = new Stack(indifferentScope, 'Stack1', {
+      stackName: 'Stack1',
+    });
+    const resource1 = new CfnResource(stack1, 'Resource', { type: 'BLA' });
+    const stack2 = new Stack(indifferentScope, 'Stack2');
+
+    // WHEN - used in another resource
+    new CfnResource(stack2, 'SomeResource', { type: 'AWS::Some::Resource', properties: {
+      someProperty: new Intrinsic(resource1.ref),
+    }});
+
+    // THEN
+    const assembly = app.synth();
+    const template2 = assembly.getStackByName(stack2.stackName).template;
+
+    test.deepEqual(template2, {
+      Resources: {
+        SomeResource: {
+          Type: 'AWS::Some::Resource',
+          Properties: {
+            someProperty: { 'Fn::ImportValue': 'Stack1:ExportsOutputRefResource1D5D905A' },
+          },
+        },
+      },
+    });
+    test.done();
+  },
+
   'cross-stack references in lazy tokens work'(test: Test) {
     // GIVEN
     const app = new App();

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

@@ -34,6 +34,16 @@ export const ENABLE_DIFF_NO_FAIL = ENABLE_DIFF_NO_FAIL_CONTEXT;
  */
 export const NEW_STYLE_STACK_SYNTHESIS_CONTEXT = '@aws-cdk/core:newStyleStackSynthesis';
 
+/**
+ * Name exports based on the construct paths relative to the stack, rather than the global construct path
+ *
+ * Combined with the stack name this relative construct path is good enough to
+ * ensure uniqueness, and makes the export names robust against refactoring
+ * the location of the stack in the construct tree (specifically, moving the Stack
+ * into a Stage).
+ */
+export const STACK_RELATIVE_EXPORTS_CONTEXT = '@aws-cdk/core:stackRelativeExports';
+
 /**
  * This map includes context keys and values for feature flags that enable
  * capabilities "from the future", which we could not introduce as the default
@@ -50,6 +60,7 @@ export const NEW_STYLE_STACK_SYNTHESIS_CONTEXT = '@aws-cdk/core:newStyleStackSyn
 export const FUTURE_FLAGS = {
   [ENABLE_STACK_NAME_DUPLICATES_CONTEXT]: 'true',
   [ENABLE_DIFF_NO_FAIL_CONTEXT]: 'true',
+  [STACK_RELATIVE_EXPORTS_CONTEXT]: 'true',
 
   // We will advertise this flag when the feature is complete
   // [NEW_STYLE_STACK_SYNTHESIS]: 'true',