fix: move reference interfaces to their own submodules

package.json

@@ -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",

packages/aws-cdk-lib/.gitignore

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

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

@@ -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-stepfunctions/lib/states/task.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/core/lib/environment.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/resource.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/index.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/interfaces/.jsiirc.json

@@ -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/README.md

@@ -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.

packages/aws-cdk-lib/interfaces/environment-aware.ts

@@ -0,0 +1,43 @@
+/**
+ * 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;
+}
+
+/**
+ * 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;
+}

packages/aws-cdk-lib/interfaces/index.ts

@@ -0,0 +1,2 @@
+export * from './environment-aware';
+export * from './index.generated';

packages/aws-cdk-lib/package.json

@@ -518,6 +518,7 @@
     "./custom-resources": "./custom-resources/index.js",
     "./custom-resources/lib/helpers-internal": "./custom-resources/lib/helpers-internal/index.js",
     "./cx-api": "./cx-api/index.js",
+    "./interfaces": "./interfaces/index.js",
     "./lambda-layer-awscli": "./lambda-layer-awscli/index.js",
     "./lambda-layer-kubectl": "./lambda-layer-kubectl/index.js",
     "./lambda-layer-node-proxy-agent": "./lambda-layer-node-proxy-agent/index.js",

packages/aws-cdk-lib/scripts/gen.ts

@@ -2,13 +2,16 @@ import * as path from 'node:path';
 import { naming, topo } from '@aws-cdk/spec2cdk';
 import { generateAll } from '@aws-cdk/spec2cdk/lib/cfn2ts';
 import * as fs from 'fs-extra';
-import submodulesGen from './submodules';
+import generateServiceSubmoduleFiles from './submodules';
+import writeCloudFormationIncludeMapping from './submodules/cloudformation-include';
 
 const awsCdkLibDir = path.join(__dirname, '..');
 const pkgJsonPath = path.join(awsCdkLibDir, 'package.json');
 const topLevelIndexFilePath = path.join(awsCdkLibDir, 'index.ts');
 const scopeMapPath = path.join(__dirname, 'scope-map.json');
 
+const NON_SERVICE_SUBMODULES = ['core', 'interfaces'];
+
 main().catch(e => {
   // eslint-disable-next-line no-console
   console.error(e);
@@ -19,17 +22,26 @@ async function main() {
   // Generate all L1s based on config in scope-map.json
 
   const generated = (await generateAll(awsCdkLibDir, {
-    coreImport: '../../core',
-    cloudwatchImport: '../../aws-cloudwatch',
     skippedServices: [],
     scopeMapPath,
   }));
 
   await updateExportsAndEntryPoints(generated);
   await topo.writeModuleMap(generated);
-  await submodulesGen(generated, awsCdkLibDir);
+  await writeCloudFormationIncludeMapping(generated, awsCdkLibDir);
+
+  for (const nss of NON_SERVICE_SUBMODULES) {
+    delete generated[nss];
+  }
+  await generateServiceSubmoduleFiles(generated, awsCdkLibDir);
 }
 
+/**
+ * Make every module in the module map visible
+ *
+ * Read `index.ts` and `package.json#exports`, and add exports for every
+ * submodule that's not in there yet.
+ */
 async function updateExportsAndEntryPoints(modules: topo.ModuleMap) {
   const pkgJson = await fs.readJson(pkgJsonPath);
 

packages/aws-cdk-lib/scripts/scope-map.json

@@ -1934,5 +1934,8 @@
         "namespace": "AWS::CloudFormation"
       }
     ]
+  },
+  "interfaces": {
+    "scopes": []
   }
 }

packages/aws-cdk-lib/scripts/submodules/cloudformation-include.ts

@@ -3,11 +3,11 @@ import * as path from 'node:path';
 import { topo } from '@aws-cdk/spec2cdk';
 import * as fs from 'fs-extra';
 
