chore(toolkit): list action (#33298)

### Issue #33179 Closes #33179 ### Description of changes Adds the list action. Converts the existing dependency calculation code into a generic feature on StackCollection. ### Describe any new or updated permissions being added n/a ### Description of how you validated changes Unit tests and integ test pipeline ### Checklist - [x] My code adheres to the [CONTRIBUTING GUIDE](https://github.com/aws/aws-cdk/blob/main/CONTRIBUTING.md) and [DESIGN GUIDELINES](https://github.com/aws/aws-cdk/blob/main/docs/DESIGN_GUIDELINES.md) ---- *By submitting this pull request, I confirm that my contribution is made under the terms of the Apache-2.0 license*
aws · Feb 7, 2025 · 873233b · 873233b
1 parent 0abcacf
commit 873233b
Show file tree

Hide file tree

Showing 21 changed files with 801 additions and 113 deletions.
diff --git a/packages/@aws-cdk/toolkit/lib/actions/list/index.ts b/packages/@aws-cdk/toolkit/lib/actions/list/index.ts
@@ -4,5 +4,5 @@ export interface ListOptions {
   /**
    * Select the stacks
    */
-  readonly stacks: StackSelector;
+  readonly stacks?: StackSelector;
 }
diff --git a/packages/@aws-cdk/toolkit/lib/api/aws-cdk.ts b/packages/@aws-cdk/toolkit/lib/api/aws-cdk.ts
@@ -33,7 +33,7 @@ export { findCloudWatchLogGroups } from '../../../../aws-cdk/lib/api/logs/find-c
 export { HotswapPropertyOverrides, EcsHotswapProperties } from '../../../../aws-cdk/lib/api/hotswap/common';
 
 // @todo Cloud Assembly and Executable - this is a messy API right now
-export { CloudAssembly, sanitizePatterns, StackCollection, ExtendedStackSelection } from '../../../../aws-cdk/lib/api/cxapp/cloud-assembly';
+export { CloudAssembly, sanitizePatterns, type StackDetails, StackCollection, ExtendedStackSelection } from '../../../../aws-cdk/lib/api/cxapp/cloud-assembly';
 export { prepareDefaultEnvironment, prepareContext, spaceAvailableForContext } from '../../../../aws-cdk/lib/api/cxapp/exec';
 export { guessExecutable } from '../../../../aws-cdk/lib/api/cxapp/exec';
 

diff --git a/packages/@aws-cdk/toolkit/lib/api/cloud-assembly/stack-selector.ts b/packages/@aws-cdk/toolkit/lib/api/cloud-assembly/stack-selector.ts
@@ -20,10 +20,11 @@ export enum StackSelectionStrategy {
   ONLY_SINGLE = 'ONLY_SINGLE',
 
   /**
-   * @todo not currently publicly exposed
    * Return stacks matched by patterns.
    * If no stacks are found, execution is halted successfully.
    * Most likely you don't want to use this but `StackSelectionStrategy.MUST_MATCH_PATTERN`
+   *
+   * @todo not currently publicly exposed in cli, but available in toolkit
    */
   PATTERN_MATCH = 'PATTERN_MATCH',
 

diff --git a/packages/@aws-cdk/toolkit/lib/api/io/private/codes.ts b/packages/@aws-cdk/toolkit/lib/api/io/private/codes.ts
@@ -1,12 +1,23 @@
 import { IoMessageCode } from '../io-message';
 
+/**
+ * We have a rough system by which we assign message codes:
+ * - First digit groups messages by action, e.g. synth or deploy
+ * - X000-X009 are reserved for timings
+ * - X900-X999 are reserved for results
+ */
 export const CODES = {
-  // Synth
+  // 1: Synth
   CDK_TOOLKIT_I1000: 'Provides synthesis times',
   CDK_TOOLKIT_I1901: 'Provides stack data',
   CDK_TOOLKIT_I1902: 'Successfully deployed stacks',
 
-  // Deploy
+  // 2: List
+  CDK_TOOLKIT_I2901: 'Provides details on the selected stacks and their dependencies',
+
+  // 4: Diff
+
+  // 5: Deploy
   CDK_TOOLKIT_I5000: 'Provides deployment times',
   CDK_TOOLKIT_I5001: 'Provides total time in deploy action, including synth and rollback',
   CDK_TOOLKIT_I5031: 'Informs about any log groups that are traced as part of the deployment',
@@ -16,19 +27,21 @@ export const CODES = {
 
   CDK_TOOLKIT_E5001: 'No stacks found',
 
-  // Rollback
+  // 6: Rollback
   CDK_TOOLKIT_I6000: 'Provides rollback times',
 
   CDK_TOOLKIT_E6001: 'No stacks found',
   CDK_TOOLKIT_E6900: 'Rollback failed',
 
-  // Destroy
+  // 7: Destroy
   CDK_TOOLKIT_I7000: 'Provides destroy times',
   CDK_TOOLKIT_I7010: 'Confirm destroy stacks',
 
   CDK_TOOLKIT_E7010: 'Action was aborted due to negative confirmation of request',
   CDK_TOOLKIT_E7900: 'Stack deletion failed',
 
+  // 9: Bootstrap
+
   // Assembly codes
   CDK_ASSEMBLY_I0042: 'Writing updated context',
   CDK_ASSEMBLY_I0241: 'Fetching missing context',

diff --git a/packages/@aws-cdk/toolkit/lib/toolkit/toolkit.ts b/packages/@aws-cdk/toolkit/lib/toolkit/toolkit.ts
@@ -14,7 +14,7 @@ import { type RollbackOptions } from '../actions/rollback';
 import { type SynthOptions } from '../actions/synth';
 import { patternsArrayForWatch, WatchOptions } from '../actions/watch';
 import { type SdkOptions } from '../api/aws-auth';
-import { DEFAULT_TOOLKIT_STACK_NAME, SdkProvider, SuccessfulDeployStackResult, StackCollection, Deployments, HotswapMode, StackActivityProgress, ResourceMigrator, obscureTemplate, serializeStructure, tagsForStack, CliIoHost, validateSnsTopicArn, Concurrency, WorkGraphBuilder, AssetBuildNode, AssetPublishNode, StackNode, formatErrorMessage, CloudWatchLogEventMonitor, findCloudWatchLogGroups, formatTime } from '../api/aws-cdk';
+import { DEFAULT_TOOLKIT_STACK_NAME, SdkProvider, SuccessfulDeployStackResult, StackCollection, Deployments, HotswapMode, StackActivityProgress, ResourceMigrator, obscureTemplate, serializeStructure, tagsForStack, CliIoHost, validateSnsTopicArn, Concurrency, WorkGraphBuilder, AssetBuildNode, AssetPublishNode, StackNode, formatErrorMessage, CloudWatchLogEventMonitor, findCloudWatchLogGroups, formatTime, StackDetails } from '../api/aws-cdk';
 import { CachedCloudAssemblySource, IdentityCloudAssemblySource, StackAssembly, ICloudAssemblySource, StackSelectionStrategy } from '../api/cloud-assembly';
 import { ALL_STACKS, CloudAssemblySourceBuilder } from '../api/cloud-assembly/private';
 import { ToolkitError } from '../api/errors';
@@ -199,19 +199,25 @@ export class Toolkit extends CloudAssemblySourceBuilder implements AsyncDisposab
   /**
    * List Action
    *
-   * List out selected stacks
+   * List selected stacks and their dependencies
    */
-  public async list(cx: ICloudAssemblySource, _options: ListOptions): Promise<void> {
+  public async list(cx: ICloudAssemblySource, options: ListOptions = {}): Promise<StackDetails[]> {
     const ioHost = withAction(this.ioHost, 'list');
+    const synthTimer = Timer.start();
     const assembly = await this.assemblyFromSource(cx);
-    ioHost;
-    assembly;
-    // temporary
-    // eslint-disable-next-line @cdklabs/no-throw-default-error
-    throw new Error('Not implemented yet');
+    const stackCollection = await assembly.selectStacksV2(options.stacks ?? ALL_STACKS);
+    await synthTimer.endAs(ioHost, 'synth');
+
+    const stacks = stackCollection.withDependencies();
+    const message = stacks.map(s => s.id).join('\n');
+
+    await ioHost.notify(result(message, 'CDK_TOOLKIT_I2901', { stacks }));
+    return stacks;
   }
 
   /**
+   * Diff Action
+   *
    * Compares the specified stack with the deployed stack or a local template file and returns a structured diff.
    */
   public async diff(cx: ICloudAssemblySource, options: DiffOptions): Promise<boolean> {
@@ -225,6 +231,8 @@ export class Toolkit extends CloudAssemblySourceBuilder implements AsyncDisposab
   }
 
   /**
+   * Deploy Action
+   *
    * Deploys the selected stacks into an AWS account
    */
   public async deploy(cx: ICloudAssemblySource, options: DeployOptions = {}): Promise<void> {

diff --git a/packages/@aws-cdk/toolkit/test/_fixtures/console-output/app.js b/packages/@aws-cdk/toolkit/test/_fixtures/console-output/app.js
@@ -1,7 +1,7 @@
 import * as cdk from 'aws-cdk-lib/core';
 
 console.log('line one');
-const app = new cdk.App();
+const app = new cdk.App({ autoSynth: false });
 console.log('line two');
 new cdk.Stack(app, 'Stack1');
 console.log('line three');

diff --git a/packages/@aws-cdk/toolkit/test/_fixtures/external-context/app.js b/packages/@aws-cdk/toolkit/test/_fixtures/external-context/app.js
@@ -1,7 +1,7 @@
 import * as s3 from 'aws-cdk-lib/aws-s3';
 import * as core from 'aws-cdk-lib/core';
 
-const app = new core.App();
+const app = new core.App({ autoSynth: false });
 const stack = new core.Stack(app, 'Stack1');
 new s3.Bucket(stack, 'MyBucket', {
     bucketName: app.node.tryGetContext('externally-provided-bucket-name')

diff --git a/packages/@aws-cdk/toolkit/test/_fixtures/external-context/index.ts b/packages/@aws-cdk/toolkit/test/_fixtures/external-context/index.ts
@@ -2,7 +2,7 @@ import * as s3 from 'aws-cdk-lib/aws-s3';
 import * as core from 'aws-cdk-lib/core';
 
 export default async () => {
-  const app = new core.App();
+  const app = new core.App({ autoSynth: false });
   const stack = new core.Stack(app, 'Stack1');
   new s3.Bucket(stack, 'MyBucket', {
     bucketName: app.node.tryGetContext('externally-provided-bucket-name'),

diff --git a/packages/@aws-cdk/toolkit/test/_fixtures/stack-with-bucket/index.js b/packages/@aws-cdk/toolkit/test/_fixtures/stack-with-bucket/index.js
diff --git a/packages/@aws-cdk/toolkit/test/_fixtures/stack-with-bucket/index.ts b/packages/@aws-cdk/toolkit/test/_fixtures/stack-with-bucket/index.ts
@@ -2,7 +2,7 @@ import * as s3 from 'aws-cdk-lib/aws-s3';
 import * as core from 'aws-cdk-lib/core';
 
 export default async () => {
-  const app = new core.App();
+  const app = new core.App({ autoSynth: false });
   const stack = new core.Stack(app, 'Stack1');
   new s3.Bucket(stack, 'MyBucket');
   return app.synth();

diff --git a/packages/@aws-cdk/toolkit/test/_fixtures/stack-with-notification-arns/index.ts b/packages/@aws-cdk/toolkit/test/_fixtures/stack-with-notification-arns/index.ts
@@ -1,7 +1,7 @@
 import * as core from 'aws-cdk-lib/core';
 
 export default async() => {
-  const app = new core.App();
+  const app = new core.App({ autoSynth: false });
   new core.Stack(app, 'Stack1', {
     notificationArns: [
       'arn:aws:sns:us-east-1:1111111111:resource',

diff --git a/packages/@aws-cdk/toolkit/test/_fixtures/stack-with-role/index.ts b/packages/@aws-cdk/toolkit/test/_fixtures/stack-with-role/index.ts
@@ -2,7 +2,7 @@ import * as iam from 'aws-cdk-lib/aws-iam';
 import * as core from 'aws-cdk-lib/core';
 
 export default async() => {
-  const app = new core.App();
+  const app = new core.App({ autoSynth: false });
   const stack = new core.Stack(app, 'Stack1');
   new iam.Role(stack, 'Role', {
     assumedBy: new iam.ArnPrincipal('arn'),

diff --git a/packages/@aws-cdk/toolkit/test/_fixtures/two-empty-stacks/app.js b/packages/@aws-cdk/toolkit/test/_fixtures/two-empty-stacks/app.js
@@ -1,6 +1,6 @@
 import * as cdk from 'aws-cdk-lib/core';
 
-const app = new cdk.App();
+const app = new cdk.App({ autoSynth: false });
 new cdk.Stack(app, 'Stack1');
 new cdk.Stack(app, 'Stack2');
 

diff --git a/packages/@aws-cdk/toolkit/test/_fixtures/two-empty-stacks/index.js b/packages/@aws-cdk/toolkit/test/_fixtures/two-empty-stacks/index.js
diff --git a/packages/@aws-cdk/toolkit/test/_fixtures/two-empty-stacks/index.ts b/packages/@aws-cdk/toolkit/test/_fixtures/two-empty-stacks/index.ts
@@ -1,7 +1,7 @@
 import * as core from 'aws-cdk-lib/core';
 
 export default async () => {
-  const app = new core.App();
+  const app = new core.App({ autoSynth: false });
   new core.Stack(app, 'Stack1');
   new core.Stack(app, 'Stack2');
 

diff --git a/packages/@aws-cdk/toolkit/test/_fixtures/validation-error/app.js b/packages/@aws-cdk/toolkit/test/_fixtures/validation-error/app.js
@@ -1,7 +1,7 @@
 import * as cdk from 'aws-cdk-lib/core';
 import * as sqs from 'aws-cdk-lib/aws-sqs';
 
-const app = new cdk.App();
+const app = new cdk.App({ autoSynth: false });
 const stack = new cdk.Stack(app, 'Stack1');
 new sqs.Queue(stack, 'Queue1', {
   queueName: "Queue1",

diff --git a/packages/@aws-cdk/toolkit/test/_helpers/index.ts b/packages/@aws-cdk/toolkit/test/_helpers/index.ts
@@ -4,6 +4,7 @@ import { Toolkit, ToolkitError } from '../../lib';
 import { determineOutputDirectory } from '../../lib/api/cloud-assembly/private';
 
 export * from './test-io-host';
+export * from './test-cloud-assembly-source';
 
 function fixturePath(...parts: string[]): string {
   return path.normalize(path.join(__dirname, '..', '_fixtures', ...parts));