feat(core): recommend the use of weak references if no choice has been made (#38070)

### Reason for this change

For backward compatibility, the default value of the context parameter `@aws-cdk/core:defaultCrossStackReferences` is 'strong'. But we want to nudge users toward 'weak', so they can avoid deadly embraces. On the other hand, we also want to respect the user's choices and not annoy them unnecessarily. So, if they set the value to 'strong' or 'weak', explicitly, we don't want to emit a warning, assuming they know what they are doing.

### Description of changes

Set 'weak' as the recommended value for `@aws-cdk/core:defaultCrossStackReferences` context parameter. The CLI will automatically pick this up on synthesis and print:

> N feature flags are not configured. Run 'cdk flags --unstable=flags' to learn more.

And, by running `cdk flags`, the user can see the details, update the value etc.

In addition, to guide the user in doing the migration, emit the following warnings:

  - Flag unset: warns to set it to "both" and deploy everywhere, with a link to docs.
  - Flag set to "both": warns that after deploying everywhere, they should set it to "weak", with the same docs link.
  - Flag set to "strong" or "weak": no warning (user made an explicit choice). 
 

### Checklist
- [x] My code adheres to the [CONTRIBUTING GUIDE](https://github.com/aws/aws-cdk/blob/main/CONTRIBUTING.md) and [DESIGN GUIDELINES](https://github.com/aws/aws-cdk/blob/main/docs/DESIGN_GUIDELINES.md)

----

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

Author: otaviomacedo

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

@@ -49,6 +49,8 @@ function crossStackReferenceStrength(scope: IConstruct): ReferenceStrength | und
   );
 }
 
