chore(toolkit): new and improved stack selection (#32928)

### Reason for this change

New unified, public stack selector interface. This was previously a mix
of `StackSelector` and options.
It was also very hard to follow.

### Summary of existing usage

```
## Stacks for list: diff and defineEnvironments

ALL+

=> ALL, error when none exists

- fail if no stacks at all
- Always ALL stacks

## listStacks.ts: Not Selector

ALL+, MATCH

=> ALL, or match by pattern with upstream

- fail if no stacks at all
- if patterns that, otherwise ALL
- Always extend Upstream

## Single: Not a Selector, used by metadata

MUST_MATCH_ONE

=> Exactly 1, matched by pattern, errors for various out of bounds

- fail if no stacks at all
- single pattern
- no extend, no default
- Custom: Exception if more than 1
- Via stack collection: will fail if not at least 1
  
## Destroy: Selector, used by: Destroy in extension Deploy

From deploy: Exactly 1 matched by pattern, exclusive

  MUST_MATCH_ONE

From destroy: many is fine

  ALL+, MUST_MATCH, ONLY_ONE

  Bug: if no top level stacks and --all

  cdk destroy --all vs cdk destroy "*/*"
  No stack found in the main cloud assembly. Use "list" to print manifest
  Are you sure you want to delete: LocalStage/NetworkStack, DevStage/NetworkStack (y/n)? n

  Bug:
    cdk destroy unknown
    Are you sure you want to delete:  (y/n)?

Selected:
 | MAIN (not empty, extended)
 | MATCH (can be empty, extended)
 | EXACTLY ONE

- fail if no stack at all
- maybe MAIN, with throw
- otherwise patterns
- otherwise exactly 1
- extends both
- can be matching none

## Diff: Selector, used by: Diff, Synth

Wants: at least 1

Possible bug: synth/diff if no top-level and no patterns

Auto:
 | MATCH (extended, must match)
 | MAIN (not empty, not extended)

- fail if no stack at all
- never all top-level
- pattern if provided (extended)
- otherwise Main (not extended)
- Custom: Not none if patterns

### Diff

ALL+, MUST_MATCH, ONLY_ONE

  Wants Exactly 1 of template path
  Bug?: When top-level is empty
    cdk diff "*/*" -> finds both
    cdk diff "*" -> finds none
    cdk diff -> 0 stacks with differences (bug!!!)

### Synth

  ALL+, MUST_MATCH

  More than one doesn't really matter
  Bug if top-level is empty
    Supply a stack id () to display its template. -> list in () is empty

## Deploy: Selector, used by: Deploy, Rollback, Import

- Custom: Not none if patterns

### Deploy

ALL+, MAIN+, MUST_MATCH, ONLY_ONE

Bug: Empty top level and "cdk deploy --all"

Wants: at least 1

- OPTION: fail if no stack at all
- OPTION: Extends
- selector: all or patterns or exactly 1
- Custom: Not none

### Rollback

ALL+, MAIN+, MUST_MATCH, ONLY_ONE

Wants: at least 1

- fail if no stack at all
- selector: all or patterns or exactly 1
- no extend
- Custom: Not none

### Import

MUST_MATCH_ONE, ONLY_ONE

Wants: Exactly 1

- fail if no stack at all
- selector: all or patterns or exactly 1
- no extend
- Custom: more then one
```

### 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*

Author: mrgrain

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

@@ -1,6 +1,9 @@
 import * as cxapi from '@aws-cdk/cx-api';
-import { CloudAssembly } from 'aws-cdk/lib/api/cxapp/cloud-assembly';
+import { CloudAssembly, sanitizePatterns, StackCollection, ExtendedStackSelection as CliExtendedStackSelection } from 'aws-cdk/lib/api/cxapp/cloud-assembly';
+import { major } from 'semver';
 import { ICloudAssemblySource } from './types';
+import { ExtendedStackSelection, StackSelectionStrategy, StackSelector } from '../../types';
+import { ToolkitError } from '../errors';
 
 /**
  * A single Cloud Assembly wrapped to provide additional stack operations.
@@ -9,4 +12,99 @@ export class StackAssembly extends CloudAssembly implements ICloudAssemblySource
   public async produce(): Promise<cxapi.CloudAssembly> {
     return this.assembly;
   }
+
+  /**
+   * Improved stack selection interface with a single selector
+   * @returns
+   * @throws when the assembly does not contain any stacks, unless `selector.failOnEmpty` is `false`
+   * @throws when individual selection strategies are not satisfied
+   */
+  public selectStacksV2(selector: StackSelector): StackCollection {
+    const asm = this.assembly;
+    const topLevelStacks = asm.stacks;
+    const allStacks = major(asm.version) < 10 ? asm.stacks : asm.stacksRecursively;
+
+    if (allStacks.length === 0 && (selector.failOnEmpty ?? true)) {
+      throw new ToolkitError('This app contains no stacks');
+    }
+
+    const extend = convertExtend(selector.extend);
+    const patterns = sanitizePatterns(selector.patterns ?? []);
+
+    switch (selector.strategy) {
+      case StackSelectionStrategy.ALL_STACKS:
+        return new StackCollection(this, allStacks);
+      case StackSelectionStrategy.MAIN_ASSEMBLY:
+        if (topLevelStacks.length < 1) {
+          //@todo text should probably be handled in io host
+          throw new ToolkitError('No stack found in the main cloud assembly. Use "list" to print manifest');
+        }
+        return this.extendStacks(topLevelStacks, allStacks, extend);
+      case StackSelectionStrategy.ONLY_SINGLE:
+        if (topLevelStacks.length !== 1) {
+          //@todo text should probably be handled in io host
+          throw new ToolkitError('Since this app includes more than a single stack, specify which stacks to use (wildcards are supported) or specify `--all`\n' +
+          `Stacks: ${allStacks.map(x => x.hierarchicalId).join(' · ')}`);
+        }
+        return new StackCollection(this, topLevelStacks);
+      default:
+        const matched = this.selectMatchingStacks(allStacks, patterns, extend);
+        if (
+          selector.strategy === StackSelectionStrategy.PATTERN_MUST_MATCH_SINGLE
+          && matched.stackCount !== 1
+        ) {
+          //@todo text should probably be handled in io host
+          throw new ToolkitError(
+            `Stack selection is ambiguous, please choose a specific stack for import [${allStacks.map(x => x.hierarchicalId).join(',')}]`,
+          );
+        }
+        if (
+          selector.strategy === StackSelectionStrategy.PATTERN_MUST_MATCH
+          && matched.stackCount < 1
+        ) {
+          //@todo text should probably be handled in io host
+          throw new ToolkitError(
+            `Stack selection is ambiguous, please choose a specific stack for import [${allStacks.map(x => x.hierarchicalId).join(',')}]`,
+          );
+        }
+
+        return matched;
+    }
+  }
+
+  /**
+   * Select all stacks.
+   *
+   * This method never throws and can safely be used as a basis for other calculations.
+   *
+   * @returns a `StackCollection` of all stacks
+   */
+  public selectAllStacks() {
+    const allStacks = major(this.assembly.version) < 10 ? this.assembly.stacks : this.assembly.stacksRecursively;
+    return new StackCollection(this, allStacks);
+  }
+
+  /**
+   * Select all stacks that have the validateOnSynth flag et.
+   *
+   * @param assembly
+   * @returns a `StackCollection` of all stacks that needs to be validated
+   */
+  public selectStacksForValidation() {
+    const allStacks = this.selectAllStacks();
+    return allStacks.filter((art) => art.validateOnSynth ?? false);
+  }
+}
+
+function convertExtend(extend?: ExtendedStackSelection): CliExtendedStackSelection | undefined {
+  switch (extend) {
+    case ExtendedStackSelection.DOWNSTREAM:
+      return CliExtendedStackSelection.Downstream;
+    case ExtendedStackSelection.UPSTREAM:
+      return CliExtendedStackSelection.Upstream;
+    case ExtendedStackSelection.NONE:
+      return CliExtendedStackSelection.None;
+    default:
+      return undefined;
+  }
 }

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

