chore(aws-cdk-lib): strip out deprecated symbols from public API (#13815

)

The jsii build the 'aws-cdk-lib' module will now run with the 'strip
deprecated' flag enabled. This ensures that the public API of this
module will contain no deprecated symbols.

This is enabled by a new option configured in the module's
`package.json` and recognized by `cdk-build`.

Previous commits - ca391b5 and a872e67 - have removed the majority of
deprecated symbols from public APIs. A few remain that are removed as
part of this change.

----

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

packages/@aws-cdk/aws-lambda/lib/log-retention.ts

@@ -3,8 +3,6 @@ import { Construct } from 'constructs';
 
 /**
  * Retry options for all AWS API calls.
- *
- * @deprecated use `LogRetentionRetryOptions` from '@aws-cdk/aws-logs' instead
  */
 export interface LogRetentionRetryOptions extends logs.LogRetentionRetryOptions {
 }

packages/@aws-cdk/aws-lambda/lib/runtime.ts

@@ -209,16 +209,23 @@ export class Runtime {
   public readonly family?: RuntimeFamily;
 
   /**
-   * The bundling Docker image for this runtime.
+   * DEPRECATED
+   * @deprecated use `bundlingImage`
    */
   public readonly bundlingDockerImage: BundlingDockerImage;
 
+  /**
+   * The bundling Docker image for this runtime.
+   */
+  public readonly bundlingImage: DockerImage;
+
   constructor(name: string, family?: RuntimeFamily, props: LambdaRuntimeProps = { }) {
     this.name = name;
     this.supportsInlineCode = !!props.supportsInlineCode;
     this.family = family;
     const imageName = props.bundlingDockerImage ?? `amazon/aws-sam-cli-build-image-${name}`;
     this.bundlingDockerImage = DockerImage.fromRegistry(imageName);
+    this.bundlingImage = this.bundlingDockerImage;
     this.supportsCodeGuruProfiling = props.supportsCodeGuruProfiling ?? false;
 
     Runtime.ALL.push(this);

packages/@aws-cdk/core/lib/construct-compat.ts

@@ -412,11 +412,17 @@ export class ConstructNode {
     return this._actualNode.tryGetContext(key);
   }
 
+  /**
+   * DEPRECATED
+   * @deprecated use `metadataEntry`
+   */
+  public get metadata() { return this._actualNode.metadata as cxapi.MetadataEntry[]; }
+
   /**
    * An immutable array of metadata objects associated with this construct.
    * This can be used, for example, to implement support for deprecation notices, source mapping, etc.
    */
-  public get metadata() { return this._actualNode.metadata as cxapi.MetadataEntry[]; }
+  public get metadataEntry() { return this._actualNode.metadata; }
 
   /**
    * Adds a metadata entry to this construct.

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

@@ -424,6 +424,17 @@ export class Stack extends CoreConstruct implements ITaggable {
     return CloudFormationLang.toJSON(obj, space).toString();
   }
 
+  /**
+   * DEPRECATED
+   * @deprecated use `reportMissingContextKey()`
+   */
+  public reportMissingContext(report: cxapi.MissingContext) {
+    if (!Object.values(cxschema.ContextProvider).includes(report.provider as cxschema.ContextProvider)) {
+      throw new Error(`Unknown context provider requested in: ${JSON.stringify(report)}`);
+    }
+    this.reportMissingContextKey(report as cxschema.MissingContext);
+  }
+
   /**
    * Indicate that a context key was expected
    *
@@ -432,11 +443,8 @@ export class Stack extends CoreConstruct implements ITaggable {
    *
    * @param report The set of parameters needed to obtain the context
    */
-  public reportMissingContext(report: cxapi.MissingContext) {
-    if (!Object.values(cxschema.ContextProvider).includes(report.provider as cxschema.ContextProvider)) {
-      throw new Error(`Unknown context provider requested in: ${JSON.stringify(report)}`);
-    }
-    this._missingContext.push(report as cxschema.MissingContext);
+  public reportMissingContextKey(report: cxschema.MissingContext) {
+    this._missingContext.push(report);
   }
 
   /**

packages/aws-cdk-lib/package.json

@@ -33,7 +33,8 @@
   "cdk-build": {
     "eslint": {
       "disable": true
-    }
+    },
+    "stripDeprecated": true
   },
   "pkglint": {
     "exclude": [

tools/cdk-build-tools/lib/compile.ts

@@ -7,7 +7,7 @@ import { Timers } from './timer';
  */
 export async function compileCurrentPackage(options: CDKBuildOptions, timers: Timers, compilers: CompilerOverrides = {}): Promise<void> {
   const env = options.env;
-  await shell(packageCompiler(compilers), { timers, env });
+  await shell(packageCompiler(compilers, options), { timers, env });
 
   // Find files in bin/ that look like they should be executable, and make them so.
   const scripts = currentPackageJson().bin || {};

tools/cdk-build-tools/lib/package-info.ts

@@ -81,9 +81,13 @@ export interface CompilerOverrides {
 /**
  * Return the compiler for this package (either tsc or jsii)
  */
-export function packageCompiler(compilers: CompilerOverrides): string[] {
+export function packageCompiler(compilers: CompilerOverrides, options?: CDKBuildOptions): string[] {
   if (isJsii()) {
-    return [compilers.jsii || require.resolve('jsii/bin/jsii'), '--silence-warnings=reserved-word'];
+    const args = ['--silence-warnings=reserved-word'];
+    if (options?.stripDeprecated) {
+      args.push('--strip-deprecated');
+    }
+    return [compilers.jsii || require.resolve('jsii/bin/jsii'), ...args];
   } else {
     return [compilers.tsc || require.resolve('typescript/bin/tsc'), '--build'];
   }
@@ -148,6 +152,12 @@ export interface CDKBuildOptions {
    * Environment variables to be passed to 'cdk-build' and all of its child processes.
    */
   env?: NodeJS.ProcessEnv;
+
+  /**
+   * Whether deprecated symbols should be stripped from the jsii assembly and typescript declaration files.
+   * @see https://aws.github.io/jsii/user-guides/lib-author/toolchain/jsii/#-strip-deprecated
+   */
+  stripDeprecated?: boolean;
 }
 
 /**