+const WEAK_REFS_WARNING_EMITTED = Symbol.for('@aws-cdk/core.WeakRefsWarningEmitted');
+
 const OVERRIDDEN_REFERENCE_SYMBOL = Symbol.for('@aws-cdk/core.CustomCoupledReference');
 
 /**
@@ -134,6 +136,27 @@ function resolveValue(consumer: Stack, reference: CfnReference, strengthOverride
     return reference;
   }
 
+  // Emit a once-per-app warning nudging users toward weak references
+  const appRoot = consumer.node.root;
+  if (!(appRoot as any)[WEAK_REFS_WARNING_EMITTED]) {
+    const contextStrength = crossStackReferenceStrength(consumer);
+    if (contextStrength === undefined) {
+      (appRoot as any)[WEAK_REFS_WARNING_EMITTED] = true;
+      Annotations.of(consumer).addWarningV2(
+        '@aws-cdk/core:crossStackReferencesDefaultStrong',
+        `No cross-stack-reference strength configured, defaulting to "strong". We recommend you set feature flag "${cxapi.DEFAULT_CROSS_STACK_REFERENCES}" to "both", then deploy everywhere, then set it to "weak". Alternatively, set it to "strong" explicitly to lock in the current producer-protecting behavior. ` +
+        '(See: https://github.com/aws/aws-cdk/blob/main/packages/aws-cdk-lib/README.md#reference-strength)',
+      );
+    } else if (contextStrength === 'both') {
+      (appRoot as any)[WEAK_REFS_WARNING_EMITTED] = true;
+      Annotations.of(consumer).addWarningV2(
+        '@aws-cdk/core:crossStackReferencesBothTransitional',
+        `Feature flag "${cxapi.DEFAULT_CROSS_STACK_REFERENCES}" currently set to "both". This is a transitory state. After you have finished deploying this application everywhere, set it to "weak". ` +
+        '(See: https://github.com/aws/aws-cdk/blob/main/packages/aws-cdk-lib/README.md#reference-strength)',
+      );
+    }
+  }
+
   // unsupported: stacks from different apps
   if (producer.node.root !== consumer.node.root) {
     throw new UnscopedValidationError(lit`CannotReferenceAcrossApps`, 'Cannot reference across apps. Consuming and producing stacks must be defined within the same CDK app.');

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

@@ -1,7 +1,7 @@
 import * as fs from 'fs';
 import { testDeprecated } from '@aws-cdk/cdk-build-tools';
 import { Construct, Node } from 'constructs';
-import { flattenMeta, toCloudFormation } from './util';
+import { flattenMeta, getWarnings, toCloudFormation } from './util';
 import * as cxapi from '../../cx-api';
 import { Fact, RegionInfo } from '../../region-info';
 import type { ITaggableV2 } from '../lib';
@@ -1074,6 +1074,82 @@ describe('stack', () => {
     expect(customResources2.length).toBeGreaterThan(0);
   });
 
+  test('emits a single warning per app when cross-stack reference flag is unset', () => {
+    // GIVEN - no context flag set, multiple consumer stacks
+    const app = new App();
+    const stack1 = new Stack(app, 'Stack1');
+    const resource1 = new CfnResource(stack1, 'Resource1', { type: 'AWS::S3::Bucket' });
+    const resource2 = new CfnResource(stack1, 'Resource2', { type: 'AWS::SNS::Topic' });
+    const stack2 = new Stack(app, 'Stack2');
+    const stack3 = new Stack(app, 'Stack3');
+
+    // WHEN - cross-stack references from multiple consumers
+    new CfnResource(stack2, 'Consumer1', {
+      type: 'AWS::S3::Bucket',
+      properties: { Prop1: resource1.getAtt('Arn') },
+    });
+    new CfnResource(stack3, 'Consumer2', {
+      type: 'AWS::S3::Bucket',
+      properties: { Prop2: resource2.getAtt('Arn') },
+    });
+
+    const assembly = app.synth();
+    const warnings = getWarnings(assembly);
+
+    // THEN - only one warning in the entire app
+    const relevantWarnings = warnings.filter(w =>
+      w.message.includes('@aws-cdk/core:crossStackReferencesDefaultStrong'),
+    );
+    expect(relevantWarnings).toHaveLength(1);
+  });
+
+  test('no warning when cross-stack reference flag is explicitly set', () => {
+    // GIVEN - context flag explicitly set to 'strong'
+    const app = new App({ context: { [cxapi.DEFAULT_CROSS_STACK_REFERENCES]: 'strong' } });
+    const stack1 = new Stack(app, 'Stack1');
+    const resource1 = new CfnResource(stack1, 'Resource1', { type: 'AWS::S3::Bucket' });
+    const stack2 = new Stack(app, 'Stack2');
+
+    // WHEN
+    new CfnResource(stack2, 'Consumer1', {
+      type: 'AWS::S3::Bucket',
+      properties: { Prop1: resource1.getAtt('Arn') },
+    });
+
+    const assembly = app.synth();
+    const warnings = getWarnings(assembly);
+
+    // THEN - no warning because the flag is explicitly set
+    const relevantWarnings = warnings.filter(w =>
+      w.message.includes('@aws-cdk/core:crossStackReferencesDefaultStrong'),
+    );
+    expect(relevantWarnings).toHaveLength(0);
+  });
+
+  test('emits transitional warning when cross-stack reference flag is set to both', () => {
+    // GIVEN - context flag set to 'both'
+    const app = new App({ context: { [cxapi.DEFAULT_CROSS_STACK_REFERENCES]: 'both' } });
+    const stack1 = new Stack(app, 'Stack1');
+    const resource1 = new CfnResource(stack1, 'Resource1', { type: 'AWS::S3::Bucket' });
+    const stack2 = new Stack(app, 'Stack2');
+
+    // WHEN
+    new CfnResource(stack2, 'Consumer1', {
+      type: 'AWS::S3::Bucket',
+      properties: { Prop1: resource1.getAtt('Arn') },
+    });
+
+    const assembly = app.synth();
+    const warnings = getWarnings(assembly);
+
+    // THEN - transitional warning telling user to move to 'weak'
+    const relevantWarnings = warnings.filter(w =>
+      w.message.includes('@aws-cdk/core:crossStackReferencesBothTransitional'),
+    );
+    expect(relevantWarnings).toHaveLength(1);
+    expect(relevantWarnings[0].path).toContain('Stack2');
+  });
+
   test('cross-region strong references use ExportWriter/ExportReader', () => {
     // GIVEN - strength is explicitly 'strong'
     const app = new App({ context: { [cxapi.DEFAULT_CROSS_STACK_REFERENCES]: 'strong' } });

packages/aws-cdk-lib/cx-api/FEATURE_FLAGS.md

@@ -201,6 +201,7 @@ The following json shows the current recommended set of flags, as `cdk init` wou
     "@aws-cdk/core:aspectPrioritiesMutating": true,
     "@aws-cdk/core:cfnIncludeRejectComplexResourceUpdateCreatePolicyIntrinsics": true,
     "@aws-cdk/core:checkSecretUsage": true,
+    "@aws-cdk/core:defaultCrossStackReferences": "weak",
     "@aws-cdk/core:enableAdditionalMetadataCollection": true,
     "@aws-cdk/core:enablePartitionLiterals": true,
     "@aws-cdk/core:explicitStackTags": true,
@@ -2497,7 +2498,7 @@ The flag is read from the **consumer** stack's context, not the producer's.
 | Since | Unset behaves like | Recommended value |
 | ----- | ----- | ----- |
 | (not in v1) |  |  |
-| 2.254.0 | `"strong"` | `"strong"` |
+| 2.254.0 | `"strong"` | `"weak"` |
 
 
 <!-- END details -->

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

@@ -1888,7 +1888,7 @@ export const FLAGS: Record<string, FlagInfo> = {
 
       **Migration from weak to strong**: set directly to \`"strong"\` (single deployment).`,
     introducedIn: { v2: '2.254.0' },
-    recommendedValue: 'strong',
+    recommendedValue: 'weak',
     unconfiguredBehavesLike: { v2: 'strong' },
   },
 };

packages/aws-cdk-lib/recommended-feature-flags.json

@@ -84,5 +84,6 @@
   "@aws-cdk/aws-cloudfront:defaultFunctionRuntimeV2_0": true,
   "@aws-cdk/aws-elasticloadbalancingv2:usePostQuantumTlsPolicy": true,
   "@aws-cdk/aws-batch:defaultToAL2023": true,
-  "@aws-cdk/core:annotationsInValidationReport": true
+  "@aws-cdk/core:annotationsInValidationReport": true,
+  "@aws-cdk/core:defaultCrossStackReferences": "weak"
 }