@@ -83,9 +83,9 @@ export class Toolkit {
   public async synth(cx: ICloudAssemblySource, options: SynthOptions): Promise<ICloudAssemblySource> {
     const ioHost = withAction(this.ioHost, 'synth');
     const assembly = await this.assemblyFromSource(cx);
-    const stacks = await assembly.selectStacks(options.stacks, false);
-    const autoValidateStacks = options.validateStacks ? await this.selectStacksForValidation(assembly) : new StackCollection(assembly, []);
-    this.processStackMessages(stacks.concat(autoValidateStacks));
+    const stacks = assembly.selectStacksV2(options.stacks);
+    const autoValidateStacks = options.validateStacks ? [assembly.selectStacksForValidation()] : [];
+    this.processStackMessages(stacks.concat(...autoValidateStacks));
 
     // if we have a single stack, print it to STDOUT
     if (stacks.stackCount === 1) {
@@ -123,7 +123,7 @@ export class Toolkit {
   public async diff(cx: ICloudAssemblySource, options: DiffOptions): Promise<boolean> {
     const ioHost = withAction(this.ioHost, 'diff');
     const assembly = await this.assemblyFromSource(cx);
-    const stacks = await assembly.selectStacks(options.stacks, {});
+    const stacks = await assembly.selectStacksV2(options.stacks);
     throw new Error('Not implemented yet');
   }
 
@@ -134,7 +134,7 @@ export class Toolkit {
     const ioHost = withAction(this.ioHost, 'deploy');
     const timer = Timer.start();
     const assembly = await this.assemblyFromSource(cx);
-    const stackCollection = await assembly.selectStacks(options.stacks, {});
+    const stackCollection = assembly.selectStacksV2(options.stacks);
 
     const synthTime = timer.end();
     await ioHost.notify(info(`\n✨  Synthesis time: ${synthTime.asSec}s\n`, 'CDK_TOOLKIT_I5001', {
@@ -219,11 +219,8 @@ export class Toolkit {
         } else {
           await ioHost.notify(warning(`${chalk.bold(stack.displayName)}: stack has no resources, deleting existing stack.`));
           await this._destroy(assembly, 'deploy', {
-            selector: { patterns: [stack.hierarchicalId] },
-            exclusively: true,
-            force: true,
+            stacks: { patterns: [stack.hierarchicalId], strategy: StackSelectionStrategy.PATTERN_MUST_MATCH_SINGLE },
             roleArn: options.roleArn,
-            fromDeploy: true,
             ci: options.ci,
           });
         }
@@ -321,7 +318,7 @@ export class Toolkit {
               }
 
               // Perform a rollback
-              await this.rollback({
+              await this.rollback(cx, {
                 selector: { patterns: [stack.hierarchicalId] },
                 toolkitStackName: options.toolkitStackName,
                 force: options.force,
@@ -454,7 +451,7 @@ export class Toolkit {
    *
    * Rolls back the selected stacks.
    */
-  public async rollback(_cx: ICloudAssemblySource, _options: WatchOptions): Promise<void> {
+  public async rollback(_cx: ICloudAssemblySource, _options: any): Promise<void> {
     const ioHost = withAction(this.ioHost, 'rollback');
     throw new Error('Not implemented yet');
   }
@@ -474,7 +471,7 @@ export class Toolkit {
    */
   private async _destroy(assembly: StackAssembly, action: 'deploy' | 'destroy', options: DestroyOptions): Promise<void> {
     const ioHost = withAction(this.ioHost, action);
-    let stacks = await assembly.selectStacks(options.stacks, false);
+    let stacks = await assembly.selectStacksV2(options.stacks);
 
     // The stacks will have been ordered for deployment, so reverse them for deletion.
     stacks = stacks.reversed();
@@ -523,8 +520,6 @@ export class Toolkit {
 
   /**
    * Create a deployments class
-   * @param action C
-   * @returns
    */
   private async deploymentsForAction(action: ToolkitAction): Promise<Deployments> {
     return new Deployments({
@@ -533,17 +528,6 @@ export class Toolkit {
     });
   }
 
-  /**
-   * Select all stacks that have the validateOnSynth flag et.
-   *
-   * @param assembly
-   * @returns a `StackCollection` of all stacks that needs to be validated
-   */
-  private async selectStacksForValidation(assembly: StackAssembly) {
-    const allStacks = await assembly.selectStacks({ strategy: StackSelectionStrategy.ALL_STACKS }, false);
-    return allStacks.filter((art) => art.validateOnSynth ?? false);
-  }
-
   /**
    * Validate the stacks for errors and warnings according to the CLI's current settings
    * @deprecated remove and use directly in synth

packages/@aws-cdk/toolkit/lib/types.ts

@@ -13,33 +13,41 @@ export type ToolkitAction =
 
 export enum StackSelectionStrategy {
   /**
-   * Returns an empty selection in case there are no stacks.
+   * Returns all stacks in the app regardless of patterns,
+   * including stacks inside nested assemblies.
    */
-  NONE = 'none',
+  ALL_STACKS = 'ALL_STACKS',
 
   /**
-   * Return matched stacks. If no patterns are provided, return the single stack in the app.
-   * If the app has more than one stack, an error is thrown.
-   *
-   * This is the default strategy used by "deploy" and "destroy".
+   * Returns all stacks in the main (top level) assembly only.
    */
-  MATCH_OR_SINGLE = 'match-or-single',
+  MAIN_ASSEMBLY = 'MAIN_ASSEMBLY',
 
   /**
-   * Throws an exception if the selector doesn't match at least one stack in the app.
+   * If the assembly includes a single stack, returns it.
+   * Otherwise throws an exception.
    */
-  MUST_MATCH_PATTERN = 'must-match-pattern',
+  ONLY_SINGLE = 'ONLY_SINGLE',
 
   /**
-   * Returns all stacks in the main (top level) assembly only.
+   * @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`
    */
-  MAIN_ASSEMBLY = 'main',
+  PATTERN_MATCH = 'PATTERN_MATCH',
 
   /**
-   * If no selectors are provided, returns all stacks in the app,
-   * including stacks inside nested assemblies.
+   * Return stacks matched by patterns.
+   * Throws an exception if the patterns don't match at least one stack in the assembly.
    */
-  ALL_STACKS = 'all',
+  PATTERN_MUST_MATCH = 'PATTERN_MUST_MATCH',
+
+  /**
+   * Returns if exactly one stack is matched by the pattern(s).
+   * Throws an exception if no stack, or more than exactly one stack are matched.
+   */
+  PATTERN_MUST_MATCH_SINGLE = 'PATTERN_MUST_MATCH_SINGLE',
 }
 
 /**
@@ -60,25 +68,44 @@ export enum ExtendedStackSelection {
    * Include stacks that depend on this stack
    */
   DOWNSTREAM = 'downstream',
+
+  /**
+   * @TODO
+   * Include both directions.
+   * I.e. stacks that this stack depends on, and stacks that depend on this stack.
+   */
+  // FULL = 'full',
 }
 
 /**
  * A specification of which stacks should be selected
  */
 export interface StackSelector {
+  /**
+   * The behavior if if no selectors are provided.
+   */
+  strategy: StackSelectionStrategy;
+
   /**
    * A list of patterns to match the stack hierarchical ids
+   * Only used with `PATTERN_*` selection strategies.
    */
   patterns?: string[];
 
   /**
-   * Extend the selection to upstream/downstream stacks
-   * @default ExtendedStackSelection.None only select the specified stacks.
+   * Extend the selection to upstream/downstream stacks.
+   * @default ExtendedStackSelection.None only select the specified/matched stacks
    */
   extend?: ExtendedStackSelection;
 
   /**
-   * The behavior if if no selectors are provided.
+   * By default, we throw an exception if the assembly contains no stacks.
+   * Set to `false`, to halt execution for empty assemblies without error.
+   *
+   * Note that actions can still throw if a stack selection result is empty,
+   * but the assembly contains stacks in principle.
+   *
+   * @default true
    */
-  strategy: StackSelectionStrategy;
+  failOnEmpty?: boolean;
 }

packages/aws-cdk/lib/api/cxapp/cloud-assembly.ts

@@ -134,7 +134,7 @@ export class CloudAssembly {
     }
   }
 
-  private selectMatchingStacks(
+  protected selectMatchingStacks(
     stacks: cxapi.CloudFormationStackArtifact[],
     patterns: string[],
     extend: ExtendedStackSelection = ExtendedStackSelection.None,
@@ -170,7 +170,7 @@ export class CloudAssembly {
     }
   }
 
-  private extendStacks(
+  protected extendStacks(
     matched: cxapi.CloudFormationStackArtifact[],
     all: cxapi.CloudFormationStackArtifact[],
     extend: ExtendedStackSelection = ExtendedStackSelection.None,
@@ -241,8 +241,8 @@ export class StackCollection {
     return new StackCollection(this.assembly, this.stackArtifacts.filter(predicate));
   }
 
-  public concat(other: StackCollection): StackCollection {
-    return new StackCollection(this.assembly, this.stackArtifacts.concat(other.stackArtifacts));
+  public concat(...others: StackCollection[]): StackCollection {
+    return new StackCollection(this.assembly, this.stackArtifacts.concat(...others.map(o => o.stackArtifacts)));
   }
 
   /**
@@ -380,7 +380,7 @@ function includeUpstreamStacks(
   }
 }
 
-function sanitizePatterns(patterns: string[]): string[] {
+export function sanitizePatterns(patterns: string[]): string[] {
   let sanitized = patterns.filter(s => s != null); // filter null/undefined
   sanitized = [...new Set(sanitized)]; // make them unique
   return sanitized;