fix: move reference interfaces to their own submodules

packages/aws-cdk-lib/index.ts

@@ -296,6 +296,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/package.json

@@ -516,6 +516,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

@@ -1,13 +1,15 @@
 import * as path from 'node:path';
 import * as fs from 'fs-extra';
 import { generateAll, ModuleMap } from './codegen';
-import submodulesGen from './submodules';
+import generateServiceSubmoduleFiles from './submodules';
 
 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);
@@ -18,17 +20,22 @@ 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 writeScopeMap(generated);
-  await submodulesGen(generated, awsCdkLibDir);
+
+  for (const nss of NON_SERVICE_SUBMODULES) {
+    delete generated[nss];
+  }
+  await generateServiceSubmoduleFiles(generated, awsCdkLibDir);
 }
 
+/**
+ * Generates `scope-map.json`, which maps every `aws-cdk-lib` submodule to the AWS service prefix in that submodule
+ */
 async function writeScopeMap(modules: ModuleMap) {
   const newScopeMap = Object.entries(modules)
     .sort(([modA], [modB]) => modA.localeCompare(modB))
@@ -41,6 +48,12 @@ async function writeScopeMap(modules: ModuleMap) {
   await fs.writeJson(scopeMapPath, newScopeMap, { spaces: 2 });
 }
 
+/**
+ * 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: ModuleMap) {
   const pkgJson = await fs.readJson(pkgJsonPath);
 

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

@@ -1338,5 +1338,6 @@
     {
       "namespace": "AWS::CloudFormation"
     }
-  ]
+  ],
+  "interfaces": []
 }

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

@@ -4,12 +4,13 @@ import * as fs from 'fs-extra';
 import cloudformationInclude from './cloudformation-include';
 import { ModuleMap, ModuleMapEntry } from '../codegen';
 
-export default async function submodulesGen(modules: 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: 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);
   }