explain and proper exports

packages/aws-cdk/lib/index.ts

@@ -1,3 +1,6 @@
+export * from './api';
 export { cli, exec } from './cli';
+
+// Re-export the legacy exports under a name
+// We import and re-export them from the index.ts file to generate a single bundle of all code and dependencies
 export * as legacy from './legacy-exports-source';
-export * as legacyLogging from './legacy-logging-source';

packages/aws-cdk/lib/legacy-exports-source.ts

@@ -1,13 +1,18 @@
+// This is a barrel export file, of all known symbols that are imported by users from the `aws-cdk` package.
+// Importing these symbols was never officially supported, but here we are.
+// In order to preserver backwards-compatibly for these users, we re-export and preserve them as explicit subpath exports.
+// See https://github.com/aws/aws-cdk/pull/33021 for more information.
+
+// Note: All type exports are in `legacy-exports.ts`
 export * from './legacy-logging-source';
-export { Obj, deepClone, flatten, ifDefined, isArray, isEmpty, numberFromBool, partition } from './util';
+export { deepClone, flatten, ifDefined, isArray, isEmpty, numberFromBool, partition } from './util';
 export { deployStack } from './api/deploy-stack';
 export { cli, exec } from './cli';
-export { Account, SdkProvider } from './api/aws-auth';
-export { ContextProviderPlugin, PluginHost } from './api/plugin';
+export { SdkProvider } from './api/aws-auth';
+export { PluginHost } from './api/plugin';
 export { contentHash } from './util/content-hash';
 export { Command, Configuration, PROJECT_CONTEXT, Settings } from './settings';
-export { BootstrapEnvironmentOptions, BootstrapSource, Bootstrapper } from './api/bootstrap';
-export { StackSelector } from './api/cxapp/cloud-assembly';
+export { Bootstrapper } from './api/bootstrap';
 export { CloudExecutable } from './api/cxapp/cloud-executable';
 export { execProgram } from './api/cxapp/exec';
 export { RequireApproval } from './diff';
@@ -22,8 +27,6 @@ export { rootDir } from './util/directories';
 export { latestVersionIfHigher, versionNumber } from './version';
 export { availableInitTemplates } from './init';
 export { cached } from './api/aws-auth/cached';
-export { DeployStackResult } from './api/deploy-stack';
 export { CfnEvaluationException } from './api/evaluate-cloudformation-template';
 export { CredentialPlugins } from './api/aws-auth/credential-plugins';
 export { AwsCliCompatible } from './api/aws-auth/awscli-compatible';
-export { Component } from './notices';

packages/aws-cdk/lib/legacy-exports.ts

@@ -1 +1,91 @@
-export { legacy as default } from './index';
+// This is the legacy symbols export file.
+// We export a number of known symbols that are imported by users from the `aws-cdk` package.
+// Importing these symbols was never officially supported, but here we are.
+// See https://github.com/aws/aws-cdk/pull/33021 for more information.
+//
+// In package.json, section `exports`, we declare all known subpaths as an explicit subpath export resolving to this file.
+// This way existing unsanctioned imports don't break immediately.
+//
+// When attempting to import a subpath other than the explicitly exported ones, the following runtime error will be thrown:
+// Error [ERR_PACKAGE_PATH_NOT_EXPORTED]: Package subpath './lib/private/subpath' is not defined by "exports" in aws-cdk/package.json
+//
+// TypeScript can warn users about the not-exported subpath at compile time. However it requires a reasonably modern tsconfig.json.
+// Specifically `moduleResolution` must be set to either "node16" or "nodenext".
+
+// We need to import the legacy exports via index.ts
+// This is because we will bundle all code and dependencies into index.js at build time.
+// It's the only place where the code exists as a working, self-contained copy.
+// While we could have bundled `legacy-exports.ts` separately, it would create an other copy of the pretty much identical bundle
+// and add an additional 16mb+ to the published package.
+// To avoid this, we deduplicated the bundled code and run everything through index.ts.
+import { legacy } from './index';
+
+// We also need to re-export some types
+// These don't need to participate in the bundling, so we can just put them here
+export type { Obj } from './util';
+export type { Account } from './api/aws-auth';
+export type { ContextProviderPlugin } from './api/plugin';
+export type { BootstrapEnvironmentOptions, BootstrapSource } from './api/bootstrap';
+export type { StackSelector } from './api/cxapp/cloud-assembly';
+export type { DeployStackResult } from './api/deploy-stack';
+export type { Component } from './notices';
+export type { LoggerFunction } from './legacy-logging-source';
+
+// Re-export all symbols via index.js
+// We do this, because index.js is the the fail that will end up with all dependencies bundled
+export const {
+  deepClone,
+  flatten,
+  ifDefined,
+  isArray,
+  isEmpty,
+  numberFromBool,
+  partition,
+  deployStack,
+  cli,
+  exec,
+  SdkProvider,
+  PluginHost,
+  contentHash,
+  Command,
+  Configuration,
+  PROJECT_CONTEXT,
+  Settings,
+  Bootstrapper,
+  CloudExecutable,
+  execProgram,
+  RequireApproval,
+  leftPad,
+  formatAsBanner,
+  enableTracing,
+  aliases,
+  command,
+  describe,
+  lowerCaseFirstCharacter,
+  deepMerge,
+  Deployments,
+  rootDir,
+  latestVersionIfHigher,
+  versionNumber,
+  availableInitTemplates,
+  cached,
+  CfnEvaluationException,
+  CredentialPlugins,
+  AwsCliCompatible,
+  withCorkedLogging,
+  LogLevel,
+  logLevel,
+  CI,
+  setLogLevel,
+  setCI,
+  increaseVerbosity,
+  trace,
+  debug,
+  error,
+  warning,
+  success,
+  highlight,
+  print,
+  data,
+  prefix,
+} = legacy;

packages/aws-cdk/lib/legacy-logging-source.ts

@@ -1,3 +1,10 @@
+// This is an exact copy of the file `packages/aws-cdk/lib/logging.ts` from 2024-11-29
+// https://github.com/aws/aws-cdk/blob/81cde0e2e1f83f80273d14724d5518cc20dc5a80/packages/aws-cdk/lib/logging.ts
+// After this we started refactoring the file and functionality changed significantly.
+// In order to preserver backwards-compatibly for users with unsanctioned usage of this file,
+// we keep a copy of the original version around.
+// See https://github.com/aws/aws-cdk/pull/33021 for more information.
+
 import { Writable } from 'stream';
 import * as util from 'util';
 import * as chalk from 'chalk';

packages/aws-cdk/package.json

@@ -38,7 +38,7 @@
     "./lib/index": "./lib/legacy-exports.js",
     "./lib/api/aws-auth/index.js": "./lib/legacy-exports.js",
     "./lib/api/aws-auth": "./lib/legacy-exports.js",
-    "./lib/logging": "./lib/legacy-logging.js"
+    "./lib/logging": "./lib/legacy-exports.js"
   },
   "scripts": {
     "build": "cdk-build",