docs(toolkit-lib): CODE_REGISTRY.md tracks valid codes and their docu…

…mentation (#44)

closes aws/aws-cdk#33434

generates `CODE_REGISTRY.md` using information gathered in `codes.ts`.
this pr:

- updates `codes.ts` to have additional information stored
- introduces a script that generates a markdown table from the `CODES`
object
- updates projen to build `CODE_REGISTRY.md` as a post-build step

---

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

---------

Co-authored-by: Momo Kornher <kornherm@amazon.co.uk>

.projenrc.ts

@@ -1174,6 +1174,7 @@ toolkitLib.package.addField('exports', {
   './package.json': './package.json',
 });
 
+toolkitLib.postCompileTask.exec('ts-node scripts/gen-code-registry.ts');
 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');

packages/@aws-cdk/toolkit-lib/CODE_REGISTRY.md

@@ -0,0 +1,31 @@
+## Toolkit Code Registry
+
+| Code | Description | Level | Data Interface |
+|------|-------------|-------|----------------|
+| CDK_TOOLKIT_I1000 | Provides synthesis times. | info | n/a |
+| CDK_TOOLKIT_I1901 | Provides stack data | result | [StackData](docs/interfaces/StackData.html) |
+| CDK_TOOLKIT_I1902 | Successfully deployed stacks | result | [AssemblyData](docs/interfaces/AssemblyData.html) |
+| CDK_TOOLKIT_I2901 | Provides details on the selected stacks and their dependencies | result | n/a |
+| CDK_TOOLKIT_E3900 | Resource import failed | error | n/a |
+| CDK_TOOLKIT_I5000 | Provides deployment times | info | n/a |
+| CDK_TOOLKIT_I5001 | Provides total time in deploy action, including synth and rollback | info | [Duration](docs/interfaces/Duration.html) |
+| CDK_TOOLKIT_I5002 | Provides time for resource migration | info | 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 | n/a |
+| CDK_TOOLKIT_I5060 | Confirm deploy security sensitive changes | info | n/a |
+| CDK_TOOLKIT_I5900 | Deployment results on success | result | [SuccessfulDeployStackResult](docs/interfaces/SuccessfulDeployStackResult.html) |
+| CDK_TOOLKIT_E5001 | No stacks found | error | n/a |
+| CDK_TOOLKIT_I6000 | Provides rollback times | info | n/a |
+| CDK_TOOLKIT_E6001 | No stacks found | error | n/a |
+| CDK_TOOLKIT_E6900 | Rollback failed | error | n/a |
+| CDK_TOOLKIT_I7000 | Provides destroy times | info | n/a |
+| CDK_TOOLKIT_I7010 | Confirm destroy stacks | info | n/a |
+| CDK_TOOLKIT_E7010 | Action was aborted due to negative confirmation of request | error | n/a |
+| CDK_TOOLKIT_E7900 | Stack deletion failed | error | n/a |
+| CDK_ASSEMBLY_I0042 | Writing updated context | debug | n/a |
+| CDK_ASSEMBLY_I0241 | Fetching missing context | debug | n/a |
+| 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 | n/a |

packages/@aws-cdk/toolkit-lib/lib/api/cloud-assembly/private/context-aware-source.ts

@@ -3,7 +3,7 @@ import * as cxapi from '@aws-cdk/cx-api';
 import { ToolkitServices } from '../../../toolkit/private';
 import { type Context, contextproviders, PROJECT_CONTEXT } from '../../aws-cdk';
 import { ToolkitError } from '../../errors';
-import { ActionAwareIoHost, debug } from '../../io/private';
+import { ActionAwareIoHost, CODES, debug } from '../../io/private';
 import { ICloudAssemblySource } from '../types';
 
 export interface ContextAwareCloudAssemblyProps {
@@ -82,7 +82,7 @@ export class ContextAwareCloudAssembly implements ICloudAssemblySource {
         previouslyMissingKeys = missingKeys;
 
         if (tryLookup) {
-          await this.ioHost.notify(debug('Some context information is missing. Fetching...', 'CDK_ASSEMBLY_I0241', {
+          await this.ioHost.notify(debug('Some context information is missing. Fetching...', CODES.CDK_ASSEMBLY_I0241, {
             missingKeys: Array.from(missingKeys),
           }));
           await contextproviders.provideContextValues(
@@ -92,7 +92,7 @@ export class ContextAwareCloudAssembly implements ICloudAssemblySource {
           );
 
           // Cache the new context to disk
-          await this.ioHost.notify(debug(`Writing updated context to ${this.contextFile}...`, 'CDK_ASSEMBLY_I0042', {
+          await this.ioHost.notify(debug(`Writing updated context to ${this.contextFile}...`, CODES.CDK_ASSEMBLY_I0042, {
             contextFile: this.contextFile,
             context: this.context.all,
           }));

packages/@aws-cdk/toolkit-lib/lib/api/cloud-assembly/private/prepare-source.ts

@@ -7,7 +7,7 @@ import { lte } from 'semver';
 import { prepareDefaultEnvironment as oldPrepare, prepareContext, spaceAvailableForContext, Settings, loadTree, some, splitBySize, versionNumber } from '../../../api/aws-cdk';
 import { ToolkitServices } from '../../../toolkit/private';
 import { ToolkitError } from '../../errors';
-import { ActionAwareIoHost, asLogger, error } from '../../io/private';
+import { ActionAwareIoHost, asLogger, CODES, error } from '../../io/private';
 import type { AppSynthOptions } from '../source-builder';
 
 export { guessExecutable } from '../../../api/aws-cdk';
@@ -160,7 +160,7 @@ export async function assemblyFromDirectory(assemblyDir: string, ioHost: ActionA
       // this means the CLI version is too old.
       // we instruct the user to upgrade.
       const message = 'This AWS CDK Toolkit is not compatible with the AWS CDK library used by your application. Please upgrade to the latest version.';
-      await ioHost.notify(error(message, 'CDK_ASSEMBLY_E1111', { error: err.message }));
+      await ioHost.notify(error(message, CODES.CDK_ASSEMBLY_E1111, { error: err.message }));
       throw new ToolkitError(`${message}\n(${err.message}`);
     }
     throw err;

packages/@aws-cdk/toolkit-lib/lib/api/cloud-assembly/private/source-builder.ts

@@ -1,14 +1,14 @@
 import * as cxapi from '@aws-cdk/cx-api';
 import * as fs from 'fs-extra';
-import type { ICloudAssemblySource } from '../';
+import type { AssemblySourceProps, ICloudAssemblySource } from '../';
 import { ContextAwareCloudAssembly, ContextAwareCloudAssemblyProps } from './context-aware-source';
 import { execInChildProcess } from './exec';
 import { assemblyFromDirectory, changeDir, determineOutputDirectory, guessExecutable, prepareDefaultEnvironment, withContext, withEnv } from './prepare-source';
 import { ToolkitServices } from '../../../toolkit/private';
 import { Context, ILock, RWLock, Settings } from '../../aws-cdk';
 import { ToolkitError } from '../../errors';
-import { debug, error, info } from '../../io/private';
-import { AssemblyBuilder, AssemblySourceProps } from '../source-builder';
+import { CODES, debug, error, info } from '../../io/private';
+import { AssemblyBuilder } from '../source-builder';
 
 export abstract class CloudAssemblySourceBuilder {
   /**
@@ -126,10 +126,10 @@ export abstract class CloudAssemblySourceBuilder {
                 eventPublisher: async (type, line) => {
                   switch (type) {
                     case 'data_stdout':
-                      await services.ioHost.notify(info(line, 'CDK_ASSEMBLY_I1001'));
+                      await services.ioHost.notify(info(line, CODES.CDK_ASSEMBLY_I1001));
                       break;
                     case 'data_stderr':
-                      await services.ioHost.notify(error(line, 'CDK_ASSEMBLY_E1002'));
+                      await services.ioHost.notify(error(line, CODES.CDK_ASSEMBLY_E1002));
                       break;
                   }
                 },

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

@@ -1,4 +1,39 @@
-import { IoMessageCode } from '../io-message';
+import { IoMessageCode, IoMessageLevel } from '../io-message';
+
+/**
+ * Information for each IO Message Code.
+ */
+export interface CodeInfo {
+  /**
+   * The message code.
+   */
+  code: IoMessageCode;
+
+  /**
+   * A brief description of the meaning of this IO Message.
+   */
+  description: string;
+
+  /**
+   * The message level
+   */
+  level: IoMessageLevel;
+
+  /**
+   * The name of the payload interface, if applicable.
+   * Some Io Messages include a payload, with a specific interface. The name of
+   * the interface is specified here so that it can be linked with the message
+   * when documentation is generated.
+   *
+   * The interface _must_ be exposed directly from toolkit-lib, so that it will
+   * have a documentation page generated (that can be linked to).
+   */
+  interface?: string;
+}
+
+function codeInfo(info: CodeInfo): CodeInfo {
+  return info;
+}
 
 /**
  * We have a rough system by which we assign message codes:
@@ -8,55 +43,162 @@ import { IoMessageCode } from '../io-message';
  */
 export const CODES = {
   // 1: Synth
-  CDK_TOOLKIT_I1000: 'Provides synthesis times',
-  CDK_TOOLKIT_I1901: 'Provides stack data',
-  CDK_TOOLKIT_I1902: 'Successfully deployed stacks',
+  CDK_TOOLKIT_I1000: codeInfo({
+    code: 'CDK_TOOLKIT_I1000',
+    description: 'Provides synthesis times.',
+    level: 'info',
+  }),
+  CDK_TOOLKIT_I1901: codeInfo({
+    code: 'CDK_TOOLKIT_I1901',
+    description: 'Provides stack data',
+    level: 'result',
+    interface: 'StackData',
+  }),
+  CDK_TOOLKIT_I1902: codeInfo({
+    code: 'CDK_TOOLKIT_I1902',
+    description: 'Successfully deployed stacks',
+    level: 'result',
+    interface: 'AssemblyData',
+  }),
 
   // 2: List
-  CDK_TOOLKIT_I2901: 'Provides details on the selected stacks and their dependencies',
+  CDK_TOOLKIT_I2901: codeInfo({
+    code: 'CDK_TOOLKIT_I2901',
+    description: 'Provides details on the selected stacks and their dependencies',
+    level: 'result',
+  }),
 
   // 3: Import & Migrate
-  CDK_TOOLKIT_E3900: 'Resource import failed',
+  CDK_TOOLKIT_E3900: codeInfo({
+    code: 'CDK_TOOLKIT_E3900',
+    description: 'Resource import failed',
+    level: 'error',
+  }),
 
   // 4: Diff
 
   // 5: Deploy & Watch
-  CDK_TOOLKIT_I5000: 'Provides deployment times',
-  CDK_TOOLKIT_I5001: 'Provides total time in deploy action, including synth and rollback',
-  CDK_TOOLKIT_I5002: 'Provides time for resource migration',
-  CDK_TOOLKIT_I5031: 'Informs about any log groups that are traced as part of the deployment',
-  CDK_TOOLKIT_I5050: 'Confirm rollback during deployment',
-  CDK_TOOLKIT_I5060: 'Confirm deploy security sensitive changes',
-  CDK_TOOLKIT_I5900: 'Deployment results on success',
+  CDK_TOOLKIT_I5000: codeInfo({
+    code: 'CDK_TOOLKIT_I5000',
+    description: 'Provides deployment times',
+    level: 'info',
+  }),
+  CDK_TOOLKIT_I5001: codeInfo({
+    code: 'CDK_TOOLKIT_I5001',
+    description: 'Provides total time in deploy action, including synth and rollback',
+    level: 'info',
+    interface: 'Duration',
+  }),
+  CDK_TOOLKIT_I5002: codeInfo({
+    code: 'CDK_TOOLKIT_I5002',
+    description: 'Provides time for resource migration',
+    level: 'info',
+  }),
+  CDK_TOOLKIT_I5031: codeInfo({
+    code: 'CDK_TOOLKIT_I5031',
+    description: 'Informs about any log groups that are traced as part of the deployment',
+    level: 'info',
+  }),
+  CDK_TOOLKIT_I5050: codeInfo({
+    code: 'CDK_TOOLKIT_I5050',
+    description: 'Confirm rollback during deployment',
+    level: 'info',
+  }),
+  CDK_TOOLKIT_I5060: codeInfo({
+    code: 'CDK_TOOLKIT_I5060',
+    description: 'Confirm deploy security sensitive changes',
+    level: 'info',
+  }),
+  CDK_TOOLKIT_I5900: codeInfo({
+    code: 'CDK_TOOLKIT_I5900',
+    description: 'Deployment results on success',
+    level: 'result',
+    interface: 'SuccessfulDeployStackResult',
+  }),
 
-  CDK_TOOLKIT_E5001: 'No stacks found',
+  CDK_TOOLKIT_E5001: codeInfo({
+    code: 'CDK_TOOLKIT_E5001',
+    description: 'No stacks found',
+    level: 'error',
+  }),
 
   // 6: Rollback
-  CDK_TOOLKIT_I6000: 'Provides rollback times',
+  CDK_TOOLKIT_I6000: codeInfo({
+    code: 'CDK_TOOLKIT_I6000',
+    description: 'Provides rollback times',
+    level: 'info',
+  }),
 
-  CDK_TOOLKIT_E6001: 'No stacks found',
-  CDK_TOOLKIT_E6900: 'Rollback failed',
+  CDK_TOOLKIT_E6001: codeInfo({
+    code: 'CDK_TOOLKIT_E6001',
+    description: 'No stacks found',
+    level: 'error',
+  }),
+  CDK_TOOLKIT_E6900: codeInfo({
+    code: 'CDK_TOOLKIT_E6900',
+    description: 'Rollback failed',
+    level: 'error',
+  }),
 
   // 7: Destroy
-  CDK_TOOLKIT_I7000: 'Provides destroy times',
-  CDK_TOOLKIT_I7010: 'Confirm destroy stacks',
+  CDK_TOOLKIT_I7000: codeInfo({
+    code: 'CDK_TOOLKIT_I7000',
+    description: 'Provides destroy times',
+    level: 'info',
+  }),
+  CDK_TOOLKIT_I7010: codeInfo({
+    code: 'CDK_TOOLKIT_I7010',
+    description: 'Confirm destroy stacks',
+    level: 'info',
+  }),
 
-  CDK_TOOLKIT_E7010: 'Action was aborted due to negative confirmation of request',
-  CDK_TOOLKIT_E7900: 'Stack deletion failed',
+  CDK_TOOLKIT_E7010: codeInfo({
+    code: 'CDK_TOOLKIT_E7010',
+    description: 'Action was aborted due to negative confirmation of request',
+    level: 'error',
+  }),
+  CDK_TOOLKIT_E7900: codeInfo({
+    code: 'CDK_TOOLKIT_E7900',
+    description: 'Stack deletion failed',
+    level: 'error',
+  }),
 
   // 9: Bootstrap
 
   // Assembly codes
-  CDK_ASSEMBLY_I0042: 'Writing updated context',
-  CDK_ASSEMBLY_I0241: 'Fetching missing context',
-  CDK_ASSEMBLY_I1000: 'Cloud assembly output starts',
-  CDK_ASSEMBLY_I1001: 'Output lines emitted by the cloud assembly to stdout',
-  CDK_ASSEMBLY_E1002: 'Output lines emitted by the cloud assembly to stderr',
-  CDK_ASSEMBLY_I1003: 'Cloud assembly output finished',
-  CDK_ASSEMBLY_E1111: 'Incompatible CDK CLI version. Upgrade needed.',
+  CDK_ASSEMBLY_I0042: codeInfo({
+    code: 'CDK_ASSEMBLY_I0042',
+    description: 'Writing updated context',
+    level: 'debug',
+  }),
+  CDK_ASSEMBLY_I0241: codeInfo({
+    code: 'CDK_ASSEMBLY_I0241',
+    description: 'Fetching missing context',
+    level: 'debug',
+  }),
+  CDK_ASSEMBLY_I1000: codeInfo({
+    code: 'CDK_ASSEMBLY_I1000',
+    description: 'Cloud assembly output starts',
+    level: 'debug',
+  }),
+  CDK_ASSEMBLY_I1001: codeInfo({
+    code: 'CDK_ASSEMBLY_I1001',
+    description: 'Output lines emitted by the cloud assembly to stdout',
+    level: 'info',
+  }),
+  CDK_ASSEMBLY_E1002: codeInfo({
+    code: 'CDK_ASSEMBLY_E1002',
+    description: 'Output lines emitted by the cloud assembly to stderr',
+    level: 'error',
+  }),
+  CDK_ASSEMBLY_I1003: codeInfo({
+    code: 'CDK_ASSEMBLY_I1003',
+    description: 'Cloud assembly output finished',
+    level: 'info',
+  }),
+  CDK_ASSEMBLY_E1111: codeInfo({
+    code: 'CDK_ASSEMBLY_E1111',
+    description: 'Incompatible CDK CLI version. Upgrade needed.',
+    level: 'error',
+  }),
 };
-
-// If we give CODES a type with key: IoMessageCode,
-// this dynamically generated type will generalize to allow all IoMessageCodes.
-// Instead, we will validate that VALID_CODE must be IoMessageCode with the '&'.
-export type VALID_CODE = keyof typeof CODES & IoMessageCode;