docs(toolkit-lib): ensure all message data interfaces are documented and other improvements

.projenrc.ts

@@ -1265,7 +1265,8 @@ toolkitLib.package.addField('exports', {
   './package.json': './package.json',
 });
 
-toolkitLib.postCompileTask.exec('ts-node --prefer-ts-exts scripts/gen-code-registry.ts');
+const registryTask = toolkitLib.addTask('registry', { exec: 'tsx scripts/gen-code-registry.ts' });
+toolkitLib.postCompileTask.spawn(registryTask);
 toolkitLib.postCompileTask.exec('node build-tools/bundle.mjs');
 // Smoke test built JS files
 toolkitLib.postCompileTask.exec('node ./lib/index.js >/dev/null 2>/dev/null </dev/null');
@@ -1277,6 +1278,7 @@ toolkitLib.postCompileTask.exec('node ./lib/private/util.js >/dev/null 2>/dev/nu
 toolkitLib.npmignore?.addPatterns(
   'assets',
   'docs',
+  'docs_html',
   'typedoc.json',
   '*.d.ts.map',
   // Explicitly allow all required files
@@ -1293,7 +1295,7 @@ toolkitLib.npmignore?.addPatterns(
 
 toolkitLib.gitignore.addPatterns(
   ...ADDITIONAL_CLI_IGNORE_PATTERNS,
-  'docs',
+  'docs_html',
   'build-info.json',
   'lib/**/*.wasm',
   'lib/**/*.yaml',

packages/@aws-cdk/toolkit-lib/docs/message-registry.md

@@ -0,0 +1,68 @@
+---
+title: IoMessages Registry
+group: Documents
+---
+# IoMessages Registry
+
+| Code | Description | Level | Data Interface |
+|------|-------------|-------|----------------|
+| `CDK_TOOLKIT_I0000` | Default info messages emitted from the Toolkit | `info` | n/a |
+| `CDK_TOOLKIT_I0000` | Default debug messages emitted from the Toolkit | `debug` | n/a |
+| `CDK_TOOLKIT_W0000` | Default warning messages emitted from the Toolkit | `warn` | n/a |
+| `CDK_TOOLKIT_I1000` | Provides synthesis times. | `info` | {@link Duration} |
+| `CDK_TOOLKIT_I1901` | Provides stack data | `result` | {@link StackAndAssemblyData} |
+| `CDK_TOOLKIT_I1902` | Successfully deployed stacks | `result` | {@link AssemblyData} |
+| `CDK_TOOLKIT_I2901` | Provides details on the selected stacks and their dependencies | `result` | {@link StackDetailsPayload} |
+| `CDK_TOOLKIT_E3900` | Resource import failed | `error` | n/a |
+| `CDK_TOOLKIT_I5000` | Provides deployment times | `info` | {@link Duration} |
+| `CDK_TOOLKIT_I5001` | Provides total time in deploy action, including synth and rollback | `info` | {@link Duration} |
+| `CDK_TOOLKIT_I5002` | Provides time for resource migration | `info` | n/a |
+| `CDK_TOOLKIT_W5021` | Empty non-existent stack, deployment is skipped | `warn` | n/a |
+| `CDK_TOOLKIT_W5022` | Empty existing stack, stack will be destroyed | `warn` | n/a |
+| `CDK_TOOLKIT_I5031` | Informs about any log groups that are traced as part of the deployment | `info` | n/a |
+| `CDK_TOOLKIT_I5050` | Confirm rollback during deployment | `info` | {@link ConfirmationRequest} |
+| `CDK_TOOLKIT_I5060` | Confirm deploy security sensitive changes | `info` | {@link DeployConfirmationRequest} |
+| `CDK_TOOLKIT_I5100` | Stack deploy progress | `info` | {@link StackDeployProgress} |
+| `CDK_TOOLKIT_I5310` | The computed settings used for file watching | `debug` | {@link WatchSettings} |
+| `CDK_TOOLKIT_I5311` | File watching started | `info` | {@link FileWatchEvent} |
+| `CDK_TOOLKIT_I5312` | File event detected, starting deployment | `info` | {@link FileWatchEvent} |
+| `CDK_TOOLKIT_I5313` | File event detected during active deployment, changes are queued | `info` | {@link FileWatchEvent} |
+| `CDK_TOOLKIT_I5314` | Initial watch deployment started | `info` | n/a |
+| `CDK_TOOLKIT_I5315` | Queued watch deployment started | `info` | n/a |
+| `CDK_TOOLKIT_I5501` | Stack Monitoring: Start monitoring of a single stack | `info` | {@link StackMonitoringControlEvent} |
+| `CDK_TOOLKIT_I5502` | Stack Monitoring: Activity event for a single stack | `info` | {@link StackActivity} |
+| `CDK_TOOLKIT_I5503` | Stack Monitoring: Finished monitoring of a single stack | `info` | {@link StackMonitoringControlEvent} |
+| `CDK_TOOLKIT_I5900` | Deployment results on success | `result` | {@link SuccessfulDeployStackResult} |
+| `CDK_TOOLKIT_I5901` | Generic deployment success messages | `info` | n/a |
+| `CDK_TOOLKIT_W5400` | Hotswap disclosure message | `warn` | n/a |
+| `CDK_TOOLKIT_E5001` | No stacks found | `error` | n/a |
+| `CDK_TOOLKIT_E5500` | Stack Monitoring error | `error` | {@link ErrorPayload} |
+| `CDK_TOOLKIT_I6000` | Provides rollback times | `info` | {@link Duration} |
+| `CDK_TOOLKIT_I6100` | Stack rollback progress | `info` | {@link StackRollbackProgress} |
+| `CDK_TOOLKIT_E6001` | No stacks found | `error` | n/a |
+| `CDK_TOOLKIT_E6900` | Rollback failed | `error` | {@link ErrorPayload} |
+| `CDK_TOOLKIT_I7000` | Provides destroy times | `info` | {@link Duration} |
+| `CDK_TOOLKIT_I7010` | Confirm destroy stacks | `info` | {@link ConfirmationRequest} |
+| `CDK_TOOLKIT_I7100` | Stack destroy progress | `info` | {@link StackDestroyProgress} |
+| `CDK_TOOLKIT_I7900` | Stack deletion succeeded | `result` | [cxapi.CloudFormationStackArtifact](https://docs.aws.amazon.com/cdk/api/v2/docs/@aws-cdk_cx-api.CloudFormationStackArtifact.html) |
+| `CDK_TOOLKIT_E7010` | Action was aborted due to negative confirmation of request | `error` | n/a |
+| `CDK_TOOLKIT_E7900` | Stack deletion failed | `error` | {@link ErrorPayload} |
+| `CDK_TOOLKIT_I9000` | Provides bootstrap times | `info` | {@link Duration} |
+| `CDK_TOOLKIT_I9100` | Bootstrap progress | `info` | {@link BootstrapEnvironmentProgress} |
+| `CDK_TOOLKIT_I9900` | Bootstrap results on success | `result` | [cxapi.Environment](https://docs.aws.amazon.com/cdk/api/v2/docs/@aws-cdk_cx-api.Environment.html) |
+| `CDK_TOOLKIT_E9900` | Bootstrap failed | `error` | {@link ErrorPayload} |
+| `CDK_ASSEMBLY_I0010` | Generic environment preparation debug messages | `debug` | n/a |
+| `CDK_ASSEMBLY_W0010` | Emitted if the found framework version does not support context overflow | `warn` | n/a |
+| `CDK_ASSEMBLY_I0042` | Writing updated context | `debug` | {@link UpdatedContext} |
+| `CDK_ASSEMBLY_I0240` | Context lookup was stopped as no further progress was made.  | `debug` | {@link MissingContext} |
+| `CDK_ASSEMBLY_I0241` | Fetching missing context. This is an iterative message that may appear multiple times with different missing keys. | `debug` | {@link MissingContext} |
+| `CDK_ASSEMBLY_I1000` | Cloud assembly output starts | `debug` | n/a |
+| `CDK_ASSEMBLY_I1001` | Output lines emitted by the cloud assembly to stdout | `info` | n/a |
+| `CDK_ASSEMBLY_E1002` | Output lines emitted by the cloud assembly to stderr | `error` | n/a |
+| `CDK_ASSEMBLY_I1003` | Cloud assembly output finished | `info` | n/a |
+| `CDK_ASSEMBLY_E1111` | Incompatible CDK CLI version. Upgrade needed. | `error` | {@link ErrorPayload} |
+| `CDK_ASSEMBLY_I0150` | Indicates the use of a pre-synthesized cloud assembly directory | `debug` | n/a |
+| `CDK_ASSEMBLY_I9999` | Annotations emitted by the cloud assembly | `info` | [cxapi.SynthesisMessage](https://docs.aws.amazon.com/cdk/api/v2/docs/@aws-cdk_cx-api.SynthesisMessage.html) |
+| `CDK_ASSEMBLY_W9999` | Warnings emitted by the cloud assembly | `warn` | [cxapi.SynthesisMessage](https://docs.aws.amazon.com/cdk/api/v2/docs/@aws-cdk_cx-api.SynthesisMessage.html) |
+| `CDK_ASSEMBLY_E9999` | Errors emitted by the cloud assembly | `error` | [cxapi.SynthesisMessage](https://docs.aws.amazon.com/cdk/api/v2/docs/@aws-cdk_cx-api.SynthesisMessage.html) |
+| `CDK_SDK_I0100` | An SDK trace. SDK traces are emitted as traces to the IoHost, but contain the original SDK logging level. | `trace` | {@link SdkTrace} |

packages/@aws-cdk/toolkit-lib/lib/actions/deploy/index.ts

@@ -2,7 +2,9 @@ import type { CloudFormationStackArtifact } from '@aws-cdk/cx-api';
 import type { BaseDeployOptions } from './private/deploy-options';
 import type { Tag } from '../../api/aws-cdk';
 import type { ConfirmationRequest } from '../../toolkit/types';
-import type { PermissionChangeType } from '../diff/private/helpers';
+import type { PermissionChangeType } from '../diff';
+
+export type { StackMonitoringControlEvent, StackActivity } from '../../api/aws-cdk';
 
 export type DeploymentMethod = DirectDeploymentMethod | ChangeSetDeploymentMethod;
 
@@ -51,6 +53,9 @@ export enum AssetBuildTime {
   JUST_IN_TIME = 'just-in-time',
 }
 
+/**
+ * @deprecated
+ */
 export enum RequireApproval {
   /**
    * Never require any security approvals
@@ -238,5 +243,5 @@ export interface DeployConfirmationRequest extends ConfirmationRequest {
   /**
    * The type of change being made to the IAM permissions.
    */
-  readonly permissionChangeType?: PermissionChangeType;
+  readonly permissionChangeType: PermissionChangeType;
 }

packages/@aws-cdk/toolkit-lib/lib/actions/diff/index.ts

@@ -115,3 +115,23 @@ export interface DiffOptions {
    */
   readonly securityOnly?: boolean;
 }
+
+/**
+ * Different types of permission related changes in a diff
+ */
+export enum PermissionChangeType {
+  /**
+   * No permission changes
+   */
+  NONE = 'none',
+
+  /**
+   * Permissions are broadening
+   */
+  BROADENING = 'broadening',
+
+  /**
+   * Permissions are changed but not broadening
+   */
+  NON_BROADENING = 'non-broadening',
+}

packages/@aws-cdk/toolkit-lib/lib/actions/diff/private/helpers.ts

@@ -1,26 +1,7 @@
 import type { DescribeChangeSetOutput } from '@aws-cdk/cloudformation-diff';
 import { fullDiff } from '@aws-cdk/cloudformation-diff';
 import type * as cxapi from '@aws-cdk/cx-api';
-
-/**
- * Different types of permissioning changes in a diff
- */
-export enum PermissionChangeType {
-  /**
-   * No permission changes
-   */
-  NONE = 'none',
-
-  /**
-   * Permissions are broadening
-   */
-  BROADENING = 'broadening',
-
-  /**
-   * Permissions are changed but not broadening
-   */
-  NON_BROADENING = 'non-broadening',
-}
+import { PermissionChangeType } from '..';
 
 /**
  * Return whether the diff has security-impacting changes that need confirmation.

packages/@aws-cdk/toolkit-lib/lib/actions/index.ts

@@ -1,6 +1,7 @@
 export * from './bootstrap';
 export * from './deploy';
 export * from './destroy';
+export { PermissionChangeType } from './diff';
 export * from './list';
 export * from './rollback';
 export * from './synth';

packages/@aws-cdk/toolkit-lib/lib/api/cloud-assembly/index.ts

@@ -1,3 +1,4 @@
+export * from './context';
 export * from './source-builder';
 export * from './stack-selector';
 export * from './types';

packages/@aws-cdk/toolkit-lib/lib/api/io/index.ts

@@ -1 +1,23 @@
 export type { IoMessageLevel, IoMessageCode, IIoHost, IoMessage, IoRequest } from '../shared-public';
+
+/**
+ * An SDK logging trace.
+ *
+ * Only info, warn and error level messages are emitted.
+ * SDK traces are emitted as traces to the IoHost, but contain the original SDK logging level.
+ */
+export interface SdkTrace {
+  /**
+   * The level the SDK has emitted the original message with
+   */
+  readonly sdkLevel: 'info' | 'warn' | 'error';
+
+  /**
+   * The content of the SDK trace
+   *
+   * This will include the request and response data for API calls, including potentially sensitive information.
+   *
+   * @see https://docs.aws.amazon.com/sdk-for-javascript/v3/developer-guide/logging-sdk-calls.html
+   */
+  readonly content: any;
+}