-export default async function cloudformationInclude(moduleMap: topo.ModuleMap, outPath: string) {
+export default async function writeCloudFormationIncludeMapping(moduleMap: topo.ModuleMap, outPath: string) {
   const classMap: { [cfnType: string]: string } = {};
   Object.entries(moduleMap).forEach(([moduleName, { resources }]) => {
     const modulePath = `aws-cdk-lib/${moduleName}`;
-    Object.entries(resources).forEach(([resourceName, resourceClassName]) => {
+    Object.entries(resources ?? {}).forEach(([resourceName, resourceClassName]) => {
       classMap[resourceName] = `${modulePath}.${resourceClassName}`;
     });
   });

packages/aws-cdk-lib/scripts/submodules/index.ts

@@ -1,21 +1,19 @@
 import * as path from 'node:path';
-import { createLibraryReadme } from '@aws-cdk/pkglint';
+import { createLibraryReadme, ModuleDefinition } from '@aws-cdk/pkglint';
 import { topo } from '@aws-cdk/spec2cdk';
 import * as fs from 'fs-extra';
-import cloudformationInclude from './cloudformation-include';
 
-export default async function submodulesGen(modules: topo.ModuleMap, outPath: string) {
+/**
+ * Make sure that a number of expected files exist for every service submodule
+ *
+ * Non-service submodules should not be passed to this function.
+ */
+export default async function generateServiceSubmoduleFiles(modules: topo.ModuleMap, outPath: string) {
   for (const submodule of Object.values(modules)) {
-    if (submodule.name === 'core') {
-      continue;
-    }
-
     const submodulePath = path.join(outPath, submodule.name);
     await ensureSubmodule(submodule, submodulePath);
+    await ensureInterfaceSubmoduleJsiiJsonRc(submodule, path.join(outPath, 'interfaces'));
   }
-
-  // Do specific code gen for certain submodules
-  await cloudformationInclude(modules, outPath);
 }
 
 async function ensureSubmodule(submodule: topo.ModuleMapEntry, modulePath: string) {
@@ -71,3 +69,43 @@ async function ensureSubmodule(submodule: topo.ModuleMapEntry, modulePath: strin
   };
   await fs.writeJson(path.join(modulePath, '.jsiirc.json'), jsiirc, { spaces: 2 });
 }
+
+/**
+ * Make a jsiirc file for every service-specific interfaces submodule
+ *
+ * Do that by taking the namespaces of the parent `interfaces` submodule and concatenating the last part
+ * of the names corresponding services namespace.
+ */
+async function ensureInterfaceSubmoduleJsiiJsonRc(submodule: topo.ModuleMapEntry, interfacesModulePath: string) {
+  if (!submodule.definition) {
+    throw new Error(`Cannot infer path or namespace for submodule named "${submodule.name}".`);
+  }
+
+  const interfacesModuleJsiiRcPath = path.join(interfacesModulePath, '.jsiirc.json');
+  const interfacesModuleJsiiRc = JSON.parse(await fs.readFile(interfacesModuleJsiiRcPath, 'utf-8'));
+
+  const jsiiRcPath = path.join(interfacesModulePath, 'generated', `${submodule.name}-interfaces.generated.jsiirc.json`);
+
+  const jsiirc = {
+    targets: {
+      ...combineLanguageNamespace('java', 'package', 'javaPackage'),
+      ...combineLanguageNamespace('dotnet', 'namespace', 'dotnetPackage'),
+      ...combineLanguageNamespace('python', 'module', 'pythonModuleName'),
+      // No Go...
+    },
+  };
+  await fs.writeJson(jsiiRcPath, jsiirc, { spaces: 2 });
+
+  function combineLanguageNamespace(language: string, whatName: string, k: keyof ModuleDefinition) {
+    const ns = `${interfacesModuleJsiiRc.targets[language][whatName]}.${lastPart(submodule.definition?.[k] ?? 'undefined')}`;
+    if (ns.includes('undefined')) {
+      throw new Error(`Could not build child namespace for language ${language} from ${JSON.stringify(interfacesModuleJsiiRc.targets[language])} and ${k} from ${JSON.stringify(submodule.definition)}`);
+    }
+
+    return { [language]: { [whatName]: ns } };
+  }
+}
+
+function lastPart(x: string): string {
+  return x.split('.').slice(-1)[0];
+}

tools/@aws-cdk/cdk-build-tools/package.json

@@ -63,8 +63,8 @@
     "jest-junit": "^13.2.0",
     "jsii": "~5.9.13",
     "jsii-rosetta": "~5.9.9",
-    "jsii-pacmak": "1.118.0",
-    "jsii-reflect": "1.118.0",
+    "jsii-pacmak": "1.119.0",
+    "jsii-reflect": "1.119.0",
     "markdownlint-cli": "^0.45.0",
     "nyc": "^15.1.0",
     "semver": "^7.7.2",