Skip to content

Commit ac56f9b

Browse files
mrgrainmrgrain
authored
docs(toolkit-lib): ensure all message data interfaces are documented and other improvements (#210)
Main change here is to fail the build when the docs generation has warnings. This enforces that all referenced message data interfaces are exported and documented. Made some organizational changes and how the message registry is presented. Also added basic support for links to external interface from `cxapi`. --- By submitting this pull request, I confirm that my contribution is made under the terms of the Apache-2.0 license
1 parent c71caf0 commit ac56f9b

File tree

20 files changed

+176
-122
lines changed

20 files changed

+176
-122
lines changed

‎.projenrc.ts

+4-2
Original file line numberDiff line numberDiff line change
@@ -1265,7 +1265,8 @@ toolkitLib.package.addField('exports', {
12651265
'./package.json': './package.json',
12661266
});
12671267

1268-
toolkitLib.postCompileTask.exec('ts-node --prefer-ts-exts scripts/gen-code-registry.ts');
1268+
const registryTask = toolkitLib.addTask('registry', { exec: 'tsx scripts/gen-code-registry.ts' });
1269+
toolkitLib.postCompileTask.spawn(registryTask);
12691270
toolkitLib.postCompileTask.exec('node build-tools/bundle.mjs');
12701271
// Smoke test built JS files
12711272
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
12771278
toolkitLib.npmignore?.addPatterns(
12781279
'assets',
12791280
'docs',
1281+
'docs_html',
12801282
'typedoc.json',
12811283
'*.d.ts.map',
12821284
// Explicitly allow all required files
@@ -1293,7 +1295,7 @@ toolkitLib.npmignore?.addPatterns(
12931295

12941296
toolkitLib.gitignore.addPatterns(
12951297
...ADDITIONAL_CLI_IGNORE_PATTERNS,
1296-
'docs',
1298+
'docs_html',
12971299
'build-info.json',
12981300
'lib/**/*.wasm',
12991301
'lib/**/*.yaml',

‎packages/@aws-cdk/toolkit-lib/.gitignore

+1-1
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎packages/@aws-cdk/toolkit-lib/.npmignore

+1
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎packages/@aws-cdk/toolkit-lib/.projen/tasks.json

+9-1
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

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

-64
This file was deleted.

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

+68
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,68 @@
1+
---
2+
title: IoMessages Registry
3+
group: Documents
4+
---
5+
# IoMessages Registry
6+
7+
| Code | Description | Level | Data Interface |
8+
|------|-------------|-------|----------------|
9+
| `CDK_TOOLKIT_I0000` | Default info messages emitted from the Toolkit | `info` | n/a |
10+
| `CDK_TOOLKIT_I0000` | Default debug messages emitted from the Toolkit | `debug` | n/a |
11+
| `CDK_TOOLKIT_W0000` | Default warning messages emitted from the Toolkit | `warn` | n/a |
12+
| `CDK_TOOLKIT_I1000` | Provides synthesis times. | `info` | {@link Duration} |
13+
| `CDK_TOOLKIT_I1901` | Provides stack data | `result` | {@link StackAndAssemblyData} |
14+
| `CDK_TOOLKIT_I1902` | Successfully deployed stacks | `result` | {@link AssemblyData} |
15+
| `CDK_TOOLKIT_I2901` | Provides details on the selected stacks and their dependencies | `result` | {@link StackDetailsPayload} |
16+
| `CDK_TOOLKIT_E3900` | Resource import failed | `error` | n/a |
17+
| `CDK_TOOLKIT_I5000` | Provides deployment times | `info` | {@link Duration} |
18+
| `CDK_TOOLKIT_I5001` | Provides total time in deploy action, including synth and rollback | `info` | {@link Duration} |
19+
| `CDK_TOOLKIT_I5002` | Provides time for resource migration | `info` | n/a |
20+
| `CDK_TOOLKIT_W5021` | Empty non-existent stack, deployment is skipped | `warn` | n/a |
21+
| `CDK_TOOLKIT_W5022` | Empty existing stack, stack will be destroyed | `warn` | n/a |
22+
| `CDK_TOOLKIT_I5031` | Informs about any log groups that are traced as part of the deployment | `info` | n/a |
23+
| `CDK_TOOLKIT_I5050` | Confirm rollback during deployment | `info` | {@link ConfirmationRequest} |
24+
| `CDK_TOOLKIT_I5060` | Confirm deploy security sensitive changes | `info` | {@link DeployConfirmationRequest} |
25+
| `CDK_TOOLKIT_I5100` | Stack deploy progress | `info` | {@link StackDeployProgress} |
26+
| `CDK_TOOLKIT_I5310` | The computed settings used for file watching | `debug` | {@link WatchSettings} |
27+
| `CDK_TOOLKIT_I5311` | File watching started | `info` | {@link FileWatchEvent} |
28+
| `CDK_TOOLKIT_I5312` | File event detected, starting deployment | `info` | {@link FileWatchEvent} |
29+
| `CDK_TOOLKIT_I5313` | File event detected during active deployment, changes are queued | `info` | {@link FileWatchEvent} |
30+
| `CDK_TOOLKIT_I5314` | Initial watch deployment started | `info` | n/a |
31+
| `CDK_TOOLKIT_I5315` | Queued watch deployment started | `info` | n/a |
32+
| `CDK_TOOLKIT_I5501` | Stack Monitoring: Start monitoring of a single stack | `info` | {@link StackMonitoringControlEvent} |
33+
| `CDK_TOOLKIT_I5502` | Stack Monitoring: Activity event for a single stack | `info` | {@link StackActivity} |
34+
| `CDK_TOOLKIT_I5503` | Stack Monitoring: Finished monitoring of a single stack | `info` | {@link StackMonitoringControlEvent} |
35+
| `CDK_TOOLKIT_I5900` | Deployment results on success | `result` | {@link SuccessfulDeployStackResult} |
36+
| `CDK_TOOLKIT_I5901` | Generic deployment success messages | `info` | n/a |
37+
| `CDK_TOOLKIT_W5400` | Hotswap disclosure message | `warn` | n/a |
38+
| `CDK_TOOLKIT_E5001` | No stacks found | `error` | n/a |
39+
| `CDK_TOOLKIT_E5500` | Stack Monitoring error | `error` | {@link ErrorPayload} |
40+
| `CDK_TOOLKIT_I6000` | Provides rollback times | `info` | {@link Duration} |
41+
| `CDK_TOOLKIT_I6100` | Stack rollback progress | `info` | {@link StackRollbackProgress} |
42+
| `CDK_TOOLKIT_E6001` | No stacks found | `error` | n/a |
43+
| `CDK_TOOLKIT_E6900` | Rollback failed | `error` | {@link ErrorPayload} |
44+
| `CDK_TOOLKIT_I7000` | Provides destroy times | `info` | {@link Duration} |
45+
| `CDK_TOOLKIT_I7010` | Confirm destroy stacks | `info` | {@link ConfirmationRequest} |
46+
| `CDK_TOOLKIT_I7100` | Stack destroy progress | `info` | {@link StackDestroyProgress} |
47+
| `CDK_TOOLKIT_I7900` | Stack deletion succeeded | `result` | [cxapi.CloudFormationStackArtifact](https://docs.aws.amazon.com/cdk/api/v2/docs/@aws-cdk_cx-api.CloudFormationStackArtifact.html) |
48+
| `CDK_TOOLKIT_E7010` | Action was aborted due to negative confirmation of request | `error` | n/a |
49+
| `CDK_TOOLKIT_E7900` | Stack deletion failed | `error` | {@link ErrorPayload} |
50+
| `CDK_TOOLKIT_I9000` | Provides bootstrap times | `info` | {@link Duration} |
51+
| `CDK_TOOLKIT_I9100` | Bootstrap progress | `info` | {@link BootstrapEnvironmentProgress} |
52+
| `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) |
53+
| `CDK_TOOLKIT_E9900` | Bootstrap failed | `error` | {@link ErrorPayload} |
54+
| `CDK_ASSEMBLY_I0010` | Generic environment preparation debug messages | `debug` | n/a |
55+
| `CDK_ASSEMBLY_W0010` | Emitted if the found framework version does not support context overflow | `warn` | n/a |
56+
| `CDK_ASSEMBLY_I0042` | Writing updated context | `debug` | {@link UpdatedContext} |
57+
| `CDK_ASSEMBLY_I0240` | Context lookup was stopped as no further progress was made. | `debug` | {@link MissingContext} |
58+
| `CDK_ASSEMBLY_I0241` | Fetching missing context. This is an iterative message that may appear multiple times with different missing keys. | `debug` | {@link MissingContext} |
59+
| `CDK_ASSEMBLY_I1000` | Cloud assembly output starts | `debug` | n/a |
60+
| `CDK_ASSEMBLY_I1001` | Output lines emitted by the cloud assembly to stdout | `info` | n/a |
61+
| `CDK_ASSEMBLY_E1002` | Output lines emitted by the cloud assembly to stderr | `error` | n/a |
62+
| `CDK_ASSEMBLY_I1003` | Cloud assembly output finished | `info` | n/a |
63+
| `CDK_ASSEMBLY_E1111` | Incompatible CDK CLI version. Upgrade needed. | `error` | {@link ErrorPayload} |
64+
| `CDK_ASSEMBLY_I0150` | Indicates the use of a pre-synthesized cloud assembly directory | `debug` | n/a |
65+
| `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) |
66+
| `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) |
67+
| `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) |
68+
| `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

+7-2
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,9 @@ import type { CloudFormationStackArtifact } from '@aws-cdk/cx-api';
22
import type { BaseDeployOptions } from './private/deploy-options';
33
import type { Tag } from '../../api/aws-cdk';
44
import type { ConfirmationRequest } from '../../toolkit/types';
5-
import type { PermissionChangeType } from '../diff/private/helpers';
5+
import type { PermissionChangeType } from '../diff';
6+
7+
export type { StackMonitoringControlEvent, StackActivity } from '../../api/aws-cdk';
68

79
export type DeploymentMethod = DirectDeploymentMethod | ChangeSetDeploymentMethod;
810

@@ -51,6 +53,9 @@ export enum AssetBuildTime {
5153
JUST_IN_TIME = 'just-in-time',
5254
}
5355

56+
/**
57+
* @deprecated
58+
*/
5459
export enum RequireApproval {
5560
/**
5661
* Never require any security approvals
@@ -238,5 +243,5 @@ export interface DeployConfirmationRequest extends ConfirmationRequest {
238243
/**
239244
* The type of change being made to the IAM permissions.
240245
*/
241-
readonly permissionChangeType?: PermissionChangeType;
246+
readonly permissionChangeType: PermissionChangeType;
242247
}

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

+20
Original file line numberDiff line numberDiff line change
@@ -115,3 +115,23 @@ export interface DiffOptions {
115115
*/
116116
readonly securityOnly?: boolean;
117117
}
118+
119+
/**
120+
* Different types of permission related changes in a diff
121+
*/
122+
export enum PermissionChangeType {
123+
/**
124+
* No permission changes
125+
*/
126+
NONE = 'none',
127+
128+
/**
129+
* Permissions are broadening
130+
*/
131+
BROADENING = 'broadening',
132+
133+
/**
134+
* Permissions are changed but not broadening
135+
*/
136+
NON_BROADENING = 'non-broadening',
137+
}

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

+1-20
Original file line numberDiff line numberDiff line change
@@ -1,26 +1,7 @@
11
import type { DescribeChangeSetOutput } from '@aws-cdk/cloudformation-diff';
22
import { fullDiff } from '@aws-cdk/cloudformation-diff';
33
import type * as cxapi from '@aws-cdk/cx-api';
4-
5-
/**
6-
* Different types of permissioning changes in a diff
7-
*/
8-
export enum PermissionChangeType {
9-
/**
10-
* No permission changes
11-
*/
12-
NONE = 'none',
13-
14-
/**
15-
* Permissions are broadening
16-
*/
17-
BROADENING = 'broadening',
18-
19-
/**
20-
* Permissions are changed but not broadening
21-
*/
22-
NON_BROADENING = 'non-broadening',
23-
}
4+
import { PermissionChangeType } from '..';
245

256
/**
267
* Return whether the diff has security-impacting changes that need confirmation.

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

+1
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,7 @@
11
export * from './bootstrap';
22
export * from './deploy';
33
export * from './destroy';
4+
export { PermissionChangeType } from './diff';
45
export * from './list';
56
export * from './rollback';
67
export * from './synth';

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

+1
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,4 @@
1+
export * from './context';
12
export * from './source-builder';
23
export * from './stack-selector';
34
export * from './types';

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

+22
Original file line numberDiff line numberDiff line change
@@ -1 +1,23 @@
11
export type { IoMessageLevel, IoMessageCode, IIoHost, IoMessage, IoRequest } from '../shared-public';
2+
3+
/**
4+
* An SDK logging trace.
5+
*
6+
* Only info, warn and error level messages are emitted.
7+
* SDK traces are emitted as traces to the IoHost, but contain the original SDK logging level.
8+
*/
9+
export interface SdkTrace {
10+
/**
11+
* The level the SDK has emitted the original message with
12+
*/
13+
readonly sdkLevel: 'info' | 'warn' | 'error';
14+
15+
/**
16+
* The content of the SDK trace
17+
*
18+
* This will include the request and response data for API calls, including potentially sensitive information.
19+
*
20+
* @see https://docs.aws.amazon.com/sdk-for-javascript/v3/developer-guide/logging-sdk-calls.html
21+
*/
22+
readonly content: any;
23+
}

0 commit comments

Comments
 (0)