chore: add new interfaces for Assets (aws#12700)

In V2, we want to get rid of the `@aws-cdk/assets` module, as it's considered deprecated in V1.
Unfortunately, the module contains an interface, `CopyOptions`, that is used, through interface inheritance, in the public API of many stable CDK modules like ECS, Lambda, ECR, CodeBuild, etc.

While we have a `CopyOptions` interface in `@aws-cdk/core`, it unfortunately shares the same name, `follow`, with the property in the "old" `CopyOptions`. But the two different `follow` properties have different types.

For that reason, if we're going to remove the "old" `CopyOptions` using JSII's "strip deprecated" option, we can't use the "new" `CopyOptions` in the inheritance hierarchy alongside the "old" `CopyOptions`, as the two definitions of `follow` would conflict.

Because of that, create a new `FileCopyOptions` interface which renames the `follow` property to `followSymlinks`. Also add a `FileFingerprintOptions` interface that does a similar trick to the `FingerprintOptions` interface (which extends `CopyOptions`), which is used in the public API of modules that use Docker assets.

Also extract a few module-private interfaces to avoid duplication of properties between all of these interfaces.

After this change, an interface from one of the non-deprecated assets libraries (S3 or ECR) using `FileOptions` from `@aws-cdk/assets` will look like this:

```ts
// this is in @aws-cdk/aws-s3-assets
export interface AssetOptions extends assets.CopyOptions, cdk.FileCopyOptions, cdk.AssetOptions {
  // ...
```

Then, when we enable stripping the deprecated elements using JSII on the V2 branch, this will be turned to:

```ts
export interface AssetOptions extends cdk.FileCopyOptions, cdk.AssetOptions {
  // ...
```

Allowing us to deprecate the `@aws-cdk/assets` module, and not ship it with `aws-cdk-lib`.

----

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

packages/@aws-cdk/assets/lib/fs/options.ts

@@ -10,6 +10,7 @@ export interface CopyOptions {
    * A strategy for how to handle symlinks.
    *
    * @default Never
+   * @deprecated use `followSymlinks` instead
    */
   readonly follow?: FollowMode;
 

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

@@ -2,14 +2,16 @@ import * as fs from 'fs';
 import * as path from 'path';
 import * as assets from '@aws-cdk/assets';
 import * as ecr from '@aws-cdk/aws-ecr';
-import { Annotations, Construct as CoreConstruct, FeatureFlags, IgnoreMode, Stack, Token } from '@aws-cdk/core';
+import {
+  Annotations, AssetStaging, Construct as CoreConstruct, FeatureFlags, FileFingerprintOptions, IgnoreMode, Stack, SymlinkFollowMode, Token,
+} from '@aws-cdk/core';
 import * as cxapi from '@aws-cdk/cx-api';
 import { Construct } from 'constructs';
 
 /**
  * Options for DockerImageAsset
  */
-export interface DockerImageAssetOptions extends assets.FingerprintOptions {
+export interface DockerImageAssetOptions extends assets.FingerprintOptions, FileFingerprintOptions {
   /**
    * ECR repository name
    *
@@ -137,8 +139,9 @@ export class DockerImageAsset extends CoreConstruct implements assets.IAsset {
     // deletion of the ECR repository the app used).
     extraHash.version = '1.21.0';
 
-    const staging = new assets.Staging(this, 'Staging', {
+    const staging = new AssetStaging(this, 'Staging', {
       ...props,
+      follow: props.followSymlinks ?? toSymlinkFollow(props.follow),
       exclude,
       ignoreMode,
       sourcePath: dir,
@@ -181,3 +184,13 @@ function validateBuildArgs(buildArgs?: { [key: string]: string }) {
     }
   }
 }
+
+function toSymlinkFollow(follow?: assets.FollowMode): SymlinkFollowMode | undefined {
+  switch (follow) {
+    case undefined: return undefined;
+    case assets.FollowMode.NEVER: return SymlinkFollowMode.NEVER;
+    case assets.FollowMode.ALWAYS: return SymlinkFollowMode.ALWAYS;
+    case assets.FollowMode.BLOCK_EXTERNAL: return SymlinkFollowMode.BLOCK_EXTERNAL;
+    case assets.FollowMode.EXTERNAL: return SymlinkFollowMode.EXTERNAL;
+  }
+}

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

@@ -15,7 +15,7 @@ import { Construct as CoreConstruct } from '@aws-cdk/core';
 
 const ARCHIVE_EXTENSIONS = ['.zip', '.jar'];
 
-export interface AssetOptions extends assets.CopyOptions, cdk.AssetOptions {
+export interface AssetOptions extends assets.CopyOptions, cdk.FileCopyOptions, cdk.AssetOptions {
   /**
    * A list of principals that should be able to read this asset from S3.
    * You can use `asset.grantRead(principal)` to grant read permissions later.
@@ -128,7 +128,7 @@ export class Asset extends CoreConstruct implements cdk.IAsset {
     const staging = new cdk.AssetStaging(this, 'Stage', {
       ...props,
       sourcePath: path.resolve(props.path),
-      follow: toSymlinkFollow(props.follow),
+      follow: props.followSymlinks ?? toSymlinkFollow(props.follow),
       assetHash: props.assetHash ?? props.sourceHash,
     });
 

packages/@aws-cdk/core/lib/fs/options.ts

@@ -56,19 +56,9 @@ export enum IgnoreMode {
    * context flag is set.
    */
   DOCKER = 'docker'
-};
-
-/**
- * Obtains applied when copying directories into the staging location.
- */
-export interface CopyOptions {
-  /**
-   * A strategy for how to handle symlinks.
-   *
-   * @default SymlinkFollowMode.NEVER
-   */
-  readonly follow?: SymlinkFollowMode;
+}
 
+interface FileOptions {
   /**
    * Glob patterns to exclude from the copy.
    *
@@ -85,9 +75,30 @@ export interface CopyOptions {
 }
 
 /**
- * Options related to calculating source hash.
+ * Options applied when copying directories
+ */
+export interface CopyOptions extends FileOptions {
+  /**
+   * A strategy for how to handle symlinks.
+   *
+   * @default SymlinkFollowMode.NEVER
+   */
+  readonly follow?: SymlinkFollowMode;
+}
+
+/**
+ * Options applied when copying directories into the staging location.
  */
-export interface FingerprintOptions extends CopyOptions {
+export interface FileCopyOptions extends FileOptions {
+  /**
+   * A strategy for how to handle symlinks.
+   *
+   * @default SymlinkFollowMode.NEVER
+   */
+  readonly followSymlinks?: SymlinkFollowMode;
+}
+
+interface ExtraHashOptions {
   /**
    * Extra information to encode into the fingerprint (e.g. build instructions
    * and other inputs)
@@ -96,3 +107,15 @@ export interface FingerprintOptions extends CopyOptions {
    */
   readonly extraHash?: string;
 }
+
+/**
+ * Options related to calculating source hash.
+ */
+export interface FingerprintOptions extends CopyOptions, ExtraHashOptions {
+}
+
+/**
+ * Options related to calculating source hash.
+ */
+export interface FileFingerprintOptions extends FileCopyOptions, ExtraHashOptions {
+}