@aws-cdk/toolkit-lib 0.1.6 → 0.1.8

package/lib/api/shared-public.d.ts

@@ -1,6 +1,6 @@
 import * as cxapi from '@aws-cdk/cx-api';
 import { CloudFormationStackArtifact } from '@aws-cdk/cx-api';
-import { StackEvent } from '@aws-sdk/client-cloudformation';
+import { DescribeChangeSetOutput as DescribeChangeSet, StackEvent } from '@aws-sdk/client-cloudformation';
 
 /**
  * Which stacks should be selected from a cloud assembly
@@ -83,99 +83,85 @@ export interface StackSelector {
 	 */
 	failOnEmpty?: boolean;
 }
-/**
- * The current action being performed by the CLI. 'none' represents the absence of an action.
- */
-export type ToolkitAction = "assembly" | "bootstrap" | "synth" | "list" | "diff" | "deploy" | "rollback" | "watch" | "destroy" | "doctor" | "gc" | "import" | "metadata" | "init" | "migrate";
-/**
- * The reporting level of the message.
- * All messages are always reported, it's up to the IoHost to decide what to log.
- */
-export type IoMessageLevel = "error" | "result" | "warn" | "info" | "debug" | "trace";
-/**
- * A valid message code.
- */
-export type IoMessageCode = `CDK_${string}_${"E" | "W" | "I"}${number}${number}${number}${number}`;
-/**
- * An IO message emitted.
- */
-export interface IoMessage<T> {
-	/**
-	 * The time the message was emitted.
-	 */
-	readonly time: Date;
-	/**
-	 * The recommended log level of the message.
-	 *
-	 * This is an indicative level and should not be used to explicitly match messages, instead match the `code`.
-	 * The level of a message may change without notice.
-	 */
-	readonly level: IoMessageLevel;
-	/**
-	 * The action that triggered the message.
-	 */
-	readonly action: ToolkitAction;
-	/**
-	 * A short message code uniquely identifying a message type using the format CDK_[CATEGORY]_[E/W/I][0000-9999].
-	 *
-	 * The level indicator follows these rules:
-	 * - 'E' for error level messages
-	 * - 'W' for warning level messages
-	 * - 'I' for info/debug/trace level messages
-	 *
-	 * Codes ending in 000 0 are generic messages, while codes ending in 0001-9999 are specific to a particular message.
-	 * The following are examples of valid and invalid message codes:
-	 * ```ts
-	 * 'CDK_ASSETS_I0000'       // valid: generic assets info message
-	 * 'CDK_TOOLKIT_E0002'      // valid: specific toolkit error message
-	 * 'CDK_SDK_W0023'          // valid: specific sdk warning message
-	 * ```
-	 *
-	 * @see https://github.com/aws/aws-cdk-cli/blob/main/packages/%40aws-cdk/toolkit-lib/CODE_REGISTRY.md
-	 */
-	readonly code: IoMessageCode;
-	/**
-	 * The message text.
-	 * This is safe to print to an end-user.
-	 */
-	readonly message: string;
+export interface Template {
+	Parameters?: Record<string, TemplateParameter>;
+	[section: string]: any;
+}
+export interface TemplateParameter {
+	Type: string;
+	Default?: any;
+	Description?: string;
+	[key: string]: any;
+}
+export interface NestedStackTemplates {
+	readonly physicalName: string | undefined;
+	readonly deployedTemplate: Template;
+	readonly generatedTemplate: Template;
+	readonly nestedStackTemplates: {
+		[nestedStackLogicalId: string]: NestedStackTemplates;
+	};
+}
+interface IDifference<ValueType> {
+	readonly oldValue: ValueType | undefined;
+	readonly newValue: ValueType | undefined;
+	readonly isDifferent: boolean;
+	readonly isAddition: boolean;
+	readonly isRemoval: boolean;
+	readonly isUpdate: boolean;
+}
+declare class Difference<ValueType> implements IDifference<ValueType> {
+	readonly oldValue: ValueType | undefined;
+	readonly newValue: ValueType | undefined;
 	/**
-	 * Identifies the message span, this message belongs to.
-	 *
-	 * A message span, groups multiple messages together that semantically related to the same operation.
-	 * This is an otherwise meaningless identifier.
+	 * Whether this is an actual different or the values are actually the same
 	 *
-	 * A message without a `spanId`, does not belong to a span.
+	 * isDifferent => (isUpdate | isRemoved | isUpdate)
 	 */
-	readonly span?: string;
+	isDifferent: boolean;
 	/**
-	 * The data attached to the message.
+	 * @param oldValue the old value, cannot be equal (to the sense of +deepEqual+) to +newValue+.
+	 * @param newValue the new value, cannot be equal (to the sense of +deepEqual+) to +oldValue+.
 	 */
-	readonly data: T;
+	constructor(oldValue: ValueType | undefined, newValue: ValueType | undefined);
+	/** @returns +true+ if the element is new to the template. */
+	get isAddition(): boolean;
+	/** @returns +true+ if the element was removed from the template. */
+	get isRemoval(): boolean;
+	/** @returns +true+ if the element was already in the template and is updated. */
+	get isUpdate(): boolean;
 }
-/**
- * An IO request emitted.
- */
-export interface IoRequest<T, U> extends IoMessage<T> {
-	/**
-	 * The default response that will be used if no data is returned.
-	 */
-	readonly defaultResponse: U;
+declare class PropertyDifference<ValueType> extends Difference<ValueType> {
+	changeImpact?: ResourceImpact;
+	constructor(oldValue: ValueType | undefined, newValue: ValueType | undefined, args: {
+		changeImpact?: ResourceImpact;
+	});
 }
-export interface IIoHost {
-	/**
-	 * Notifies the host of a message.
-	 * The caller waits until the notification completes.
-	 */
-	notify(msg: IoMessage<unknown>): Promise<void>;
-	/**
-	 * Notifies the host of a message that requires a response.
-	 *
-	 * If the host does not return a response the suggested
-	 * default response from the input message will be used.
-	 */
-	requestResponse<T, U>(msg: IoRequest<T, U>): Promise<U>;
+declare enum ResourceImpact {
+	/** The existing physical resource will be updated */
+	WILL_UPDATE = "WILL_UPDATE",
+	/** A new physical resource will be created */
+	WILL_CREATE = "WILL_CREATE",
+	/** The existing physical resource will be replaced */
+	WILL_REPLACE = "WILL_REPLACE",
+	/** The existing physical resource may be replaced */
+	MAY_REPLACE = "MAY_REPLACE",
+	/** The existing physical resource will be destroyed */
+	WILL_DESTROY = "WILL_DESTROY",
+	/** The existing physical resource will be removed from CloudFormation supervision */
+	WILL_ORPHAN = "WILL_ORPHAN",
+	/** The existing physical resource will be added to CloudFormation supervision */
+	WILL_IMPORT = "WILL_IMPORT",
+	/** There is no change in this resource */
+	NO_CHANGE = "NO_CHANGE"
 }
+interface Resource {
+	Type: string;
+	Properties?: {
+		[name: string]: any;
+	};
+	[key: string]: any;
+}
+type DescribeChangeSetOutput = DescribeChangeSet;
 interface BootstrapRole {
 	/**
 	 * The ARN of the IAM role created as part of bootrapping
@@ -871,29 +857,101 @@ interface KeyContextQuery extends ContextLookupRoleOptions {
 }
 interface CcApiContextQuery extends ContextLookupRoleOptions {
 	/**
-	 * The Cloudformation resource type.
+	 * The CloudFormation resource type.
 	 * See https://docs.aws.amazon.com/cloudcontrolapi/latest/userguide/supported-resources.html
 	 */
 	readonly typeName: string;
 	/**
-	 * exactIdentifier of the resource.
-	 * Specifying exactIdentifier will return at most one result.
-	 * Either exactIdentifier or propertyMatch should be specified.
-	 * @default - None
+	 * Identifier of the resource to look up using `GetResource`.
+	 *
+	 * Specifying exactIdentifier will return exactly one result, or throw an error
+	 * unless `ignoreErrorOnMissingContext` is set.
+	 *
+	 * @default - Either exactIdentifier or propertyMatch should be specified.
 	 */
 	readonly exactIdentifier?: string;
 	/**
-	 * This indicates the property to search for.
-	 * If both exactIdentifier and propertyMatch are specified, then exactIdentifier is used.
-	 * Specifying propertyMatch will return 0 or more results.
-	 * Either exactIdentifier or propertyMatch should be specified.
-	 * @default - None
+	 * Returns any resources matching these properties, using `ListResources`.
+	 *
+	 * By default, specifying propertyMatch will successfully return 0 or more
+	 * results. To throw an error if the number of results is unexpected (and
+	 * prevent the query results from being committed to context), specify
+	 * `expectedMatchCount`.
+	 *
+	 * ## Notes on property completeness
+	 *
+	 * CloudControl API's `ListResources` may return fewer properties than
+	 * `GetResource` would, depending on the resource implementation.
+	 *
+	 * The resources that `propertyMatch` matches against will *only ever* be the
+	 * properties returned by the `ListResources` call.
+	 *
+	 * @default - Either exactIdentifier or propertyMatch should be specified.
 	 */
 	readonly propertyMatch?: Record<string, unknown>;
 	/**
 	 * This is a set of properties returned from CC API that we want to return from ContextQuery.
+	 *
+	 * If any properties listed here are absent from the target resource, an error will be thrown.
+	 *
+	 * The returned object will always include the key `Identifier` with the CC-API returned
+	 * field `Identifier`.
+	 *
+	 * ## Notes on property completeness
+	 *
+	 * CloudControl API's `ListResources` may return fewer properties than
+	 * `GetResource` would, depending on the resource implementation.
+	 *
+	 * The returned properties here are *currently* selected from the response
+	 * object that CloudControl API returns to the CDK CLI.
+	 *
+	 * However, if we find there is need to do so, we may decide to change this
+	 * behavior in the future: we might change it to perform an additional
+	 * `GetResource` call for resources matched by `propertyMatch`.
 	 */
 	readonly propertiesToReturn: string[];
+	/**
+	 * Expected count of results if `propertyMatch` is specified.
+	 *
+	 * If the expected result count does not match the actual count,
+	 * by default an error is produced and the result is not committed to cached
+	 * context, and the user can correct the situation and try again without
+	 * having to manually clear out the context key using `cdk context --remove`
+	 *
+	 * If the value of * `ignoreErrorOnMissingContext` is `true`, the value of
+	 * `expectedMatchCount` is `at-least-one | exactly-one` and the number
+	 * of found resources is 0, `dummyValue` is returned and committed to context
+	 * instead.
+	 *
+	 * @default 'any'
+	 */
+	readonly expectedMatchCount?: "any" | "at-least-one" | "at-most-one" | "exactly-one";
+	/**
+	 * The value to return if the resource was not found and `ignoreErrorOnMissingContext` is true.
+	 *
+	 * If supplied, `dummyValue` should be an array of objects.
+	 *
+	 * `dummyValue` does not have to have elements, and it may have objects with
+	 * different properties than the properties in `propertiesToReturn`, but it
+	 * will be easiest for downstream code if the `dummyValue` conforms to
+	 * the expected response shape.
+	 *
+	 * @default - No dummy value available
+	 */
+	readonly dummyValue?: any;
+	/**
+	 * Ignore an error and return the `dummyValue` instead if the resource was not found.
+	 *
+	 * - In case of an `exactIdentifier` lookup, return the `dummyValue` if the resource with
+	 *   that identifier was not found.
+	 * - In case of a `propertyMatch` lookup, return the `dummyValue` if `expectedMatchCount`
+	 *   is `at-least-one | exactly-one` and the number of resources found was 0.
+	 *
+	 * if `ignoreErrorOnMissingContext` is set, `dummyValue` should be set and be an array.
+	 *
+	 * @default false
+	 */
+	readonly ignoreErrorOnMissingContext?: boolean;
 }
 interface PluginContextQuery {
 	/**
@@ -1904,88 +1962,140 @@ declare class Manifest {
 	private static replaceStackTags;
 	private constructor();
 }
-export interface BootstrapEnvironmentProgress {
+/**
+ * The current action being performed by the CLI. 'none' represents the absence of an action.
+ */
+export type ToolkitAction = "assembly" | "bootstrap" | "synth" | "list" | "diff" | "deploy" | "rollback" | "watch" | "destroy" | "doctor" | "gc" | "import" | "metadata" | "init" | "migrate";
+/**
+ * The reporting level of the message.
+ * All messages are always reported, it's up to the IoHost to decide what to log.
+ */
+export type IoMessageLevel = "error" | "result" | "warn" | "info" | "debug" | "trace";
+/**
+ * A valid message code.
+ */
+export type IoMessageCode = `CDK_${string}_${"E" | "W" | "I"}${number}${number}${number}${number}`;
+/**
+ * An IO message emitted.
+ */
+export interface IoMessage<T> {
 	/**
-	 * The total number of environments being deployed
+	 * The time the message was emitted.
 	 */
-	readonly total: number;
+	readonly time: Date;
 	/**
-	 * The count of the environment currently bootstrapped
+	 * The recommended log level of the message.
 	 *
-	 * This is counting value, not an identifier.
+	 * This is an indicative level and should not be used to explicitly match messages, instead match the `code`.
+	 * The level of a message may change without notice.
 	 */
-	readonly current: number;
+	readonly level: IoMessageLevel;
 	/**
-	 * The environment that's currently being bootstrapped
+	 * The action that triggered the message.
 	 */
-	readonly environment: cxapi.Environment;
-}
-interface IManifestEntry {
+	readonly action: ToolkitAction;
 	/**
-	 * The identifier of the asset and its destination
+	 * A short message code uniquely identifying a message type using the format CDK_[CATEGORY]_[E/W/I][0000-9999].
+	 *
+	 * The level indicator follows these rules:
+	 * - 'E' for error level messages
+	 * - 'W' for warning level messages
+	 * - 'I' for info/debug/trace level messages
+	 *
+	 * Codes ending in 000 0 are generic messages, while codes ending in 0001-9999 are specific to a particular message.
+	 * The following are examples of valid and invalid message codes:
+	 * ```ts
+	 * 'CDK_ASSETS_I0000'       // valid: generic assets info message
+	 * 'CDK_TOOLKIT_E0002'      // valid: specific toolkit error message
+	 * 'CDK_SDK_W0023'          // valid: specific sdk warning message
+	 * ```
+	 *
+	 * @see https://github.com/aws/aws-cdk-cli/blob/main/packages/%40aws-cdk/toolkit-lib/CODE_REGISTRY.md
 	 */
-	readonly id: DestinationIdentifier;
+	readonly code: IoMessageCode;
 	/**
-	 * The type of asset
+	 * The message text.
+	 * This is safe to print to an end-user.
 	 */
-	readonly type: string;
+	readonly message: string;
 	/**
-	 * Type-dependent source data
+	 * Identifies the message span, this message belongs to.
+	 *
+	 * A message span, groups multiple messages together that semantically related to the same operation.
+	 * This is an otherwise meaningless identifier.
+	 *
+	 * A message without a `spanId`, does not belong to a span.
 	 */
-	readonly genericSource: unknown;
+	readonly span?: string;
 	/**
-	 * Type-dependent destination data
+	 * The data attached to the message.
 	 */
-	readonly genericDestination: unknown;
+	readonly data: T;
+}
+/**
+ * An IO request emitted.
+ */
+export interface IoRequest<T, U> extends IoMessage<T> {
 	/**
-	 * Return a display name for this asset
-	 *
-	 * The `includeDestination` parameter controls whether or not to include the
-	 * destination ID in the display name.
-	 *
-	 * - Pass `false` if you are displaying notifications about building the
-	 *   asset, or if you are describing the work of building the asset and publishing
-	 *   to all destinations at the same time.
-	 * - Pass `true` if you are displaying notifications about publishing to a
-	 *   specific destination.
+	 * The default response that will be used if no data is returned.
 	 */
-	displayName(includeDestination: boolean): string;
+	readonly defaultResponse: U;
 }
-declare class DestinationIdentifier {
+export interface IIoHost {
 	/**
-	 * Identifies the asset, by source.
+	 * Notifies the host of a message.
+	 * The caller waits until the notification completes.
+	 */
+	notify(msg: IoMessage<unknown>): Promise<void>;
+	/**
+	 * Notifies the host of a message that requires a response.
 	 *
-	 * The assetId will be the same between assets that represent
-	 * the same physical file or image.
+	 * If the host does not return a response the suggested
+	 * default response from the input message will be used.
 	 */
-	readonly assetId: string;
+	requestResponse<T, U>(msg: IoRequest<T, U>): Promise<U>;
+}
+interface CodeInfo {
 	/**
-	 * Identifies the destination where this asset will be published
+	 * The message code.
 	 */
-	readonly destinationId: string;
-	constructor(assetId: string, destinationId: string);
+	readonly code: IoMessageCode;
 	/**
-	 * Return a string representation for this asset identifier
+	 * A brief description of the meaning of this IO Message.
 	 */
-	toString(): string;
+	readonly description: string;
+	/**
+	 * 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).
+	 */
+	readonly interface?: string;
 }
-/**
- * Different types of permission related changes in a diff
- */
-export declare enum PermissionChangeType {
+interface MessageInfo extends CodeInfo {
 	/**
-	 * No permission changes
+	 * The message level
 	 */
-	NONE = "none",
+	readonly level: IoMessageLevel;
+}
+interface IoMessageMaker<T> extends MessageInfo {
 	/**
-	 * Permissions are broadening
+	 * Create a message for this code, with or without payload.
 	 */
-	BROADENING = "broadening",
+	msg: [
+		T
+	] extends [
+		AbsentData
+	] ? (message: string) => ActionLessMessage<AbsentData> : (message: string, data: T) => ActionLessMessage<T>;
 	/**
-	 * Permissions are changed but not broadening
+	 * Returns whether the given `IoMessage` instance matches the current message definition
 	 */
-	NON_BROADENING = "non-broadening"
+	is(x: IoMessage<unknown>): x is IoMessage<T>;
 }
+type AbsentData = void;
 /**
  * Assembly data returned in the payload of an IO Message.
  */
@@ -2075,6 +2185,183 @@ export interface ConfirmationRequest {
 	 */
 	readonly concurrency?: number;
 }
+export interface ContextProviderMessageSource {
+	/**
+	 * The name of the context provider sending the message
+	 */
+	readonly provider: string;
+}
+interface SpanEnd {
+	readonly duration: number;
+}
+interface SpanDefinition<S extends object, E extends SpanEnd> {
+	readonly name: string;
+	readonly start: IoMessageMaker<S>;
+	readonly end: IoMessageMaker<E>;
+}
+type EmptyObject = {
+	[index: string | number | symbol]: never;
+};
+type VoidWhenEmpty<T> = T extends EmptyObject ? void : T;
+type ForceEmpty<T> = T extends EmptyObject ? EmptyObject : T;
+type Optional<T, K extends keyof T> = Pick<Partial<T>, K> & Omit<T, K>;
+interface ElapsedTime {
+	readonly asMs: number;
+	readonly asSec: number;
+}
+interface IMessageSpan<E extends SpanEnd> {
+	/**
+	 * Get the time elapsed since the start
+	 */
+	elapsedTime(): Promise<ElapsedTime>;
+	/**
+	 * Sends a simple, generic message with the current timing
+	 * For more complex intermediate messages, get the `elapsedTime` and use `notify`
+	 */
+	timing(maker: IoMessageMaker<Duration>, message?: string): Promise<ElapsedTime>;
+	/**
+	 * Sends an arbitrary intermediate message as part of the span
+	 */
+	notify(message: ActionLessMessage<unknown>): Promise<void>;
+	/**
+	 * End the span with a payload
+	 */
+	end(payload: VoidWhenEmpty<Omit<E, keyof SpanEnd>>): Promise<ElapsedTime>;
+	/**
+	 * End the span with a payload, overwriting
+	 */
+	end(payload: VoidWhenEmpty<Optional<E, keyof SpanEnd>>): Promise<ElapsedTime>;
+	/**
+	 * End the span with a message and payload
+	 */
+	end(message: string, payload: ForceEmpty<Optional<E, keyof SpanEnd>>): Promise<ElapsedTime>;
+}
+declare class SpanMaker<S extends object, E extends SpanEnd> {
+	private readonly definition;
+	private readonly ioHelper;
+	constructor(ioHelper: IoHelper, definition: SpanDefinition<S, E>);
+	/**
+	 * Starts the span and initially notifies the IoHost
+	 * @returns a message span
+	 */
+	begin(payload: VoidWhenEmpty<S>): Promise<IMessageSpan<E>>;
+	begin(message: string, payload: S): Promise<IMessageSpan<E>>;
+}
+type ActionLessMessage<T> = Omit<IoMessage<T>, "action">;
+type ActionLessRequest<T, U> = Omit<IoRequest<T, U>, "action">;
+declare class IoHelper implements IIoHost {
+	static fromIoHost(ioHost: IIoHost, action: ToolkitAction): IoHelper;
+	private readonly ioHost;
+	private readonly action;
+	private constructor();
+	/**
+	 * Forward a message to the IoHost, while injection the current action
+	 */
+	notify(msg: ActionLessMessage<unknown>): Promise<void>;
+	/**
+	 * Forward a request to the IoHost, while injection the current action
+	 */
+	requestResponse<T, U>(msg: ActionLessRequest<T, U>): Promise<U>;
+	/**
+	 * Create a new marker from a given registry entry
+	 */
+	span<S extends object, E extends SpanEnd>(definition: SpanDefinition<S, E>): SpanMaker<S, E>;
+}
+export interface BootstrapEnvironmentProgress {
+	/**
+	 * The total number of environments being deployed
+	 */
+	readonly total: number;
+	/**
+	 * The count of the environment currently bootstrapped
+	 *
+	 * This is counting value, not an identifier.
+	 */
+	readonly current: number;
+	/**
+	 * The environment that's currently being bootstrapped
+	 */
+	readonly environment: cxapi.Environment;
+}
+interface IManifestEntry {
+	/**
+	 * The identifier of the asset and its destination
+	 */
+	readonly id: DestinationIdentifier;
+	/**
+	 * The type of asset
+	 */
+	readonly type: string;
+	/**
+	 * Type-dependent source data
+	 */
+	readonly genericSource: unknown;
+	/**
+	 * Type-dependent destination data
+	 */
+	readonly genericDestination: unknown;
+	/**
+	 * Return a display name for this asset
+	 *
+	 * The `includeDestination` parameter controls whether or not to include the
+	 * destination ID in the display name.
+	 *
+	 * - Pass `false` if you are displaying notifications about building the
+	 *   asset, or if you are describing the work of building the asset and publishing
+	 *   to all destinations at the same time.
+	 * - Pass `true` if you are displaying notifications about publishing to a
+	 *   specific destination.
+	 */
+	displayName(includeDestination: boolean): string;
+}
+declare class DestinationIdentifier {
+	/**
+	 * Identifies the asset, by source.
+	 *
+	 * The assetId will be the same between assets that represent
+	 * the same physical file or image.
+	 */
+	readonly assetId: string;
+	/**
+	 * Identifies the destination where this asset will be published
+	 */
+	readonly destinationId: string;
+	constructor(assetId: string, destinationId: string);
+	/**
+	 * Return a string representation for this asset identifier
+	 */
+	toString(): string;
+}
+/**
+ * Different types of permission related changes in a diff
+ */
+export declare enum PermissionChangeType {
+	/**
+	 * No permission changes
+	 */
+	NONE = "none",
+	/**
+	 * Permissions are broadening
+	 */
+	BROADENING = "broadening",
+	/**
+	 * Permissions are changed but not broadening
+	 */
+	NON_BROADENING = "non-broadening"
+}
+/**
+ * Output of the diff command
+ */
+export interface DiffResult extends Duration {
+	/**
+	 * Stack diff formatted as a string
+	 */
+	readonly formattedStackDiff: string;
+	/**
+	 * Security diff formatted as a string
+	 */
+	readonly formattedSecurityDiff: string;
+}
 export interface StackDeployProgress {
 	/**
 	 * The total number of stacks being deployed
@@ -2198,7 +2485,7 @@ export interface StackDetails {
 	dependencies: StackDependency[];
 }
 export interface StackDetailsPayload {
-	stacks: StackDetails[];
+	readonly stacks: StackDetails[];
 }
 /**
  * An SDK logging trace.
@@ -2384,66 +2671,6 @@ export interface CloudWatchLogEvent {
 	 */
 	readonly timestamp: Date;
 }
-interface IDifference<ValueType> {
-	readonly oldValue: ValueType | undefined;
-	readonly newValue: ValueType | undefined;
-	readonly isDifferent: boolean;
-	readonly isAddition: boolean;
-	readonly isRemoval: boolean;
-	readonly isUpdate: boolean;
-}
-declare class Difference<ValueType> implements IDifference<ValueType> {
-	readonly oldValue: ValueType | undefined;
-	readonly newValue: ValueType | undefined;
-	/**
-	 * Whether this is an actual different or the values are actually the same
-	 *
-	 * isDifferent => (isUpdate | isRemoved | isUpdate)
-	 */
-	isDifferent: boolean;
-	/**
-	 * @param oldValue the old value, cannot be equal (to the sense of +deepEqual+) to +newValue+.
-	 * @param newValue the new value, cannot be equal (to the sense of +deepEqual+) to +oldValue+.
-	 */
-	constructor(oldValue: ValueType | undefined, newValue: ValueType | undefined);
-	/** @returns +true+ if the element is new to the template. */
-	get isAddition(): boolean;
-	/** @returns +true+ if the element was removed from the template. */
-	get isRemoval(): boolean;
-	/** @returns +true+ if the element was already in the template and is updated. */
-	get isUpdate(): boolean;
-}
-declare class PropertyDifference<ValueType> extends Difference<ValueType> {
-	changeImpact?: ResourceImpact;
-	constructor(oldValue: ValueType | undefined, newValue: ValueType | undefined, args: {
-		changeImpact?: ResourceImpact;
-	});
-}
-declare enum ResourceImpact {
-	/** The existing physical resource will be updated */
-	WILL_UPDATE = "WILL_UPDATE",
-	/** A new physical resource will be created */
-	WILL_CREATE = "WILL_CREATE",
-	/** The existing physical resource will be replaced */
-	WILL_REPLACE = "WILL_REPLACE",
-	/** The existing physical resource may be replaced */
-	MAY_REPLACE = "MAY_REPLACE",
-	/** The existing physical resource will be destroyed */
-	WILL_DESTROY = "WILL_DESTROY",
-	/** The existing physical resource will be removed from CloudFormation supervision */
-	WILL_ORPHAN = "WILL_ORPHAN",
-	/** The existing physical resource will be added to CloudFormation supervision */
-	WILL_IMPORT = "WILL_IMPORT",
-	/** There is no change in this resource */
-	NO_CHANGE = "NO_CHANGE"
-}
-interface Resource {
-	Type: string;
-	Properties?: {
-		[name: string]: any;
-	};
-	[key: string]: any;
-}
 /**
  * A resource affected by a change
  */
@@ -2467,6 +2694,13 @@ export interface AffectedResource {
 	 * A physical name is not always available, e.g. new resources will not have one until after the deployment
 	 */
 	readonly physicalName?: string;
+	/**
+	 * Resource metadata attached to the logical id from the cloud assembly
+	 *
+	 * This is only present if the resource is present in the current Cloud Assembly,
+	 * i.e. resource deletions will not have metadata.
+	 */
+	readonly metadata?: ResourceMetadata;
 }
 /**
  * Represents a change in a resource
@@ -2488,6 +2722,13 @@ export interface ResourceChange {
 	 * The changes made to the resource properties
 	 */
 	readonly propertyUpdates: Record<string, PropertyDifference<unknown>>;
+	/**
+	 * Resource metadata attached to the logical id from the cloud assembly
+	 *
+	 * This is only present if the resource is present in the current Cloud Assembly,
+	 * i.e. resource deletions will not have metadata.
+	 */
+	readonly metadata?: ResourceMetadata;
 }
 /**
  * A change that can be hotswapped
@@ -2497,11 +2738,118 @@ export interface HotswappableChange {
 	 * The resource change that is causing the hotswap.
 	 */
 	readonly cause: ResourceChange;
+	/**
+	 * A list of resources that are being hotswapped as part of the change
+	 */
+	readonly resources: AffectedResource[];
+}
+export declare enum NonHotswappableReason {
+	/**
+	 * Tags are not hotswappable
+	 */
+	TAGS = "tags",
+	/**
+	 * Changed resource properties are not hotswappable on this resource type
+	 */
+	PROPERTIES = "properties",
+	/**
+	 * A stack output has changed
+	 */
+	OUTPUT = "output",
+	/**
+	 * A dependant resource is not hotswappable
+	 */
+	DEPENDENCY_UNSUPPORTED = "dependency-unsupported",
+	/**
+	 * The resource type is not hotswappable
+	 */
+	RESOURCE_UNSUPPORTED = "resource-unsupported",
+	/**
+	 * The resource is created in the deployment
+	 */
+	RESOURCE_CREATION = "resource-creation",
+	/**
+	 * The resource is removed in the deployment
+	 */
+	RESOURCE_DELETION = "resource-deletion",
+	/**
+	 * The resource identified by the logical id has its type changed
+	 */
+	RESOURCE_TYPE_CHANGED = "resource-type-changed",
+	/**
+	 * The nested stack is created in the deployment
+	 */
+	NESTED_STACK_CREATION = "nested-stack-creation"
+}
+export interface RejectionSubject {
+	/**
+	 * The type of the rejection subject, e.g. Resource or Output
+	 */
+	readonly type: string;
+	/**
+	 * The logical ID of the change that is not hotswappable
+	 */
+	readonly logicalId: string;
+	/**
+	 * Resource metadata attached to the logical id from the cloud assembly
+	 *
+	 * This is only present if the resource is present in the current Cloud Assembly,
+	 * i.e. resource deletions will not have metadata.
+	 */
+	readonly metadata?: ResourceMetadata;
+}
+export interface ResourceSubject extends RejectionSubject {
+	/**
+	 * A rejected resource
+	 */
+	readonly type: "Resource";
+	/**
+	 * The type of the rejected resource
+	 */
+	readonly resourceType: string;
+	/**
+	 * The list of properties that are cause for the rejection
+	 */
+	readonly rejectedProperties?: string[];
+}
+export interface OutputSubject extends RejectionSubject {
+	/**
+	 * A rejected output
+	 */
+	readonly type: "Output";
+}
+/**
+ * A change that can not be hotswapped
+ */
+export interface NonHotswappableChange {
+	/**
+	 * The subject of the change that was rejected
+	 */
+	readonly subject: ResourceSubject | OutputSubject;
+	/**
+	 * Why was this change was deemed non-hotswappable
+	 */
+	readonly reason: NonHotswappableReason;
+	/**
+	 * Tells the user exactly why this change was deemed non-hotswappable and what its logical ID is.
+	 * If not specified, `displayReason` default to state that the properties listed in `rejectedChanges` are not hotswappable.
+	 */
+	readonly description: string;
+}
+export interface HotswapDeploymentAttempt {
+	/**
+	 * The stack that's currently being deployed
+	 */
+	readonly stack: cxapi.CloudFormationStackArtifact;
+	/**
+	 * The mode the hotswap deployment was initiated with.
+	 */
+	readonly mode: "hotswap-only" | "fall-back";
 }
 /**
  * Information about a hotswap deployment
  */
-export interface HotswapDeployment {
+export interface HotswapDeploymentDetails {
 	/**
 	 * The stack that's currently being deployed
 	 */
@@ -2510,6 +2858,144 @@ export interface HotswapDeployment {
 	 * The mode the hotswap deployment was initiated with.
 	 */
 	readonly mode: "hotswap-only" | "fall-back";
+	/**
+	 * The changes that were deemed hotswappable
+	 */
+	readonly hotswappableChanges: HotswappableChange[];
+	/**
+	 * The changes that were deemed not hotswappable
+	 */
+	readonly nonHotswappableChanges: NonHotswappableChange[];
+}
+/**
+ * The result of an attempted hotswap deployment
+ */
+export interface HotswapResult extends Duration, HotswapDeploymentDetails {
+	/**
+	 * Whether hotswapping happened or not.
+	 *
+	 * `false` indicates that the deployment could not be hotswapped and full deployment may be attempted as fallback.
+	 */
+	readonly hotswapped: boolean;
+}
+/**
+ * @deprecated
+ */
+declare enum RequireApproval$1 {
+	/**
+	 * Never require any security approvals
+	 */
+	NEVER = "never",
+	/**
+	 * Any security changes require an approval
+	 */
+	ANY_CHANGE = "any-change",
+	/**
+	 * Require approval only for changes that are access broadening
+	 */
+	BROADENING = "broadening"
+}
+interface FormatSecurityDiffOutput {
+	/**
+	 * Complete formatted security diff, if it is prompt-worthy
+	 */
+	readonly formattedDiff?: string;
+}
+interface FormatStackDiffOutput {
+	/**
+	 * Number of stacks with diff changes
+	 */
+	readonly numStacksWithChanges: number;
+	/**
+	 * Complete formatted diff
+	 */
+	readonly formattedDiff: string;
+}
+interface DiffFormatterProps {
+	/**
+	 * Helper for the IoHost class
+	 */
+	readonly ioHelper: IoHelper;
+	/**
+	 * The old/current state of the stack.
+	 */
+	readonly oldTemplate: any;
+	/**
+	 * The new/target state of the stack.
+	 */
+	readonly newTemplate: cxapi.CloudFormationStackArtifact;
+}
+interface FormatSecurityDiffOptions {
+	/**
+	 * The approval level of the security diff
+	 */
+	readonly requireApproval: RequireApproval$1;
+	/**
+	 * The name of the Stack.
+	 */
+	readonly stackName?: string;
+	/**
+	 * The changeSet for the Stack.
+	 *
+	 * @default undefined
+	 */
+	readonly changeSet?: DescribeChangeSetOutput;
+}
+interface FormatStackDiffOptions {
+	/**
+	 * do not filter out AWS::CDK::Metadata or Rules
+	 *
+	 * @default false
+	 */
+	readonly strict?: boolean;
+	/**
+	 * lines of context to use in arbitrary JSON diff
+	 *
+	 * @default 3
+	 */
+	readonly context?: number;
+	/**
+	 * silences \'There were no differences\' messages
+	 *
+	 * @default false
+	 */
+	readonly quiet?: boolean;
+	/**
+	 * The name of the stack
+	 */
+	readonly stackName?: string;
+	/**
+	 * @default undefined
+	 */
+	readonly changeSet?: DescribeChangeSetOutput;
+	/**
+	 * @default false
+	 */
+	readonly isImport?: boolean;
+	/**
+	 * @default undefined
+	 */
+	readonly nestedStackTemplates?: {
+		[nestedStackLogicalId: string]: NestedStackTemplates;
+	};
+}
+/**
+ * Class for formatting the diff output
+ */
+export declare class DiffFormatter {
+	private readonly ioHelper;
+	private readonly oldTemplate;
+	private readonly newTemplate;
+	constructor(props: DiffFormatterProps);
+	/**
+	 * Format the stack diff
+	 */
+	formatStackDiff(options: FormatStackDiffOptions): FormatStackDiffOutput;
+	private formatStackDiffHelper;
+	/**
+	 * Format the security diff
+	 */
+	formatSecurityDiff(options: FormatSecurityDiffOptions): FormatSecurityDiffOutput;
 }
 /**
  * Represents a general toolkit error in the AWS CDK Toolkit.
@@ -2531,6 +3017,10 @@ export declare class ToolkitError extends Error {
 	 * Determines if a given error is an instance of AssemblyError.
 	 */
 	static isContextProviderError(x: any): x is ContextProviderError;
+	/**
+	 * An AssemblyError with an original error as cause
+	 */
+	static withCause(message: string, error: unknown): ToolkitError;
 	/**
 	 * The type of the error, defaults to "toolkit".
 	 */
@@ -2539,7 +3029,11 @@ export declare class ToolkitError extends Error {
 	 * Denotes the source of the error as the toolkit.
 	 */
 	readonly source: "toolkit" | "user";
-	constructor(message: string, type?: string);
+	/**
+	 * The specific original cause of the error, if available
+	 */
+	readonly cause?: unknown;
+	constructor(message: string, type?: string, cause?: unknown);
 }
 /**
  * Represents an authentication-specific error in the AWS CDK Toolkit.
@@ -2576,10 +3070,6 @@ export declare class AssemblyError extends ToolkitError {
 	 * Absence indicates synthesis didn't fully complete.
 	 */
 	readonly stacks?: cxapi.CloudFormationStackArtifact[];
-	/**
-	 * The specific original cause of the error, if available
-	 */
-	readonly cause?: unknown;
 	private constructor();
 }
 /**
@@ -2593,22 +3083,10 @@ export declare class ContextProviderError extends ToolkitError {
 	constructor(message: string);
 }
 /**
- * @deprecated
+ * Removes CDKMetadata and Outputs in the template so that only resources for importing are left.
+ * @returns template with import resources only
  */
-declare enum RequireApproval$1 {
-	/**
-	 * Never require any security approvals
-	 */
-	NEVER = "never",
-	/**
-	 * Any security changes require an approval
-	 */
-	ANY_CHANGE = "any-change",
-	/**
-	 * Require approval only for changes that are access broadening
-	 */
-	BROADENING = "broadening"
-}
+export declare function removeNonImportResources(stack: CloudFormationStackArtifact): any;
 
 export {
 	MissingContext$1 as MissingContext,