fix: move reference interfaces to their own submodules (#35971)

The introduction of reference interfaces (`IBucketRef`, `IRoleRef`, etc) led to an increased potential for cyclic references between service modules. Cyclic references are a problem in both Python and Go, and prevents us from taking this idea as far as we want to go.

In this PR, we introduce a new submodule `aws-cdk-lib.interfaces` where all reference interfaces will live. Because some services have resources with the same name, there are submodules inside the `interfaces` submodule, so actual interface references will look like `aws-cdk-lib.interfaces.aws_s3.IBucketRef`.

Because moving the canonical location for these interfaces will be breaking, we leave behind aliases for them in the old location, so TypeScript code can still do `import { IBucketRef } from 'aws-cdk-lib/aws-s3';`. Unfortunately we cannot do the same for other languages because (a) jsii doesn't understand type aliases yet and (b) even if it did, type aliases can not be rendered appropriately in either Java or C#. This means that this change might be backwards breaking for some consumers that implement L2 interfaces in jsii client languages, but we are assuming that most people doing this would be using TypeScript which will remain unaffected. It is unfortunate that we have to do this, but we have painted ourselves into a corner that we otherwise cannot get out of.

## Implementation notes

This PR contains heavy refactoring in `spec2cdk` around determining file paths and import paths. We used to have to pass import paths into every service module that we code generated; but if we determine the file names ahead of time, we can also just use `path.posix.relative()` to determine the right import location, which is much easier to use.

----

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

Author: rix0rrr

allowed-breaking-changes.txt

@@ -26,9 +26,9 @@
     "fs-extra": "^9.1.0",
     "graceful-fs": "^4.2.11",
     "jest-junit": "^13.2.0",
-    "jsii-diff": "1.118.0",
-    "jsii-pacmak": "1.118.0",
-    "jsii-reflect": "1.118.0",
+    "jsii-diff": "1.119.0",
+    "jsii-pacmak": "1.119.0",
+    "jsii-reflect": "1.119.0",
     "lerna": "^8.2.4",
     "nx": "^20",
     "semver": "^7.7.2",

package.json

@@ -1,5 +1,5 @@
 *.d.ts
-*.generated.ts
+*.generated.*
 *.js
 *.js.map
 *.snk

packages/aws-cdk-lib/.gitignore

@@ -2,6 +2,7 @@ import { Dependable, IConstruct, IDependable } from 'constructs';
 import { PolicyStatement } from './policy-statement';
 import { IGrantable, IPrincipal } from './principals';
 import * as cdk from '../../core';
+import { IEnvironmentAware } from '../../interfaces/environment-aware';
 
 /**
  * Basic options for a grant operation
@@ -421,7 +422,7 @@ interface GrantProps {
 /**
  * A resource with a resource policy that can be added to
  */
-export interface IResourceWithPolicyV2 extends cdk.IEnvironmentAware {
+export interface IResourceWithPolicyV2 extends IEnvironmentAware {
   /**
    * Add a statement to the resource's resource policy
    */

packages/aws-cdk-lib/aws-iam/lib/grant.ts

@@ -8,7 +8,7 @@ import { FieldUtils } from '../fields';
 import { noEmptyObject } from '../private/util';
 import { StateGraph } from '../state-graph';
 import { IStepFunctionsTask, StepFunctionsTaskConfig } from '../step-functions-task';
-import { CatchProps, IChainable, INextable, RetryProps } from '../types';
+import { CatchProps, IChainable, INextable, QueryLanguage, RetryProps } from '../types';
 
 /**
  * Props that are common to all tasks
@@ -162,7 +162,7 @@ export class Task extends State implements INextable {
   /**
    * Return the Amazon States Language object for this state
    */
-  public toStateJson(): object {
+  public toStateJson(_?: QueryLanguage): object {
     return {
       ...this.renderNextEnd(),
       ...this.renderRetryCatch(),

packages/aws-cdk-lib/aws-stepfunctions/lib/states/task.ts

@@ -31,46 +31,5 @@ export interface Environment {
   readonly region?: string;
 }
 
-/**
- * Represents the environment a given resource lives in.
- *
- * Used as the return value for the `IEnvironmentAware.env` property.
- */
-export interface ResourceEnvironment {
-  /**
-   * The AWS Account ID that this resource belongs to.
-   *
-   * Since this can be a Token (for example, when the account is
-   * CloudFormation's `AWS::AccountId` intrinsic), make sure to use
-   * `Token.compareStrings()` instead of comparing the values with direct
-   * string equality.
-   */
-  readonly account: string;
-
-  /**
-   * The AWS Region that this resource belongs to.
-   *
-   * Since this can be a Token (for example, when the region is CloudFormation's
-   * `AWS::Region` intrinsic), make sure to use `Token.compareStrings()` instead
-   * of comparing the values with direct string equality.
-   */
-  readonly region: string;
-}
-
-/**
- * Used to indicate that a particular construct has an resource environment
- */
-export interface IEnvironmentAware {
-  /**
-   * The environment this resource belongs to.
-   *
-   * For resources that are created and managed in a Stack (those created by
-   * creating new class instances like `new Role()`, `new Bucket()`, etc.), this
-   * is always the same as the environment of the stack they belong to.
-   *
-   * For referenced resources (those obtained from referencing methods like
-   * `Role.fromRoleArn()`, `Bucket.fromBucketName()`, etc.), they might be
-   * different than the stack they were imported into.
-   */
-  readonly env: ResourceEnvironment;
-}
+// For backwards compatibility with TypeScript users
+export type { IEnvironmentAware, ResourceEnvironment } from '../../interfaces/environment-aware';

packages/aws-cdk-lib/core/lib/environment.ts

@@ -1,7 +1,6 @@
 import { ArnComponents, ArnFormat } from './arn';
 import { CfnResource } from './cfn-resource';
 import { RESOURCE_SYMBOL } from './constants';
-import { IEnvironmentAware, ResourceEnvironment } from './environment';
 import { ValidationError } from './errors';
 import { IStringProducer, Lazy } from './lazy';
 import { generatePhysicalName, isGeneratedWhenNeededMarker } from './private/physical-name-generator';
@@ -10,6 +9,7 @@ import { RemovalPolicy } from './removal-policy';
 import { IResolveContext } from './resolvable';
 import { Stack } from './stack';
 import { Token, Tokenization } from './token';
+import { IEnvironmentAware, ResourceEnvironment } from '../../interfaces/environment-aware';
 
 // v2 - leave this as a separate section so it reduces merge conflicts when compat is removed
 // eslint-disable-next-line import/order

packages/aws-cdk-lib/core/lib/resource.ts

@@ -298,6 +298,7 @@ export * as cloud_assembly_schema from './cloud-assembly-schema';
 export * as cloudformation_include from './cloudformation-include';
 export * as custom_resources from './custom-resources';
 export * as cx_api from './cx-api';
+export * as interfaces from './interfaces';
 export * as lambda_layer_awscli from './lambda-layer-awscli';
 export * as lambda_layer_node_proxy_agent from './lambda-layer-node-proxy-agent';
 export * as pipelines from './pipelines';

packages/aws-cdk-lib/index.ts

@@ -0,0 +1,13 @@
+{
+  "targets": {
+    "java": {
+      "package": "software.amazon.awscdk.interfaces"
+    },
+    "dotnet": {
+      "namespace": "Amazon.CDK.Interfaces"
+    },
+    "python": {
+      "module": "aws_cdk.interfaces"
+    }
+  }
+}

packages/aws-cdk-lib/interfaces/.jsiirc.json

@@ -0,0 +1,33 @@
+CDK Resource Interfaces
+=======================
+
+This module contains resource interfaces for all AWS service resources.
+
+These are interfaces that look like this:
+
+```
+/**
+ * Indicates that this resource can be referenced as a Bucket.
+ */
+interface IBucketRef {
+  /**
+   * A reference to a Bucket resource.
+   */
+  readonly bucketRef: BucketReference;
+}
+
+interface BucketReference {
+  /**
+   * The BucketName of the Bucket resource.
+   */
+  readonly bucketName: string;
+
+  /**
+   * The ARN of the Bucket resource.
+   */
+  readonly bucketArn: string;
+}
+```
+
+These are in a separate submodule so that they can be referenced from all other
+service submodules without introducing cyclic dependencies between them.